GenderAPI.io V2: ricerca per nome e nome completo

Prima di inviare la richiesta

Invia le richieste di previsione a GenderAPI.io V2 con POST https://api.genderapi.io/api/v2/gender, indicando type e value nel corpo JSON. Usa la tua chiave GenderAPI.io esistente in Authorization: Bearer YOUR_API_KEY e Content-Type: application/json. Leggi il risultato in data e le informazioni su accesso e addebito in meta. Ogni richiesta viene elaborata in modo indipendente.

Scegli il linguaggio di programmazione nell'esempio di codice. Imposta GENDERAPI_API_KEY nell'ambiente del processo prima di eseguirlo. Le chiavi mancanti o non riconosciute possono usare la prova IP condivisa: quando integri un account, verifica quindi che meta.access.mode sia api_key.

Genere da un nome

Parametro	Tipo	Obbligatorio	Valore predefinito	Descrizione
`type`	`string`	Sì	`—`	Categoria di input: name, email o username.
`value`	`string`	Sì	`—`	Obbligatorio. 1–254 caratteri; non vuoto e senza caratteri di controllo. I valori email devono avere una sintassi email valida.
`country`	`string`	No	`—`	Codice ISO 3166-1 alpha-2 facoltativo, in maiuscolo, ad esempio TR o US. Una ricerca specifica per paese può ricorrere al set di dati globale.
`forceToGenderize`	`boolean`	No	`false`	Consulta prima il set di dati, poi l'IA con interpretazione dei nickname se non c'è un risultato. Supportato per name, email e username.
`options`	`object`	No	`—`	Oggetto con le opzioni IA per ciascun input.
`options.ai_mode`	`string`	No	`fallback`	Valori ammessi: off, fallback, always. Con forceToGenderize: true, ometti questo campo o usa fallback.
`id`	`string`	No	`—`	Identificatore facoltativo di 1–64 caratteri nel JSON POST. Viene restituito accanto al rispettivo risultato del batch e deve essere univoco all'interno del batch. Accettato ma non restituito per le previsioni singole. Non supportato nelle query GET.

Per un nome o un nome completo, invia type: name e l'input completo in value a POST https://api.genderapi.io/api/v2/gender. GenderAPI.io V2 usa gli stessi campi di richiesta per entrambi i formati. Anche una risposta riuscita può contenere data.gender: null. Le richieste singole consultano prima il set di dati e, per impostazione predefinita, usano l'IA quando da lì non è possibile determinare un genere.

Scegli un linguaggio di programmazione. Configura la tua chiave API, poi esegui l'esempio sul tuo server.

Ogni richiesta di previsione è una nuova operazione a pagamento, anche quando è un nuovo tentativo. Questi esempi non riprovano automaticamente. Controlla lo stato dell'addebito prima di inviare un'altra richiesta.

Prima dell'esecuzione: accesso e gestione degli errori

Esegui questi esempi sul tuo server. Imposta GENDERAPI_API_KEY nell'ambiente del processo con la tua chiave API esistente. Verifica che meta.access.mode sia api_key: una chiave non riconosciuta può portare alla prova IP.

Per le risposte JSON con HTTP 4xx e 5xx, il corpo dell'errore viene conservato e l'esempio termina con un codice di uscita diverso da zero. Controlla code, action e meta.usage.billing_status prima di riprovare.

Guida a errori e nuovi tentativi →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "Lorenzo",
  "country": "IT"
}'

cURL 7.76+ in una shell POSIX. Esegui nel terminale. Documentazione del runtime

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "name",
  "value": "Lorenzo",
  "country": "IT"
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+; fetch integrato. Salva come example.mjs ed esegui node example.mjs. Documentazione del runtime

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"name\",\"value\":\"Lorenzo\",\"country\":\"IT\"}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+; libreria standard. Salva come example.py ed esegui python3 example.py. Documentazione del runtime

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Lorenzo","country":"IT"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+ con l'estensione cURL. Salva come example.php ed esegui php example.php. Documentazione del runtime

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"name\",\"value\":\"Lorenzo\",\"country\":\"IT\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+; client HTTP standard. Salva come GenderApiExample.java ed esegui java GenderApiExample.java. Documentazione del runtime

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"Lorenzo\",\"country\":\"IT\"}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

Applicazione console .NET 8+. Usalo come Program.cs in un progetto console, poi esegui dotnet run. Documentazione del runtime

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"name\",\"value\":\"Lorenzo\",\"country\":\"IT\"}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+; libreria standard. Salva come main.go ed esegui go run main.go. Documentazione del runtime

Esempio di risposta

