Gender From Name API – Single Request Documentation

Request overview

Send one name per request

Submit a JSON object with a first name and authenticate with a Bearer token. Add a country code when regional naming patterns can improve the prediction.

MethodPOST

Content typeapplication/json

AuthenticationBearer token

Credit cost1 lookup

HDR

Required HTTP headers

Authorize the request

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

Keep the API key in server-side environment variables. See the authentication guide for credential safety.

JSON request body

Parameters

Parameter	Type	Requirement	Description
`name`	string	Required	First name to analyze. Use a clean name value without titles or prefixes.
`country`	string	Optional	ISO 3166-1 alpha-2 country code, such as US or TR, to add regional context.
`askToAI`	boolean	Optional	When true, use the AI fallback if the name is not found in the database.
`forceToGenderize`	boolean	Optional	When true, attempt a result for nicknames or inputs that do not resemble typical names.

About AI fallback

askToAI applies only when the database has no result. Forced predictions for unusual inputs can be less reliable, so treat probability as an important signal.

Code examples

Make a single request

These examples send the same request using Bearer authentication.

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Alice","country":"US","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "US", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "US", "askToAI": True}
)
print(response.json())

200 response

Prediction result

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "US",
  "total_names": 10234,
  "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 available after the request.
`expires`	integer	Package expiration time as a UNIX timestamp.
`q`	string	Original name submitted in the request.
`name`	string	Name analyzed by GenderAPI.
`gender`	string \| null	Predicted value: male, female or null.
`country`	string	Country code considered for the prediction.
`total_names`	integer	Number of samples supporting the prediction.
`probability`	integer	Prediction confidence as a percentage.
`duration`	string	Server processing time.

Send clean, correctly encoded input

Use a first name without titles or prefixes. JSON clients handle encoding automatically, but always validate external input before creating the request body.

Next guide

Analyze multiple names

Multiple name requestProcess several names in one request →AuthenticationReview API key security →