GenderAPI.io V2 · Guide

Determinare il genere da nomi indiani

Prova i nomi usati in India con GenderAPI.io V2. Conserva la grafia originale, scegli il contesto IN in modo consapevole e interpreta correttamente le corrispondenze dei nomi completi, i risultati dell'IA e i risultati sconosciuti.

Ultimo aggiornamento:

Prova l'API V2

Analizza un nome

Set di dati + IA

Invia un valore ed esamina la risposta completa, inclusi i risultati sconosciuti e i crediti utilizzati.

Lo strumento usa un contesto del paese di esempio: India (IN). Non è un valore predefinito per tutti i nomi in questa lingua né una prova di nazionalità.

Richiesta standard: 1 credito, inclusi il fallback IA e i risultati sconosciuti. Con l'interpretazione dei nickname: 1 credito se il risultato viene dal set di dati, oppure 2 in totale se viene usata l'IA, anche quando il risultato è sconosciuto.

Il valore inviato (il nome) viene trasmesso a GenderAPI.io e può essere inoltrato al servizio IA configurato se serve il fallback IA. Maggiori informazioni sul trattamento dei dati.

Nessuna chiave API salvata. Puoi usare la prova IP condivisa finché ha crediti disponibili.

La risposta qui sotto è un esempio illustrativo. Fai clic su Analizza per inviare una richiesta.

Esempio di risposta V2 · nessun risultato in tempo reale
Nome—
GenereSconosciuto
Affidabilità—
FonteModello IA
Crediti usati1

Frequenze, valori e saldo dell'esempio mostrano il formato della risposta. I valori reali possono essere diversi. Una previsione non è un'identità confermata.

Usare il nome originale senza presupporre un unico alfabeto o un ordine fisso

La dimostrazione usa un esempio in devanagari e il contesto del paese IN. È un esempio di input e non una definizione di tutti i nomi usati in India. L'API accetta stringhe Unicode, quindi puoi inviare la grafia presente nel record della tua applicazione senza convertirla prima in caratteri latini.

La ricerca usa parti normalizzate. Non effettua una conversione generale tra alfabeti e non garantisce che una grafia latina e una grafia nell'alfabeto originale portino alla stessa voce. Conserva l'input originale insieme al nome restituito. Il fatto che un alfabeto venga accettato non implica un'accuratezza misurata in modo indipendente per ogni lingua o comunità.

Non dare per scontato che la prima o l'ultima parte abbia sempre lo stesso ruolo. V2 sceglie il candidato disponibile con il conteggio totale memorizzato più alto e non garantisce una posizione precisa del nome proprio. Iniziali, parti brevi e voci memorizzate mancanti possono lasciare irrisolto il risultato del set di dati; il fallback IA può interpretare l'intero valore inviato.

Esempio di inputChe cosa rappresentaChe cosa controllare
प्रिया शर्माNome completo in devanagariPiù parti possono diventare candidati. Verifica il nome scelto e la corrispondenza invece di presumere che prevalga la prima parte.
Priya SharmaEsempio in caratteri latiniÈ una grafia distinta; una corrispondenza identica tra alfabeti non è garantita.
A. KumarIniziale e un'altra parteUn'iniziale di una sola lettera non diventa un candidato del set di dati. Una corrispondenza sull'altra parte non conferma il nome proprio previsto.
country: INContesto di esempio: IndiaUsalo quando il tuo record ha un contesto del paese pertinente, non solo perché il nome compare in questa guida.

Scegliere consapevolmente il contesto del paese IN

La demo invia country: IN (India). L'API non sceglie il paese in base all'alfabeto in cui è scritto il nome. Nella tua integrazione usa un contesto del paese noto e pertinente oppure ometti country. Non trasformare questo valore di esempio in un valore predefinito per tutti i record.

Per ogni candidato, la ricerca sceglie la voce specifica del paese, se esiste, e altrimenti considera la voce globale. Seleziona poi il candidato disponibile con il conteggio totale memorizzato più alto. L'ambito effettivo della corrispondenza è indicato in data.match.scope e data.match.country. Una voce specifica del paese con frequenze in parità non viene sostituita automaticamente dal risultato globale; se il fallback è attivo, può essere usata invece l'IA.

data.input.country descrive il contesto inviato nella richiesta. data.country e data.country_source descrivono l'associazione con un paese restituita e la sua origine. Sono campi diversi e non indicano né la cittadinanza né l'origine etnica né il luogo di residenza.

Inviare una richiesta V2 per un nome dalla tua applicazione

Imposta GENDERAPI_API_KEY sulla tua chiave esistente ed esegui l'esempio sul tuo server. La richiesta attiva esplicitamente il normale fallback IA. Mostra il formato della richiesta, non un'accuratezza misurata o una copertura confermata. Per una previsione basata solo sul set di dati imposta options.ai_mode: off.

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
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": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
}'

cURL 7.76+ in una shell POSIX. Esegui nel terminale. Documentazione del 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": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
};

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

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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}")

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
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"प्रिया शर्मा","country":"IN","options":{"ai_mode":"fallback"}}', 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

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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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

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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}", 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

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\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    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

Salvare il risultato insieme alle evidenze

Un'associazione dedotta non è il genere dichiarato da una persona. Salva separatamente l'input originale, le evidenze restituite e ciò che la persona ha dichiarato. Un risultato sconosciuto è un risultato valido e non dovrebbe diventare una categoria indovinata nella tua applicazione.

