CEPT API Documentation

Services

Generally, services generate JSON responses ('application/json') by default. XML responses ('application/xml') can be requested by appending the suffix '.xml' to the service path, e.g. /similarterms.xml. The 'Accept' request header field is intentionally ignored.

Query Language

The `similarterms` and `disambiguate` can be applied to simple terms, to text snippets (using single quotes) or to complex expressions by means of the CEPT query language. The CEPT query language allows to do calculations with words. for example to express a specific meaning of a multi-sense-word the AND operator can be used (e.g. "apple" AND "fruit" ) or to exclude a specific aspect of a multi-sense word the AND NOT oeprators e.g. "java" AND NOT "island". The following operators are supported: binary AND OR XOR SUB, unary NOT and n-ary merge. The operators can be combined to form complex queries. Input words must be quoted with double quotes and parantheses can be used to group expressions. expression evaluation is performed from left to right. a AND b AND C OR d gets evaluated as (((a AND b) and c) or d) Behind the scenes input words are translated into their bitmap representations on which the various operations are performed. AND,OR,XOR,SUB and NOT correspond to the bitwise operations. the merge functions calculates the most active overlaps of several words. As the merge function is a very useful one there existss a shortcut: instead of writing merge("a","b","c","d") you can put the text in singular quotes 'a b c d'.

Response Codes

The number of response status codes used by the CEPT API is kept to a minimum to keep the complexity low. The status codes actually used by the services are listed in their descriptions.

In case something goes wrong on the server side, we take full responsibility and code '500 Internal Server Error' is returned. Because the client application can't do anything about this kind of error, we are continuously monitoring the log files to spot such cases in order to fix them.

All error responses have a data structure in the response body that contains an error code and an error message. The error code replicates the HTTP status code and the error message states what the problem was. With the exception of error 415 (response format is always JSON), the format of the error response is either JSON or XML depending on what has been requested.

Sample Error Response in JSON
{
    "errorCode": 400,
    "errorMessage": "at least 'term1' or 'term2' must be specified"
}