Capire la risposta JSON
Le previsioni singole di GenderAPI.io V2 restituiscono un oggetto data per il risultato e un oggetto meta per le informazioni su richiesta, accesso e addebito. Leggi data.gender e data.confidence insieme a data.confidence_kind e data.source. Il seguente esempio dal set di dati è una risposta reale acquisita il 1° ottobre 2026 con una chiave API; è stato sostituito solo il saldo dell'account. Non rappresenta un'accuratezza misurata del prodotto e una richiesta in tempo reale può restituire un risultato diverso. Le richieste con chiave API riportano access.mode: api_key e null nei campi di quota validi solo per la prova; le richieste tramite prova IP riportano ip_trial con il limite della prova e l'orario di reimpostazione.
{
"data": {
"input": {
"type": "name",
"value": "Lorenzo",
"country": "IT"
},
"name": "lorenzo",
"gender": "male",
"country": "IT",
"confidence": 0.996386630532972,
"confidence_kind": "observed_frequency",
"sample_count": 3321,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "lorenzo",
"method": "normalized",
"scope": "country",
"country": "IT"
}
},
"meta": {
"request_id": "a1bda295-3045-4caa-8aa8-a461859ea5b3",
"duration_ms": 12,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Campi della risposta di previsione
| Campo | Tipo | Può essere null | Esempio | Descrizione |
|---|---|---|---|---|
data.input | object | No | {"type":"name","value":"Lorenzo","country":"IT"} | Tipo di input, valore e paese. forceToGenderize è incluso quando è true. |
data.name | string | Sì | "lorenzo" | Nome proprio trovato o estratto; null se non disponibile. |
data.gender | string | Sì | "male" | male, female o JSON null. Una previsione, non un'identità personale verificata. |
data.result_status | string | No | "identified" | identified se viene restituito un genere; altrimenti unknown. |
data.reason | string | Sì | null | null per i risultati identified. Motivi per unknown: not_found, no_name_candidate, ambiguous o insufficient_evidence. |
data.confidence | number | Sì | 0.95 | Valore da 0 a 1 oppure null. Se gender è null, anche la confidenza è null. |
data.confidence_kind | string | Sì | "observed_frequency" | observed_frequency: conteggio dominante nel set di dati diviso per il totale. model_reported: valore fornito dall'IA, non una probabilità calibrata. null se non disponibile. |
data.sample_count | integer | Sì | 1200 | Dimensione del campione nel set di dati oppure null. L'IA non inventa un conteggio dei campioni. |
data.source | string | No | "dataset" | dataset, ai o none. |
data.country | string | Sì | "IT" | Associazione al paese da dataset o ai_association, oppure null. Non stabilisce nazionalità, residenza né origine etnica. |
data.country_source | string | Sì | "dataset" | Origine dell'associazione al paese: dataset, ai_association o null. |
data.match | object | No | {"name":"lorenzo","method":"normalized","scope":"country","country":"IT"} | Nome trovato nel set di dati, metodo (normalized, token, substring o model_inference), ambito country o global e paese associato. Le evidenze non disponibili sono null. |
Campi di input restituiti
| Campo | Tipo | Può essere null | Esempio | Descrizione |
|---|---|---|---|---|
data.input.type | string | No | "name" | Categoria di input: name, email o username. |
data.input.value | string | No | "Lorenzo" | Il valore inviato per la previsione. |
data.input.country | string | Sì | "IT" | Contesto del paese inviato; null se omesso. |
data.input.forceToGenderize | boolean | No | true | Presente solo quando la modalità nickname è attiva; altrimenti omesso. |
Campi della corrispondenza nel set di dati
| Campo | Tipo | Può essere null | Esempio | Descrizione |
|---|---|---|---|---|
data.match.name | string | Sì | "lorenzo" | Candidato selezionato nel set di dati; null se non è stata selezionata alcuna riga del set di dati. |
data.match.method | string | Sì | "normalized" | normalized, token, substring o model_inference; null se non disponibile. |
data.match.scope | string | Sì | "country" | country o global per le ricerche nel set di dati; null per l'IA o in assenza di evidenze. |
data.match.country | string | Sì | "IT" | Paese della riga selezionata nel set di dati; null per le righe globali o per l'IA. |
Metadati di accesso, addebito e richiesta
| Campo | Tipo | Può essere null | Esempio | Descrizione |
|---|---|---|---|---|
meta.request_id | string | No | "550e8400-e29b-41d4-a716-446655440000" | Identificatore univoco di questo tentativo HTTP; inviato anche in X-Request-ID. |
meta.duration_ms | integer | No | 42 | Tempo di elaborazione della richiesta in millisecondi. |
meta.access.mode | string | No | "api_key" | api_key, ip_trial o unauthenticated. Con un account a pagamento verifica che venga riportato api_key. |
meta.access.reason | string | Sì | null | Motivo del passaggio alla prova IP: api_key_missing, api_key_invalid o api_key_not_found; altrimenti null. |
meta.usage.charged_credits | integer | Sì | 1 | Crediti netti addebitati. Zero prima dell'addebito o dopo un rimborso completo confermato; null se l'addebito non è confermato. |
meta.usage.remaining_credits | integer | Sì | 99 | Saldo al termine dell'operazione. Può essere negativo; null se non disponibile o se l'addebito non è confermato. |
meta.usage.billing_status | string | No | "confirmed" | not_charged, confirmed o unconfirmed. Controllalo prima di ripetere una previsione non riuscita. |
meta.usage.resets_at | string | Sì | "2026-09-27T12:00:00.000Z" | Momento del ripristino della prova IP in UTC (ISO 8601); null per gli account con chiave API o se sconosciuto. |
meta.usage.limit | integer | Sì | 10 | Quota della prova IP; null per gli account con chiave API. |
meta.usage.period_seconds | integer | Sì | 86400 | Durata del periodo della prova IP in secondi; null per gli account con chiave API. |
Un risultato sconosciuto riuscito
HTTP 200 significa che l'operazione è stata completata; non garantisce un genere. Conserva il valore JSON null invece di convertirlo in male, female, una stringa vuota o una confidenza pari a zero. Controlla data.result_status e data.reason separatamente dagli errori HTTP.
Questo esempio reale basato solo sul set di dati, acquisito il 1° ottobre 2026, restituisce source: none e reason: not_found e costa comunque 1 credito. Una riga del set di dati in parità può restituire reason: ambiguous mantenendo sample_count. Un risultato sconosciuto dell'IA usa source: ai e 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
}
}
}Interpretare la confidenza e le evidenze della corrispondenza
Una confidenza di 0.9 si esprime su una scala da 0 a 1. Per observed_frequency indica il conteggio dominante diviso per il totale della riga selezionata nel set di dati; non è un'accuratezza del prodotto misurata end-to-end. Un valore model_reported è fornito dall'IA e non è calibrato sulle frequenze del set di dati.
Definisci le soglie della tua applicazione in base ai tuoi dati di valutazione e a confidence_kind. Non mettere direttamente a confronto in un'unica graduatoria i valori del set di dati e quelli dell'IA, come se misurassero la stessa cosa. Per l'IA, match.name, match.scope e match.country sono null perché non è stata selezionata alcuna riga del set di dati; match.method è model_inference.
Per i nomi completi, un risultato del set di dati può derivare da una parte del nome anziché dall'intera stringa. data.input conserva il valore inviato; data.name descrive il nome restituito e data.match il candidato e l'ambito della ricerca.
Decidere che cosa deve fare la tua applicazione
Gestisci prima gli errori della richiesta e dei singoli elementi, poi controlla result_status. Per una previsione singola leggi data; per un batch applica la stessa decisione a data di ogni elemento riuscito. Conserva i risultati sconosciuti nella tua applicazione invece di forzare l'etichetta male o female.
| Risultato | Che cosa significa | Gestione consigliata |
|---|---|---|
| identified; gender: male o female | La previsione ha restituito un genere, sulla base del set di dati o dell'IA. | Applica una regola valutata proprio per questo confidence_kind; conserva source e le evidenze della corrispondenza. |
| unknown; reason: not_found | Nessuna voce memorizzata nel set di dati corrisponde ai candidati interpretati. | Lascia gender a null. Una nuova richiesta intenzionale con altre opzioni IA è una nuova operazione a pagamento. |
| unknown; reason: no_name_candidate | L'interpretazione per il set di dati non ha prodotto un candidato di nome utilizzabile. | Conserva null; controlla il tipo di input e il valore prima di scegliere un'ulteriore previsione. |
| unknown; reason: ambiguous | La riga selezionata nel set di dati ha lo stesso numero di occorrenze maschili e femminili; sample_count può comunque essere presente. | Non decidere tu quale genere vale e non convertire la confidenza null in zero. |
| unknown; reason: insufficient_evidence | L'IA ha completato la richiesta senza evidenze sufficienti per restituire un genere. | Trattalo come un risultato sconosciuto completato, non come un errore del provider né come candidato a nuovi tentativi automatici. |
| Problem Details o error di un elemento | L'esecuzione non è riuscita, ad esempio per ai_upstream_error o prediction_timeout. | Salva il codice di errore e l'ID della richiesta, controlla l'addebito e segui le indicazioni sui nuovi tentativi. |
Scegliere le soglie in base alla propria valutazione
Non esiste una soglia di confidenza universale che renda corretta una previsione. Valuta observed_frequency e model_reported separatamente, con esempi rappresentativi ed etichettati in modo indipendente tratti dal tuo caso d'uso. Una frequenza nel set di dati e un valore riportato dall'IA sono segnali diversi, anche quando entrambi valgono 0.9. Misura quanto spesso la tua regola produce una risposta e quanto spesso queste risposte sono corrette; per tutto il resto conserva un risultato sconosciuto o prevedi una revisione manuale.
Se, ad esempio, result_status è identified ma confidence_kind è model_reported, applica la regola che hai valutato per l'IA, non la soglia del set di dati. Se è stato usato forceToGenderize, name: null insieme a un genere diverso da null è valido: un alias può essere interpretato senza estrarre un vero nome proprio. Controlla gender e result_status, non solo name, per stabilire se la previsione ha dato una risposta. Il risultato resta una stima, non la conferma dell'identità di una persona.