API

Application Programming Interface

 

The services are available through rest via http protocol. To be able to access the services, you need to obtain an API key. To get an API key, fill the form on the sidebar on the left of this page.

The services are divided in 2 main components, write and read.

The write services are used to send your data for processing to our servers, and to update the data when is necessary.

The read services are intended to consume the data from your application or website.

The usual workflow using Tyk services is to send once your data and then to explore it with the services. So there will be a lot of read and not so much writes.

This documentation and the API are subject to change. While the API is versioned, early versions of the API may be aggressively deprecated.

Write

update http://tyk.li/ws/v0/update
method:post
DESCRIPTION

Update the dataset, parameters are:

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
overwrite Overwrite the dataset, do a clean update, wiping existing data. If no data were published before, this parameter do nothing bool false
lang Language to use, currently EN and IT are supported enum(EN,IT) EN
stripHtml Strip html before running keyword extraction bool false
enableNlp Enable keyword extraction on title and description. That is, when you send your data, the field description an title will be analyzed to extract keywords bool false
data Data to send to the service, look at the sample request for details JSON array - yes
REQUEST

Oid: is your dataset id, we do not check for unicity of the id, if there are more then one id, we will save the last.

token=fsahiosudhfh9h
&overwrite=true
&lang=EN
&stripHtml=true
&enableNlp=true
&data=[
    {
    	"oid":"item1",                                    
    	"title":"This is the Item One",
    	"src":"http:\/\/tyk.li\/data\/test\/item1",
    	"cats":"category1,category2",                     
    	"tags":"tag1,tag2,tag3",                          
    	"img": "http:\/\/tyk.li\/data\/test\/item1.png",
    	"date":"20081001 12:02:48",
    	"descr":"description of item 1",
    	"lang": "en",
    	"publisher":"my publisher",
    	"creator":"System Administrator"
    }, ...
]
RETURN

A json object containing a status and message. status 0 means that the request was successful.

{
     "status":0,
     "message":"";
}
delete http://tyk.li/ws/v0/delete
method:post
DESCRIPTION

Delete records from the dataset

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
data Data to send to the service, look at the sample request for details JSON array - yes
REQUEST

List of documents ids to be removed from the dataset

token=fsahiosudhfh9h
&data=[
    "item1",
    "item2",
    "item3"
]
RETURN

A json object describing the result of the operation

{
     "status":0,
     "message":"4 records deleted";
}

Read

doc http://tyk.li/rs/v0/doc
method:post
DESCRIPTION

Get the documents details of the documents tagged with the terms in request

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
turis Comma seprated list of tag identifiers, without any spaces, or empty string -
ps Index of entry for pagination int 0
pe Pagination lenght, how many results should be returned. Must be greather then 0. int 12
REQUEST

token=fsahiosudhfh9h
&turis=u140,t710
&ps=0
&pe=12
&data=[
    {
    	"oid":"item1",
    	"status":0
    },
    {
    	"oid":"item2",
    	"status":1
    }, ..
]
RETURN

[
  {
    "tags":"",
    "title":"Item 1 title",
    "desc":"",
    "source":"http:\/\/tyk.li\/data\/#\/test\/item1",
    "oid":"item1",
    "img":"",
    "date":"2012\/09\/13 12:19:37",
    "uri":"o1",
    "auth":"The Writer"
  }, ...
]
docscount http://tyk.li/rs/v0/docscount
method:post
DESCRIPTION

Get the number of documents connected to the terms requested, if no term is requested, get the total count of documents

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
turis Comma seprated list of tag identifiers, without any spaces, or empty string -
REQUEST

token=fsahiosudhfh9h
&turis=u140,t710
RETURN

{"count":83}
term http://tyk.li/rs/v0/term
method:post
DESCRIPTION

Get the detail of a term by it's id

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
turis Comma seprated list of tag identifiers, without any spaces, or empty string - yes
REQUEST

