Separar un nombre completo en nombre y apellido
Un campo de nombre combinado, una llamada a la API, dos campos limpios — con las partículas, los títulos y el orden invertido que rompen una partición escrita a mano ya resueltos, y el género en la misma respuesta.
La respuesta corta
- Envía el campo combinado y recibe first_name y last_name — más el género, la precisión y el número de muestras, en la misma respuesta, por un credit.
- Las partículas nobiliarias («van der», «von den», «de la») y los títulos académicos y profesionales se procesan en lugar de hacer tropezar — y un «Rossi, Andrea» invertido también se resuelve, a partir de los datos de nombres y no de la coma.
- Donde las dos mitades podrían ser cualquiera de las dos cosas, la decisión viene de con qué frecuencia aparece cada parte como nombre frente a con qué frecuencia aparece como apellido — no de su posición en la cadena.
- El modo estricto devuelve un apellido vacío en lugar de una suposición cuando el apellido no está en la base de datos, así que ves el hueco.
Por qué partir por el espacio no funciona
Casi todas las bases de código tienen una versión de esto: coge el campo de nombre, parte por los espacios, el primer elemento es el nombre y el último el apellido. Pasa la revisión porque los datos de prueba están en inglés, y se va al garete en silencio con el primer cliente que no lo está.
Lo caro es la forma de fallar. Nada lanza una excepción. Acabas con una base de datos llena de gente cuyo apellido es «van», un envío masivo que los saluda así, y ninguna línea de log que apunte a la causa.
Qué decide la partición
Cuatro cosas, en este orden — y la última es la que una partición basada en reglas no puede tener, porque requiere saber cómo se distribuyen los nombres en realidad.
- Los títulos salen primero. «Prof. Dr.», «Dipl.-Ing.», «Managing Director» y el resto de una lista mantenida se quitan antes de decidir cualquier otra cosa, para que nunca acaben en un campo de nombre.
- Las partículas se quedan con el apellido. «van», «van der», «van den», «von», «von der», «de», «de la», «du», «le», «di», «des» y sus vecinas se reconocen como parte del apellido al que pertenecen.
- No se confía en la puntuación para llevar el orden. La coma de «Rossi, Andrea» se elimina junto con los títulos, y el orden se lee después de los datos de nombres — una coma es una costumbre de formato, y muchas listas la usan de forma incoherente. En la subida de CSV y Excel puedes indicar el orden de la columna en su lugar, y un orden indicado se usa tal cual.
- La ambigüedad la resuelven los datos. Cada parte candidata se busca en la base de nombres y en la de apellidos, y la parte que se comporta mucho más como apellido que como nombre es el apellido.
Pasa un código de país y la misma comparación se hace con ese país en lugar de con todos a la vez — que es lo que quieres cuando ya sabes de dónde viene la lista.
Cómo llamarlo
Hay dos endpoints que hacen esto, y cuál te conviene depende de si necesitas el modo estricto.
v2 — la API actual
POST https://gender-api.com/v2/gender/by-full-name
{ "full_name": "Anna van der Berg", "country": "NL" }
{
"result_found": true,
"first_name": "Anna",
"last_name": "van der Berg",
"gender": "female",
"probability": 0.98,
"details": { "credits_used": 1, "samples": 8961, "duration": "33ms" }
}
v1 — cuando necesitas el modo estricto
El modo estricto solo existe en el endpoint de partición v1. Si un apellido vacío te importa más que estar en la API más nueva, usa este.
GET https://gender-api.com/get?split=Anna%20van%20der%20Berg&strict=true&key=…
- referencia v2 de nombre completo — campos, errores, descripción OpenAPI.
- referencia v1 de partición — el parámetro strict y sus respuestas exactas.
- Clientes oficiales para PHP, Python, Node, Java, Go, Ruby, Rust, Perl y .NET.
Primero: ¿esa columna contiene realmente nombres completos?
Conviene saberlo antes de procesar un archivo que no has creado tú. Envía una muestra de hasta 100 valores y recibes si parecen nombres completos — y no cuesta credits.
POST https://gender-api.com/v2/name-format-detect
{ "names": ["Sophie Jones", "Lorenzo Carlos", "Anna van der Berg"] }
{
"is_fullname": true,
"fullname_probability": 1,
"validHints": [ … ]
}
Ten claro qué mide esto: fullname_probability es la parte de los valores enviados que tiene más de una palabra, y is_fullname es esa parte por encima de 0,6. Es un juicio sobre la columna, no sobre cada nombre — que es exactamente lo que necesitas al decidir si partir o no, y no un sustituto de la partición en sí.
Una columna mixta también es una respuesta válida: algunas listas tienen «Thomas» y «John Smith» juntos, y la partición resuelve los dos sin que los ordenes antes.
Donde todavía necesita tu ayuda
Una partición que dijera resolver todos los nombres del mundo estaría mintiendo. Estos son los casos en los que ninguna regla resuelve la cadena por sí sola.
Si controlas el formulario, la solución más barata no es una API en absoluto: dos campos en lugar de uno, o una indicación de que el formato es «nombre, apellido». Todo lo que sigue vale para cuando no lo controlas.
- Apellido primero. Haya coma o no, gana la lectura que respaldan los datos de nombres frente a una regla de posición — y acierta muchas más veces de las que falla, pero no es una garantía. Si sabes que toda la columna lleva el apellido primero, indícalo en la subida en lugar de fiarte de la puntuación.
- Nombres de una sola palabra. Un mononímico no tiene apellido que encontrar. El apellido vuelve vacío en lugar de partir el nombre por la mitad.
- Transliteración incoherente. El mismo nombre escrito de tres formas en una lista se resuelve como tres nombres, porque eso es lo que es en los datos.
- Nombres compuestos sin guion. «Anna Maria» se mantiene junto donde los datos lo respaldan, pero una lista que mezcla «Anna Maria Rossi» y «Anna Rossi» no será uniforme.
En los cuatro casos, un código de país acota el problema, y el modo estricto hace visibles las filas dudosas en lugar de silenciosamente plausibles. Un campo vacío que puedes filtrar vale más que uno equivocado que no detectas.
Una columna entera de una vez
Si los nombres están en una hoja de cálculo y no en una aplicación, no necesitas la API. Sube el archivo, señala la columna con los nombres combinados y las partes separadas vuelven como columnas nuevas junto a tus datos — hasta 10,000,000 filas por CSV o 100,000 por libro de Excel, y tu libro vuelve intacto.
- Subir un archivo CSV o Excel — sin código, conservando el formato original.
- Determinación de género en masa — los límites, el precio por volumen y las respuestas para compras.
- ¿Trabajas en una hoja de cálculo o un CRM? Hay integraciones listas para usar para Excel, Google Sheets, Shopify, HubSpot, Salesforce, Zapier y más.
Preguntas frecuentes
¿Por qué no partir simplemente por el espacio?
Porque el espacio no es el límite. «Anna van der Berg» da el apellido «van» en el primer espacio y el nombre «Anna van der» en el último. Ambos están mal, ambos quedan bien en una prueba con nombres ingleses, y ambos fallan en silencio en cuanto llega un apellido neerlandés, alemán, francés, español o portugués.
¿Qué decide dónde se parte?
Primero se quitan los títulos conocidos, y las partículas nobiliarias como «van der», «von den» y «de la» se quedan con el apellido. Después se compara con qué frecuencia aparece cada parte como nombre frente a con qué frecuencia aparece como apellido — así que no lo decide la posición de la palabra, ni la puntuación: una coma se elimina junto con los títulos en lugar de leerse como marca de «apellido primero». En la subida de CSV y Excel puedes indicar directamente el orden de la columna, y entonces se usa tal cual.
¿Qué pasa cuando el apellido no está en la base de datos?
Para eso está el modo estricto, en el endpoint v1. Con el modo estricto activado, el apellido vuelve vacío en lugar de adivinado, así que el hueco se ve en tus datos. Sin él se extrae un apellido de todos modos, lo mejor posible.
¿Me da también el género?
Sí, en la misma respuesta y por el mismo credit — junto con el número de muestras y la precisión que hay detrás. Partir el nombre y determinar su género es una llamada, no dos.
¿Cómo sé si mi columna contiene nombres completos?
Envía una muestra de hasta 100 valores al endpoint name-format-detect. No cuesta credits y te dice si la columna parece contener nombres completos, nombres de pila o una mezcla — útil antes de decidir cómo procesar el archivo.
¿Cuánto cuesta partir el nombre?
Un credit por nombre, lo mismo que una simple determinación de género, desde €0.35 por 1.000. Los credits se compran por adelantado y no caducan.
¿Funciona con nombres no occidentales?
En parte, y es mejor conocer los límites. Los nombres escritos con el apellido primero y sin separador, los nombres de una sola palabra y los nombres transliterados de forma incoherente son los casos difíciles — ninguna regla los resuelve solo con la cadena. Enviar un código de país ayuda, porque entonces la consulta compara las partes con ese país en lugar de con todo.
PRUÉBALO CON LOS NOMBRES QUE ROMPEN TU PARTICIÓN
100 consultas gratis al mes, sin tarjeta. Coge las veinte filas que tu código actual falla y empieza por esas.
Documentación de la API · Sube un archivo en su lugar · Hacer una pregunta