Nationality from a name: what a name can and cannot tell you
One API call turns a first or last name into a ranked list of the countries it comes from, with a probability on each. It answers a question about the name — which is a different question from where the person lives, and a different question again from who they are.
The short answer
- You get a ranked list of up to 25 countries, each with a probability, an ISO code, a country name and, where the country has them on record, its continental and statistical region.
- The same response also carries the gender, the language of origin, the meaning of the name and its distribution across ethnic groups, drawn from a database covering 192 countries.
- It costs 2 credits per name — twice a plain gender lookup, because it is a heavier query. Credits are bought in advance and do not expire.
- It is a statistic about the name, not a claim about the person. Use it for salutations, aggregate analysis and data quality — not to decide anything about an individual.
Where does the number come from?
There is no model guessing here, and nothing is generated. The probability is arithmetic over records we actually hold, which is why the same name returns the same list today, next month and next year.
Two signals go in. The first is how the records for that name are spread across countries — a name we hold mostly from Poland leans Polish. The second is how large each of those populations is, which stops a small country with a well-sampled name from outranking a large one on volume alone. The two are averaged per country, anything under one percent is dropped, and what remains is sorted.
Because it is a distribution, a name common in two countries answers with two countries rather than picking a winner. That is the useful part: the shape of the list tells you how much to trust the top entry.
What comes back
One POST, one name, one response. The list below is shortened; the real one runs to the top 25 countries.
POST https://gender-api.com/v2/country-of-origin
{ "first_name": "Johann" }{
"result_found": true,
"first_name": "Johann",
"gender": "male",
"probability": 0.9,
"language_of_origin": "Germanic",
"meaning": "…",
"country_of_origin": [
{
"country_name": "Germany",
"country": "DE",
"probability": 0.52,
"continental_region": "Europe",
"statistical_region": "Western Europe"
},
{
"country_name": "Austria",
"country": "AT",
"probability": 0.48,
"continental_region": "Europe",
"statistical_region": "Western Europe"
}
],
"ethnicity": {
"id": "GERMANIC",
"name": "Germanic (German, Austrian, Swiss)",
"distribution": [ … ]
},
"details": { "credits_used": 2, "samples": 890, "duration": "414ms" }
}Note the two fields that make the answer auditable: samples tells you how many records the answer rests on, and credits_used confirms the two credits. A response with a low sample count is not hidden from you.
- continental_region and statistical_region let you roll the list up to a region without maintaining your own mapping.
- The response also contains a link to an interactive map of that name, which is a fast way to sanity-check a result by eye.
- Every field is documented in the v2 reference.
Origin is not residence
This is the single most common misreading, and it goes both ways. Two different fields, two different meanings, opposite directions of travel.
| Question | The country you send | The country you get back |
|---|---|---|
| Field | country, locale, ip |
country_of_origin |
| Means | Where the person is now | Where the name comes from |
| Changes the gender answer | Yes — Andrea is male in Italy and female in Germany | No — it is an output, not an input |
| You usually already know it | Yes — from the shipping address, the domain or the IP | No — this is the part you are buying |
| Credits | Free — a parameter, not a query | 2 per name |
What this is not
A name is evidence about a name. Treating it as evidence about a person is where this kind of data goes wrong, so it is worth being blunt about the limits before you build on it.
A person named Nguyen may have been born in Melbourne, and a person named Smith may never have set foot in an English-speaking country. The endpoint answers "where does this name come from", and that is the only question it answers.
- It is not a nationality, a citizenship or a birthplace, and it is not evidence of any of them.
- It is not an ethnicity of the person. The ethnic distribution describes how the name is spread across groups, which is a property of the name.
- It should not decide anything about an individual — not a price, not an application, not a risk score. Data pointing at ethnic origin is a special category under Article 9 of the GDPR, and that decision is yours as the controller, not ours.
- It is not a guess. Where we hold too little, result_found is false and the sample count says so, rather than a plausible country being invented to fill the field.
On our side: we are a German company, all servers are located in Germany, the data is processed inside the EU, and a data-processing agreement can be requested in your account. The full picture is on the privacy overview.
What people actually use it for
- Getting the salutation right. Knowing a name is Italian rather than German is what turns "Andrea" from the wrong greeting into the right one — and the gender lookup in the same response is the part that acts on it.
- Market and audience analysis in aggregate. Which language to translate a campaign into, which regions a mailing list actually reaches, where a customer base has grown.
- Data quality. A list where the origin distribution suddenly changes shape usually means an import went wrong, not that the audience moved.
- Research and demography, where a name-level distribution over a whole cohort is the unit of analysis and no individual conclusion is drawn.
- Transliteration and matching, where knowing the likely origin of a name narrows the plausible spellings of it.
Running it over a list
The batch form takes up to 100 names per request, with no ceiling on the number of requests. The payload is a bare JSON array.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- A full name or an e-mail address works instead of a first name — the name is extracted first, then the origin is resolved.
- Official clients for PHP, Python, Node, Java, Go, Ruby, Rust, Perl and .NET.
- For a one-off list rather than an integration, see bulk gender lookup — the same credits, no code.
- Every field, every error and an OpenAPI description: the v2 reference.
Frequently asked questions
Can you tell me a person's nationality from their name?
No, and no honest service can. What you get is where the name occurs and how strongly, ranked by country — a statistic about the name, not a fact about the person carrying it. Plenty of people carry a name whose origin is nowhere near where they were born.
What does the endpoint return?
A ranked list of up to 25 countries, each with a probability, an ISO country code, a country name and — where the country has them on record — its continental and statistical region. The same response also carries the gender, the language of origin, the meaning of the name and its distribution across ethnic groups.
How is the probability calculated?
From two signals: what share of the records we hold for that name come from each country, and how large each of those populations is. The two are averaged per country, countries at one percent or less are dropped, and the rest is sorted. Each value is a share of the whole rather than a score for that country on its own — so read them against each other. They will not add up to exactly 1: everything below one percent is left out, and so is anything past the twenty-fifth country.
What does a country-of-origin lookup cost?
Two credits per name, because it is a heavier query than a plain gender lookup. Credits start at €0.35 per 1,000, are bought in advance, and do not expire.
Is this the same as the country parameter I send?
No — they are opposite directions. The country, locale or ip you send describes where the person is now and changes which gender comes back. The country of origin you get back describes where the name comes from and does not depend on where the person lives.
Can I run a whole list through it?
Yes. The batch variant takes up to 100 names per request with no ceiling on the number of requests, and the same endpoint answers a single name just as well.
Is inferring origin from a name lawful under the GDPR?
That depends on what you do with it, and it is your call as the controller, not ours. Data pointing at ethnic origin is a special category under Article 9, so using it to make decisions about individuals needs a legal basis you can show. Aggregate analysis and correct salutations are the ordinary uses. We are a German company, all servers are in Germany, and a data-processing agreement can be requested in your account.
TRY IT ON NAMES YOU ALREADY KNOW
100 free lookups a month, no credit card. Start with names whose origin you can check yourself — it is the fastest way to see what the distribution is telling you.
