GenderAPI.io V2 · Veiledning

Finn kjønn fra indiske navn

Prøv navn som brukes i India, i GenderAPI.io V2. Behold opprinnelige stavemåter, velg landkonteksten IN bevisst, og tolk treff på fulle navn, KI-resultater og ukjente resultater.

Sist oppdatert:

Prøv V2-API-et

Analyser et navn

Datasett + KI

Send en verdi og se hele svaret, inkludert ukjente resultater og brukte kreditter.

Verktøyet bruker en landkontekst som eksempel: India (IN). Dette er ikke en standardverdi for alle navn på dette språket og ikke et bevis på nasjonalitet.

Vanlig forespørsel: 1 kreditt, inkludert KI-reserve og ukjente resultater. Med tolkning av kallenavn: 1 kreditt hvis resultatet kommer fra datasettet, eller 2 kreditter totalt hvis KI brukes, også når resultatet er ukjent.

Verdien du sender (navnet), overføres til GenderAPI.io og kan videresendes til den konfigurerte KI-tjenesten hvis KI-reserve trengs. Les mer om hvordan dataene behandles.

Ingen lagret API-nøkkel. Du kan bruke den delte IP-prøveperioden så lenge den har kreditter igjen.

Svaret nedenfor er et illustrerende eksempel. Velg Analyser for å sende en forespørsel.

Eksempel på V2-svar · ikke et resultat i sanntid
Navn—
KjønnUkjent
Sikkerhet—
KildeAI-modell
Brukte kreditter1

Frekvenser, verdier og saldo i eksemplet viser bare formatet på svaret; faktiske verdier kan være annerledes. En prediksjon er ikke en bekreftet identitet.

Bruk det opprinnelige navnet uten å anta én skrift eller ett navnemønster

Denne demonstrasjonen bruker et eksempel på devanagari og landkonteksten IN. Det er ett eksempel på inndata og ikke en definisjon av alle navn som brukes i India. API-et tar imot Unicode-tegnstrenger, så du kan sende stavemåten som finnes i posten din, uten først å gjøre den om til latinske bokstaver.

Oppslaget i datasettet bruker normaliserte navnedeler. Det gjør ingen generell konvertering mellom skrifter og lover ikke at latinske stavemåter og stavemåter i den opprinnelige skriften gir den samme oppføringen. Behold de opprinnelige inndataene sammen med navnet som returneres. At en skrift godtas, betyr ikke at det finnes en uavhengig målt nøyaktighet for dette språket eller samfunnet.

Ikke anta at den første eller siste navnedelen har en fast rolle. V2 velger den tilgjengelige kandidaten med det høyeste lagrede totalantallet og garanterer ikke en bestemt plassering av fornavnet. Initialer, korte navnedeler og manglende lagrede treff kan gjøre at datasettet ikke gir noe resultat; KI-reserve kan forsøke hele verdien som ble sendt.

Eksempel på inndataHva det viserHva du bør kontrollere
प्रिया शर्माEksempel på et fullt navn på devanagariFlere navnedeler kan bli kandidater. Kontroller navnet og treffet som ble valgt, i stedet for å anta at den første navnedelen vinner.
Priya SharmaEksempel med latinske bokstaverDette er en separat stavemåte; det er ikke lovet et identisk treff på tvers av skrifter.
A. KumarInitial pluss en navnedelInitialen på én bokstav blir ikke en kandidat i datasettet. Et treff på den andre navnedelen bekrefter ikke det tiltenkte fornavnet.
country: INEksempelkontekst: IndiaBruk den når posten din har relevant landkontekst, ikke bare fordi navnet står i denne veiledningen.

Velg landkonteksten IN bevisst

Demoen i sanntid sender country: IN (India). API-et velger ikke dette landet ut fra skriften navnet er skrevet med. I integrasjonen din bruker du en kjent og relevant landkontekst, eller du utelater country; ikke gjør denne eksempelverdien til en standardverdi for alle poster.

For hver kandidat foretrekker oppslaget i datasettet en eksisterende landrad og vurderer ellers den globale raden. Deretter velges den tilgjengelige kandidaten med det høyeste lagrede totalantallet. Les data.match.scope og data.match.country for å se hvilket omfang treffet faktisk hadde. En landrad med likt antall for begge kjønn erstattes ikke automatisk av et globalt resultat; med fallback kan KI brukes i stedet.

