Introduction

Our blazing fast RESTful API returns JSON objects that easily integrate into any new or existing platform. For each endpoint listed below we have extensive documentation and code examples for PHP, Python, Javascript and C#.

To use our API you need to create an account. After you login to your dashboard you will find your API key. The API key gives you access to the following endpoints:

Endpoints

Endpoint Description
Account Use this endpoint if you want to programmatically get access your account details and rate limits. This endpoint used by default if you don't specify an endpoint.
Parse This endpoint parses a complete name and returns the first name, middle names and last name. Additionally the result object also contains a persons gender, nationality, title and salutation.
Gender This endpoint returns the gender for any given first name. Get access to our high quality database with 1.597.154 first names originating from 104 countries categorized by gender.
Generate This endpoint generates a random, fictional complete name by combining a random first name and a random last name for any given country code.
Validate This endpoint checks if a given name exists, is not misspelled and if it is not fake by comparing it with existing famous, fictional and humorous names.
Extract This endpoint extracts complete names of persons from any text. By using millions of first and last names we can extract names with an extremely high precision and accuracy.

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.

Code Text Description
200 OK Success!
400 Bad Request The server could not understand the request due to invalid syntax.
401 Unauthorized The given API key does not exist, is disabled or is not valid.
403 Forbidden The request is missing the API key.
404 Not Found No name could be found in the request.
410 Gone The given endpoint is unknown or does not exist anymore.
429 Too Many Requests The rate limit per hour, day or month is reached.
500 Internal Server Error Something is broken.
502 Bad Gateway Our service is down, or being upgraded.
503 Service Unavailable The servers are up but overloaded with requests.

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-).

Header Description
X-API-Version: Our API can be updated without notice. This header returns the version of the live API. Use this field to detect updates programmatically. Changes can be found in our changelog.
X-Database-Version: Our name database can be updated without notice. This header returns the version of the live database. Use this field to detect updates programmatically. Changes can be found in our changelog.
X-Execution-Time: Time in milliseconds (ms) it took to execute the request. Use this to track performance of our API. This header will always be returned.
X-Requests-Remaining-Hour: Number of requests that you can still do in this hour. The rate limit per hour is a moving time window. It looks back an hour and counts the number of requests in that period. This header will always be returned.
X-Requests-Remaining-Day: Number of requests that you can still do during this 24 hour time window. The rate limit per day is a moving time window. It looks back 24 hours and count the number of requests in that period. This header will only be returned if you don't have a payed subscription.
X-Requests-Remaining-Month: Number of requests that you can still do during the current month. This header will only be returned if you have a payed subscription.

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.