GenderAPI.io V2 · Handleiding

Geslacht bepalen op basis van Indiase namen

Probeer namen die in India worden gebruikt met GenderAPI.io V2. Behoud de oorspronkelijke spelling, kies de landcontext IN bewust en interpreteer matches op volledige namen, AI-resultaten en onbekende resultaten correct.

Laatst bijgewerkt:

Probeer de V2-API

Analyseer een naam

Dataset + AI

Verstuur een waarde en bekijk het volledige antwoord, inclusief onbekende resultaten en gebruikte credits.

De tool gebruikt een voorbeeld van landcontext: India (IN). Dit is geen standaardwaarde voor alle namen in deze taal en geen bewijs van nationaliteit.

Standaardverzoek: 1 credit, inclusief de AI-fallback en onbekende resultaten. Met bijnaaminterpretatie: 1 credit als het resultaat uit de dataset komt, of in totaal 2 als AI wordt gebruikt, ook als het resultaat onbekend is.

De verstuurde waarde (de naam) wordt naar GenderAPI.io verstuurd en kan worden doorgegeven aan de geconfigureerde AI-dienst als de AI-fallback nodig is. Meer informatie over de verwerking van gegevens.

Geen API-sleutel opgeslagen. U kunt de gedeelde IP-proefperiode gebruiken zolang er credits beschikbaar zijn.

Het antwoord hieronder is een voorbeeld ter illustratie. Klik op Analyseren om een verzoek te versturen.

Voorbeeld van een V2-antwoord · geen live resultaat
Naam—
GeslachtOnbekend
Betrouwbaarheid—
BronAI-model
Gebruikte credits1

De frequenties, waarden en het saldo in het voorbeeld laten de opbouw van het antwoord zien. Echte waarden kunnen afwijken. Een voorspelling is geen bevestigde identiteit.

De oorspronkelijke naam gebruiken zonder uit te gaan van één schrift of een vaste volgorde

De demonstratie gebruikt een voorbeeld in Devanagari en de landcontext IN. Het is een voorbeeld van invoer en geen definitie van alle namen die in India worden gebruikt. De API accepteert Unicode-tekenreeksen, dus u kunt de spelling uit het record in uw applicatie versturen zonder die eerst naar het Latijnse schrift om te zetten.

De zoekopdracht gebruikt genormaliseerde delen. Er is geen algemene omzetting tussen schriften en er is geen garantie dat een Latijnse spelling en een spelling in het oorspronkelijke schrift naar hetzelfde item leiden. Bewaar de oorspronkelijke invoer samen met de teruggegeven naam. Dat een schrift wordt geaccepteerd, betekent niet dat er voor elke taal of gemeenschap een onafhankelijk gemeten nauwkeurigheid is.

Ga er niet van uit dat het eerste of laatste deel altijd dezelfde rol heeft. V2 kiest de beschikbare kandidaat met de hoogste opgeslagen totale telling en garandeert geen vaste positie van de voornaam. Initialen, korte delen en ontbrekende opgeslagen items kunnen het resultaat uit de dataset onopgelost laten; de AI-fallback kan de volledige verstuurde waarde interpreteren.

VoorbeeldinvoerWat het voorsteltWat u controleert
प्रिया शर्माVolledige naam in DevanagariMeerdere delen kunnen kandidaten worden. Controleer de gekozen naam en de match in plaats van aan te nemen dat het eerste deel voorrang krijgt.
Priya SharmaVoorbeeld in Latijns schriftDit is een aparte spelling; een identieke match tussen schriften is niet gegarandeerd.
A. KumarInitiaal en een ander deelEen initiaal van één letter wordt geen kandidaat in de dataset. Een match op het andere deel bevestigt niet de bedoelde voornaam.
country: INVoorbeeldcontext: IndiaGebruik dit als uw record relevante landcontext heeft, niet alleen omdat de naam in deze handleiding voorkomt.

De landcontext IN bewust kiezen

De live demo verstuurt country: IN (India). De API kiest dit land niet op basis van het schrift waarin de naam is geschreven. Gebruik in uw integratie bekende, relevante landcontext of laat country weg. Maak van deze voorbeeldwaarde geen standaardwaarde voor alle records.

Per kandidaat kiest de zoekopdracht het landspecifieke item als dat bestaat en anders het globale item. Daarna wordt de beschikbare kandidaat met de hoogste opgeslagen totale telling gekozen. Het werkelijke bereik van de match staat in data.match.scope en data.match.country. Een landspecifiek item met gelijke frequenties wordt niet automatisch vervangen door het globale resultaat; als de fallback actief is, kan in plaats daarvan AI worden gebruikt.

