Assistenza per GenderAPI.io V2
Domande frequenti
Risposte su richieste V2, confidenza, risultati sconosciuti, crediti, privacy e account. Se gestisci un'integrazione con la versione precedente, usa la documentazione V1.
Risultati e confidenza
Capire le previsioni e i loro limiti
Contesto geografico, valori di confidenza e risultati sconosciuti nell'API V2.
Un risultato di GenderAPI stabilisce il genere di una persona?
No. GenderAPI deduce il genere da segnali legati al nome o, quando l'opzione è attiva, da segnali presenti nei nickname. Una previsione non è un dato verificato su una persona. Conserva l'incertezza, rispetta l'identità di genere dichiarata dalla persona e non basare decisioni con conseguenze rilevanti solo su questa stima.
In che modo il contesto geografico influisce su un risultato?
Un codice paese ISO facoltativo in maiuscolo fornisce alla richiesta un contesto regionale. Indicalo solo quando è pertinente e noto. Lo stesso nome può essere usato in modo diverso nelle varie regioni; il paese restituito descrive un legame con il nome e non prova cittadinanza o residenza.
Che cosa significa il valore di confidenza in V2?
confidence è un valore da 0 a 1, oppure null quando non è disponibile alcun valore. Leggilo insieme a confidence_kind: observed_frequency indica il conteggio della categoria prevalente nel set di dati diviso per il conteggio totale; model_reported è un valore indicato dall'IA. Questi valori non sono probabilità calibrate su una persona né un'accuratezza del prodotto misurata. Definisci le soglie di revisione sulla base di dati rappresentativi.
Che cosa significa gender: null e questo risultato viene addebitato?
Un risultato V2 riuscito con gender: null significa che i segnali disponibili non hanno permesso di determinare il genere. Si tratta del valore null nativo di JSON, non della stringa "null". Un risultato sconosciuto riuscito viene addebitato secondo il costo della modalità scelta. Trattalo come sconosciuto; un errore del provider o della richiesta è un caso di errore distinto.
Posso inviare nomi in sistemi di scrittura diversi?
Sì. Invia i nomi in Unicode con i caratteri originali e i segni diacritici significativi. Copertura e confidenza dipendono dal nome, dalla regione e dai segnali disponibili. Verifica quindi un campione rappresentativo dei sistemi di scrittura e dei paesi gestiti dalla tua applicazione.
API e IA
Scegli il tipo di richiesta e le opzioni IA
Tipi di richiesta V2, batch, comportamento dell'IA e limiti di utilizzo.
Posso analizzare nomi, indirizzi email e nomi utente in un batch?
Sì. POST /api/v2/gender/batch accetta fino a 50 elementi con chiave API o 10 con la prova IP. Ogni elemento ha i propri campi type e value, un country facoltativo e impostazioni IA proprie. Per impostazione predefinita l'IA è disattivata per gli elementi batch. Controlla ogni risultato: un batch può restituire HTTP 200 anche se singoli elementi non sono riusciti. I crediti vengono addebitati per ogni elemento elaborato correttamente, anche per i risultati sconosciuti.
Come funziona una richiesta con un indirizzo email?
Usa type: email con un indirizzo valido. L'API cerca un segnale di nome utilizzabile nella parte locale prima della @; il dominio non dice nulla sull'identità o sul paese di una persona. Le caselle condivise e gli indirizzi senza segnale di nome possono dare un risultato sconosciuto. Una richiesta singola usa per impostazione predefinita l'IA quando il set di dati non fornisce un risultato.
Come funziona una richiesta con un nome utente?
Usa type: username. Una richiesta normale cerca un nome riconoscibile in un nome utente o in un nome visualizzato. Gli alias astratti possono dare un risultato sconosciuto. Attiva forceToGenderize se vuoi che, dopo una verifica senza esito nel set di dati, venga usata l'IA con analisi dei nickname; in questo modo il genere può essere determinato anche senza estrarre un vero nome.
Quando V2 usa l'IA?
Le richieste singole usano per impostazione predefinita options.ai_mode: fallback: viene consultato prima il set di dati e, se il genere non viene determinato, si usa l'IA, per 1 credito in totale. off usa solo il set di dati per 1 credito; always salta il set di dati e usa l'IA per 2 crediti. Gli elementi batch usano off per impostazione predefinita e possono attivare l'IA singolarmente. Nessuna di queste modalità garantisce un risultato diverso da null.
Che cosa fa forceToGenderize?
Questo flag facoltativo funziona con nomi, indirizzi email e nomi utente, anche nei singoli elementi di un batch. Un risultato determinato dal set di dati costa 1 credito. Altrimenti viene usata l'IA con analisi dei nickname, per 2 crediti in totale, anche se il risultato riuscito rimane sconosciuto. Non è necessario un vero nome. Ometti ai_mode o usa fallback; combinare il flag con off o always restituisce 422.
Come vengono addebitati i crediti in V2?
Leggi meta.usage.charged_credits per i crediti effettivamente addebitati per un'operazione e billing_status per la conferma dell'addebito. Le normali previsioni dal set di dati e in modalità fallback costano 1 credito per ogni elemento elaborato correttamente; always e l'IA con analisi dei nickname costano 2 crediti. Una convalida completata di un numero di telefono costa 1 credito, anche con un risultato non valido. Basta un saldo iniziale positivo, quindi l'addebito finale può rendere il saldo negativo. I crediti delle previsioni non riuscite vengono rimborsati; un addebito non confermato deve essere verificato dall'assistenza.
Esistono limiti di richieste in V2?
Sì. I valori predefiniti attuali sono 120 richieste al minuto per account, 600 al minuto per indirizzo IP e 2 operazioni simultanee per account. Si applica inoltre la capacità condivisa del servizio. Le richieste POST sono limitate a 64 KiB; i batch accettano 50 elementi con chiave o 10 con la prova IP. Gestisci l'HTTP 429 e Retry-After invece di presumere che le richieste entro questi limiti vengano sempre accettate.
Posso ripetere una richiesta non riuscita o andata in timeout?
Ogni richiesta di previsione è una nuova operazione e viene addebitata normalmente. Un timeout o una risposta persa non dimostrano che non siano stati addebitati crediti. Controlla billing_status prima di riprovare; se l'addebito non è confermato, contatta l'assistenza indicando il request_id. In caso di batch parzialmente non riuscito, ripeti solo gli elementi non riusciti quando l'addebito è confermato. In caso di 429, rispetta l'intestazione Retry-After.
Dove trovo esempi di codice e strumenti per V2?
Le guide V2 contengono esempi in cURL, JavaScript, Python, PHP, Java, C# e Go. Swagger e Postman usano lo stesso contratto V2. Scegli il tipo di input e conserva la tua chiave API nella configurazione lato server.
Posso continuare a usare V1?
Sì. Le integrazioni V1 esistenti mantengono i loro endpoint e formati di risposta. V1 e V2 usano la stessa chiave API e lo stesso saldo, ma differiscono nei campi di richiesta, nelle risposte e negli errori. Usa la documentazione V1 separata per mantenere un client esistente e la guida alla migrazione quando vuoi passare a V2.
Privacy e file
Capire come vengono trattati i dati
Dove trovare informazioni aggiornate su trattamento, conservazione e cancellazione.
Le richieste riuscite a GenderAPI vengono conservate?
L'Informativa sulla privacy spiega quali dati delle richieste, dati operativi e log di sicurezza possono essere conservati, per quali finalità vengono trattati e come avviene la cancellazione. Verifica queste informazioni per la tua integrazione e non inviare dati personali non necessari.
Gli indirizzi email delle richieste vengono conservati?
L'Informativa sulla privacy descrive come vengono gestiti gli indirizzi email delle richieste e i relativi dati tecnici. Un indirizzo email può essere un dato personale: invia solo ciò che la richiesta richiede e non conservare indirizzi completi nei tuoi log diagnostici.
Per quanto tempo vengono conservati i file Excel o CSV caricati?
L'Informativa sulla privacy stabilisce conservazione, cancellazione e backup dei file caricati. Esporta i risultati che ti servono ed elimina il file con le funzioni dell'area di lavoro quando non ti serve più. Contatta l'assistenza se hai domande sui requisiti di conservazione della tua organizzazione.
I fornitori di servizi possono trattare i dati delle richieste o dei file caricati?
L'Informativa sulla privacy e le informazioni sui sub-responsabili del trattamento descrivono come i fornitori di servizi trattano i dati e quali misure di protezione si applicano. Esamina questi documenti e ogni accordo applicabile al tuo account quando valuti dove vengono trattati i tuoi dati.
Informativa sulla privacy →Sub-responsabili del trattamento →Informazioni sul GDPR →
Account e assistenza
Collega le chiavi e gestisci il tuo account
Accesso gratuito, autenticazione, controllo del saldo e assistenza.
Posso provare GenderAPI gratuitamente?
Sì. Un account gratuito registrato include 200 crediti al giorno. Indipendentemente da questo, la prova IP di V2 senza chiave offre 10 crediti per indirizzo IP pubblico ogni 24 ore, condivisi con V1 e con gli altri utenti dello stesso indirizzo IP. In entrambi i casi si applicano i normali costi; il numero di crediti non corrisponde sempre al numero di richieste HTTP.
Come mi autentico e proteggo la mia chiave API?
Usa Authorization: Bearer YOUR_API_KEY in codice lato server affidabile; le richieste POST richiedono inoltre Content-Type: application/json. Tieni la chiave reale fuori dal codice del browser, dai repository pubblici e dai log. Chiavi mancanti, con formato non valido o non riconosciute possono portare alla prova IP; verifica quindi che meta.access.mode abbia il valore api_key. Le chiavi riconosciute ma disattivate, scadute o limitate non passano alla prova.
Come controllo i crediti rimanenti?
Chiama GET /api/v2/usage con la tua chiave Bearer. Questo controllo del saldo è gratuito e restituisce data.remaining_credits. Senza chiave viene letto il saldo condiviso della prova IP. V1 e V2 usano lo stesso saldo dell'account; il valore remaining_credits in una previsione indica il saldo al momento in cui l'operazione è stata completata.
Dove posso gestire o annullare un abbonamento?
Accedi all'applicazione GenderAPI per gestire l'abbonamento collegato alla tua chiave API. Nelle impostazioni attuali dell'account trovi il tuo pacchetto e le opzioni di annullamento.
Dove posso modificare i miei dati di fatturazione?
Le impostazioni di fatturazione e pagamento si gestiscono dopo l'accesso all'applicazione GenderAPI, per ciascuna chiave API o abbonamento.
Come segnalo un risultato errato o ricevo aiuto con un'integrazione?
Invia all'assistenza la versione dell'API, l'endpoint, il request_id e un breve esempio riproducibile. Indica il codice di errore, se presente, ma rimuovi la tua chiave API e i dati personali sensibili.
Base di conoscenza tecnica
Guide all'implementazione e all'uso responsabile
Risposte su risultati, privacy e funzionamento di V2, con link alle guide e una versione Markdown di ogni risposta.
Risultati, confidenza e uso responsabile
Una previsione V2 non risolta restituisce per gender il valore null nativo di JSON, non la stringa "null". Un nome può essere ambiguo oppure i segnali disponibili possono non bastare; controlla result_status e reason quando sono presenti. Conserva il risultato sconosciuto invece di forzarlo in una categoria. Una previsione riuscita senza risultato viene addebitata secondo il costo della modalità scelta. Gli errori della richiesta o del provider sono casi di errore distinti; i dettagli sul relativo addebito sono in meta.usage.
Leggi la risposta completa →Come viene valutata l'accuratezza di GenderAPI?Una valutazione significativa dell'accuratezza indica la popolazione esaminata, la data, il metodo di campionamento, la quota di risultati sconosciuti e i risultati per regione e sistema di scrittura. L'attuale pagina sulla metodologia descrive un protocollo di valutazione, non un valore di accuratezza misurato in percentuale. I campi V2 confidence e confidence_kind spiegano su quali segnali si basa un risultato; non sostituiscono una valutazione con dati rappresentativi.
Leggi la risposta completa →Fonti dei dati, privacy e conformità
La pagina sulla provenienza dei dati descrive il quadro per documentare categorie di fonti, criteri di selezione, licenze e limiti geografici e relativi ai sistemi di scrittura. Al momento non vi è pubblicato un elenco di fonti verificato. Leggi quella pagina e contatta l'assistenza se la tua integrazione ha requisiti relativi alle fonti; non presumere fonti, dimensioni del set di dati o valori di copertura che non sono documentati.
Leggi la risposta completa →Con quale frequenza vengono aggiornati i dati sui nomi?L'attuale pagina sulla provenienza dei dati non indica un calendario di aggiornamento unico per tutti i record dei nomi o le regole di elaborazione. Se l'attualità dei dati è importante per il tuo caso d'uso, chiedi all'assistenza del set di dati o del processo in questione e verifica risultati rappresentativi. La data di revisione di una pagina non indica che tutti i record sottostanti siano stati aggiornati quel giorno.
Leggi la risposta completa →Dove trovo le informazioni sul GDPR e sull'accordo per il trattamento dei dati?L'informativa sulla privacy, le informazioni sul GDPR, l'accordo per il trattamento dei dati e l'elenco dei sub-responsabili del trattamento descrivono le condizioni di trattamento pubblicate e le misure di protezione. Esamina i documenti aggiornati e ogni accordo applicabile al tuo account. Per domande specifiche della tua organizzazione, per esempio sui ruoli nel trattamento, sui trasferimenti di dati o sulle richieste degli interessati, contatta GenderAPI; una FAQ generale non sostituisce l'accordo in vigore.
Leggi la risposta completa →Funzionamento dell'API, errori e addebiti
Usa Authorization: Bearer YOUR_API_KEY in codice lato server affidabile. Le richieste POST di V2 richiedono inoltre Content-Type: application/json. GET /api/v2/gender accetta anche una chiave come parametro di query, ma le intestazioni evitano che le credenziali compaiano negli URL del browser. Chiavi mancanti, con formato non valido o non riconosciute possono portare alla prova IP condivisa; in un'integrazione con account verifica che meta.access.mode abbia il valore api_key. Le chiavi riconosciute ma disattivate, scadute o limitate non passano a una prova.
Leggi la risposta completa →Come gestisco i limiti di richieste e i nuovi tentativi?V2 applica limiti al numero di richieste e alle richieste simultanee; gestisci l'HTTP 429 e Retry-After. Ogni previsione ripetuta è una nuova operazione e viene addebitata normalmente. Non ripetere automaticamente le richieste dopo un timeout, una risposta persa o un addebito non confermato. Controlla prima code, action e meta.usage.billing_status; in caso di billing_reconciliation_required contatta l'assistenza indicando il request_id. Usa un backoff limitato solo quando l'addebito è confermato e l'action documentata consente un nuovo tentativo.
Leggi la risposta completa →Come interpreto gli errori V2?Gli errori dell'API V2 usano codici di stato HTTP di errore e Problem Details secondo la RFC 9457, con i campi stabili code e action. Basati su questi campi invece di confrontare il testo di detail e conserva il request_id per l'assistenza. Un risultato sconosciuto riuscito non è un errore. Le risposte batch possono contenere errori per singoli elementi anche con HTTP 200. Un proxy può restituire un errore in un formato diverso da JSON, e una risposta persa o illeggibile non dimostra che non siano stati addebitati crediti.
Leggi la risposta completa →Come controllo i crediti rimanenti?Chiama GET /api/v2/usage con la tua chiave API nell'intestazione Bearer da codice lato server affidabile. Questa richiesta è gratuita e restituisce data.remaining_credits; senza chiave viene letto il saldo della prova IP condivisa. V1 e V2 usano lo stesso saldo dell'account. Il campo meta.usage di una previsione indica il costo di quell'operazione e il saldo al momento del suo completamento, che può cambiare con richieste simultanee. Tieni le credenziali fuori dai log e non considerare un controllo del saldo come prova che una determinata richiesta con risposta persa non sia stata addebitata.
Leggi la risposta completa →Come passo da V1 a V2 senza interruzioni?Crea le nuove integrazioni con V2 e lascia che i client V1 esistenti usino i loro endpoint documentati finché non vuoi passare a V2. Entrambe le versioni usano le stesse chiavi API e gli stessi crediti, ma differiscono nei campi di richiesta, nella struttura delle risposte e nel formato degli errori. Segui la guida alla migrazione, verifica risultati riusciti, sconosciuti ed errori e adatta la gestione delle risposte prima di cambiare endpoint. La documentazione V1 resta disponibile per le integrazioni esistenti.
Leggi la risposta completa →Come individuo gli errori e monitoro la disponibilità del servizio?Quando le richieste non riescono, usa il codice di errore restituito per distinguere tra disservizi, input non validi, problemi di accesso all'account, crediti esauriti e limiti di richieste. Monitora la quota di richieste riuscite e i tempi di risposta nella tua integrazione. Contatta l'assistenza indicando il request_id in caso di errore inspiegabile o di addebito poco chiaro. Basa le affermazioni sulla disponibilità su misurazioni; questa FAQ non indica alcun valore di disponibilità garantito in percentuale.
Leggi la risposta completa →Ti serve ancora aiuto?
Inviaci un esempio riproducibile
Indica endpoint, parametri della richiesta ed errore restituito, ma non inviare la tua chiave API di produzione né dati personali sensibili.