API genere dal nome: documentazione richiesta singola

Panoramica della richiesta

Invia un nome per richiesta

Invia un oggetto JSON con un nome proprio e autenticati con un token Bearer. Aggiungi il codice paese quando le convenzioni onomastiche regionali possono migliorare la previsione.

MetodoPOST

Content typeapplication/json

AutenticazioneToken Bearer

Costo in crediti1 ricerca

HDR

Header HTTP obbligatori

Autorizza la richiesta

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

Conserva la chiave API in variabili d’ambiente lato server. Consulta la guida all’autenticazione per proteggere le credenziali.

Corpo JSON della richiesta

Parametri

Parametro	Tipo	Requisito	Descrizione
`name`	string	Obbligatorio	Nome proprio da analizzare, senza titoli o prefissi.
`country`	string	Facoltativo	Codice paese ISO 3166-1 alpha-2, per esempio IT o US, per aggiungere il contesto regionale.
`askToAI`	boolean	Facoltativo	Se true, usa il supporto AI quando il nome non viene trovato nel database.
`forceToGenderize`	boolean	Facoltativo	Se true, tenta un risultato per nickname o input che non sembrano nomi tipici.

Informazioni sul supporto AI

askToAI viene applicato soltanto quando il database non restituisce risultati. Le previsioni forzate per input insoliti possono essere meno affidabili: considera sempre la probabilità come un segnale importante.

Esempi di codice

Esegui una richiesta singola

Gli esempi inviano la stessa richiesta usando l’autenticazione Bearer.

cURL

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

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "IT", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "IT", "askToAI": True}
)
print(response.json())

Risposta 200

Risultato della previsione

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "IT",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

Campi della risposta

Campo	Tipo	Descrizione
`status`	boolean	Indica se la richiesta è stata completata correttamente.
`used_credits`	integer	Crediti consumati dalla richiesta.
`remaining_credits`	integer	Crediti disponibili dopo la richiesta.
`expires`	integer	Scadenza del pacchetto come timestamp UNIX.
`q`	string	Nome originale inviato nella richiesta.
`name`	string	Nome analizzato da GenderAPI.
`gender`	string \| null	Valore previsto: male, female oppure null.
`country`	string	Codice paese considerato per la previsione.
`total_names`	integer	Numero di campioni alla base della previsione.
`probability`	integer	Attendibilità della previsione espressa in percentuale.
`duration`	string	Tempo di elaborazione sul server.

Invia input puliti e codificati correttamente

Usa un nome proprio senza titoli o prefissi. I client JSON gestiscono automaticamente la codifica, ma valida sempre gli input esterni prima di creare il corpo della richiesta.

Guida successiva

Analizza più nomi

Richiesta con più nomiElabora più nomi in una sola richiesta →AutenticazioneRivedi la sicurezza della chiave API →