Overview

Requests are GET. Responses are JSON. There is one endpoint:

https://api.genderize.io

Every successful response includes a gender, a probability, and the count of data points behind the prediction. The same API key works for all three Demografix services — Genderize, Agify, and Nationalize.

Basic usage

Pass a name query parameter. The response contains the predicted gender and confidence.

curl "https://api.genderize.io?name=peter"

import requests

response = requests.get("https://api.genderize.io", params={"name": "peter"})
print(response.json())

const response = await fetch("https://api.genderize.io?name=peter");
const data = await response.json();
console.log(data);

$response = file_get_contents("https://api.genderize.io?name=peter");
echo $response;

require "net/http"
require "json"

response = Net::HTTP.get(URI("https://api.genderize.io?name=peter"))
puts JSON.parse(response)

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://api.genderize.io?name=peter")
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

{
  "name": "peter",
  "gender": "male",
  "probability": 1.0,
  "count": 1346866
}

Field	Type	Description
`name`	string	The name as it was processed by the API.
`gender`	string	"male" or "female". null when no prediction can be made.
`probability`	number	Confidence ratio between 0 and 1. The share of data points matching the predicted gender.
`count`	integer	Data points the prediction was based on.

A first name produces the most accurate prediction. Full names are accepted and parsed — see Input fallbacks.

Authentication

Log in to get your API key, then pass it as an apikey query parameter:

curl "https://api.genderize.io?name=peter&apikey=YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.genderize.io",
    params={"name": "peter", "apikey": "YOUR_API_KEY"},
)
print(response.json())

const url = new URL("https://api.genderize.io");
url.searchParams.set("name", "peter");
url.searchParams.set("apikey", "YOUR_API_KEY");

const response = await fetch(url);
console.log(await response.json());

$response = file_get_contents(
    "https://api.genderize.io?name=peter&apikey=YOUR_API_KEY"
);
echo $response;

require "net/http"
require "json"

uri = URI("https://api.genderize.io")
uri.query = URI.encode_www_form(name: "peter", apikey: "YOUR_API_KEY")
puts JSON.parse(Net::HTTP.get(uri))

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://api.genderize.io?name=peter&apikey=YOUR_API_KEY")
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Localization

The gender associated with a name varies by country — Andrea skews male in Italy and female in most other places. Pass country_id to scope the prediction to a specific country. The value is a two-letter ISO 3166-1 alpha-2 code.

curl "https://api.genderize.io?name=kim&country_id=US"

import requests

response = requests.get(
    "https://api.genderize.io",
    params={"name": "kim", "country_id": "US"},
)
print(response.json())

const url = new URL("https://api.genderize.io");
url.searchParams.set("name", "kim");
url.searchParams.set("country_id", "US");

const response = await fetch(url);
console.log(await response.json());

$response = file_get_contents(
    "https://api.genderize.io?name=kim&country_id=US"
);
echo $response;

require "net/http"
require "json"

uri = URI("https://api.genderize.io")
uri.query = URI.encode_www_form(name: "kim", country_id: "US")
puts JSON.parse(Net::HTTP.get(uri))

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    resp, _ := http.Get("https://api.genderize.io?name=kim&country_id=US")
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

{
  "name": "kim",
  "gender": "female",
  "probability": 0.94,
  "count": 62805,
  "country_id": "US"
}

The response echoes country_id when localization is applied. Without country_id, the API uses the global frequency model. In a batch request, country_id applies to every name in the batch.

Batch usage

Send up to 10 names per request using repeated name[] parameters. The response is an array in the same order as the input.

curl "https://api.genderize.io?name[]=peter&name[]=lois&name[]=stewie"

import requests

response = requests.get(
    "https://api.genderize.io",
    params={"name[]": ["peter", "lois", "stewie"]},
)
print(response.json())

const params = new URLSearchParams();
["peter", "lois", "stewie"].forEach(n => params.append("name[]", n));

const response = await fetch(`https://api.genderize.io?${params}`);
console.log(await response.json());

$query = http_build_query(["name" => ["peter", "lois", "stewie"]]);
$response = file_get_contents("https://api.genderize.io?$query");
echo $response;

require "net/http"
require "json"

uri = URI("https://api.genderize.io")
uri.query = URI.encode_www_form("name[]" => ["peter", "lois", "stewie"])
puts JSON.parse(Net::HTTP.get(uri))

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
)

func main() {
    q := url.Values{}
    for _, n := range []string{"peter", "lois", "stewie"} {
        q.Add("name[]", n)
    }
    resp, _ := http.Get("https://api.genderize.io?" + q.Encode())
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

[
  { "name": "peter",  "gender": "male",   "probability": 1.0,  "count": 1346866 },
  { "name": "lois",   "gender": "female", "probability": 0.96, "count": 57781   },
  { "name": "stewie", "gender": "male",   "probability": 0.94, "count": 592     }
]

Each name in the batch counts toward your quota. A batch of 10 names consumes 10 from your monthly allowance.

Input fallbacks

The API tries three lookups in order before giving up on a name:

Direct match. The input is looked up as-is.
Diacritic-stripped match. If the direct match fails, diacritics are removed and the lookup is retried. José falls back to Jose.
First-name extraction. If a row contains a multi-word string — for example, a full-name field from a CRM export — the parser extracts what looks like the first name and retries. Sarah Johnson falls back to Sarah.

Responses and errors

Success

200 OK returns a single JSON object for single-name requests, or an array for batch requests. Field shapes are documented under Basic usage.

Rate-limit headers

Every response — success or error — includes the current rate-limit state:

`X-Rate-Limit-Limit`	Total names allowed in the current window.
`X-Rate-Limit-Remaining`	Names remaining in the current window.
`X-Rate-Limit-Reset`	Seconds until the window resets.

Errors

Errors return JSON with an error field and an appropriate HTTP status code.

Status	Error	Cause
401	`Invalid API key`	The key was not recognized.
402	`Subscription is not active`	The subscription tied to the key is paused, expired, or unpaid.
422	`Missing 'name' parameter`	No name was sent.
422	`Invalid 'name' parameter`	The name value is empty, too long, or otherwise malformed.
429	`Request limit reached`	The monthly quota or per-IP limit is exhausted.
429	`Request too low to process`	The request was throttled. Retry after a short delay.

{
  "error": "Invalid API key"
}

API reference