Ottenere il genere tramite username - Richiesta singola

L’endpoint Get Gender by Username ti permette di determinare il genere di una persona analizzando uno username o un nickname. Tutti i parametri vengono inviati tramite una richiesta POST in formato JSON. È necessario autenticarsi usando il metodo Bearer token nell’intestazione Authorization.

URL della richiesta

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

Header HTTP richiesti

  • Content-Type: application/json
  • Authorization: Bearer YOUR_API_KEY

Parametri del corpo della richiesta (Request Body)

Parametro Tipo Obbligatorio Descrizione
username String Sì Lo username o nickname da analizzare. Può essere un handle social, uno screen name o un alias. Può contenere parole che non rappresentano nomi reali, come termini fantasy o riferimenti a brand.
country String No Un codice paese di due lettere (ISO 3166-1 alpha-2) per migliorare l’accuratezza della previsione. Esempio: TR per la Turchia.
askToAI Boolean No Se impostato su true, l’API chiederà a un modello AI di determinare il genere se il nome estratto non è presente nel database.
forceToGenderize Boolean No Se impostato su true, l’API proverà comunque a indovinare il genere anche per username che non sembrano nomi umani reali, come termini fantasy o soprannomi (es. sparkling_unicorn).

Esempi di richieste


Esempio cURL

curl -X POST "https://api.genderapi.io/api/username" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{"username": "sparkling_unicorn", "country": "US", "askToAI": true, "forceToGenderize": true}'

Esempio PHP cURL

<?php
$url = "https://api.genderapi.io/api/username";

$data = array(
    "username" => "sparkling_unicorn",
    "country" => "US",
    "askToAI" => true,
    "forceToGenderize" => true
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Esempio JavaScript fetch

fetch("https://api.genderapi.io/api/username", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    username: "sparkling_unicorn",
    country: "US",
    askToAI: true,
    forceToGenderize: true
  })
})
.then(response => response.json())
.then(data => console.log(data));

Esempio Python requests

import requests

url = "https://api.genderapi.io/api/username"

payload = {
    "username": "sparkling_unicorn",
    "country": "US",
    "askToAI": True,
    "forceToGenderize": True
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Esempio di risposta JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "sparkling_unicorn",
  "name": "Sparkling",
  "gender": "female",
  "country": "US",
  "total_names": 9876,
  "probability": 92,
  "duration": "6ms"
}

Campi nella risposta

Campo Tipo Descrizione
status Boolean Indica se la richiesta è andata a buon fine.
used_credits Integer Numero di crediti utilizzati per questa richiesta.
remaining_credits Integer Crediti rimasti nel tuo account dopo questa richiesta.
expires Integer (timestamp) Data di scadenza del pacchetto in formato UNIX timestamp.
q String La tua query di input (lo username inviato).
name String Il nome proprio estratto dallo username.
gender Enum[String] Genere previsto. Valori possibili: male, female o null.
country String Codice paese considerato durante la previsione.
total_names Integer Numero di campioni utilizzati per questa previsione.
probability Integer Percentuale di confidenza nella previsione del genere.
duration String Tempo impiegato per elaborare la richiesta (es. 6ms).