GenderAPI.io V2 · Guide

Bestem køn ud fra arabiske navne

Prøv navne med arabisk skrift i GenderAPI.io V2. Læs, hvordan diakritiske tegn, match på fulde navne, landekontekst, AI-fallback og ukendte resultater fungerer, før du integrerer.

Senest opdateret:

Prøv V2-API'et

Analysér et navn

Datasæt + AI

Send en værdi, og se hele svaret, inklusive ukendte resultater og brugte kreditter.

Værktøjet bruger en landekontekst som eksempel: Saudi-Arabien (SA). Det er ikke en standard for alle navne på dette sprog og heller ikke et bevis på nationalitet.

Standardforespørgsel: 1 kredit, inklusive automatisk AI-fallback og ukendte resultater. Med fortolkning af kaldenavne: 1 kredit, hvis resultatet kommer fra datasættet, eller 2 i alt, hvis AI bruges, også når resultatet er ukendt.

Den sendte værdi (navnet) sendes til GenderAPI.io og kan videregives til den konfigurerede AI-tjeneste, hvis der er brug for AI-fallback. Læs mere om behandlingen af data.

Ingen API-nøgle er gemt. Du kan bruge den delte IP-prøveadgang, så længe den har kreditter tilbage.

Svaret nedenfor er et illustrativt eksempel. Klik på Analysér for at sende en forespørgsel.

Eksempel på et V2-svar · intet live-resultat
Navn—
KønUkendt
Sikkerhed—
KildeAI-model
Brugte kreditter1

Frekvenser, værdier og saldo i eksemplet viser svarets format. De faktiske værdier kan være anderledes. En forudsigelse er ikke en bekræftet identitet.

Bevar den arabiske skrift, og kontrollér det fundne navn

Send navnet i den oprindelige Unicode-stavemåde. Værktøjets inputfelt viser arabisk tekst fra højre mod venstre, mens denne danske guide og svarets JSON læses fra venstre mod højre. Du behøver ikke først at omskrive navnet til latinsk skrift. At API'et accepterer denne skrift, garanterer ikke, at datasættet indeholder en tilsvarende post.

Opslaget i datasættet anvender Unicode-normaliseringen NFKC og deler teksten op i dele. Der er ingen generel regel, der fjerner arabiske diakritiske tegn eller sidestiller forskellige stavemåder. Vokaltegn og andre forskelle i stavemåden kan derfor afgøre, hvilken lagret post der findes. Bevar den oprindelige værdi i stedet for i stilhed at behandle alle varianter som ens.

Et fuldt navn kan give flere kandidater. Den tilgængelige post med det højeste lagrede samlede antal vælges, så det første ord er ikke nødvendigvis det fornavn, der returneres. Kontrollér data.name og data.match.name, før du bruger et resultat til at berige en post.

Eksempel på inputHvad det viserHvad du kontrollerer
ليلى الخطيبEksempel på et fuldt navnFlere dele kan indgå i opslaget. Kontrollér det valgte match; eksemplet forudsiger ikke et live-resultat.
ليلى / لَيْلَىStavemåde uden og med vokaltegnSend den faktiske stavemåde. Det er ikke garanteret, at begge tegnstrenge fører til den samme lagrede post.
Layla / LeilaStavemåder med latinsk skriftDet er forskellige inputværdier. V2 garanterer ikke, at translitterationer automatisk sidestilles.
country: SAEksempel på kontekst: Saudi-ArabienDenne kontekst er ikke en standard for alle arabisktalende fællesskaber. Udelad country, hvis landet ikke er kendt.

Vælg landekonteksten SA bevidst

Live-demoen sender country: SA (Saudi-Arabien). API'et vælger ikke dette land ud fra den skrift, navnet er skrevet med. Brug en kendt, relevant landekontekst i din integration, eller udelad country. Gør ikke denne eksempelværdi til en standard for alle poster.

For hver kandidat vælger opslaget den landespecifikke post, hvis den findes, og ellers den globale post. Derefter vælges den tilgængelige kandidat med det højeste lagrede samlede antal. Matchets faktiske omfang fremgår af data.match.scope og data.match.country. En landespecifik post med lige store frekvenser erstattes ikke automatisk af det globale resultat; hvis fallback er slået til, kan AI bruges i stedet.

