Gender

Resolve many names in one request

Exists so that 100 names do not cost 100 HTTP round trips. Names are resolved in a single batch lookup. Credits are checked for the whole batch up front: either every name is processed or none is.

post/api/v1/gender/bulk

Request

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

Request body

namesstring[] required

The values to resolve, each at most 200 characters. Each one costs one credit.

countrystring

ISO-3166 alpha-2 code applied to every value in the batch. Alpha-3 and country names are also accepted.

localestring

Language tag whose region becomes the batch country when country is not sent, for example it-IT. A tag without a region sets no country.

ipstring

End user IP address whose country becomes the batch country when neither country nor a regional locale is sent. Not stored. IP geolocation by DB-IP (db-ip.com), CC BY 4.0.

type'name' | 'email' | 'username'

How to read the values in names.

ai_fallbackboolean

Ask a language model for values the dataset cannot answer. Requires AI lookups to be enabled in account settings; otherwise the batch fails with ai_consent_required.

best_guessboolean

Return the most likely gender even below the confidence threshold, instead of null. For email and username batches it applies to the extracted first name.

Example request

{
  "names": [
    "Ayşe",
    "Mehmet",
    "Andrea"
  ],
  "country": "TR"
}

Response

Every name resolved. Results are returned in the order they were sent.

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.

took_msinteger

Whole milliseconds spent resolving the batch on our side, network time excluded.

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).

Example response

{
  "data_version": "2026.10",
  "took_ms": 12,
  "results": [
    {
      "took_ms": 1
    }
  ]
}

Changes

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