Estimate the age of a first name

Agify.io estimates the age of a person from their first name. It utilizes big datasets to find historic naming trends and estimates the most likely age of a person with that name today. Use the API for analytics, ad targeting, user segmenting etc.

To achieve more qualified guesses, it is also possible to use localization filters to retreive a guess based only on data for a certain country. It's recommended to always use a filter if you have the needed data, since the outcome can rely heavily on demographics.

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

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

GET http://api.agify.io/

Single Usage

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

GET https://api.agify.io/?name=michael

This would render a JSON response like the following. The count represents the number of data entries examined in order to calculate the response.

{"name": "michael", "age": 60, "count": 41938}

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.agify.io/?name[]=michael&name[]=matthew&name[]=jane

Which would render a response like this.

[
  {"name":"michael","age":"60","count":41938},
  {"name":"matthew","age":"36","count":13520},
  {"name":"jane","age":"66","count":1639}
]

Localization

The endpoint accepts an optional localization parameter.

  • country_id STRING Adds a filter with the following country ID

The parameter is available for both single and batch requests.

An example could look like this.

GET https://api.agify.io/?name=kim
GET https://api.agify.io/?name=michael&country_id=dk

The last response will now be calculated exclusively from danish profiles. The response would look like this.

{"name":"michael","age":"60","count":41938}
{"name":"michael","age":"51","count":419,"country_id":"dk"}

The API follows ISO 3166-1 alpha-2 for country codes

Rate Limiting

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

GET https://api.agify.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 the age from a name, it will return the age with a value of null. You can then check for null values and handle the errors as you like.

{"name":"hippopotamus","age":"null","count":0}