Basic Usage

GenderAPI lets you determine the gender of a person using different types of input data. You can analyze first names directly, or extract names from email addresses and usernames. Here’s how you can start:

1. Gender from Name

Send a first name to the following endpoint: 

https://api.genderapi.io/api

Example: 

curl "https://api.genderapi.io/api?name=Alice&key=YOUR_API_KEY"

You can also add optional parameters:

  • country: Pass a two-letter country code ( ISO 3166-1 alpha-2 ) to improve prediction accuracy. For example: country=TR for Turkey.
  • askToAI: If set to true, the API will ask an AI model to determine the gender when the name cannot be found in the database.
  • forceToGenderize: If set to true, the API will attempt to guess a gender even for inputs that do not look like real human names, such as nicknames or fantasy names like sparkling unicorn or mystic warrior. This can be useful for analyzing usernames, but results may be less accurate. Note: This parameter is not available in the email endpoint.

Example with parameters: 

curl "https://api.genderapi.io/api?name=sparkling%20unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

2. Gender from Email Address

Use this endpoint if you only have an email address: 

https://api.genderapi.io/api/email

Example: 

curl "https://api.genderapi.io/api/email?email=alice.smith@example.com&country=TR&askToAI=true&key=YOUR_API_KEY"

Note: The forceToGenderize parameter is not available for the email endpoint because this endpoint first extracts the name internally.


3. Gender from Username

For usernames or nicknames, use: 

https://api.genderapi.io/api/username

Example: 

curl "https://api.genderapi.io/api/username?username=sparkling_unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

The forceToGenderize parameter is especially useful here because usernames often contain non-name words or fantasy terms. It forces the API to attempt a gender prediction even if the input is not a typical human name.

All methods support single or bulk requests. For more details, check the specific sections in the left navigation menu.


✅ API Response

Example JSON response for all endpoints: 

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "michael.smith@example.com",
  "name": "Michael",
  "gender": "male",
  "country": "US",
  "total_names": 325,
  "probability": 98,
  "duration": "4ms"
}

Response Fields

Field Type Description
status Boolean true if the request was successful. Check errors if false.
used_credits Integer Number of credits used for this request.
remaining_credits Integer Remaining credits available in your account after this request.
expires Integer (timestamp) Package expiration date as a UNIX timestamp (seconds).
q String Your input query (name, email, or username).
name String The found or extracted first name.
gender Enum[String] Predicted gender. Possible values: male, female, or null.
country Enum[String] The most likely country code (e.g. US, DE).
total_names Integer Number of samples used behind the prediction.
probability Integer Likelihood percentage of the gender prediction (e.g. 50-100).
duration String Processing time for the request (e.g. 4ms).
Warning: If your input values include spaces or special characters (e.g. sparkling unicorn), always URL-encode them before making GET requests. Otherwise, the request might fail or other parameters could be misinterpreted by your programming language or HTTP library. 
curl "https://api.genderapi.io/api?name=sparkling unicorn&key=YOUR_API_KEY"
you should use: 
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&key=YOUR_API_KEY"
Or apply proper URL-encoding functions in your programming language.