Endpoints

Request objects

Each endpoint listed above has different parameters. There are three parameters that are globally used. These are your API key, the response type and the gender type.

Response objects

The API returns JSON objects written in key/value pairs by default. (JSON Arrays is optional). The key is always a string and values are data types like: string, integer, boolean, array or null. If a boolean, integer or string is empty the value contains a null. If an array is empty we'll return an empty array. Each response object will have a structure like this:

{
    results: 1,
    error: null,
    data: []
}

The key 'results' is an integer that tells you how many result objects you can expect in the 'data' array. The 'error' key will (hopefully) always be null but if an error occurs it wil contain a description as a string and the data array will be empty. Additionally an appropriate status code will be returned.

Rate limits

To make sure our APIs are running as efficiently as possible we have rate limits. Depending on your subscription you can send a limited number of requests per hour. Payed subscriptions have a higher rate limit. The rate limit per day and per hour are a 'moving time window'. For each request we look back in time and count how many requests where made during that time window. The rate limit per month (for payed subscriptions) is a 'fixed window'.

The rate limit is applicable for all endpoints except for the account information endpoint. If you exceed the rate limit then the response will contain an error and status code 429 will be raised. Requests that result into an error responses (status code 4XX) will be excluded from rate limit calculations.

HTTP status codes

The API will always return the appropriate HTTP status codes for every request. When using the API you can get the status code from the HTTP headers. Each endpoint listed above has a code example showing how to use the status codes for error handling.

HTTP headers

The HTTP headers allow us to pass additional information with the response. An HTTP header consists of its case-insensitive name followed by a colon ':' and then by its value (without line breaks). The API passes the following additional information with each response using the custom headers (always start with X-).

Versioning

Unfortunately REST does not provide for any specific versioning guidelines. Our API is using custom HTTP headers for versioning (X-API-Version and X-Database-Version). The version number of our API uses the format major.minor. So if the API version is 1.3 then the major version is 1 and the minor version is 3. Changes in minor versions have non-breaking changes, such as adding new endpoints or new response parameters. Changes in major versions can have breaking changes. You can the version number we return in the header to detect updates programmatically by including the version in your scripts.

If you're implementing our API and the current version is 1.3, then you can hard code this in your script. If the version is not 1.3 anymore then you can skip your logic and throw a exception. This way you can notify yourself if any changes occur.