data.input.country beskriver konteksten i forespørselen. data.country og data.country_source beskriver en tilknytning som returneres. Dette er ulike felt, og de fastslår ikke statsborgerskap, etnisitet eller bosted.

Send et indisk navn med V2

Kjør forespørselen på serveren din med GENDERAPI_API_KEY satt til den eksisterende nøkkelen din. Eksemplet aktiverer vanlig KI-reserve eksplisitt. Det viser hvordan en forespørsel ser ut, ikke en målt prediksjon eller en målt dekning. Bruk options.ai_mode: off hvis du bare vil bruke datasettet.

Velg et programmeringsspråk. Konfigurer API-nøkkelen, og kjør deretter eksemplet på serveren din.

Hver prediksjonsforespørsel er en ny operasjon som belastes, også nye forsøk. Disse eksemplene prøver ikke automatisk på nytt. Sjekk belastningsstatusen før du sender en ny forespørsel.

Før du kjører: tilgang og feilhåndtering

Kjør disse eksemplene på serveren din. Sett GENDERAPI_API_KEY i prosessmiljøet til din eksisterende API-nøkkel. Bekreft at meta.access.mode er api_key: en nøkkel som ikke gjenkjennes, kan føre til IP-prøveperioden.

Ved JSON-svar med HTTP 4xx og 5xx beholdes feilinnholdet, og eksemplet avsluttes med en exit-status som ikke er null. Sjekk code, action og meta.usage.billing_status før du prøver på nytt.

Veiledning om feil og nye forsøk →
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+ i et POSIX-skall. Kjør i terminalen. Dokumentasjon for kjøretidsmiljøet

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+; innebygd fetch. Lagre som example.mjs og kjør node example.mjs. Dokumentasjon for kjøretidsmiljøet

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+; standardbiblioteket. Lagre som example.py og kjør python3 example.py. Dokumentasjon for kjøretidsmiljøet

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+ med cURL-utvidelsen. Lagre som example.php og kjør php example.php. Dokumentasjon for kjøretidsmiljøet

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+; standard HTTP-klient. Lagre som GenderApiExample.java og kjør java GenderApiExample.java. Dokumentasjon for kjøretidsmiljøet

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.
}

Konsollapplikasjon i .NET 8+. Bruk som Program.cs i et konsollprosjekt, og kjør deretter dotnet run. Dokumentasjon for kjøretidsmiljøet

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+; standardbiblioteket. Lagre som main.go og kjør go run main.go. Dokumentasjon for kjøretidsmiljøet

Lagre resultatet sammen med grunnlaget

En utledet tilknytning er ikke det kjønnet en person selv har oppgitt. Lagre de opprinnelige inndataene, grunnlaget som ble returnert, og det personen selv har oppgitt, hver for seg. Et ukjent resultat er et gyldig resultat og bør ikke bli en gjettet kategori i applikasjonen din.

FeltBruk
data.gender / data.result_statusBruk male eller female bare sammen med identified. Ved et ukjent resultat beholder du den opprinnelige JSON-verdien null.
data.name / data.matchKontroller det returnerte navnet og den valgte kandidaten. Et treff på en delstreng beviser ikke at inndataene tilhører en person med dette navnet.
data.confidence / data.confidence_kindKonfidensen er en verdi fra 0 til 1 eller null. observed_frequency bygger på lagrede frekvenser; model_reported er en verdi fra KI. Evaluer tersklene separat for hver type.
data.source / data.sample_countSkill mellom dataset, ai og none. KI-resultater har ingen lagret utvalgsstørrelse. En utvalgsstørrelse er ikke en målt nøyaktighet.
meta.access.modeKontroller at api_key rapporteres i en integrasjon med konto. Nøkler som mangler eller ikke gjenkjennes, kan i stedet bruke den delte IP-prøveperioden.
meta.usageLes charged_credits og billing_status. Et vellykket ukjent resultat belastes. Et tapt svar beviser ikke at forespørselen var gratis.

Bestem når KI skal brukes

forceToGenderize er valgfritt for navn, e-postadresser og brukernavn. Når det er aktivert, utelater du ai_mode eller bruker fallback; off og always kan ikke kombineres med dette alternativet og gir 422. En positiv startsaldo er nok til å starte en forespørsel, selv om den endelige belastningen gjør saldoen negativ.

