Gender

Gender from a username

Digits, separators and common suffixes are stripped before lookup.

post/api/v1/gender/username

Request

  • Base URL: https://namegender.com
  • URL: https://namegender.com/api/v1/gender/username
  • Auth: one of:
    • HTTP bearer
    • API key in header X-Api-Key

Request body

usernamestring required
countrystring
localestring
ipstring
ai_fallbackboolean
best_guessboolean

Response

Resolved. gender is null when the name is not recognised — that is a successful answer of "we do not know", not an error, and it still costs one credit.

credits_chargedinteger required

How many credits this call took from the balance: one per value resolved.

credits_remaininginteger required

Balance once this call is paid for: purchased credits plus whatever is left of today's free quota.

data_versionstring nullable

Name-dataset snapshot that produced the answer.

request_idstring nullable

Identifier of this call, also sent as the X-Request-Id header. Quote it in support requests.

country_source'country' | 'locale' | 'ip' | 'null' nullable

Where the country came from: the country parameter, the region of locale, the ip address, or none of them (null, worldwide answer).

querystring required

The input exactly as you sent it.

namestring nullable required

The first name actually looked up, after stripping titles and surnames.

first_namestring nullable

Given name parsed from the input. Present even when gender is null, and not charged separately. Titles and initials are never returned. For Chinese, Korean and Japanese script the surname comes first in the input and is returned in last_name.

middle_namestring nullable

Any further given names between the first name and the surname, for example "Fitzgerald" in "John Fitzgerald Kennedy". Initials are dropped.

last_namestring nullable

Surname parsed from the input, including particles such as "van" or "de la". "Smith, John" is read as surname first. With a Spanish-speaking country the last two words are both surnames (Pérez García). Always null for usernames, where a surname cannot be told apart from any other word.

name_type'personal' | 'organization' | 'role' | 'null' nullable

organization when the input carries a company marker (Acme LLC, Müller GmbH, Stanford University); role for shared mailboxes and placeholder accounts (info@, Customer Service, guest). Both return gender: null and no name parts. personal means no such marker was found; it does not confirm the input is a real name. null when the input is not a name at all.

gender'male' | 'female' | 'null' nullable required

null means the dataset has no confident answer. This is not an error.

probabilityinteger required

Share of people with this name who have the reported gender. 0 when unknown. Measured against held-out data, answers at 80+ come true about 95% of the time, so this number runs slightly conservative rather than optimistic.

sample_sizeinteger required

How many real people the answer is based on. A probability of 100 from a sample of 3 is weaker than 85 from a sample of 90,000 — read the two fields together. 0 means the source recorded proportions rather than counts.

countrystring nullable

The country the answer came from, when narrowed.

took_msinteger

Whole milliseconds spent resolving this value on our side; network time is not included.

source'db' | 'script' | 'fuzzy' | 'llm' | 'cache' | 'none' required

How the answer was reached. db exact match; script matched after transliterating a non-Latin script; fuzzy closest spelling; llm language model; none no answer. Use it to decide how much to trust a row.

confidence'high' | 'medium' | 'low' | 'unverified' | 'unknown'

Sample size bucket: high ≥100 people, medium ≥25, low ≥1, unverified when the source gave proportions instead of counts.

matched_asstring nullable

For fuzzy and script sources, the dictionary entry that was actually matched. Always inspect this before accepting a fuzzy result.

Example response

{
  "data_version": "2026.10",
  "took_ms": 1
}

Changes

No recorded changes to this operation across all 1 revision of this API.