DOCUMENTAZIONE API V2

genere da un nome con API v2

Prevedi il genere dal nome o dal nome completo con GenderAPI v2. Visualizza esempi in sette lingue, risposte JSON, contesto nazionale, fallback IA e costi del credito.

Prima di inviare la richiesta

Invia JSON a POST https://api.genderapi.io/api/v2/gender. Utilizza la chiave API esistente in Authorization: Bearer YOUR_API_KEY e Content-Type: application/json. Ogni richiesta viene elaborata in modo indipendente.

Scegli la tua lingua nell'esempio di codice. Impostare GENDERAPI_API_KEY nell'ambiente del processo prima di eseguirlo. Le chiavi mancanti o non riconosciute possono utilizzare la versione di prova IP condivisa, quindi conferma che meta.access.mode è api_key quando integri un account.

Genere da un nome

ParametroTipoObbligatorioValore predefinitoDescrizione
typestringSì—Categoria di input: name, email o username.
valuestringSì—Obbligatorio. 1–254 caratteri; non vuoto, senza caratteri di controllo. I valori email devono avere una sintassi email valida.
countrystringNo—Codice ISO 3166-1 alpha-2 maiuscolo opzionale, ad esempio TR o US. La ricerca specifica per paese può ricorrere al set di dati globale.
forceToGenderizebooleanNofalseConsulta prima il dataset, poi l’IA per soprannomi se il risultato non è risolto. Supporta name, email e username.
optionsobjectNo—Oggetto contenente le opzioni IA di ciascun input.
options.ai_modestringNofallbackValori ammessi: off, fallback, always. Con forceToGenderize: true, ometti il campo o usa fallback.
idstringNo—Identificatore facoltativo con 1-64 caratteri nel corpo POST JSON. Deve essere univoco all'interno di un batch e viene restituito con il risultato del batch. Le richieste singole accettano questo identificatore ma non lo includono nella risposta. Le query GET non lo supportano.

Utilizza type: name per inviare un nome o un nome completo. Una risposta riuscita può contenere gender: null. Le richieste singole cercano prima il set di dati. Se non è possibile determinare il genere, utilizzano l'intelligenza artificiale per impostazione predefinita.

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

Ogni richiesta di previsione è una nuova operazione fatturabile, inclusi i nuovi tentativi. Questi esempi non riprovano automaticamente. Controlla lo stato della fatturazione prima di inviare un'altra richiesta.

Prima di eseguire: accesso e gestione degli errori

Esegui questi esempi sul tuo server. Impostare GENDERAPI_API_KEY nell'ambiente di processo sulla chiave API esistente. Conferma che meta.access.mode è api_key: una chiave non riconosciuta può ricadere nella versione di prova IP.

HTTP Le risposte 4xx e 5xx JSON preservano il corpo dell'errore e restituiscono uno stato di uscita diverso da zero. Controllare code, action e meta.usage.billing_status prima di riprovare.

Guida all'errore e al nuovo tentativo →
cURL
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": "Onur",
  "country": "TR"
}'

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

JavaScript / Node.js
// 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": "Onur",
  "country": "TR"
};

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+; recupero integrato. Salva come example.mjs ed esegui node example.mjs. Documentazione di runtime

Python
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\":\"Onur\",\"country\":\"TR\"}")

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

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Onur","country":"TR"}', 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 estensione cURL. Salva come example.php ed esegui php example.php. Documentazione di runtime

Java
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\":\"Onur\",\"country\":\"TR\"}";
        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 di runtime

C# / .NET
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\":\"Onur\",\"country\":\"TR\"}", 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+. Utilizzare come Program.cs in un progetto console, quindi eseguire dotnet run. Documentazione di runtime

Go
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\":\"Onur\",\"country\":\"TR\"}"
    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 di runtime

Esempio di risposta

Questa risposta sintetica illustra la forma dello JSON, non la precisione misurata o un risultato live garantito. Mostra l'accesso di prova IP; un'operazione autenticata riporta i campi quota di sola prova meta.access.mode: api_key e null. Leggere i dati per l'inferenza e meta.usage per l'esito della fatturazione dell'operazione.

Risposta JSON illustrativa
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

Campi della risposta di previsione

