Country hints for gender prediction: when and how to use them

The same first name can lean male in one country and female in another. If your users are spread across markets, a single global answer for names like Andrea or Jean will be wrong for a meaningful share of them. This post explains why that happens, how to pass a country hint to Finowl, and how to pick a sensible hint from the data you already have.

#Why names lean differently by country

Gender prediction from a name is a statistical estimate of how that name is typically used. Usage is cultural, and culture is local. A few well-known examples:

• Andrea is widely used as a male name in Italy and as a female name in many other countries, including the United States and Germany.
• Jean is a common male name in France and French-speaking regions, while in English-speaking countries it is mostly a female name.
• Kim is often a female given name in the United States and the UK, and is used as a male name in parts of Scandinavia.
• Nikita is a male name in Russia and much of Eastern Europe, and is more often a female name in India and in some English-speaking communities.

Without context, a prediction for these names blends usage across every country in the data. The global answer may lean one way, but it can easily be the wrong way for the person in front of you. A country hint narrows the question from "how is this name used?" to "how is this name used here?"

#Names that do not need a hint

Most names lean the same way everywhere. A hint will not change much for them, but it does not hurt either. That makes the simplest policy "send a country whenever you have a reasonable one," rather than trying to maintain a list of names that need it.

#How to pass a country hint

The country field is optional on name lookups and on batch items. It takes an ISO 3166-1 alpha-2 code: two letters, any case. Finowl accepts all 249 assigned codes.

#Single lookup

curl -X POST https://api.finowl.co/v1/gender/name \
  -H "Authorization: Bearer $FINOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Andrea Rossi", "country": "IT" }'

The response echoes the country it used, alongside the prediction:

{
  "data": {
    "result_status": "identified",
    "gender": "male",
    "confidence": 0.97,
    "confidence_kind": "observed_frequency",
    "sample_count": 1840,
    "name": "andrea",
    "country": "IT",
    "source": "dataset",
    "reason": null
  }
}

The numbers above are illustrative; your real response carries the actual confidence and sample count. Always read country in the response during testing so you can confirm the hint was applied.

#Common code mistakes

• Use GB for the United Kingdom. UK is not an ISO 3166-1 alpha-2 code.
• Do not send three-letter codes (USA) or country names ("Germany").
• Do not send language codes. en is a language; US, GB and AU are countries.
• If you do not know the country, omit the field instead of sending an empty string or a placeholder.

An invalid value is rejected with 400 and code invalid_input. Rejected requests run no lookup and are free, but in a batch, validation is all-or-nothing, so one bad code fails the whole request. Validate codes before you send them.

#Choosing the right hint

You rarely have a field called "country of name origin," and you should not try to guess one. The goal is a reasonable proxy for where the person lives or which market they belong to. In rough order of reliability:

#1. Billing or account country

If a user has entered a billing address or picked a country during signup, use it. It is something they told you directly, and it is usually already stored as an ISO code.

#2. Profile or shipping country

For marketplaces and commerce products, a shipping or profile country is a close second.

#3. Browser or app locale

A locale such as de-DE or pt-BR contains a region subtag. Take the part after the hyphen and uppercase it. Locales without a region, such as plain fr, do not tell you a country, so skip the hint.

function countryFromLocale(locale) {
  // "pt-BR" -> "BR", "en_GB" -> "GB", "fr" -> null
  const match = /^[a-z]{2,3}[-_]([a-z]{2})\b/i.exec(locale || "");
  return match ? match[1].toUpperCase() : null;
}

#4. Your market, as a default

If your product only operates in one country, that country is a fine default for everyone.

#What to avoid

Do not infer a country from the name itself, from someone's appearance, or from anything that amounts to guessing ethnicity. That is both unreliable and inappropriate. If none of the signals above are available, leave country out and accept the global estimate, including the possibility of an unknown result.

#Country hints in batch enrichment

When enriching a contact list, set country per item. The batch endpoint accepts 1 to 50 items per request, each with a unique id.

import os
import requests

contacts = [
    {"id": "c1", "name": "Andrea Rossi", "country": "IT"},
    {"id": "c2", "name": "Andrea Schmidt", "country": "DE"},
    {"id": "c3", "name": "Jean Dupont", "country": "FR"},
    {"id": "c4", "name": "Nikita Ivanov", "country": "RU"},
    {"id": "c5", "name": "Kim Larsen", "country": None},
]

items = []
for c in contacts:
    item = {"id": c["id"], "type": "name", "value": c["name"]}
    if c["country"]:
        item["country"] = c["country"]
    items.append(item)

res = requests.post(
    "https://api.finowl.co/v1/gender/batch",
    headers={"Authorization": f"Bearer {os.environ['FINOWL_API_KEY']}"},
    json={"items": items},
    timeout=30,
)
res.raise_for_status()

for row in res.json()["data"]:
    if "error" in row:
        print(row["id"], "error", row["error"]["code"])
        continue
    d = row["data"]
    print(row["id"], d["result_status"], d["gender"], d["confidence"], d["country"])

A few batch details worth knowing:

• Results come back in the same order as your items, with both index and id, so match on id.
• A 200 response can still contain per-item errors. Check each row for an error object.
• Each row reports charged_credits, so you can reconcile cost per contact.
• Batch items default to ai_mode: "off", meaning dataset answers only, unless you set options otherwise.
• A whole batch counts as one request against the 60-requests-per-minute rate limit.
• Never resend a whole batch after a partial failure. Retry only the items that failed, and only when it is safe to do so.

The batch gender enrichment guide walks through chunking and retries, and batch-enriching 100k contacts covers a full pipeline.

#Measuring the effect of hints

If you are adding hints to an existing pipeline, compare before and after on a sample. Useful things to watch:

• The share of results that are identified versus unknown.
• How often the predicted gender changes for names you know are country-sensitive.
• How often reason is ambiguous; hints can reduce ambiguity when a name's usage is clear within one country.

Each lookup costs 1 credit whether the result is identified or unknown, and every account gets 100 free credits per month, so a small test sample costs little. See pricing for larger volumes.

#Responsible use

A country hint makes predictions more relevant, but it does not change what they are: statistical estimates of how a name is typically used, which will be wrong for some people. Keep to these rules:

• Use results only for aggregate analytics and low-stakes personalization.
• Never use them for eligibility, pricing, access or decisions with significant effects.
• Let people state or correct their own gender, and prefer what they tell you.
• Mention gender lookups in your privacy notice, since names and countries are personal data.

For the fundamentals of how predictions are produced, read how gender prediction from names works. Product details are on the gender API page.

#Frequently asked questions

#Is the country parameter required?

No. country is optional. Without it, you get an estimate based on how the name is used across all the data, which is fine for names that lean the same way everywhere.

#What format does the country hint use?

An ISO 3166-1 alpha-2 code, such as US, IT or GB, in any case. Finowl accepts all 249 assigned codes. Invalid values return 400 with invalid_input.

#Does adding a country hint cost extra?

No. A name lookup costs 1 credit with or without a country hint. Only lookups that request AI, with ai_mode: "always" or forceToGenderize: true, cost 3 credits.

#Can I use a different country for each item in a batch?

Yes. Set country on each item individually, and leave it out for items where you have no reasonable hint.