token=fsahiosudhfh9h
&turis=u140,t710
RETURN

The reply content is:

w
weight of the term. that is for how many docs the term is used (max 1 for each doc)
t
type of the term, 0:connected, 1: category, 2:related
alt
alternative lables (not yet implemented)
o
occurrences of the term. that is how many times the term appears in the dataset
label
the term itself
uri
identifier of the term

[
  {
    "w":202,                    
    "t":1,                      
    "alt":[],					
    "o":219,                    
    "label":"Requirement",      
    "uri":"u0"                  
  }, ...
]
categories http://tyk.li/rs/v0/categories
method:post
DESCRIPTION

Get the list of categories

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
compact Retrieve only the ids of requested item and not all the informations bool false
limit Maximum number of tags that should be given back in the reply int -1
REQUEST

token=fsahiosudhfh9h
&compact=false
&limit=50
RETURN

[
  {
    "w":202,
    "t":1,
    "alt":[],
    "o":219,
    "label":"Requirement",
    "uri":"u0"
  }, ...
]
linked http://tyk.li/rs/v0/linked
method:post
DESCRIPTION

Get the terms linked

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
turis Comma seprated list of tag identifiers, without any spaces, or empty string -
REQUEST

token=fsahiosudhfh9h
&turis=u140,t710
RETURN

Get the categories and tags linked or connected to the terms requested in AND

[
  {
    "w":202,
    "t":1,  
    "alt":[],
    "o":219,
    "label":"Requirement",
    "uri":"u0"
  }, ...
]
related http://tyk.li/rs/v0/related
method:post
DESCRIPTION

Get the related terms. Related terms are those terms automatically connectected by tyk tecnology

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
turis Comma seprated list of tag identifiers, without any spaces, or empty string -
compact Retrieve only the ids of requested item and not all the informations bool false
limit Maximum number of tags that should be given back in the reply int -1
REQUEST

token=fsahiosudhfh9h
&turis=u140,t710
&compact=false
&limit=50
RETURN

Get the related terms in AND

[
  {
    "w":202,
    "alt":[],
    "o":219,
    "label":"Requirement",
    "uri":"u0"
  }, ...
]
connected http://tyk.li/rs/v0/connected
method:get
DESCRIPTION

Get the connected terms. Connected terms are those terms that where connected in the original data

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
turis Comma seprated list of tag identifiers, without any spaces, or empty string -
compact Retrieve only the ids of requested item and not all the informations bool false
limit Maximum number of tags that should be given back in the reply int -1
REQUEST

token=fsahiosudhfh9h
&turis=u140,t710
&compact=false
&limit=50
RETURN

Get the the connected terms in AND

[
  {
    "w":202,
    "alt":[],
    "o":219,
    "label":"Requirement",
    "uri":"u0"
  }, ...
]
search http://tyk.li/rs/v0/search
method:get
DESCRIPTION

Search for a term in an autocomplete fashion

PARAMETERS
Name Meaning Type Default Required
token Your API key string - yes
query Text to search in from terms labels string - yes
REQUEST

token=fsahiosudhfh9h
&query=art
RETURN

[
  {
    "value":"u102",
    "label":"Arts & Entertainment"
  }, ...
]

Miscellanea

Error Codes

While working with the api, it can happen that you will receive some error codes, here there are some exaplanations.

In addition to the http code there the services return a json object with some more information. This information can be useful to find out more details about the error.

This is a sample error reply:

{
    "status" : 1,
    "message" : "some message"
}		  	   

Here there is a list of the more common errors, with code and meaning.

Http Code Status Code Meaning
401 1 or 5 The token (apy key) was not provided or was not recognized
401 2 dataset was disabled (contact us directly to know why)
401 3 dataset availability has expired (contact us directly to know why)
401 4 invalid request source for this dataset, it means that the caller of the service is not allowed to browse the dataset
204 7 or 8 generic application error
400 6 malformed request, means that there are missing or wrong parameters