Basic usage
Make your first Gender API request
Send one input value and receive the predicted gender, probability, country and usage information. Start with a name, then use the dedicated email or username endpoint when that is the data you have.
Add your API key with the key query parameter. Keep production keys on your server—never expose a private key in browser code or a public repository.
Gender from name
First name or full name
Use the base endpoint when your input is a first name or full name.
https://api.genderapi.io/apicurl "https://api.genderapi.io/api?name=Alice&key=YOUR_API_KEY"Optional parameters
| Parameter | Type | Description |
|---|---|---|
country | string | Two-letter country code such as TR or US. |
askToAI | boolean | When true, asks the AI fallback if the name is not found in the database. |
forceToGenderize | boolean | Attempts a prediction for unusual inputs that may not look like human names. |
Gender from email
Email address
The email endpoint extracts a likely name from the address before performing gender detection.
https://api.genderapi.io/api/emailcurl "https://api.genderapi.io/api/email?email=alice.smith%40example.com&country=TR&askToAI=true&key=YOUR_API_KEY"forceToGenderize is not available for this endpoint because the name is extracted internally.Gender from username
Social username
Use this endpoint for usernames, handles and nicknames that may contain a recognizable name.
https://api.genderapi.io/api/usernamecurl "https://api.genderapi.io/api/username?username=sparkling_unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"JSON response
Understand the GenderAPI response
All three endpoints use the same core response structure.
{
"status": true,
"used_credits": 1,
"remaining_credits": 4999,
"expires": 1743659200,
"q": "Alice",
"name": "alice",
"gender": "female",
"country": "US",
"total_names": 325,
"probability": 98,
"duration": "4ms"
}Response fields
| Field | Type | Description |
|---|---|---|
status | boolean | Whether the request completed successfully. |
used_credits | integer | Credits consumed by this request. |
remaining_credits | integer | Credits remaining after the request. |
expires | integer | Package expiration time as a UNIX timestamp. |
q | string | The original name, email or username query. |
name | string | The normalized or extracted first name. |
gender | string | null | Predicted gender: male, female or null. |
country | string | Most likely ISO 3166-1 alpha-2 country code. |
total_names | integer | Number of name records behind the prediction. |
probability | integer | Prediction confidence as a percentage. |
duration | string | Server processing time for the request. |
Always URL-encode input values
Spaces and special characters must be encoded by your HTTP client. For example, use sparkling%20unicorn instead of a raw space.
Continue building