Gender

Gender from a name

Pass a full name or a first name. Titles, punctuation and surnames are stripped before lookup; name in the response shows what was actually looked up.

get/api/v1/gender

Request

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

Query parameters

namestring required

The value to resolve.

countrystring

ISO-3166 alpha-2 code. Alpha-3 (ITA) and country names (Italy, Italia, Italien) are also accepted and converted, so a free-text CRM country field can be passed as it is. Narrows the lookup to one country, which matters for names that flip gender across borders: Andrea is male in Italy and female in Germany. Omit it and the answer is the worldwide aggregate.

localestring

A language tag such as de-DE, en_US or pt_BR.UTF-8, typically the browser's navigator.language or the Accept-Language header of your sign-up form. Its region becomes the country when country is not sent. A tag without a region (en, de) sets no country: a language alone does not say which country it is spoken in. country_source in the response tells you which one was used.

ipstring

The end user's IP address (IPv4 or IPv6), for example from your sign-up request. Its country is used when neither country nor a locale with a region is sent. Private and reserved ranges are ignored. The address is used for this lookup only and is not stored. IP geolocation by DB-IP (db-ip.com), CC BY 4.0.

ai_fallbackboolean

Ask a language model when the dataset has no answer. Slower and less certain; the response reports source: "llm" so you can tell these apart. Requires AI lookups to be enabled in account settings; otherwise the call fails with ai_consent_required.

best_guessboolean

Return the most likely gender even below the confidence threshold, instead of null. Check probability before trusting the result.

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.