Kallenavnmodus kan returnere et kjønn sammen med name: null. Den kan også gi et ukjent resultat. Verken vanlig KI-reserve eller tolkning av kallenavn garanterer et riktig svar eller en verdi som ikke er null.

Alternativ i forespørselenVirkemåteKreditter for et vellykket oppslag
options.ai_mode: offBruker bare datasettet.1, også for et ukjent resultat
options.ai_mode: fallbackSøker først i datasettet og bruker deretter vanlig KI hvis det ikke returneres et kjønn. Dette er standard for enkeltforespørsler.1 totalt, inkludert KI-reserve
options.ai_mode: alwaysBruker KI direkte.2
forceToGenderize: trueSøker først i datasettet og lar deretter KI tolke et personlig kallenavn eller alias, selv uten et ekte fornavn.1 for et resultat fra datasettet; 2 totalt hvis KI brukes

Behandle en navneliste uten å miste konteksten

Bruk POST /api/v2/gender/batch for høyst 50 elementer med en registrert API-nøkkel eller 10 elementer i IP-prøveperioden. Gi hvert element en unik id, og behold den opprinnelige verdien for hver rad. Hvert element kan ha sitt eget land og sine egne KI-regler; utelat country når landet er ukjent.

I motsetning til enkeltforespørsler, der fallback er standard, bruker elementer i en samleforespørsel bare datasettet som standard. Angi options.ai_mode: fallback for hvert element som trenger KI. Kontroller hvert resultat, også etter HTTP 200, behold ukjente resultater, og gå gjennom feil for enkeltelementer og belastningen før du sender på nytt. Hvert vellykket vanlig element koster 1 kreditt; én HTTP-forespørsel med en samleforespørsel er ikke det samme som én kreditt for én prediksjon.

Vit hva du sender

Demoen i sanntid sender verdien du skriver inn, til GenderAPI.io bare når du selv sender den. Hvis KI brukes, overføres type, value og landkonteksten som ble sendt, til tjenesten som er konfigurert for prediksjoner. For en prediksjon som bare bruker datasettet, angir du options.ai_mode: off uten forceToGenderize i integrasjonen din.

Personvernerklæringen, databehandleravtalen og listen over underdatabehandlere beskriver de publiserte vilkårene for behandlingen. Et resultat er en utledet tilknytning, og det en person selv oppgir, har forrang. Ikke bruk det som grunnlag for beslutninger som har store konsekvenser for en person.

Vanlige spørsmål

Støtter demoen for indiske navn bare hindinavn?

Demoen bruker ett eksempel på devanagari, men API-et godtar navn som Unicode-tegnstrenger. At slike inndata godtas, er ikke en påstand om full dekning i datasettet eller om målt nøyaktighet for hvert språk som brukes i India.

Gir en latinsk stavemåte det samme resultatet som den opprinnelige skriften?

Det er ikke garantert. Oppslaget i datasettet likestiller ikke translitterasjoner generelt. Lagre hver stavemåte som ble sendt, sammen med source, match og konfidensen som returneres.

Er nøyaktigheten målt for hvert indisk navn?

Denne siden publiserer ingen slik måling. At inndata godtas, lagrede antall og en konfidensverdi er ikke en uavhengig måling av nøyaktigheten. Se metodesiden for grunnlaget som finnes, og for målingene som ennå ikke er publisert.

Belastes et ukjent resultat med kreditter?

Et vellykket ukjent resultat belastes. Vanlig modus med datasettet eller fallback koster 1 kreditt totalt. Med forceToGenderize koster et resultat fra datasettet 1 kreditt, og bruk av KI koster 2 totalt, også når KI gir et ukjent resultat. Feil har egne regler for belastning; kontroller meta.usage.

Fortsett testingen

Bruk GenderAPI-nøkkelen din

Skriv inn API-nøkkelen fra GenderAPI-kontoen for å fortsette å teste når de delte kredittene i IP-prøveperioden på 24 timer er brukt opp. Lagring av nøkkelen sender ingen forespørsel – send forespørselen på nytt når du er klar.

Lagres bare i denne nettleserfanen og slettes når fanen lukkes.