Here you will find generic information about our APIs: how to authenticate, how to submit requests and interpret the responses, what error you could meet and why, and so forth. If you don't find something try looking in the specific documentation of the API you're using (our documentation HQ is a good starting point) or write in our support forum .
Perhaps you would like to check out these cool integrations before calling our APIs directly:
RubyEvery 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:
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:
We still support the legacy authentication scheme, which uses the pair (app-id, app-key). Show me more
When using this legacy mechanism, you must authenticate using both these parameters:
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?
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
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
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.
Error code | Description |
---|---|
error.notFound | The requested resource cannot be found. |
error.missingParameter | A required parameter is missing. |
error.unknownParameter | The request sent an unknown parameter. |
error.invalidParameter | One or more parameters have an invalid value. |
error.requestURITooLong | The URI of the submitted request was too long. This usually happens when calling the APIs using HTTP-GET; please use HTTP-POST for large requests. |
error.methodNotAllowed | You are using an HTTP method (GET/POST) for sending your request that is not allowed. |
error.requestTooLarge | The body of the submitted request was too large (the current limit is set to 1MiB, as described here). |
error.authenticationError | Your request is not allowed: this happens when no more units are available or when the authentication token is not correct (or legacy $app_id and $app_key are not valid). |
error.internalServerError | Something very wrong happened on our side. If this happens, we are probably already on it. |
error.badGateway | Some external resource needed to answer your query did not respond successfully. |
error.RateLimitExceeded | You exceeded the rate limit, the request has not been processed and no unit has been consumed. Please consider adding a delay when calling Dandelion API to meet the limit. |
Dandelion API
built with ❤ by SpazioDati S.r.l.
Company subject to management and coordination of Cerved Group S.p.A.
site privacy | api privacy | tos | cookies | consent preferences
We're a startup based in Italy, specialized in Semantics & Big Data.
Find out more about us at spaziodati.eu