data.input.country beschrijft de landcontext die in het verzoek is verstuurd. data.country en data.country_source beschrijven de teruggegeven koppeling met een land en de herkomst daarvan. Dit zijn verschillende velden en ze zeggen niets over nationaliteit, etnische afkomst of woonplaats.

Een V2-verzoek voor een naam versturen vanuit uw applicatie

Stel GENDERAPI_API_KEY in op uw bestaande sleutel en voer het voorbeeld uit op uw server. Het verzoek schakelt de normale AI-fallback expliciet in. Het laat de opbouw van het verzoek zien, geen gemeten nauwkeurigheid of bevestigde dekking. Stel voor een voorspelling die alleen de dataset gebruikt options.ai_mode: off in.

Kies een programmeertaal. Stel uw API-sleutel in, voer daarna het voorbeeld uit op uw server.

Elk voorspellingsverzoek is een nieuwe betaalde bewerking, ook als het een nieuwe poging is. Deze voorbeelden proberen het niet automatisch opnieuw. Controleer de afschrijvingsstatus voordat u een nieuw verzoek verstuurt.

Voordat u het uitvoert: toegang en foutafhandeling

Voer deze voorbeelden uit op uw server. Stel in de procesomgeving GENDERAPI_API_KEY in op uw bestaande API-sleutel. Controleer of meta.access.mode api_key is: een niet-herkende sleutel kan terugvallen op de IP-proefperiode.

Bij JSON-antwoorden met HTTP 4xx en 5xx blijft de body van de fout behouden en eindigt het voorbeeld met een afsluitcode die niet nul is. Controleer code, action en meta.usage.billing_status voordat u het opnieuw probeert.

Handleiding voor fouten en nieuwe pogingen →
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 een POSIX-shell. Voer uit in uw terminal. Documentatie van de 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+; ingebouwde fetch. Sla op als example.mjs en voer node example.mjs uit. Documentatie van de 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+; standaardbibliotheek. Sla op als example.py en voer python3 example.py uit. Documentatie van de 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+ met de cURL-extensie. Sla op als example.php en voer php example.php uit. Documentatie van de 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+; standaard HTTP-client. Sla op als GenderApiExample.java en voer java GenderApiExample.java uit. Documentatie van de 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.
}

.NET 8+-consoleapplicatie. Gebruik als Program.cs in een consoleproject en voer daarna dotnet run uit. Documentatie van de 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+; standaardbibliotheek. Sla op als main.go en voer go run main.go uit. Documentatie van de runtime

Het resultaat samen met het bewijs opslaan

Een afgeleide koppeling is niet het geslacht dat iemand zelf opgeeft. Sla de oorspronkelijke invoer, het teruggegeven bewijs en wat de persoon zelf heeft opgegeven apart op. Een onbekend resultaat is een geldig resultaat en mag in uw applicatie geen geraden categorie worden.

VeldGebruik
data.gender / data.result_statusGebruik male of female alleen bij identified. Bewaar bij een onbekend resultaat de oorspronkelijke JSON-waarde null.
data.name / data.matchControleer de teruggegeven naam en de geselecteerde kandidaat. Een match op een deel van de tekenreeks bewijst niet dat de invoer bij een persoon met die naam hoort.
data.confidence / data.confidence_kindDe betrouwbaarheidsscore staat op een schaal van 0 tot 1 of is null. observed_frequency is gebaseerd op opgeslagen frequenties; model_reported is een waarde die AI opgeeft. Evalueer drempels per soort afzonderlijk.
data.source / data.sample_countMaak onderscheid tussen dataset, ai en none. AI-resultaten hebben geen opgeslagen steekproefgrootte. Een steekproefgrootte is geen gemeten nauwkeurigheid.
meta.access.modeControleer bij een integratie met een account of api_key wordt vermeld. Ontbrekende of niet-herkende sleutels kunnen anders de gedeelde IP-proefperiode gebruiken.
meta.usageLees charged_credits en billing_status. Een geslaagd onbekend resultaat wordt afgeschreven. Een verloren antwoord bewijst niet dat het verzoek gratis was.

Bepalen wanneer u AI gebruikt

forceToGenderize is optioneel voor namen, e-mailadressen en gebruikersnamen. Als het is ingeschakeld, laat ai_mode dan weg of gebruik fallback; off en always kunnen niet met deze optie worden gecombineerd en geven 422 terug. Een positief beginsaldo is genoeg om een verzoek te starten, ook als de uiteindelijke afschrijving het saldo negatief maakt.

