Introduction
Our blazing fast RESTful API returns JSON objects that easily integrate into any new or existing project. 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.