Nationalität aus einem Namen: was ein Name sagen kann und was nicht
Ein API-Aufruf macht aus einem Vor- oder Nachnamen eine sortierte Liste der Länder, aus denen er kommt, mit einer Wahrscheinlichkeit für jedes. Er beantwortet eine Frage über den Namen — und das ist eine andere Frage als die, wo die Person lebt, und noch einmal eine andere als die, wer sie ist.
Die kurze Antwort
- Du bekommst eine sortierte Liste von bis zu 25 Ländern, jedes mit einer Wahrscheinlichkeit, einem ISO-Code, einem Ländernamen und, sofern für das Land hinterlegt, seiner kontinentalen und statistischen Region.
- Dieselbe Antwort enthält außerdem das Geschlecht, die Herkunftssprache, die Bedeutung des Namens und seine Verteilung über ethnische Gruppen — aus einer Datenbank mit 192 Ländern.
- Es kostet 2 Credits pro Name — doppelt so viel wie eine reine Geschlechtsbestimmung, weil die Abfrage aufwendiger ist. Credits werden im Voraus gekauft und verfallen nicht.
- Es ist eine Statistik über den Namen, keine Aussage über die Person. Nutze es für Anreden, aggregierte Analysen und Datenqualität — nicht, um über einen einzelnen Menschen zu entscheiden.
Woher kommt die Zahl?
Hier rät kein Modell, und nichts wird generiert. Die Wahrscheinlichkeit ist Arithmetik über Datensätze, die wir tatsächlich haben — deshalb liefert derselbe Name heute, nächsten Monat und nächstes Jahr dieselbe Liste.
Zwei Signale gehen ein. Das erste ist, wie sich die Datensätze zu diesem Namen über die Länder verteilen — ein Name, den wir überwiegend aus Polen haben, tendiert polnisch. Das zweite ist, wie groß die jeweilige Bevölkerung ist; das verhindert, dass ein kleines Land mit einem gut belegten Namen ein großes allein über die Menge überholt. Beide werden pro Land gemittelt, alles unter einem Prozent fällt heraus, und der Rest wird sortiert.
Weil es eine Verteilung ist, antwortet ein Name, der in zwei Ländern häufig ist, mit zwei Ländern statt einen Sieger zu wählen. Genau das ist der nützliche Teil: die Form der Liste sagt dir, wie sehr du dem ersten Eintrag trauen kannst.
Was zurückkommt
Ein POST, ein Name, eine Antwort. Die Liste unten ist gekürzt; die echte reicht bis zu den 25 wahrscheinlichsten Ländern.
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" }
}Beachte die zwei Felder, die die Antwort prüfbar machen: samples sagt dir, auf wie vielen Datensätzen sie beruht, und credits_used bestätigt die zwei Credits. Eine Antwort mit wenigen Samples wird dir nicht verheimlicht.
- Mit continental_region und statistical_region kannst du die Liste auf Regionen zusammenfassen, ohne ein eigenes Mapping zu pflegen.
- Die Antwort enthält außerdem einen Link zu einer interaktiven Karte dieses Namens — der schnellste Weg, ein Ergebnis mit dem Auge zu prüfen.
- Jedes Feld ist in der v2-Referenz dokumentiert.
Herkunft ist nicht Wohnort
Das ist das häufigste Missverständnis, und es geht in beide Richtungen. Zwei verschiedene Felder, zwei verschiedene Bedeutungen, entgegengesetzte Richtungen.
| Frage | Das Land, das du sendest | Das Land, das du zurückbekommst |
|---|---|---|
| Feld | country, locale, ip |
country_of_origin |
| Bedeutet | Wo die Person jetzt ist | Woher der Name kommt |
| Ändert die Geschlechts-Antwort | Ja — Andrea ist in Italien männlich und in Deutschland weiblich | Nein — es ist eine Ausgabe, keine Eingabe |
| Du kennst es meistens schon | Ja — aus der Lieferadresse, der Domain oder der IP | Nein — genau das kaufst du hier |
| Credits | Kostenlos — ein Parameter, keine Abfrage | 2 pro Name |
Was es nicht ist
Ein Name ist ein Hinweis auf einen Namen. Ihn als Hinweis auf eine Person zu behandeln, ist der Punkt, an dem diese Art von Daten schiefgeht — deshalb lohnt es sich, die Grenzen deutlich zu sagen, bevor du darauf aufbaust.
Eine Person namens Nguyen kann in Melbourne geboren sein, und eine Person namens Smith war vielleicht nie in einem englischsprachigen Land. Der Endpoint beantwortet „woher kommt dieser Name“ — und das ist die einzige Frage, die er beantwortet.
- Es ist keine Nationalität, keine Staatsbürgerschaft und kein Geburtsort — und kein Beweis für irgendetwas davon.
- Es ist keine Ethnie der Person. Die ethnische Verteilung beschreibt, wie sich der Name über Gruppen verteilt — eine Eigenschaft des Namens.
- Es sollte nichts über eine einzelne Person entscheiden — keinen Preis, keine Bewerbung, keinen Risiko-Score. Daten, die auf ethnische Herkunft hindeuten, sind eine besondere Kategorie nach Artikel 9 der GDPR, und diese Entscheidung liegt bei dir als Verantwortlichem, nicht bei uns.
- Es ist keine Vermutung. Wo wir zu wenig haben, ist result_found false und die Anzahl der Samples sagt es — statt ein plausibles Land zu erfinden, um das Feld zu füllen.
Auf unserer Seite: wir sind ein deutsches Unternehmen, alle Server stehen in Deutschland, die Daten werden innerhalb der EU verarbeitet, und einen Auftragsverarbeitungsvertrag kannst du in deinem Konto anfordern. Das ganze Bild steht in der Datenschutz-Übersicht.
Wofür es tatsächlich genutzt wird
- Die richtige Anrede. Zu wissen, dass ein Name italienisch und nicht deutsch ist, macht aus „Andrea“ die richtige statt der falschen Begrüßung — und die Geschlechtsbestimmung in derselben Antwort ist der Teil, der es umsetzt.
- Markt- und Zielgruppenanalyse in der Summe. In welche Sprache eine Kampagne übersetzt werden soll, welche Regionen eine Mailingliste tatsächlich erreicht, wo ein Kundenstamm gewachsen ist.
- Datenqualität. Eine Liste, in der die Herkunftsverteilung plötzlich ihre Form ändert, heißt meist, dass ein Import schiefging — nicht, dass die Zielgruppe umgezogen ist.
- Forschung und Demografie, wo eine Verteilung auf Namensebene über eine ganze Kohorte die Analyseeinheit ist und kein Schluss auf Einzelpersonen gezogen wird.
- Transliteration und Abgleich, wo die wahrscheinliche Herkunft eines Namens die plausiblen Schreibweisen einschränkt.
Über eine ganze Liste laufen lassen
Die Batch-Form nimmt bis zu 100 Namen pro Request, ohne Obergrenze bei der Anzahl der Requests. Der Payload ist ein reines JSON-Array.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Statt eines Vornamens funktioniert auch ein vollständiger Name oder eine E-Mail-Adresse — der Name wird zuerst extrahiert, dann die Herkunft aufgelöst.
- Offizielle Clients für PHP, Python, Node, Java, Go, Ruby, Rust, Perl und .NET.
- Für eine einmalige Liste statt einer Integration siehe Massen-Geschlechtsbestimmung — dieselben Credits, kein Code.
- Jedes Feld, jeder Fehler und eine OpenAPI-Beschreibung: die v2-Referenz.
Häufige Fragen
Kannst du mir die Nationalität einer Person aus ihrem Namen sagen?
Nein, und kein ehrlicher Dienst kann das. Du bekommst, wo der Name vorkommt und wie stark, nach Ländern sortiert — eine Statistik über den Namen, keine Tatsache über die Person, die ihn trägt. Viele Menschen tragen einen Namen, dessen Herkunft nichts mit ihrem Geburtsort zu tun hat.
Was gibt der Endpoint zurück?
Eine sortierte Liste von bis zu 25 Ländern, jedes mit einer Wahrscheinlichkeit, einem ISO-Ländercode, einem Ländernamen und — sofern für das Land hinterlegt — seiner kontinentalen und statistischen Region. Dieselbe Antwort enthält außerdem das Geschlecht, die Herkunftssprache, die Bedeutung des Namens und seine Verteilung über ethnische Gruppen.
Wie wird die Wahrscheinlichkeit berechnet?
Aus zwei Signalen: welcher Anteil der Datensätze, die wir zu diesem Namen haben, aus welchem Land kommt, und wie groß die jeweilige Bevölkerung ist. Beide werden pro Land gemittelt, Länder mit einem Prozent oder weniger fallen heraus, der Rest wird sortiert. Jeder Wert ist ein Anteil am Ganzen und keine Bewertung des Landes für sich — lies sie also im Verhältnis zueinander. Sie ergeben nicht exakt 1: alles unter einem Prozent bleibt draußen, und alles ab dem fünfundzwanzigsten Land ebenfalls.
Was kostet eine Herkunftsland-Abfrage?
Zwei Credits pro Name, weil die Abfrage aufwendiger ist als eine reine Geschlechtsbestimmung. Credits beginnen bei €0.35 pro 1.000, werden im Voraus gekauft und verfallen nicht.
Ist das dasselbe wie der country-Parameter, den ich sende?
Nein — das sind entgegengesetzte Richtungen. Das country, locale oder ip, das du sendest, beschreibt, wo die Person jetzt ist, und ändert, welches Geschlecht zurückkommt. Das Herkunftsland, das du zurückbekommst, beschreibt, woher der Name kommt, und hängt nicht davon ab, wo die Person lebt.
Kann ich eine ganze Liste durchlaufen lassen?
Ja. Die Batch-Variante nimmt bis zu 100 Namen pro Request, ohne Obergrenze bei der Anzahl der Requests, und derselbe Endpoint beantwortet einen einzelnen Namen genauso gut.
Ist es nach der GDPR erlaubt, Herkunft aus einem Namen abzuleiten?
Das hängt davon ab, was du damit machst, und es ist deine Entscheidung als Verantwortlicher, nicht unsere. Daten, die auf ethnische Herkunft hindeuten, sind eine besondere Kategorie nach Artikel 9 — sie für Entscheidungen über einzelne Personen zu nutzen, braucht eine Rechtsgrundlage, die du belegen kannst. Aggregierte Analysen und korrekte Anreden sind die üblichen Anwendungen. Wir sind ein deutsches Unternehmen, alle Server stehen in Deutschland, und einen Auftragsverarbeitungsvertrag kannst du in deinem Konto anfordern.
PROBIERE ES MIT NAMEN, DIE DU SCHON KENNST
100 kostenlose Abfragen pro Monat, ohne Kreditkarte. Fang mit Namen an, deren Herkunft du selbst prüfen kannst — das ist der schnellste Weg zu sehen, was die Verteilung dir sagt.
API-Dokumentation · Eine ganze Liste verarbeiten · Eine Frage stellen
