API documentation

Perhaps you would like to check out these cool integrations before calling our APIs directly:

Endpoint

Every one of our APIs follows a general schema for requesting data. All the requests must be sent, either by GET or POST, to the API endpoint, which follows this structure:

For example, for accessing the Entity Extraction API method, the endpoint would be the following:

Authentication

Every request must be authenticated. Dandelion API implements authentication through a single token parameter which univocally identify the caller. Currently only one token is given to each user, but we plan to let you create more than one in the near future.

When calling any API, you must authenticate using this parameter:

Legacy app_id/app_key Authentication

We still support the legacy authentication scheme, which uses the pair (app-id, app-key). Show me more

Request size limit

We limited the size of each request to a maximum of 1MiB (therefore 1048576 bytes, just to avoid confusions). Unlikely you will need to submit larger requests, and if you do it's probably a symptom of misuse; maybe you should think of splitting your query in more requests?

Rate limit

Dandelion API has a rate limit of 50 calls per second per token (or $app_id/$app_key pair if you are still using the old authentication method). If you exceed the rate limit your request will be denied with the status code 429 and the error code error.RateLimitExceeded

Headers

Independently of the API you're using, Dandelion will give you some information using HTTP headers. Since each API has its own output structure, this allows you to access such information in a standard way, without customizing your code based on the API you are accessing. Such headers are:

Connection: keep-alive
Content-Length: 2748
Content-Type: application/json;charset=UTF-8
Date: Sat, 10 Oct 2015 16:29:37 GMT
Server: Apache-Coyote/1.1
X-DL-units: 1
X-DL-units-left: 999
X-DL-units-reset: 2015-10-22 00:00:00 +0000

Error codes

In case of errors, the response will contain an object with the following structure (other than having the status-code set as of the HTTP standard, of course):

{
  "message": "A human-readable error message, that suggests the cause of the error",
  "code": "A machine-readable error code, representing the type of error",
  "data": "An object containing useful metadata for programmatic use. May be empty",
  "error": "True, that's it",
}

For example, querying Dandelion API without specifying the text parameter you'll get:

{
  "message": "Parameter [text] not found",
  "code": "error.missingParameter",
  "data": {
    "parameter": "text"
  },
  "error": true
}

The possible error codes you could get are defined here.