Usare il nome originale senza presupporre un unico alfabeto o un ordine fisso
La dimostrazione usa un esempio in devanagari e il contesto del paese IN. È un esempio di input e non una definizione di tutti i nomi usati in India. L'API accetta stringhe Unicode, quindi puoi inviare la grafia presente nel record della tua applicazione senza convertirla prima in caratteri latini.
La ricerca usa parti normalizzate. Non effettua una conversione generale tra alfabeti e non garantisce che una grafia latina e una grafia nell'alfabeto originale portino alla stessa voce. Conserva l'input originale insieme al nome restituito. Il fatto che un alfabeto venga accettato non implica un'accuratezza misurata in modo indipendente per ogni lingua o comunità.
Non dare per scontato che la prima o l'ultima parte abbia sempre lo stesso ruolo. V2 sceglie il candidato disponibile con il conteggio totale memorizzato più alto e non garantisce una posizione precisa del nome proprio. Iniziali, parti brevi e voci memorizzate mancanti possono lasciare irrisolto il risultato del set di dati; il fallback IA può interpretare l'intero valore inviato.
| Esempio di input | Che cosa rappresenta | Che cosa controllare |
|---|---|---|
प्रिया शर्मा | Nome completo in devanagari | Più parti possono diventare candidati. Verifica il nome scelto e la corrispondenza invece di presumere che prevalga la prima parte. |
Priya Sharma | Esempio in caratteri latini | È una grafia distinta; una corrispondenza identica tra alfabeti non è garantita. |
A. Kumar | Iniziale e un'altra parte | Un'iniziale di una sola lettera non diventa un candidato del set di dati. Una corrispondenza sull'altra parte non conferma il nome proprio previsto. |
country: IN | Contesto di esempio: India | Usalo quando il tuo record ha un contesto del paese pertinente, non solo perché il nome compare in questa guida. |
Scegliere consapevolmente il contesto del paese IN
La demo invia country: IN (India). L'API non sceglie il paese in base all'alfabeto in cui è scritto il nome. Nella tua integrazione usa un contesto del paese noto e pertinente oppure ometti country. Non trasformare questo valore di esempio in un valore predefinito per tutti i record.
Per ogni candidato, la ricerca sceglie la voce specifica del paese, se esiste, e altrimenti considera la voce globale. Seleziona poi il candidato disponibile con il conteggio totale memorizzato più alto. L'ambito effettivo della corrispondenza è indicato in data.match.scope e data.match.country. Una voce specifica del paese con frequenze in parità non viene sostituita automaticamente dal risultato globale; se il fallback è attivo, può essere usata invece l'IA.
data.input.country descrive il contesto inviato nella richiesta. data.country e data.country_source descrivono l'associazione con un paese restituita e la sua origine. Sono campi diversi e non indicano né la cittadinanza né l'origine etnica né il luogo di residenza.
Inviare una richiesta V2 per un nome dalla tua applicazione
Imposta GENDERAPI_API_KEY sulla tua chiave esistente ed esegui l'esempio sul tuo server. La richiesta attiva esplicitamente il normale fallback IA. Mostra il formato della richiesta, non un'accuratezza misurata o una copertura confermata. Per una previsione basata solo sul set di dati imposta options.ai_mode: off.
Scegli un linguaggio di programmazione. Configura la tua chiave API, poi esegui l'esempio sul tuo server.
Ogni richiesta di previsione è una nuova operazione a pagamento, anche quando è un nuovo tentativo. Questi esempi non riprovano automaticamente. Controlla lo stato dell'addebito prima di inviare un'altra richiesta.
Prima dell'esecuzione: accesso e gestione degli errori
Esegui questi esempi sul tuo server. Imposta GENDERAPI_API_KEY nell'ambiente del processo con la tua chiave API esistente. Verifica che meta.access.mode sia api_key: una chiave non riconosciuta può portare alla prova IP.
Per le risposte JSON con HTTP 4xx e 5xx, il corpo dell'errore viene conservato e l'esempio termina con un codice di uscita diverso da zero. Controlla code, action e meta.usage.billing_status prima di riprovare.
Guida a errori e nuovi tentativi →cURL 7.76+ in una shell POSIX. Esegui nel terminale. Documentazione del runtime
Node.js 22+; fetch integrato. Salva come example.mjs ed esegui node example.mjs. Documentazione del runtime
Python 3.10+; libreria standard. Salva come example.py ed esegui python3 example.py. Documentazione del runtime
PHP 8+ con l'estensione cURL. Salva come example.php ed esegui php example.php. Documentazione del runtime
Java 17+; client HTTP standard. Salva come GenderApiExample.java ed esegui java GenderApiExample.java. Documentazione del runtime
Applicazione console .NET 8+. Usalo come Program.cs in un progetto console, poi esegui dotnet run. Documentazione del runtime
Go 1.22+; libreria standard. Salva come main.go ed esegui go run main.go. Documentazione del runtime
Salvare il risultato insieme alle evidenze
Un'associazione dedotta non è il genere dichiarato da una persona. Salva separatamente l'input originale, le evidenze restituite e ciò che la persona ha dichiarato. Un risultato sconosciuto è un risultato valido e non dovrebbe diventare una categoria indovinata nella tua applicazione.
| Campo | Utilizzo |
|---|---|
data.gender / data.result_status | Usa male o female solo con identified. In caso di risultato sconosciuto conserva il valore JSON null nativo. |
data.name / data.match | Verifica il nome restituito e il candidato selezionato. Una corrispondenza su una sottostringa non dimostra che l'input appartenga a una persona con quel nome. |
data.confidence / data.confidence_kind | La confidenza è su una scala da 0 a 1 oppure è null. observed_frequency si basa su frequenze memorizzate; model_reported è un valore fornito dall'IA. Valuta le soglie separatamente per ciascun tipo. |
data.source / data.sample_count | Distingui tra dataset, ai e none. I risultati dell'IA non hanno una dimensione del campione memorizzata. Una dimensione del campione non è un valore di accuratezza misurato. |
meta.access.mode | In un'integrazione con account verifica che venga riportato api_key. Le chiavi mancanti o non riconosciute possono invece usare la prova IP condivisa. |
meta.usage | Leggi charged_credits e billing_status. Un risultato sconosciuto riuscito viene addebitato. Una risposta persa non dimostra che la richiesta sia stata gratuita. |
Decidere quando usare l'IA
forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente. Quando è attivo, ometti ai_mode o usa fallback; off e always non possono essere combinati con questa opzione e restituiscono 422. Un saldo iniziale positivo basta per avviare una richiesta, anche se l'addebito finale rende il saldo negativo.
La modalità nickname può restituire un genere insieme a name: null. Può anche dare un risultato sconosciuto. Né il normale fallback IA né l'interpretazione dei nickname garantiscono una risposta corretta o un valore diverso da null.
| Opzione della richiesta | Comportamento | Crediti per una ricerca riuscita |
|---|---|---|
| options.ai_mode: off | Usa solo il set di dati. | 1, anche per un risultato sconosciuto |
| options.ai_mode: fallback | Consulta prima il set di dati e poi usa la normale IA se non viene restituito un genere. È il valore predefinito per le richieste singole. | 1 in totale, fallback IA incluso |
| options.ai_mode: always | Usa direttamente l'IA. | 2 |
| forceToGenderize: true | Consulta prima il set di dati e poi lascia che l'IA interpreti un nickname personale o un alias, anche senza un vero nome proprio. | 1 per un risultato trovato nel set di dati; 2 in totale se viene usata l'IA |
Elaborare un elenco di nomi senza perdere il contesto
Invia fino a 50 elementi con una chiave API o 10 con la prova IP tramite POST /api/v2/gender/batch. Assegna a ogni elemento un id univoco e conserva il valore originale di ogni riga. Ogni elemento può avere opzioni proprie per il paese e l'IA; ometti il paese quando non è noto.
A differenza delle richieste singole, che usano il fallback per impostazione predefinita, gli elementi di un batch usano per impostazione predefinita solo il set di dati. Imposta options.ai_mode: fallback per ogni elemento che richiede l'IA. Controlla ogni risultato, anche dopo HTTP 200, conserva i risultati sconosciuti e verifica errori e addebito prima di un nuovo invio. Ogni elemento normale riuscito costa 1 credito; una richiesta HTTP batch non corrisponde a un credito per previsione.
Sapere che cosa invii
La demo in tempo reale invia il valore inserito a GenderAPI.io solo quando lo invii tu. Se viene usata l'IA, type, value e il contesto del paese inviati vengono trasmessi al servizio configurato per le previsioni. Per una previsione basata solo sul set di dati, nella tua integrazione imposta options.ai_mode: off senza forceToGenderize.
L'informativa sulla privacy, l'accordo sul trattamento dei dati e l'elenco dei sub-responsabili descrivono le condizioni di trattamento pubblicate. Un risultato è un'associazione dedotta e ciò che una persona dichiara ha la precedenza. Non usarlo come base per decisioni con conseguenze rilevanti per una persona.
Domande frequenti
La demo per i nomi indiani accetta solo nomi in hindi?
La demo usa un esempio in devanagari, ma l'API accetta nomi come stringhe Unicode. Questa possibilità non implica né una copertura completa del set di dati né un'accuratezza misurata per ogni lingua usata in India.
La grafia latina restituisce lo stesso risultato dell'alfabeto originale?
Non è garantito. La ricerca attuale non prevede un'equivalenza generale tra traslitterazioni. Conserva ogni grafia inviata insieme alle informazioni source, match e confidence restituite.
È stata pubblicata una valutazione indipendente dell'accuratezza per questo gruppo di nomi?
Questa pagina non pubblica una valutazione di questo tipo. L'accettazione dell'input, la visualizzazione delle frequenze memorizzate o la restituzione di un valore di confidenza non sono una misurazione indipendente dell'accuratezza. La metodologia indica quali dati sono disponibili e quali misurazioni non sono ancora state pubblicate.
Un risultato senza previsione consuma crediti?
Un risultato sconosciuto riuscito viene addebitato. La modalità normale con il set di dati o con il fallback costa 1 credito in totale. Con forceToGenderize la richiesta costa 1 credito se il risultato proviene dal set di dati, oppure 2 in totale se viene usata l'IA, anche in caso di risultato sconosciuto. Per gli errori valgono regole di addebito separate; controlla meta.usage.