data.input.country beskriver den landekontekst, der blev sendt i forespørgslen. data.country og data.country_source beskriver den returnerede tilknytning til et land og dens oprindelse. Det er forskellige felter, og de siger intet om nationalitet, etnisk oprindelse eller bopæl.

Send en V2-forespørgsel med et navn fra din applikation

Angiv din eksisterende nøgle i GENDERAPI_API_KEY, og kør eksemplet på din server. Forespørgslen slår den almindelige automatiske AI-fallback eksplicit til. Den viser, hvordan forespørgslen er opbygget, ikke en målt nøjagtighed eller en bekræftet dækning. Angiv options.ai_mode: off, hvis du vil have en forudsigelse, der kun bruger datasættet.

Vælg et programmeringssprog. Konfigurér din API-nøgle, og kør derefter eksemplet på din server.

Hver forespørgsel om en forudsigelse er en ny operation, der koster kreditter, også når den gentages. Eksemplerne prøver ikke automatisk igen. Kontrollér opkrævningsstatus, før du sender en ny forespørgsel.

Før du kører: adgang og fejlhåndtering

Kør eksemplerne på din server. Sæt GENDERAPI_API_KEY i procesmiljøet til din eksisterende API-nøgle. Bekræft, at meta.access.mode er api_key: En nøgle, der ikke genkendes, kan føre til IP-prøveadgangen.

JSON-svar med HTTP 4xx og 5xx bevarer fejlens body og returnerer en exitstatus, der ikke er nul. Kontrollér code, action og meta.usage.billing_status, før du prøver igen.

Guide til fejl og nye forsøg →
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": "SA",
  "options": {
    "ai_mode": "fallback"
  }
}'

cURL 7.76+ i en POSIX-shell. Kør i din terminal. Dokumentation for kørselsmiljø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": "SA",
  "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+, indbygget fetch. Gem som example.mjs, og kør node example.mjs. Dokumentation for kørselsmiljø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\":\"SA\",\"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. Gem som example.py, og kør python3 example.py. Dokumentation for kørselsmiljøet

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"ليلى الخطيب","country":"SA","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-udvidelsen. Gem som example.php, og kør php example.php. Dokumentation for kørselsmiljø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\":\"SA\",\"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-klienten. Gem som GenderApiExample.java, og kør java GenderApiExample.java. Dokumentation for kørselsmiljø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\":\"SA\",\"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.
}

Konsolapplikation med .NET 8+. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Dokumentation for kørselsmiljø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\":\"SA\",\"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. Gem som main.go, og kør go run main.go. Dokumentation for kørselsmiljøet

Gem resultatet sammen med evidensen

En udledt sammenhæng er ikke det køn, en person selv har oplyst. Gem det oprindelige input, den returnerede evidens og det, personen selv har oplyst, hver for sig. Et ukendt resultat er et gyldigt resultat og bør ikke blive til en gættet kategori i din applikation.

FeltSådan bruger du det
data.gender / data.result_statusBrug kun male eller female, når status er identified. Bevar den native JSON-værdi null, når resultatet er ukendt.
data.name / data.matchKontrollér det returnerede navn og den valgte kandidat. Et match på en delstreng beviser ikke, at inputtet tilhører en person med det navn.
data.confidence / data.confidence_kindKonfidensen ligger på en skala fra 0 til 1 eller er null. observed_frequency bygger på lagrede frekvenser, mens model_reported er en værdi angivet af AI. Vurdér tærskelværdier separat for hver type.
data.source / data.sample_countSkeln mellem dataset, ai og none. AI-resultater har ingen lagret stikprøvestørrelse. En stikprøvestørrelse er ikke en målt nøjagtighed.
meta.access.modeKontrollér i en integration med konto, at api_key returneres. Manglende eller ukendte nøgler kan i stedet bruge den delte IP-prøveadgang.
meta.usageLæs charged_credits og billing_status. Et gennemført ukendt resultat koster kreditter. Et mistet svar beviser ikke, at forespørgslen var gratis.

Beslut, hvornår AI skal bruges

forceToGenderize er valgfrit for navne, e-mailadresser og brugernavne. Når det er slået til, skal du udelade ai_mode eller bruge fallback. off og always kan ikke kombineres med denne indstilling og returnerer 422. En positiv startsaldo er nok til at starte en forespørgsel, også selvom den endelige opkrævning gør saldoen negativ.

