Determine Gender by Username – Single Request

The Get Gender by Username endpoint allows you to determine a person’s gender by analyzing a username or nickname. All parameters must be sent as a JSON-formatted POST request. You need to authenticate the request using a Bearer token in the Authorization header.

Request URL

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

Required HTTP Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body Parameters

Parameter	Type	Required	Description
username	String	Yes	The username or nickname to be analyzed. This can be a social media handle, display name, or alias. May include non-real name terms like fantasy words or brand names.
country	String	No	Two-letter country code to improve prediction accuracy (ISO 3166-1 alpha-2). For example, use `TR` for Turkey.
askToAI	Boolean	No	If set to `true`, the API will request the AI model to predict gender for names not found in the database.
forceToGenderize	Boolean	No	If set to `true`, the API will attempt to predict gender even for usernames that do not resemble real human names (e.g., fantasy terms or nicknames like `sparkling_unicorn`).

Example Requests

cURL Example

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

PHP cURL Example

<?php
$url = "https://api.genderapi.io/api/username";

$data = array(
    "username" => "sparkling_unicorn",
    "country" => "US",
    "askToAI" => true,
    "forceToGenderize" => true
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization": "Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

JavaScript fetch Example

fetch("https://api.genderapi.io/api/username", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    username: "sparkling_unicorn",
    country: "US",
    askToAI: true,
    forceToGenderize: true
  })
})
.then(response => response.json())
.then(data => console.log(data));

Python requests Example

import requests

url = "https://api.genderapi.io/api/username"

payload = {
    "username": "sparkling_unicorn",
    "country": "US",
    "askToAI": True,
    "forceToGenderize": True
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Example JSON Response

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "sparkling_unicorn",
  "name": "Sparkling",
  "gender": "female",
  "country": "US",
  "total_names": 9876,
  "probability": 92,
  "duration": "6ms"
}

Response Fields

Field	Type	Description
status	Boolean	Indicates whether the request was successful.
used_credits	Integer	The number of credits used for this request.
remaining_credits	Integer	The number of credits remaining in your account after this request.
expires	Integer (timestamp)	The expiration date of your plan, as a UNIX timestamp.
q	String	The input query you submitted (username).
name	String	The name extracted from the username.
gender	Enum[String]	The predicted gender. Possible values: `male`, `female`, or `null`.
country	String	The country code considered during the prediction.
total_names	Integer	The number of name samples used for this prediction.
probability	Integer	The confidence score (in percentage) for the gender prediction.
duration	String	The time it took to process the request (e.g., `6ms`).