Questa è una risposta reale acquisita il 1° ottobre 2026 con una chiave API; è stato sostituito solo il saldo dell'account. Non è una misura dell'accuratezza e una richiesta in tempo reale può restituire un risultato diverso. Le richieste con chiave API riportano meta.access.mode: api_key e null nei campi di quota validi solo per la prova; le richieste tramite prova IP riportano ip_trial. Leggi data per la previsione e meta.usage per l'esito dell'addebito dell'operazione.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Lorenzo",
      "country": "IT"
    },
    "name": "lorenzo",
    "gender": "male",
    "country": "IT",
    "confidence": 0.996386630532972,
    "confidence_kind": "observed_frequency",
    "sample_count": 3321,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "lorenzo",
      "method": "normalized",
      "scope": "country",
      "country": "IT"
    }
  },
  "meta": {
    "request_id": "a1bda295-3045-4caa-8aa8-a461859ea5b3",
    "duration_ms": 12,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Campi della risposta e confidenza

Campi della risposta di previsione

Campo	Tipo	Può essere null	Esempio	Descrizione
`data.input`	`object`	No	`{"type":"name","value":"Lorenzo","country":"IT"}`	Tipo di input, valore e paese. forceToGenderize è incluso quando è true.
`data.name`	`string`	Sì	`"lorenzo"`	Nome proprio trovato o estratto; null se non disponibile.
`data.gender`	`string`	Sì	`"male"`	male, female o JSON null. Una previsione, non un'identità personale verificata.
`data.result_status`	`string`	No	`"identified"`	identified se viene restituito un genere; altrimenti unknown.
`data.reason`	`string`	Sì	`null`	null per i risultati identified. Motivi per unknown: not_found, no_name_candidate, ambiguous o insufficient_evidence.
`data.confidence`	`number`	Sì	`0.95`	Valore da 0 a 1 oppure null. Se gender è null, anche la confidenza è null.
`data.confidence_kind`	`string`	Sì	`"observed_frequency"`	observed_frequency: conteggio dominante nel set di dati diviso per il totale. model_reported: valore fornito dall'IA, non una probabilità calibrata. null se non disponibile.
`data.sample_count`	`integer`	Sì	`1200`	Dimensione del campione nel set di dati oppure null. L'IA non inventa un conteggio dei campioni.
`data.source`	`string`	No	`"dataset"`	dataset, ai o none.
`data.country`	`string`	Sì	`"IT"`	Associazione al paese da dataset o ai_association, oppure null. Non stabilisce nazionalità, residenza né origine etnica.
`data.country_source`	`string`	Sì	`"dataset"`	Origine dell'associazione al paese: dataset, ai_association o null.
`data.match`	`object`	No	`{"name":"lorenzo","method":"normalized","scope":"country","country":"IT"}`	Nome trovato nel set di dati, metodo (normalized, token, substring o model_inference), ambito country o global e paese associato. Le evidenze non disponibili sono null.

Metadati di accesso, addebito e richiesta

Campo	Tipo	Può essere null	Esempio	Descrizione
`meta.request_id`	`string`	No	`"550e8400-e29b-41d4-a716-446655440000"`	Identificatore univoco di questo tentativo HTTP; inviato anche in X-Request-ID.
`meta.duration_ms`	`integer`	No	`42`	Tempo di elaborazione della richiesta in millisecondi.
`meta.access.mode`	`string`	No	`"api_key"`	api_key, ip_trial o unauthenticated. Con un account a pagamento verifica che venga riportato api_key.
`meta.access.reason`	`string`	Sì	`null`	Motivo del passaggio alla prova IP: api_key_missing, api_key_invalid o api_key_not_found; altrimenti null.
`meta.usage.charged_credits`	`integer`	Sì	`1`	Crediti netti addebitati. Zero prima dell'addebito o dopo un rimborso completo confermato; null se l'addebito non è confermato.
`meta.usage.remaining_credits`	`integer`	Sì	`99`	Saldo al termine dell'operazione. Può essere negativo; null se non disponibile o se l'addebito non è confermato.
`meta.usage.billing_status`	`string`	No	`"confirmed"`	not_charged, confirmed o unconfirmed. Controllalo prima di ripetere una previsione non riuscita.
`meta.usage.resets_at`	`string`	Sì	`"2026-09-27T12:00:00.000Z"`	Momento del ripristino della prova IP in UTC (ISO 8601); null per gli account con chiave API o se sconosciuto.
`meta.usage.limit`	`integer`	Sì	`10`	Quota della prova IP; null per gli account con chiave API.
`meta.usage.period_seconds`	`integer`	Sì	`86400`	Durata del periodo della prova IP in secondi; null per gli account con chiave API.

Contesto del paese e nomi sconosciuti

Indica country solo se disponi di un contesto pertinente. L'API può selezionare una riga del set di dati specifica per il paese o ricorrere a una riga globale. data.match.scope indica quale è stata selezionata; il paese restituito non stabilisce dove vive la persona.

Per impostazione predefinita le richieste singole usano il fallback IA, per 1 credito in totale. Per usare solo il set di dati, invia options: {"ai_mode": "off"}. Gli input non risolti possono restituire gender: null e vengono comunque addebitati se l'operazione riesce. Un nome completo può trovare corrispondenza tramite una delle sue parti; data.match riporta il candidato selezionato e il metodo di corrispondenza.

Per valori di tipo name simili a un nickname, forceToGenderize: true consente una previsione senza un vero nome proprio: un risultato trovato nel set di dati costa 1 credito, altrimenti l'IA con interpretazione dei nickname costa 2 crediti in totale. Basta un saldo iniziale positivo e il saldo risultante può diventare negativo.

Cercare un nome completo senza dare per scontato che conti la prima parola

Invia il nome originale in Unicode. La corrispondenza con il set di dati usa la normalizzazione NFKC, le lettere minuscole e l'estrazione delle parti del nome; non devi convertire il nome in ASCII. Tra i candidati disponibili, l'API sceglie la voce del set di dati con il conteggio totale memorizzato più alto. Il candidato può essere una parte successiva del nome, quindi non dare per scontato che sia stata scelta la prima parola o il nome proprio.

Questa richiesta usa solo il set di dati, così è più facile verificare le evidenze selezionate. Leggi data.input.value per il nome completo inviato, data.match.name per il candidato cercato e data.match.method per il metodo di corrispondenza. L'esempio non promette un genere specifico né una determinata parte del nome selezionata. I candidati del set di dati devono avere più di due caratteri e gli input brevi possono restare senza risultato. Usa il normale fallback IA quando la previsione aggiuntiva è adatta alla tua applicazione.