genderize.io

Determine the gender of a first name

Genderize.io determines the gender of a first name. Use the API for analytics, ad targeting, user segmenting etc. It utilizes big datasets of information, from user profiles across major social networks and exposes this data through its API. The response includes a certainty factor as well.

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.

At the moment, the database contains 86710 distinct names across 74 countries and 81 languages.

The API is free, but limited at 250 requests/hour. If you need more requests or you want to buy the data outright, you should feel free to get in contact.

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

GET http://api.genderize.io

Single Usage

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

GET http://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":"0.99","count":796}

Multiple Usage

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

GET http://api.genderize.io?name[0]=peter&name[1]=lois&name[2]=stevie

Which would render a response like this.

[
  {"name":"peter","gender":"male","probability":"1.00","count":796},
  {"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

Both parameters are availible both when genderizing a single or multiple names.

An example could look like this.

GET http://api.genderize.io?name=kim
GET http://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 alpha-2 for country codes and ISO 639-1 for language codes.

Responses and Errors

The API uses four types of HTTP status codes. All responses will be in content-type: application/json; charset=utf-8

200 - OK
{ "DATA" }

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

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

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

If the API is not able to determine the gender from a name, it will return the gender with a value of null. You can then check for null values and handle the errors as you like.

{"name":"hippopotamus","gender":"null"}

Extensions

Ruby

Python

  • gender.py - by Brian Smith  github.com/block8437/gender.py

  • A simple python library to take first names and return their gender using the genderize.io API.

Follow along

Genderize is literally improving by the minute. Besides that, i am working to add more data and functionality to the API. Common age, geographical estimates, ethnicity? Things are in the working. Sign up and i'll send you a mail whenever i do major updates.

To get in contact, please use info@genderize.io or the comment thread below.


*The email will NOT be used for anything else.

Comments

comments powered by Disqus