# Usare GenderAPI.io V2 con Python

> Chiama GenderAPI.io V2 da Python con un esempio basato sulla libreria standard. Invia nomi, indirizzi email e nomi utente, elabora batch misti e leggi i campi data/meta.

Canonical HTML: https://www.genderapi.io/it/integrations/python

Last reviewed: 2026-09-28

## Ambiente di esecuzione ed esempio da scaricare

Python 3.10+. Esempio di integrazione HTTP da scaricare; nessun SDK pubblicato separatamente.

- [Scarica l'esempio](https://www.genderapi.io/examples/v2/genderapi_v2.py)

## Preparare un progetto Python lato server

Questa guida chiama l'endpoint di GenderAPI.io V2 https://api.genderapi.io/api/v2/gender con la chiave API nell'intestazione Bearer. Usa Python 3.10 o versioni successive e scarica genderapi_v2.py nel tuo progetto. L'esempio usa urllib.request e json della libreria standard di Python; non richiede alcun pacchetto pip.

Imposta GENDERAPI_API_KEY nell'ambiente del server. YOUR_API_KEY nell'esempio seguente non è una chiave valida. Non inserire credenziali reali in file sotto controllo di versione, notebook condivisi o applicazioni lato client. Importare il modulo o eseguirlo senza opzioni demo non invia alcuna richiesta.

**Configurare l'ambiente Python**

```bash
python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"
```

- [Scarica genderapi_v2.py](https://www.genderapi.io/examples/v2/genderapi_v2.py)
- [Verificare la chiave con l'endpoint gratuito di utilizzo](https://www.genderapi.io/it/docs/v2/authentication#environment-setup)

## Inviare una richiesta esplicita basata solo sul set di dati

Salva il codice seguente come single.py accanto al file scaricato ed esegui python3 single.py. Il modulo di supporto invia type: name, value: Alice e options.ai_mode: off in JSON. La previsione si legge in data, mentre le informazioni sulla richiesta e sull'addebito si trovano in meta.

Una chiamata riuscita costa 1 credito, anche in caso di risultato sconosciuto; il nome di esempio non garantisce una previsione. make_item accetta name, email o username e richiede una modalità IA esplicita. Aggiungi country solo quando disponi di un contesto pertinente.

Prima di inviare qualsiasi cosa, il modulo di supporto richiede una chiave API esadecimale di 24 caratteri. Questo verifica il formato della chiave, non la sua esistenza. Il modulo rifiuta inoltre le risposte riuscite della prova IP come modalità di accesso inattesa; il controllo avviene dopo la ricezione della risposta e non può annullare un credito di prova già consumato.

**Ricerca singola in Python**

```python
from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])
```

- [Tutti i campi delle richieste singole](https://www.genderapi.io/it/docs/v2/request-parameters)

## 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. |

- [Campi della risposta e risultati sconosciuti](https://www.genderapi.io/it/docs/v2/responses)
- [Accuratezza e confidenza spiegate](https://www.genderapi.io/it/accuracy-methodology)
- [Fonti dei dati e profilo datato del database](https://www.genderapi.io/it/data-provenance)

## Elaborare un batch misto e conservare l'id di ogni riga

GenderAPI.io V2 elabora batch misti tramite POST https://api.genderapi.io/api/v2/gender/batch: fino a 50 elementi con una chiave dell'account o 10 con la prova IP. Questi esempi richiedono una chiave dell'account. Assegna a ogni elemento un id stabile e univoco e una modalità IA esplicita. Un batch può combinare nomi, indirizzi email e nomi utente, e ogni elemento può avere un contesto country facoltativo.

Leggi ogni elemento in data e il riepilogo in meta.summary. Una risposta HTTP 200 può contenere errori di singoli elementi; un batch in cui tutti gli elementi non sono riusciti può restituire una risposta Problem di primo livello con i risultati. I risultati sconosciuti riusciti vengono contati in succeeded. Con index e id colleghi ogni risultato alla riga di origine corretta.

Per i lavori più grandi suddividi l'input in gruppi di al massimo 50 elementi e inviali inizialmente uno alla volta. Salva ogni risposta e il relativo utilizzo prima di passare al gruppo successivo. Fermati in caso di errore di trasporto, di errore di accesso all'account o di addebito non confermato e chiarisci la situazione del gruppo corrente. Introduci invii paralleli solo dopo aver verificato i limiti del tuo account; la dimensione massima del batch non garantisce una determinata capacità di elaborazione.

**Ricerca batch in Python**

```python
from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)
```

- [Input, risultati e addebito dei batch](https://www.genderapi.io/it/docs/v2/batch)

## 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.

Il modulo di supporto per Python richiede sempre ai_mode. Per l'interpretazione dei nickname usa make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Il modulo converte force_to_genderize nel campo JSON forceToGenderize.

| 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 |

- [Opzioni IA e interpretazione dei nickname](https://www.genderapi.io/it/docs/v2/ai-options)
- [Crediti e utilizzo](https://www.genderapi.io/it/docs/v2/credits-and-usage)

## Decidere che cosa fare dopo un errore

Gli esempi inviano ogni operazione una sola volta. Non la ripetono mai automaticamente: un nuovo invio è una nuova operazione soggetta ad addebito. Un timeout o un errore di connessione significa che il client non ha ricevuto una risposta completa; non dimostra che il server abbia interrotto l'elaborazione né che non siano stati addebitati crediti.

Salva il request_id restituito e lo stato dell'addebito insieme al record del tuo lavoro. L'oggetto di errore conserva la risposta per un'analisi controllata, ma può contenere l'input originale: non scrivere nei log ordinari né l'intero oggetto né la risposta né la chiave API.

| Situazione | Decisione dell'applicazione |
| --- | --- |
| Risultato sconosciuto riuscito | Conserva null, reason e usage. È un risultato completato e addebitato, non una riga non riuscita da ritentare automaticamente. |
| Errore di convalida 422 | Correggi l'input indicato nei campi di Problem Details prima di inviare una nuova richiesta. |
| 401 / 403 | Verifica l'accesso all'account o il saldo disponibile. Inviare di nuovo la stessa richiesta non risolve la causa. |
| 429 | Rispetta l'intestazione Retry-After, se presente. Verifica l'errore e lo stato dell'addebito, poi pianifica consapevolmente il tentativo successivo. |
| Errore di rete, timeout o risposta illeggibile | Registra che il risultato e l'addebito non sono confermati. Chiarisci la situazione prima di inviare di nuovo; il client non può annullare un'elaborazione già completata sul server. |
| billing_status: unconfirmed | charged_credits e remaining_credits possono essere null. Contatta l'assistenza indicando il request_id prima di un nuovo tentativo; non sostituire null con zero crediti. |
| Errori in alcuni elementi di un batch | Salva prima gli elementi completati. Verifica gli elementi non riusciti e il relativo addebito; invia di nuovo solo gli errori ammissibili, non l'intero batch. |

- [Problem Details e decisioni sui nuovi tentativi](https://www.genderapi.io/it/docs/v2/errors-and-retries)
- [Crediti e conferma dell'addebito](https://www.genderapi.io/it/docs/v2/credits-and-usage)

## Conoscere il comportamento di rete dell'esempio

Il timeout di 10 secondi di urllib si applica alle operazioni bloccanti sui socket; non è un limite garantito alla durata totale della richiesta. L'esempio disattiva i reindirizzamenti HTTP, analizza le risposte JSON riuscite e conserva le risposte Problem HTTP. Non ripete mai automaticamente le richieste.

I test locali usano risposte di trasporto simulate per chiamate riuscite, risultati sconosciuti, batch parzialmente riusciti, accesso all'account ed errori. Verificano la logica di controllo dell'esempio; non misurano la disponibilità dell'API in produzione, l'accuratezza dell'inferenza o i tempi di risposta. Ogni comando demo esplicito riportato di seguito invia una propria richiesta soggetta ad addebito.

**Demo esplicite facoltative in Python**

```bash
python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch
```

- [Documentazione Python su urllib.request](https://docs.python.org/3/library/urllib.request.html)
- [Documentazione Python su HTTPError](https://docs.python.org/3/library/urllib.error.html)

## Perché Python mostra None invece di null?

Il decodificatore JSON di Python converte null in None. Conserva il valore sconosciuto: non sostituirlo con un genere predefinito né con una confidenza pari a zero quando salvi o esporti il risultato.

## Un risultato sconosciuto consuma crediti?

Sì. Una normale ricerca riuscita costa 1 credito, anche quando gender è null. Il normale fallback IA è incluso in quel credito. La modalità always costa 2 crediti; forceToGenderize costa 1 credito se il risultato proviene dal set di dati, oppure 2 se viene usata l'IA.

## L'esempio ripete una richiesta non riuscita?

No. Ogni nuova richiesta è un'operazione a sé. Verifica l'errore, i risultati dei singoli elementi e lo stato dell'addebito prima di decidere se inviare di nuovo. Una risposta mancante non dimostra che il tentativo precedente sia stato gratuito.

## Devo installare un pacchetto?

No. Scarica l'esempio direttamente da questa guida di GenderAPI.io. Non ha dipendenze di esecuzione da pacchetti esterni e non è un SDK separato pubblicato su pip o npm. Esaminalo e adattalo alla tua applicazione; per il contratto dell'API fa fede la documentazione di GenderAPI.io V2.

## Documentazione di riferimento

- [Autenticazione in GenderAPI.io V2](https://www.genderapi.io/it/docs/v2/authentication)
- [Campi della risposta V2](https://www.genderapi.io/it/docs/v2/responses)
- [Risultati e limiti dei batch](https://www.genderapi.io/it/docs/v2/batch)
- [Documentazione su errori e nuovi tentativi](https://www.genderapi.io/it/docs/v2/errors-and-retries)