CampoUtilizzo
data.gender / data.result_statusUsa male o female solo con identified. In caso di risultato sconosciuto conserva il valore JSON null nativo.
data.name / data.matchVerifica il nome restituito e il candidato selezionato. Una corrispondenza su una sottostringa non dimostra che l'input appartenga a una persona con quel nome.
data.confidence / data.confidence_kindLa confidenza è su una scala da 0 a 1 oppure è null. observed_frequency si basa su frequenze memorizzate; model_reported è un valore fornito dall'IA. Valuta le soglie separatamente per ciascun tipo.
data.source / data.sample_countDistingui tra dataset, ai e none. I risultati dell'IA non hanno una dimensione del campione memorizzata. Una dimensione del campione non è un valore di accuratezza misurato.
meta.access.modeIn un'integrazione con account verifica che venga riportato api_key. Le chiavi mancanti o non riconosciute possono invece usare la prova IP condivisa.
meta.usageLeggi charged_credits e billing_status. Un risultato sconosciuto riuscito viene addebitato. Una risposta persa non dimostra che la richiesta sia stata gratuita.

Decidere quando usare l'IA

forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente. Quando è attivo, ometti ai_mode o usa fallback; off e always non possono essere combinati con questa opzione e restituiscono 422. Un saldo iniziale positivo basta per avviare una richiesta, anche se l'addebito finale rende il saldo negativo.

La modalità nickname può restituire un genere insieme a name: null. Può anche dare un risultato sconosciuto. Né il normale fallback IA né l'interpretazione dei nickname garantiscono una risposta corretta o un valore diverso da null.

Opzione della richiestaComportamentoCrediti per una ricerca riuscita
options.ai_mode: offUsa solo il set di dati.1, anche per un risultato sconosciuto
options.ai_mode: fallbackConsulta prima il set di dati e poi usa la normale IA se non viene restituito un genere. È il valore predefinito per le richieste singole.1 in totale, fallback IA incluso
options.ai_mode: alwaysUsa direttamente l'IA.2
forceToGenderize: trueConsulta prima il set di dati e poi lascia che l'IA interpreti un nickname personale o un alias, anche senza un vero nome proprio.1 per un risultato trovato nel set di dati; 2 in totale se viene usata l'IA

Elaborare un elenco di nomi senza perdere il contesto

Invia fino a 50 elementi con una chiave API o 10 con la prova IP tramite POST /api/v2/gender/batch. Assegna a ogni elemento un id univoco e conserva il valore originale di ogni riga. Ogni elemento può avere opzioni proprie per il paese e l'IA; ometti il paese quando non è noto.

A differenza delle richieste singole, che usano il fallback per impostazione predefinita, gli elementi di un batch usano per impostazione predefinita solo il set di dati. Imposta options.ai_mode: fallback per ogni elemento che richiede l'IA. Controlla ogni risultato, anche dopo HTTP 200, conserva i risultati sconosciuti e verifica errori e addebito prima di un nuovo invio. Ogni elemento normale riuscito costa 1 credito; una richiesta HTTP batch non corrisponde a un credito per previsione.

Sapere che cosa invii

La demo in tempo reale invia il valore inserito a GenderAPI.io solo quando lo invii tu. Se viene usata l'IA, type, value e il contesto del paese inviati vengono trasmessi al servizio configurato per le previsioni. Per una previsione basata solo sul set di dati, nella tua integrazione imposta options.ai_mode: off senza forceToGenderize.

L'informativa sulla privacy, l'accordo sul trattamento dei dati e l'elenco dei sub-responsabili descrivono le condizioni di trattamento pubblicate. Un risultato è un'associazione dedotta e ciò che una persona dichiara ha la precedenza. Non usarlo come base per decisioni con conseguenze rilevanti per una persona.

Domande frequenti

La demo per i nomi indiani accetta solo nomi in hindi?

La demo usa un esempio in devanagari, ma l'API accetta nomi come stringhe Unicode. Questa possibilità non implica né una copertura completa del set di dati né un'accuratezza misurata per ogni lingua usata in India.

La grafia latina restituisce lo stesso risultato dell'alfabeto originale?

Non è garantito. La ricerca attuale non prevede un'equivalenza generale tra traslitterazioni. Conserva ogni grafia inviata insieme alle informazioni source, match e confidence restituite.

È stata pubblicata una valutazione indipendente dell'accuratezza per questo gruppo di nomi?

Questa pagina non pubblica una valutazione di questo tipo. L'accettazione dell'input, la visualizzazione delle frequenze memorizzate o la restituzione di un valore di confidenza non sono una misurazione indipendente dell'accuratezza. La metodologia indica quali dati sono disponibili e quali misurazioni non sono ancora state pubblicate.

Un risultato senza previsione consuma crediti?

Un risultato sconosciuto riuscito viene addebitato. La modalità normale con il set di dati o con il fallback costa 1 credito in totale. Con forceToGenderize la richiesta costa 1 credito se il risultato proviene dal set di dati, oppure 2 in totale se viene usata l'IA, anche in caso di risultato sconosciuto. Per gli errori valgono regole di addebito separate; controlla meta.usage.

Continua il test

Usa la tua chiave GenderAPI

Incolla la chiave API del tuo account GenderAPI per continuare i test quando i crediti condivisi della prova IP di 24 ore sono esauriti. Il salvataggio della chiave non invia alcuna richiesta: inviala di nuovo quando sei pronto.

Viene salvata solo in questa scheda del browser e rimossa alla chiusura.