# Nationality from a name: what a name can and cannot tell you Plain-Markdown twin of . Last reviewed 2026-09-01. Prices and the country count are rendered live on the HTML page; the figures quoted here were correct on that date. 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 - 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, drawn from a database covering 192 countries and 9,124,598 names. - 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 the number comes from No model guesses, and nothing is generated. The probability is arithmetic over records actually held, which is why the same name returns the same list today, next month and next year. Two signals go in: 1. **Share of records per country** — how the records held for that name are spread across countries. A name held mostly from Poland leans Polish. 2. **Population weighting** — how large each of those populations is. This stops a small country with a well-sampled name from outranking a large one on volume alone. The two are averaged per country, countries at 1% probability or less are dropped, and what remains is sorted. Each value is a share of the whole, not a score for that country on its own — read them against each other. They will **not** sum to exactly 1: everything at or below 1% is left out, and so is anything past the 25th country. A name spread thinly over many countries can return rows summing to well under 1, and that is not a confidence signal. Because it is a distribution, a name common in two countries answers with two countries rather than picking a winner. The shape of the list tells you how much to trust the top entry. ## What comes back ``` POST https://gender-api.com/v2/country-of-origin Authorization: Bearer Content-Type: application/json { "first_name": "Johann" } ``` ```json { "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" } } ``` The list above is shortened; the real one runs to the top 25 countries. Two fields make the answer auditable: `details.samples` tells you how many records the answer rests on, and `details.credits_used` confirms the two credits. A response resting on 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. Full field reference: ## Origin is not residence The most common misreading, and it goes both ways. | | 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 | Independent, and best used together: send the residence you know, read the origin you don't. ## 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. 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. - **Not a nationality, a citizenship or a birthplace**, and not evidence of any of them. - **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 a guess.** Where too little is held, `result_found` is `false` and the sample count says so, rather than a plausible country being invented to fill the field. On our side: a German company, all servers located in Germany, data processed inside the EU, and a data-processing agreement available on request in your account. Details: ## 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 whose 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 the likely origin narrows the plausible spellings of a name. ## 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, not an object with a `data` key. ``` 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, the same credits with no code: ## FAQ **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. **How is the probability calculated?** From the share of records held for that name per country, and how large each of those populations is. The two are averaged per country, countries at 1% or less are dropped, and the rest is sorted. Each value is a share of the whole rather than a standalone score, so read them against each other — they do not sum to exactly 1, because the sub-1% tail and anything past the 25th country are left out. **What does a lookup cost?** Two credits per name. Credits are bought in advance and do not expire. **Is this the same as the `country` parameter I send?** No — opposite directions. See "Origin is not residence" above. **Can I run a whole list through it?** Yes — up to 100 names per request, with no ceiling on the number of requests. **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. 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. ## Start 100 free lookups a month, no credit card: