Nacionalidad a partir de un nombre: qué puede y qué no puede decirte un nombre
Una llamada a la API convierte un nombre o apellido en una lista ordenada de los países de los que viene, con una probabilidad en cada uno. Responde a una pregunta sobre el nombre — que es una pregunta distinta de dónde vive la persona, y otra distinta más de quién es.
La respuesta corta
- Obtienes una lista ordenada de hasta 25 países, cada uno con una probabilidad, un código ISO, un nombre de país y, cuando el país los tiene registrados, su región continental y estadística.
- La misma respuesta incluye además el género, el idioma de origen, el significado del nombre y su distribución entre grupos étnicos, a partir de una base de datos con 192 países.
- Cuesta 2 credits por nombre — el doble que una simple determinación de género, porque es una consulta más pesada. Los credits se compran por adelantado y no caducan.
- Es una estadística sobre el nombre, no una afirmación sobre la persona. Úsalo para fórmulas de tratamiento, análisis agregado y calidad de datos — no para decidir nada sobre una persona concreta.
¿De dónde viene el número?
Aquí no adivina ningún modelo, y nada se genera. La probabilidad es aritmética sobre registros que realmente tenemos, y por eso el mismo nombre devuelve la misma lista hoy, el mes que viene y el año que viene.
Entran dos señales. La primera es cómo se reparten los registros de ese nombre entre los países — un nombre que tenemos sobre todo de Polonia tiende a polaco. La segunda es cuán grande es cada una de esas poblaciones, lo que evita que un país pequeño con un nombre bien muestreado supere a uno grande solo por volumen. Las dos se promedian por país, todo lo que queda por debajo del uno por ciento se descarta, y lo que queda se ordena.
Como es una distribución, un nombre frecuente en dos países responde con dos países en lugar de elegir un ganador. Eso es justo lo útil: la forma de la lista te dice cuánto puedes fiarte de la primera entrada.
Qué se devuelve
Un POST, un nombre, una respuesta. La lista de abajo está recortada; la real llega hasta los 25 países más 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" }
}Fíjate en los dos campos que hacen auditable la respuesta: samples te dice sobre cuántos registros se apoya, y credits_used confirma los dos credits. Una respuesta con pocas muestras no se te oculta.
- Con continental_region y statistical_region puedes agrupar la lista por regiones sin mantener tu propia tabla de correspondencias.
- La respuesta contiene además un enlace a un mapa interactivo de ese nombre, la forma más rápida de comprobar un resultado a ojo.
- Cada campo está documentado en la referencia v2.
El origen no es la residencia
Es el malentendido más frecuente, y va en las dos direcciones. Dos campos distintos, dos significados distintos, sentidos opuestos.
| Pregunta | El país que envías | El país que recibes |
|---|---|---|
| Campo | country, locale, ip |
country_of_origin |
| Significa | Dónde está la persona ahora | De dónde viene el nombre |
| Cambia la respuesta de género | Sí — Andrea es masculino en Italia y femenino en Alemania | No — es una salida, no una entrada |
| Normalmente ya lo sabes | Sí — por la dirección de envío, el dominio o la IP | No — esto es justo lo que estás comprando |
| Credits | Gratis — un parámetro, no una consulta | 2 por nombre |
Lo que no es
Un nombre es evidencia sobre un nombre. Tratarlo como evidencia sobre una persona es donde este tipo de datos se descarrila, así que vale la pena ser claro con los límites antes de construir sobre ello.
Una persona llamada Nguyen puede haber nacido en Melbourne, y una persona llamada Smith puede no haber pisado nunca un país anglófono. El endpoint responde a «de dónde viene este nombre», y esa es la única pregunta que responde.
- No es una nacionalidad, ni una ciudadanía, ni un lugar de nacimiento — y no es prueba de ninguno de los tres.
- No es la etnia de la persona. La distribución étnica describe cómo se reparte el nombre entre grupos: una propiedad del nombre.
- No debería decidir nada sobre una persona concreta — ni un precio, ni una solicitud, ni una puntuación de riesgo. Los datos que apuntan al origen étnico son una categoría especial según el artículo 9 del GDPR, y esa decisión es tuya como responsable del tratamiento, no nuestra.
- No es una suposición. Donde tenemos demasiado poco, result_found vale false y el número de muestras lo dice, en lugar de inventarse un país plausible para rellenar el campo.
Por nuestra parte: somos una empresa alemana, todos los servidores están en Alemania, los datos se procesan dentro de la UE y puedes solicitar un acuerdo de tratamiento de datos en tu cuenta. El cuadro completo está en el resumen de privacidad.
Para qué se usa de verdad
- Acertar con el tratamiento. Saber que un nombre es italiano y no alemán es lo que convierte «Andrea» del saludo equivocado en el correcto — y la determinación de género en la misma respuesta es la parte que lo aplica.
- Análisis de mercado y audiencia en agregado. A qué idioma traducir una campaña, a qué regiones llega de verdad una lista de correo, dónde ha crecido una base de clientes.
- Calidad de datos. Una lista en la que la distribución de origen cambia de forma de repente suele significar que una importación salió mal, no que la audiencia se haya mudado.
- Investigación y demografía, donde una distribución a nivel de nombre sobre una cohorte entera es la unidad de análisis y no se saca ninguna conclusión individual.
- Transliteración y emparejamiento, donde conocer el origen probable de un nombre reduce sus grafías plausibles.
Pasarlo por una lista
La forma por lotes acepta hasta 100 nombres por petición, sin límite en el número de peticiones. El payload es un simple array JSON.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- En lugar de un nombre de pila también funciona un nombre completo o una dirección de correo — primero se extrae el nombre y después se resuelve el origen.
- Clientes oficiales para PHP, Python, Node, Java, Go, Ruby, Rust, Perl y .NET.
- Para una lista puntual en lugar de una integración, mira determinación de género en masa — los mismos credits, sin código.
- Cada campo, cada error y una descripción OpenAPI: la referencia v2.
Preguntas frecuentes
¿Puedes decirme la nacionalidad de una persona a partir de su nombre?
No, y ningún servicio honesto puede. Lo que obtienes es dónde aparece el nombre y con qué fuerza, ordenado por país — una estadística sobre el nombre, no un hecho sobre la persona que lo lleva. Mucha gente lleva un nombre cuyo origen no tiene nada que ver con su lugar de nacimiento.
¿Qué devuelve el endpoint?
Una lista ordenada de hasta 25 países, cada uno con una probabilidad, un código de país ISO, un nombre de país y —cuando el país los tiene registrados— su región continental y estadística. La misma respuesta incluye además el género, el idioma de origen, el significado del nombre y su distribución entre grupos étnicos.
¿Cómo se calcula la probabilidad?
A partir de dos señales: qué parte de los registros que tenemos de ese nombre viene de cada país, y cuán grande es cada una de esas poblaciones. Las dos se promedian por país, los países con un uno por ciento o menos se descartan, y el resto se ordena. Cada valor es una parte del total y no una puntuación de ese país por sí solo — así que léelos unos frente a otros. No sumarán exactamente 1: todo lo que está por debajo del uno por ciento queda fuera, y también todo lo que pasa del país veinticinco.
¿Cuánto cuesta una consulta de país de origen?
Dos credits por nombre, porque es una consulta más pesada que una simple determinación de género. Los credits empiezan en €0.35 por 1.000, se compran por adelantado y no caducan.
¿Es lo mismo que el parámetro country que envío?
No — son direcciones opuestas. El country, locale o ip que envías describe dónde está la persona ahora y cambia qué género se devuelve. El país de origen que recibes describe de dónde viene el nombre y no depende de dónde vive la persona.
¿Puedo pasar una lista entera?
Sí. La variante por lotes acepta hasta 100 nombres por petición, sin límite en el número de peticiones, y el mismo endpoint responde igual de bien a un solo nombre.
¿Es lícito según el GDPR inferir el origen a partir de un nombre?
Depende de lo que hagas con ello, y es tu decisión como responsable del tratamiento, no la nuestra. Los datos que apuntan al origen étnico son una categoría especial según el artículo 9, así que usarlos para tomar decisiones sobre personas concretas necesita una base legal que puedas demostrar. Los análisis agregados y las fórmulas de tratamiento correctas son los usos habituales. Somos una empresa alemana, todos los servidores están en Alemania y puedes solicitar un acuerdo de tratamiento de datos en tu cuenta.
PRUÉBALO CON NOMBRES QUE YA CONOCES
100 consultas gratis al mes, sin tarjeta. Empieza con nombres cuyo origen puedas comprobar tú mismo — es la forma más rápida de ver qué te está diciendo la distribución.
Documentación de la API · Procesar una lista entera · Hacer una pregunta
