Support

API documentation

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 .

Calling our APIs

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:

https://api.dandelion.eu/api/product/method path/api-version

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

https://api.dandelion.eu/datatxt/nex/v1
Did you know?
For security reasons we allow only https requests to our APIs. You will not be able to connect to our APIs through http and you will never be.
Hint: Keep-alive
If you need to send many requests to the server api, it is suggested to use keep-alive to avoid the connection overhead. To know how to enable it, please refer to your http client documentation (eg: python-requests, ruby, php).

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:

token required
An alphanumeric key associated to your profile, which can be found here.

Legacy app_id/app_key Authentication

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

Did you know?
Your old authentication pair will be replaced with the new token parameter the first time you'll refurbish your key from your profile dashboard.

When using this legacy mechanism, you must authenticate using both these parameters:

$app_id deprecated
The alphanumeric id of the application you want to use to query Dandelion API. You can get yours here.
$app_key deprecated
The alphanumeric key associated to your application, which can be found here. You can see it as a kind of password for accessing the API.
Did you know?
The $ character is part of the parameter name, and must be escaped when calling the Dandelion API using a terminal (i.e. using curl in bash).

Request limits

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?

Did you know?
Each API may override this settings, please refer to its specific documentation to know more.

API response

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:

X-DL-units < integer >
The number of units used for the request. Each user has a limited number of units per given period of time, depending on their plan. See the Plans and Pricing page for more information.
X-DL-units-left < integer >
The number of units left until the next reset.
X-DL-units-reset < datetime >
Date and time, specified in ISO-8601, of the next reset of the user's units, always given in UTC.
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.

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.
SpazioDati Via A. Olivetti 13, 38122, Trento (TN) -


Dandelion API built with by

privacy | tos | cookies

Contact Us

@dandelionapi

Need more info or a custom project? Write us: hello@dandelion.eu

About Us

We're a startup based in Italy, specialized in Semantics & Big Data.
Find out more about us at spaziodati.eu