Kaldenavnstilstanden kan returnere et køn sammen med name: null. Den kan også give et ukendt resultat. Hverken den almindelige automatiske AI-fallback eller fortolkningen af kaldenavne garanterer et korrekt svar eller en værdi, der ikke er null.

Indstilling i forespørgslenAdfærdKreditter for en gennemført forespørgsel
options.ai_mode: offBruger kun datasættet.1, også for et ukendt resultat
options.ai_mode: fallbackSlår først op i datasættet og bruger derefter almindelig AI, hvis der ikke returneres et køn. Det er standarden for enkeltforespørgsler.1 i alt, inklusive automatisk AI-fallback
options.ai_mode: alwaysBruger AI direkte.2
forceToGenderize: trueSlår først op i datasættet og lader derefter AI fortolke et personligt kaldenavn eller alias, også uden et egentligt fornavn.1 for et resultat fra datasættet, 2 i alt, hvis AI bruges

Behandl en liste med navne uden at miste konteksten

Send op til 50 elementer med en API-nøgle eller 10 med IP-prøveadgangen via POST /api/v2/gender/batch. Giv hvert element et unikt id, og bevar den oprindelige værdi for hver række. Hvert element kan have sine egne indstillinger for land og AI; udelad landet, hvis det ikke er kendt.

I modsætning til enkeltforespørgsler, der som standard bruger fallback, bruger elementer i en batch som standard kun datasættet. Angiv options.ai_mode: fallback for hvert element, der har brug for AI. Kontrollér hvert resultat, også efter HTTP 200, gem ukendte resultater, og kontrollér fejl og opkrævning, før du sender igen. Hvert gennemført almindeligt element koster 1 kredit; én HTTP-forespørgsel med en batch svarer ikke til én kredit pr. forudsigelse.

Vid, hvad du sender

Live-demoen sender kun den indtastede værdi til GenderAPI.io, når du selv sender den. Hvis AI bruges, videregives type, value og den sendte landekontekst til den tjeneste, der er konfigureret til forudsigelser. Hvis du kun vil have en forudsigelse fra datasættet, skal du i din integration angive options.ai_mode: off uden forceToGenderize.

Privatlivspolitikken, databehandleraftalen og listen over underdatabehandlere beskriver de offentliggjorte vilkår for behandlingen. Et resultat er en udledt sammenhæng, og det, en person selv oplyser, har forrang. Brug det ikke som grundlag for beslutninger, der har betydelige konsekvenser for en person.

Ofte stillede spørgsmål

Accepterer V2 arabiske navne med diakritiske tegn?

V2 accepterer navne i Unicode, også tekst med arabisk skrift. Datasættets normalisering fjerner som regel ikke arabiske vokaltegn. Stavemåder med og uden vokaltegn kan derfor give forskellige match eller et ukendt resultat.

Fastslår værktøjet en arabisktalende persons nationalitet?

Nej. SA er den landekontekst, der udtrykkeligt er valgt til denne demonstration. Skriften, navnets sammenhæng eller et returneret landefelt siger intet om nationalitet eller bopæl.

Er der offentliggjort en uafhængig evaluering af nøjagtigheden for denne gruppe navne?

Denne side offentliggør ikke en sådan evaluering. At input accepteres, at lagrede frekvenser vises, eller at der returneres en konfidensværdi, er ikke en uafhængig måling af nøjagtigheden. Metodebeskrivelsen forklarer, hvilke data der er tilgængelige, og hvilke målinger der endnu ikke er offentliggjort.

Koster et resultat uden forudsigelse kreditter?

Et gennemført ukendt resultat opkræves. Den almindelige tilstand med datasættet eller med fallback koster 1 kredit i alt. Med forceToGenderize koster forespørgslen 1 kredit, hvis resultatet kommer fra datasættet, eller 2 i alt, hvis AI bruges, også ved et ukendt resultat. Fejl følger separate opkrævningsregler; kontrollér meta.usage.

Fortsæt testen

Brug din GenderAPI-nøgle

Indsæt API-nøglen fra din GenderAPI-konto for at fortsætte testen, når de delte kreditter i IP-prøveadgangen for 24 timer er brugt. Når du gemmer nøglen, sendes der ingen forespørgsel – send forespørgslen igen, når du er klar.

Gemmes kun i denne browserfane og slettes, når fanen lukkes.