CampoTipoAmmette null?EsempioDescrizione
data.inputobjectNo{"type":"name","value":"Onur","country":"TR"}Tipo di input, valore e paese. forceToGenderize è incluso quando true.
data.namestringSì"onur"Nome abbinato o estratto; null quando nessuno è disponibile.
data.genderstringSì"male"male, female o JSON null. Questa è una previsione, non una prova dell'identità di una persona.
data.result_statusstringNo"identified"identified se viene restituito un genere; altrimenti unknown.
data.reasonstringSìnullnull per i risultati identified. Motivi dei risultati sconosciuti: not_found, no_name_candidate, ambiguous o insufficient_evidence.
data.confidencenumberSì0.95Punteggio 0–1 o null. Il genere null ha la confidenza null.
data.confidence_kindstringSì"observed_frequency"observed_frequency: il conteggio del genere dominante diviso per il conteggio totale nel set di dati selezionato. model_reported: un punteggio IA, non una probabilità calibrata. Il valore è null quando non disponibile.
data.sample_countintegerSì1200Dimensioni del campione del set di dati o null. L'intelligenza artificiale non inventa un conteggio dei campioni.
data.sourcestringNo"dataset"dataset, ai o none.
data.countrystringSì"TR"Associazione paese dal set di dati o ai_association o null. Non stabilisce nazionalità, residenza o etnia.
data.country_sourcestringSì"dataset"Origine dell’associazione al paese: dataset, ai_association o null.
data.matchobjectNo{"name":"onur","method":"normalized","scope":"country","country":"TR"}Nome corrispondente nel set di dati, metodo (normalized, token, substring o model_inference), ambito (country o global) e paese associato. Le informazioni non disponibili sono null.

Accesso, addebiti e metadati della richiesta

CampoTipoAmmette null?EsempioDescrizione
meta.request_idstringNo"550e8400-e29b-41d4-a716-446655440000"Identificatore univoco di questo tentativo HTTP; inviato anche in X-Request-ID.
meta.duration_msintegerNo42Tempo di elaborazione della richiesta in millisecondi.
meta.access.modestringNo"api_key"api_key, ip_trial o unauthenticated. Verifica api_key quando usi un account a pagamento.
meta.access.reasonstringSìnullMotivo del passaggio alla prova: api_key_missing, api_key_invalid o api_key_not_found; altrimenti null.
meta.usage.charged_creditsintegerSì1Crediti netti addebitati. Zero prima dell’addebito o dopo un rimborso completo confermato; null se l’addebito non è confermato.
meta.usage.remaining_creditsintegerSì99Saldo al termine dell’operazione. Può essere negativo; null se non disponibile o se l’addebito non è confermato.
meta.usage.billing_statusstringNo"confirmed"not_charged, confirmed o unconfirmed. Controlla prima di ripetere una previsione non riuscita.
meta.usage.resets_atstringSì"2026-09-27T12:00:00.000Z"Ripristino della prova per IP in UTC (ISO 8601); null per gli account con chiave API o se sconosciuto.
meta.usage.limitintegerSì10Crediti disponibili nella prova per IP; null per gli account con chiave API.
meta.usage.period_secondsintegerSì86400Durata della prova per IP in secondi; null per gli account con chiave API.

Contesto del paese e nomi sconosciuti

Fornisci il paese solo quando disponi di un contesto pertinente. Lo API può selezionare una riga del set di dati specifica del paese o ricorrere a una riga globale. data.match.scope mostra quale è stato selezionato; il paese rimpatriato non stabilisce dove vive la persona.

Per impostazione predefinita, una singola richiesta utilizza l'intelligenza artificiale quando il set di dati non può determinare un genere, per un totale di 1 credito. Per utilizzare solo il set di dati, inviare options: {"ai_mode": "off"}. Una richiesta completata costa comunque crediti se restituisce gender: null. Una ricerca per nome completo può corrispondere a una parte del nome. data.match registra il candidato scelto e il metodo di corrispondenza.

Per un nickname fornito come nome, forceToGenderize: true consente l'inferenza IA senza un vero nome. Un genere identificato nel dataset costa 1 credito. Se è necessaria l'IA, il costo totale è di 2 crediti. Qualsiasi saldo iniziale positivo è sufficiente; il saldo finale potrebbe essere negativo.

Guide correlate