De bijnaammodus kan een geslacht teruggeven samen met name: null. Ook een onbekend resultaat is mogelijk. Noch de normale AI-fallback noch de bijnaaminterpretatie garandeert een juist antwoord of een waarde anders dan null.

Optie in het verzoekWerkingCredits per geslaagde zoekopdracht
options.ai_mode: offGebruikt alleen de dataset.1, ook bij een onbekend resultaat
options.ai_mode: fallbackRaadpleegt eerst de dataset en gebruikt daarna de normale AI als er geen geslacht wordt teruggegeven. Dit is de standaardwaarde voor losse verzoeken.In totaal 1, inclusief AI-fallback
options.ai_mode: alwaysGebruikt direct AI.2
forceToGenderize: trueRaadpleegt eerst de dataset en laat daarna AI een persoonlijke bijnaam of alias interpreteren, ook zonder echte voornaam.1 voor een resultaat uit de dataset; in totaal 2 als AI wordt gebruikt

Een lijst met namen verwerken zonder de context te verliezen

Verstuur maximaal 50 items met een API-sleutel of 10 met de IP-proefperiode via POST /api/v2/gender/batch. Geef elk item een unieke id en bewaar de oorspronkelijke waarde van elke rij. Elk item kan eigen opties voor land en AI hebben; laat het land weg als het niet bekend is.

Anders dan losse verzoeken, die standaard de fallback gebruiken, gebruiken items in een batch standaard alleen de dataset. Stel options.ai_mode: fallback in voor elk item dat AI nodig heeft. Controleer elk resultaat, ook na HTTP 200, bewaar onbekende resultaten en controleer fouten en de afschrijving voordat u opnieuw verstuurt. Elk geslaagd normaal item kost 1 credit; één HTTP-verzoek voor een batch staat niet gelijk aan één credit per voorspelling.

Weten wat u verstuurt

De live demo verstuurt de ingevoerde waarde pas naar GenderAPI.io wanneer u die zelf verstuurt. Als AI wordt gebruikt, worden type, value en de verstuurde landcontext doorgegeven aan de dienst die voor voorspellingen is geconfigureerd. Stel voor een voorspelling die alleen de dataset gebruikt in uw integratie options.ai_mode: off in zonder forceToGenderize.

Het privacybeleid, de verwerkersovereenkomst en de lijst met subverwerkers beschrijven de gepubliceerde voorwaarden voor de verwerking. Een resultaat is een afgeleide koppeling en wat iemand zelf opgeeft, gaat altijd voor. Gebruik het niet als basis voor beslissingen met belangrijke gevolgen voor een persoon.

Veelgestelde vragen

Accepteert de demo voor Indiase namen alleen Hindi-namen?

De demo gebruikt een voorbeeld in Devanagari, maar de API accepteert namen als Unicode-tekenreeksen. Dat betekent niet dat de dataset volledige dekking heeft of dat er voor elke taal in India een gemeten nauwkeurigheid is.

Geeft de Latijnse spelling hetzelfde resultaat als het oorspronkelijke schrift?

Dat is niet gegarandeerd. De huidige zoekopdracht kent geen algemene gelijkstelling van transliteraties. Bewaar elke verstuurde spelling samen met de teruggegeven gegevens voor source, match en confidence.

Is er voor deze groep namen een onafhankelijke evaluatie van de nauwkeurigheid gepubliceerd?

Deze pagina publiceert zo'n evaluatie niet. Het accepteren van invoer, het tonen van opgeslagen frequenties of het teruggeven van een betrouwbaarheidsscore is geen onafhankelijke meting van de nauwkeurigheid. De methodologie beschrijft welke gegevens beschikbaar zijn en welke metingen nog niet zijn gepubliceerd.

Kost een resultaat zonder voorspelling credits?

Een geslaagd onbekend resultaat wordt afgeschreven. De normale modus met de dataset of met de fallback kost in totaal 1 credit. Met forceToGenderize kost het verzoek 1 credit als het resultaat uit de dataset komt, of in totaal 2 als AI wordt gebruikt, ook bij een onbekend resultaat. Voor fouten gelden aparte afschrijvingsregels; controleer meta.usage.

Doorgaan met testen

Gebruik je GenderAPI-sleutel

Plak de API-sleutel uit je GenderAPI-account om verder te testen wanneer de gedeelde credits van de IP-proefperiode van 24 uur op zijn. Het opslaan van de sleutel verstuurt geen verzoek; verstuur het verzoek daarna opnieuw.

Wordt alleen in dit browsertabblad bewaard en verwijderd wanneer je het tabblad sluit.