Utilizzo di Base

GenderAPI ti permette di determinare il genere di una persona utilizzando diversi tipi di dati in ingresso. Puoi analizzare direttamente i nomi propri oppure estrarre nomi da indirizzi email e nomi utente. Ecco come iniziare:

1. Genere dal Nome

Invia un nome proprio al seguente endpoint: 

https://api.genderapi.io/api

Esempio: 

curl "https://api.genderapi.io/api?name=Alice&key=YOUR_API_KEY"

Puoi anche aggiungere parametri opzionali:

  • country: Passa un codice paese a due lettere ( ISO 3166-1 alpha-2 ) per migliorare la precisione della previsione. Ad esempio: country=TR per la Turchia.
  • askToAI: Se impostato su true, l’API chiederà a un modello AI di determinare il genere se il nome non è presente nel database.
  • forceToGenderize: Se impostato su true, l’API proverà a indovinare il genere anche per input che non sembrano veri nomi umani, come soprannomi o nomi di fantasia come sparkling unicorn o mystic warrior. Può essere utile per analizzare nomi utente, ma i risultati potrebbero essere meno accurati. Nota: Questo parametro non è disponibile per l’endpoint email.

Esempio con parametri: 

curl "https://api.genderapi.io/api?name=sparkling%20unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

2. Genere da Indirizzo Email

Utilizza questo endpoint se hai solo un indirizzo email: 

https://api.genderapi.io/api/email

Esempio: 

curl "https://api.genderapi.io/api/email?email=alice.smith@example.com&country=TR&askToAI=true&key=YOUR_API_KEY"

Nota: Il parametro forceToGenderize non è disponibile per l’endpoint email perché questo endpoint estrae prima il nome internamente.


3. Genere dal Nome Utente

Per nomi utente o soprannomi, utilizza: 

https://api.genderapi.io/api/username

Esempio: 

curl "https://api.genderapi.io/api/username?username=sparkling_unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"

Il parametro forceToGenderize è particolarmente utile qui perché i nomi utente spesso contengono parole che non sono nomi reali o termini di fantasia. Costringe l’API a tentare una previsione del genere anche se l’input non è un nome umano tradizionale.

Tutti i metodi supportano richieste singole o multiple. Per ulteriori dettagli, consulta le sezioni specifiche nel menu di navigazione a sinistra.


✅ Risposta dell’API

Esempio di risposta JSON per tutti gli endpoint: 

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "michael.smith@example.com",
  "name": "Michael",
  "gender": "male",
  "country": "US",
  "total_names": 325,
  "probability": 98,
  "duration": "4ms"
}

Campi di Risposta

Campo Tipo Descrizione
status Boolean true se la richiesta è stata eseguita con successo. Controlla eventuali errori se è false.
used_credits Integer Numero di crediti utilizzati per questa richiesta.
remaining_credits Integer Crediti rimanenti nel tuo account dopo questa richiesta.
expires Integer (timestamp) Data di scadenza del pacchetto in formato UNIX timestamp (secondi).
q String La tua query in ingresso (nome, email o nome utente).
name String Il nome trovato o estratto.
gender Enum[String] Genere previsto. Valori possibili: male, female o null.
country Enum[String] Codice paese più probabile (ad es. US o DE).
total_names Integer Numero di campioni utilizzati per la previsione.
probability Integer Percentuale di probabilità della previsione di genere (ad es. 50-100).
duration String Tempo di elaborazione della richiesta (ad es. 4ms).
Attenzione: Se i tuoi valori in ingresso contengono spazi o caratteri speciali (ad es. sparkling unicorn), assicurati sempre di eseguire l’URL encoding prima di effettuare richieste GET. Altrimenti, la richiesta potrebbe fallire oppure altri parametri potrebbero essere interpretati in modo errato dal tuo linguaggio di programmazione o dalla libreria HTTP. 
curl "https://api.genderapi.io/api?name=sparkling unicorn&key=YOUR_API_KEY"
dovresti invece usare: 
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&key=YOUR_API_KEY"
oppure applicare le opportune funzioni di URL encoding nel tuo linguaggio di programmazione.