Documentation

Every technical detail you'll need to know

Overview

Genderize.io determines the gender of a first name. The gender is returned along with a certainty factor and a count that represents the number of data entries examined in order to calculate the response. You can use the cartainty factor along with the count to determine whether or not you want to trust the result.

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 or language. It's recommended to always use a filter if you have the needed data, since naming can rely heavily on demographics.


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

GET https://api.genderize.io/

Authentication

To authenticate yourself to the API you will need to append an API key parameter to your request. If you don't have an API key yet, then simpy head to the sign up page and create an account.

GET https://api.genderize.io/?apikey=your-api-key

Every following example in this documentation needs an API key appended.

Single usage


An example of genderizing a single name could look like this.

GET https://api.genderize.io/?name=peter

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: "peter",
	gender: "male",
	probability: "1.00",
	count: 1388
}

Batch usage


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

The API is limited to accept 10 names per request.

GET https://api.genderize.io/?name[]=peter&name[]=lois&name[]=stevie

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: "peter",
	gender: "male",
	probability: "1.00",
	count: 1388
},
{	
	name: "lois",
	gender: "female",
	probability: "0.94",
	count: 70
},
{ 
	name: "stevie",
	gender: "male",
	probability: "0.63",
	count: 39
}

Localization


The endpoint accepts two optional localization parameters.

  • country_id string Adds a filter with the following country ID - optional
  • language_id string Adds a filter with the following language ID - optional

When using one of those paramters on a batch request, the filter will be applied to all names.

An example could look like this.

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

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

{
	name: "kim",
	gender: "female",
	probability: "0.90",
	count: 687
}

{
	name: "kim",
	gender: "male",
	probability: "1.00",
	count: 17,
	country_id: "dk"
}

The API follows ISO 3166-1 for country codes and ISO 639-1 for language codes.

Rate Limiting


To keep track of your remaining names for a given subscription period, you should use the X-Rate headers in the API response.

X-Rate-Limit-Limit: 100000 // The amount of names in the current subscription period
X-Rate-Limit-Remaining: 1398 // The number of names left in the current subscription period
X-Rate-Reset: 13829 // Seconds remaining until a new subscription period starts

Responses and Errors


Following is a list of HTTP status codes used by the API.

200 - OK
{ 
	data: ...
}

400 - Bad Request
{ 
	status: "error",
	code: 400,
	message: "here's your problem, dude!" 
}

401 - Unauthorized
{
	status: "error",
	code: 401,
	message: "No or invalid API key provided"
}

402 - Payment Required
{
	status: "error",
	code: 402,
	message: "No active subscription for the given API key"
}

429 - Too Many Requests
{ 
	status: "error",
	code: 429,
	message: "you need to slow down!" 
}

500 - Internal Server Error
{ 
	status: "error",
	code: 500,
	message: "sorry, my bad!" 
}

Comments

comments powered by Disqus