Comprender la respuesta JSON
Las predicciones individuales de GenderAPI.io V2 devuelven data con el resultado y meta con información de solicitud, acceso y cobro. Interpreta data.gender y data.confidence junto con data.confidence_kind y data.source. El ejemplo siguiente del conjunto de datos es una respuesta real capturada el 1 de octubre de 2026 con una clave de API; solo se sustituyó el saldo de la cuenta. No representa una medición de la precisión del producto, y una consulta real puede devolver un resultado distinto. Las solicitudes con clave de API indican access.mode: api_key y null en los campos exclusivos de la prueba; las solicitudes de prueba por IP indican ip_trial con el límite de la prueba y la hora de reinicio.
{
"data": {
"input": {
"type": "name",
"value": "Javier",
"country": "ES"
},
"name": "javier",
"gender": "male",
"country": "ES",
"confidence": 0.9955271565495207,
"confidence_kind": "observed_frequency",
"sample_count": 6260,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "javier",
"method": "normalized",
"scope": "country",
"country": "ES"
}
},
"meta": {
"request_id": "48437027-f346-4e88-904f-5e2cd896d661",
"duration_ms": 15,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Campos de la respuesta de predicción
| Campo | Tipo | ¿Admite null? | Ejemplo | Descripción |
|---|---|---|---|---|
data.input | object | No | {"type":"name","value":"Javier","country":"ES"} | Tipo de entrada, valor y país. forceToGenderize se incluye cuando true. |
data.name | string | Sí | "javier" | Nombre de pila coincidente o extraído; null cuando no hay ninguno disponible. |
data.gender | string | Sí | "male" | male, female o JSON null. Esta es una predicción, no una prueba de la identidad de una persona. |
data.result_status | string | No | "identified" | identified si se devuelve un género; unknown en caso contrario. |
data.reason | string | Sí | null | null en resultados identified. Para unknown: not_found, no_name_candidate, ambiguous o insufficient_evidence. |
data.confidence | number | Sí | 0.95 | Puntuación entre 0 y 1, o null. Si gender es null, confidence también lo es. |
data.confidence_kind | string | Sí | "observed_frequency" | observed_frequency: el recuento de género dominante dividido por el recuento total en el conjunto de datos seleccionado. model_reported: una puntuación de IA, no una probabilidad calibrada. El valor es null cuando no está disponible. |
data.sample_count | integer | Sí | 1200 | Tamaño de muestra del conjunto de datos o null. La IA no inventa un recuento de muestras. |
data.source | string | No | "dataset" | dataset, ai o none. |
data.country | string | Sí | "ES" | Asociación de país del conjunto de datos o ai_association, o null. No establece nacionalidad, residencia ni etnia. |
data.country_source | string | Sí | "dataset" | Origen de la asociación de país: dataset, ai_association o null. |
data.match | object | No | {"name":"javier","method":"normalized","scope":"country","country":"ES"} | Nombre coincidente en el conjunto de datos, método (normalized, token, substring o model_inference), ámbito (country o global) y país de la coincidencia. La información no disponible se representa con null. |
Campos de entrada devueltos
| Campo | Tipo | ¿Admite null? | Ejemplo | Descripción |
|---|---|---|---|---|
data.input.type | string | No | "name" | Categoría de entrada: name, email o username. |
data.input.value | string | No | "Javier" | Valor enviado para la predicción. |
data.input.country | string | Sí | "ES" | Contexto de país enviado; null si se omitió. |
data.input.forceToGenderize | boolean | No | true | Solo aparece cuando está activado el modo de apodos; se omite en los demás casos. |
Campos de coincidencia del conjunto de datos
| Campo | Tipo | ¿Admite null? | Ejemplo | Descripción |
|---|---|---|---|---|
data.match.name | string | Sí | "javier" | Candidato seleccionado del conjunto de datos; null si no se seleccionó ninguna fila. |
data.match.method | string | Sí | "normalized" | normalized, token, substring o model_inference; null si no está disponible. |
data.match.scope | string | Sí | "country" | country o global en consultas al conjunto de datos; null para IA o sin evidencia. |
data.match.country | string | Sí | "ES" | País de la fila seleccionada; null para filas globales o IA. |
Acceso, facturación y metadatos de la solicitud
| Campo | Tipo | ¿Admite null? | Ejemplo | Descripción |
|---|---|---|---|---|
meta.request_id | string | No | "550e8400-e29b-41d4-a716-446655440000" | Identificador único de este intento HTTP; también se envía en X-Request-ID. |
meta.duration_ms | integer | No | 42 | Tiempo de procesamiento de la solicitud en milisegundos. |
meta.access.mode | string | No | "api_key" | api_key, ip_trial o unauthenticated. Comprueba api_key para cualquier integración de cuenta, gratuita o de pago. |
meta.access.reason | string | Sí | null | Motivo del acceso de prueba: api_key_missing, api_key_invalid o api_key_not_found; null en otros casos. |
meta.usage.charged_credits | integer | Sí | 1 | Créditos netos cobrados. Cero antes del cobro o tras un reembolso completo confirmado; null si el cobro no está confirmado. |
meta.usage.remaining_credits | integer | Sí | 99 | Saldo al finalizar la operación. Puede ser negativo; null si no está disponible o el cobro no está confirmado. |
meta.usage.billing_status | string | No | "confirmed" | not_charged, confirmed o unconfirmed. Compruébelo antes de reintentar una predicción fallida. |
meta.usage.resets_at | string | Sí | "2026-09-27T12:00:00.000Z" | Reinicio de la prueba por IP en UTC (ISO 8601); null para cuentas con clave API o si se desconoce. |
meta.usage.limit | integer | Sí | 10 | Créditos de la prueba por IP; null para cuentas con clave API. |
meta.usage.period_seconds | integer | Sí | 86400 | Duración de la prueba por IP en segundos; null para cuentas con clave API. |
Un resultado completado sin predicción
HTTP 200 significa que la operación se completó; no garantiza un género. Conserva JSON null en lugar de convertirlo a male, female, una cadena vacía o confianza cero. Comprueba data.result_status y data.reason por separado de los errores HTTP.
Este ejemplo real, solo con el conjunto de datos y capturado el 1 de octubre de 2026, devuelve source: none y reason: not_found y aún cuesta 1 crédito. Si los recuentos del conjunto de datos para los dos géneros son iguales, el resultado puede contener reason: ambiguous y conservar sample_count. Un resultado de IA desconocido utiliza source: ai y reason: insufficient_evidence.
{
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
},
"meta": {
"request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Interpretar la confianza y los datos de coincidencia
Una confianza de 0.9 está en una escala de 0 a 1. Para observed_frequency, es el recuento dominante dividido entre el total del registro seleccionado; no es una medida de la precisión global del producto. La IA devuelve model_reported, una puntuación que no está calibrada con las frecuencias del conjunto de datos.
Define los umbrales con tus propios datos de evaluación y confidence_kind. No compares directamente frecuencias del conjunto de datos y puntuaciones de IA como si midieran lo mismo. En respuestas de IA, match.name, match.scope y match.country son null porque no se seleccionó un registro; match.method es model_inference.
Para nombres completos, el resultado de un conjunto de datos puede provenir de un componente en lugar de la cadena completa. data.input conserva el valor enviado; data.name describe el nombre devuelto y data.match describe el candidato y el alcance de la búsqueda.
Decide cómo debe continuar tu aplicación
Gestiona primero los errores de solicitud o de registro y después consulta result_status. Para una predicción individual, lee data; en un lote, aplica la misma decisión a data de cada registro completado. Conserva los resultados unknown en lugar de forzar una etiqueta male o female.
| Resultado | Significado | Cómo gestionarlo |
|---|---|---|
| identified; gender: male o female | La inferencia produjo una predicción de género a partir del conjunto de datos o de la IA. | Aplica una regla evaluada para ese confidence_kind; conserva source y los datos de coincidencia. |
| unknown; reason: not_found | Ningún registro del conjunto de datos coincidió con los candidatos extraídos. | Conserva gender como null. Una nueva consulta con otras opciones de IA es una operación distinta con coste. |
| unknown; reason: no_name_candidate | No se extrajo un candidato de nombre utilizable para consultar el conjunto de datos. | Conserva null; revisa el tipo y el valor de entrada antes de solicitar otra inferencia. |
| unknown; reason: ambiguous | El registro seleccionado tiene el mismo recuento masculino y femenino; sample_count puede seguir presente. | No deshagas el empate por tu cuenta ni conviertas confidence: null en cero. |
| unknown; reason: insufficient_evidence | La IA terminó sin información suficiente para devolver una predicción. | Trátalo como un unknown completado, no como un fallo del proveedor ni como motivo para reintentar automáticamente. |
| Problem Details o error de un registro | La operación falló, por ejemplo con ai_upstream_error o prediction_timeout. | Guarda el código de error y el identificador de solicitud, comprueba el cobro y sigue la guía de reintentos. |
Define los umbrales de confianza con tus propios datos de evaluación
No existe un umbral universal que garantice una predicción correcta. Evalúa observed_frequency y model_reported por separado con ejemplos representativos de tu caso de uso y etiquetas de referencia obtenidas de forma independiente. Una frecuencia del conjunto de datos y una puntuación declarada por la IA son señales distintas, aunque ambas valgan 0.9. Mide qué proporción de entradas acepta tu regla y cuántas predicciones aceptadas son correctas; conserva la opción unknown o de revisión para las demás.
Por ejemplo, si result_status es identified y confidence_kind es model_reported, aplica la regla que hayas evaluado para IA, no el umbral del conjunto de datos. Con forceToGenderize, name: null junto con un gender distinto de null es válido: se puede interpretar un alias sin extraer un nombre real. Comprueba gender y result_status, no solo name, para determinar si hay predicción. El resultado sigue siendo una estimación, no una verificación de identidad.