Estimate the nationality of a first name

Nationalize.io estimates the nationality of a first name. Use the API for analytics, ad targeting, user segmenting etc.

The API is free, but limited at 1000 names/day. If you need more requests, you should check out store.nationalize.io.

All requests are sent to the following base URL using GET.

GET http://api.nationalize.io/

Single Usage

An example of looking up a single name could look like this.

GET https://api.nationalize.io/?name=jess

This would render a JSON response like the following. At most, the three most likely countries will be returned. It's possible that less or zero countries will be returned if the name doesn't exist for other countries in the dataset. A probability will also be returned, which will be a number between 0 and 1.

{
  "name": "jess",
  "countries": [
    { "country_id": "AU", "probability": 0.41 },
    { "country_id": "US", "probability": 0.26 },
    { "country_id": "GB", "probability": 0.19 }
  ]
}

Batch Usage

To request multiple names at a time, send along an array as the name parameter.

The API is limited to a maximum of 10 names per request

GET https://api.nationalize.io/?name[]=jess&name[]=klaus

Which would render a response like this.

[
  {
    "name": "jess",
    "countries": [
      { "country_id": "AU", "probability": 0.41 },
      { "country_id": "US", "probability": 0.26 },
      { "country_id": "GB", "probability": 0.19 }
    ]
  },
  {
    "name": "klaus",
    "countries": [
      { "country_id": "DK", "probability": 0.35 },
      { "country_id": "AT", "probability": 0.24 },
      { "country_id": "DE", "probability": 0.23 }
    ]
  }
]

Rate Limiting

If you need more than 1000 names/day you need to obtain an API key from store.nationalize.io. The key should be appended to every request like the following.

GET https://api.nationalize.io?name=peter&apikey={YOUR_API_KEY}

To keep track of the number of names you have left for a given time period, you should use the HTTP X-Rate headers returned in the response.

X-Rate-Limit-Limit: 1000 // The amount of names in the current time window
X-Rate-Limit-Remaining: 738 // The number of names left in the current time window
X-Rate-Reset: 13829 // Seconds remaining until a new time window opens

Responses and Errors

All responses will be in content-type: application/json; charset=utf-8

Here's a list of the errors the API can respond with. Some of them will only apply if you're using an API key.

401 - Unautherized
{ "error": "Invalid API key" }

402 - Payment Required
{ "error": "Subscription is not active" }

422 - Unprocessable Entity
{ "error": "Missing 'name' parameter" }

422 - Unprocessable Entity
{ "error": "Invalid 'name' parameter" }

429 - Too Many Requests
{ "error": "Request limit reached" }

429 - Too Many Requests
{ "error": "Request limit too low to process request" }

If the API is not able to determine any nationalities from a name, it will return an empty country array.

{"name":"hippopotamus","countries": []}