Nationalité à partir d'un nom : ce qu'un nom peut dire et ce qu'il ne peut pas
Un appel API transforme un prénom ou un nom de famille en une liste classée des pays d'où il vient, avec une probabilité sur chacun. Il répond à une question sur le nom — ce qui n'est pas la même question que le lieu où vit la personne, et encore moins la même que celle de qui elle est.
La réponse courte
- Tu obtiens une liste classée de 25 pays au maximum, chacun avec une probabilité, un code ISO, un nom de pays et, lorsque le pays les a en base, sa région continentale et statistique.
- La même réponse contient aussi le genre, la langue d'origine, la signification du nom et sa répartition entre groupes ethniques, à partir d'une base couvrant 192 pays.
- Cela coûte 2 credits par nom — le double d'une simple détermination de genre, parce que la requête est plus lourde. Les credits s'achètent à l'avance et n'expirent pas.
- C'est une statistique sur le nom, pas une affirmation sur la personne. Utilise-la pour les formules d'appel, l'analyse agrégée et la qualité des données — pas pour décider quoi que ce soit au sujet d'un individu.
D'où vient le chiffre ?
Aucun modèle ne devine ici, et rien n'est généré. La probabilité est de l'arithmétique sur des enregistrements que nous détenons réellement — c'est pourquoi le même nom renvoie la même liste aujourd'hui, le mois prochain et l'an prochain.
Deux signaux entrent en jeu. Le premier : comment les enregistrements de ce nom se répartissent entre les pays — un nom que nous détenons surtout depuis la Pologne penche polonais. Le second : la taille de chacune de ces populations, ce qui empêche un petit pays avec un nom bien échantillonné de dépasser un grand pays sur le seul volume. Les deux sont moyennés par pays, tout ce qui est sous un pour cent est écarté, et ce qui reste est trié.
Comme il s'agit d'une répartition, un nom courant dans deux pays répond avec deux pays au lieu de désigner un gagnant. C'est justement ce qui est utile : la forme de la liste te dit à quel point tu peux faire confiance à la première entrée.
Ce qui revient
Un POST, un nom, une réponse. La liste ci-dessous est raccourcie ; la vraie va jusqu'aux 25 pays les plus probables.
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 les deux champs qui rendent la réponse vérifiable : samples t'indique sur combien d'enregistrements elle repose, et credits_used confirme les deux credits. Une réponse fondée sur peu d'échantillons ne t'est pas cachée.
- continental_region et statistical_region te permettent de regrouper la liste par région sans maintenir ta propre table de correspondance.
- La réponse contient aussi un lien vers une carte interactive de ce nom — le moyen le plus rapide de vérifier un résultat à l'œil.
- Chaque champ est documenté dans la référence v2.
L'origine n'est pas la résidence
C'est le contresens le plus fréquent, et il va dans les deux sens. Deux champs différents, deux significations différentes, des directions opposées.
| Question | Le pays que tu envoies | Le pays que tu récupères |
|---|---|---|
| Domaine | country, locale, ip |
country_of_origin |
| Signifie | Où la personne est maintenant | D'où vient le nom |
| Change la réponse sur le genre | Oui — Andrea est masculin en Italie et féminin en Allemagne | Non — c'est une sortie, pas une entrée |
| Tu le connais déjà, en général | Oui — depuis l'adresse de livraison, le domaine ou l'IP | Non — c'est justement ce que tu achètes |
| Credits | Gratuit — un paramètre, pas une requête | 2 par nom |
Ce que ce n'est pas
Un nom est un indice sur un nom. Le traiter comme un indice sur une personne, c'est là que ce type de données déraille — autant être direct sur les limites avant de construire dessus.
Une personne nommée Nguyen peut être née à Melbourne, et une personne nommée Smith n'a peut-être jamais mis les pieds dans un pays anglophone. L'endpoint répond à « d'où vient ce nom », et c'est la seule question à laquelle il répond.
- Ce n'est pas une nationalité, ni une citoyenneté, ni un lieu de naissance — et ce n'est la preuve d'aucun des trois.
- Ce n'est pas l'origine ethnique de la personne. La répartition ethnique décrit comment le nom se répartit entre les groupes : une propriété du nom.
- Cela ne doit rien décider au sujet d'un individu — ni un prix, ni une candidature, ni un score de risque. Les données qui pointent vers l'origine ethnique sont une catégorie particulière au titre de l'article 9 du GDPR, et cette décision t'appartient en tant que responsable du traitement, pas à nous.
- Ce n'est pas une supposition. Là où nous en avons trop peu, result_found vaut false et le nombre d'échantillons le dit — plutôt qu'un pays plausible inventé pour remplir le champ.
De notre côté : nous sommes une société allemande, tous les serveurs sont en Allemagne, les données sont traitées dans l'UE, et un accord de traitement des données peut être demandé depuis ton compte. Le tableau complet est sur l'aperçu de la confidentialité.
À quoi cela sert vraiment
- Trouver la bonne formule d'appel. Savoir qu'un nom est italien et non allemand, c'est ce qui fait passer « Andrea » de la mauvaise salutation à la bonne — et la détermination du genre dans la même réponse est ce qui l'applique.
- Analyse de marché et d'audience en agrégé. Dans quelle langue traduire une campagne, quelles régions une liste de diffusion atteint réellement, où une base de clients a grandi.
- Qualité des données. Une liste dont la répartition d'origine change soudain de forme signifie généralement qu'un import a mal tourné, pas que l'audience a déménagé.
- Recherche et démographie, où une répartition au niveau des noms sur une cohorte entière est l'unité d'analyse et où aucune conclusion individuelle n'est tirée.
- Translittération et rapprochement, où connaître l'origine probable d'un nom réduit l'éventail de ses orthographes plausibles.
L'exécuter sur une liste
La forme par lot accepte jusqu'à 100 noms par requête, sans plafond sur le nombre de requêtes. Le payload est un simple tableau JSON.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Un nom complet ou une adresse e-mail fonctionne à la place d'un prénom — le nom est extrait d'abord, puis l'origine est résolue.
- Clients officiels pour PHP, Python, Node, Java, Go, Ruby, Rust, Perl et .NET.
- Pour une liste ponctuelle plutôt qu'une intégration, voir détermination de genre en masse — les mêmes credits, sans code.
- Chaque champ, chaque erreur et une description OpenAPI : la référence v2.
Questions fréquentes
Peux-tu me dire la nationalité d'une personne à partir de son nom ?
Non, et aucun service honnête ne peut le faire. Ce que tu obtiens, c'est où le nom apparaît et avec quelle force, classé par pays — une statistique sur le nom, pas un fait sur la personne qui le porte. Beaucoup de gens portent un nom dont l'origine n'a rien à voir avec leur lieu de naissance.
Que renvoie l'endpoint ?
Une liste classée de 25 pays au maximum, chacun avec une probabilité, un code pays ISO, un nom de pays et — lorsque le pays les a en base — sa région continentale et statistique. La même réponse contient aussi le genre, la langue d'origine, la signification du nom et sa répartition entre groupes ethniques.
Comment la probabilité est-elle calculée ?
À partir de deux signaux : la part des enregistrements que nous avons pour ce nom qui provient de chaque pays, et la taille de chacune de ces populations. Les deux sont moyennés par pays, les pays à un pour cent ou moins sont écartés, et le reste est trié. Chaque valeur est une part du tout et non une note du pays pris isolément — lis-les donc les unes par rapport aux autres. Elles ne feront pas exactement 1 : tout ce qui est sous un pour cent est laissé de côté, et tout ce qui vient après le vingt-cinquième pays aussi.
Combien coûte une requête de pays d'origine ?
Deux credits par nom, parce que la requête est plus lourde qu'une simple détermination de genre. Les credits commencent à €0.35 pour 1 000, s'achètent à l'avance et n'expirent pas.
Est-ce la même chose que le paramètre country que j'envoie ?
Non — ce sont des directions opposées. Le country, locale ou ip que tu envoies décrit où la personne se trouve maintenant et change le genre renvoyé. Le pays d'origine que tu récupères décrit d'où vient le nom et ne dépend pas du lieu de résidence de la personne.
Puis-je y passer une liste entière ?
Oui. La variante par lot accepte jusqu'à 100 noms par requête, sans plafond sur le nombre de requêtes, et le même endpoint répond aussi bien pour un seul nom.
Déduire l'origine d'un nom est-il licite au titre du GDPR ?
Cela dépend de ce que tu en fais, et c'est ta décision en tant que responsable du traitement, pas la nôtre. Les données qui pointent vers l'origine ethnique sont une catégorie particulière au titre de l'article 9 : les utiliser pour décider au sujet de personnes précises exige une base légale démontrable. Les analyses agrégées et les formules d'appel correctes sont les usages courants. Nous sommes une société allemande, tous les serveurs sont en Allemagne, et un accord de traitement des données peut être demandé depuis ton compte.
ESSAIE-LE SUR DES NOMS QUE TU CONNAIS DÉJÀ
100 requêtes gratuites par mois, sans carte bancaire. Commence par des noms dont tu peux vérifier l'origine toi-même — c'est le moyen le plus rapide de voir ce que la répartition te dit.
Documentation de l'API · Traiter une liste entière · Poser une question
