GenderAPI.io V2: zoeken op voornaam en volledige naam

Voordat u het verzoek verstuurt

Verstuur voorspellingsverzoeken naar GenderAPI.io V2 met POST https://api.genderapi.io/api/v2/gender en geef type en value op in de JSON-body. Gebruik uw bestaande GenderAPI.io-sleutel in Authorization: Bearer YOUR_API_KEY en Content-Type: application/json. Lees het resultaat in data en de informatie over toegang en afschrijving in meta. Elk verzoek wordt afzonderlijk verwerkt.

Kies de programmeertaal in het codevoorbeeld. Stel GENDERAPI_API_KEY in de procesomgeving in voordat u het uitvoert. Ontbrekende of niet-herkende sleutels kunnen de gedeelde IP-proefperiode gebruiken: controleer daarom bij de koppeling van een account of meta.access.mode api_key is.

Geslacht op basis van een naam

Parameter	Type	Verplicht	Standaardwaarde	Beschrijving
`type`	`string`	Ja	`—`	Invoercategorie: name, email of username.
`value`	`string`	Ja	`—`	Verplicht. 1–254 tekens; niet leeg en zonder besturingstekens. E-mailwaarden moeten een geldige e-mailsyntaxis hebben.
`country`	`string`	Nee	`—`	Optionele ISO 3166-1 alpha-2-code in hoofdletters, bijvoorbeeld TR of US. Een landspecifieke zoekopdracht kan terugvallen op de wereldwijde dataset.
`forceToGenderize`	`boolean`	Nee	`false`	Raadpleegt eerst de dataset en daarna AI met bijnaaminterpretatie als er geen resultaat is. Ondersteund voor name, email en username.
`options`	`object`	Nee	`—`	Object met de AI-opties per invoer.
`options.ai_mode`	`string`	Nee	`fallback`	Toegestane waarden: off, fallback, always. Laat dit veld bij forceToGenderize: true weg of gebruik fallback.
`id`	`string`	Nee	`—`	Optionele identificatie van 1–64 tekens in de POST-JSON. Wordt naast het bijbehorende batchresultaat teruggegeven en moet uniek zijn binnen de batch. Wordt bij losse voorspellingen geaccepteerd maar niet teruggegeven. Niet ondersteund in GET-query's.

Verstuur voor een voornaam of volledige naam type: name en de volledige invoer in value naar POST https://api.genderapi.io/api/v2/gender. GenderAPI.io V2 gebruikt voor beide vormen dezelfde verzoekvelden. Ook een succesvol antwoord kan data.gender: null bevatten. Losse verzoeken raadplegen eerst de dataset en gebruiken standaard AI wanneer daar geen geslacht uit kan worden bepaald.

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 --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": "Daan",
  "country": "NL"
}'

cURL 7.76+ in een POSIX-shell. Voer uit in uw terminal. Documentatie van de runtime

// 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": "Daan",
  "country": "NL"
};

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

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\":\"Daan\",\"country\":\"NL\"}")

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
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Daan","country":"NL"}', 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

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\":\"Daan\",\"country\":\"NL\"}";
        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

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\":\"Daan\",\"country\":\"NL\"}", 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

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\":\"Daan\",\"country\":\"NL\"}"
    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

Voorbeeldantwoord

Dit is een echt antwoord dat op 1 oktober 2026 met een API-sleutel is opgehaald; alleen het accountsaldo is vervangen. Het is geen maatstaf voor nauwkeurigheid, en een live verzoek kan een ander resultaat geven. Verzoeken met een API-sleutel geven meta.access.mode: api_key en null in de quotumvelden die alleen voor de proefperiode gelden; verzoeken via de IP-proefperiode geven ip_trial. Lees data voor de voorspelling en meta.usage voor de afschrijving van de bewerking.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Daan",
      "country": "NL"
    },
    "name": "daan",
    "gender": "male",
    "country": "NL",
    "confidence": 0.9633838383838383,
    "confidence_kind": "observed_frequency",
    "sample_count": 792,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "daan",
      "method": "normalized",
      "scope": "country",
      "country": "NL"
    }
  },
  "meta": {
    "request_id": "0a92fb23-a289-42dd-9102-ee40c0dcaad2",
    "duration_ms": 8,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Antwoordvelden en betrouwbaarheidsscore

Velden van het voorspellingsantwoord

Veld	Type	Kan null zijn	Voorbeeld	Beschrijving
`data.input`	`object`	Nee	`{"type":"name","value":"Daan","country":"NL"}`	Invoertype, waarde en land. forceToGenderize wordt opgenomen als het true is.
`data.name`	`string`	Ja	`"daan"`	Gevonden of afgeleide voornaam; null als er geen beschikbaar is.
`data.gender`	`string`	Ja	`"male"`	male, female of JSON null. Een voorspelling, geen geverifieerde persoonlijke identiteit.
`data.result_status`	`string`	Nee	`"identified"`	identified als er een geslacht wordt teruggegeven; anders unknown.
`data.reason`	`string`	Ja	`null`	null bij identified resultaten. Redenen bij unknown: not_found, no_name_candidate, ambiguous of insufficient_evidence.
`data.confidence`	`number`	Ja	`0.95`	Score van 0 tot 1 of null. Als gender null is, is ook de betrouwbaarheidsscore null.
`data.confidence_kind`	`string`	Ja	`"observed_frequency"`	observed_frequency: dominante telling in de dataset gedeeld door het totaal. model_reported: score die AI opgeeft, geen gekalibreerde kans. null als die niet beschikbaar is.
`data.sample_count`	`integer`	Ja	`1200`	Steekproefgrootte in de dataset of null. AI verzint geen steekproefgrootte.
`data.source`	`string`	Nee	`"dataset"`	dataset, ai of none.
`data.country`	`string`	Ja	`"NL"`	Koppeling aan een land via dataset of ai_association, of null. Bepaalt geen nationaliteit, woonplaats of etnische afkomst.
`data.country_source`	`string`	Ja	`"dataset"`	Herkomst van de koppeling aan een land: dataset, ai_association of null.
`data.match`	`object`	Nee	`{"name":"daan","method":"normalized","scope":"country","country":"NL"}`	Gevonden naam in de dataset, methode (normalized, token, substring of model_inference), bereik country of global en het bijbehorende land. Ontbrekend bewijs is null.

Metadata over toegang, afschrijving en verzoek

Veld	Type	Kan null zijn	Voorbeeld	Beschrijving
`meta.request_id`	`string`	Nee	`"550e8400-e29b-41d4-a716-446655440000"`	Unieke identificatie van deze HTTP-poging; wordt ook verstuurd in X-Request-ID.
`meta.duration_ms`	`integer`	Nee	`42`	Verwerkingstijd van het verzoek in milliseconden.
`meta.access.mode`	`string`	Nee	`"api_key"`	api_key, ip_trial of unauthenticated. Controleer bij een betaald account of api_key wordt vermeld.
`meta.access.reason`	`string`	Ja	`null`	Reden om naar de IP-proefperiode over te schakelen: api_key_missing, api_key_invalid of api_key_not_found; anders null.
`meta.usage.charged_credits`	`integer`	Ja	`1`	Netto afgeschreven credits. Nul vóór de afschrijving of na een bevestigde volledige terugboeking; null als de afschrijving niet is bevestigd.
`meta.usage.remaining_credits`	`integer`	Ja	`99`	Saldo bij voltooiing van de bewerking. Kan negatief zijn; null als het niet beschikbaar is of de afschrijving niet is bevestigd.
`meta.usage.billing_status`	`string`	Nee	`"confirmed"`	not_charged, confirmed of unconfirmed. Controleer dit voordat u een mislukte voorspelling herhaalt.
`meta.usage.resets_at`	`string`	Ja	`"2026-09-27T12:00:00.000Z"`	Tijdstip waarop de IP-proefperiode wordt hersteld, in UTC (ISO 8601); null voor accounts met een API-sleutel of als het onbekend is.
`meta.usage.limit`	`integer`	Ja	`10`	Tegoed van de IP-proefperiode; null voor accounts met een API-sleutel.
`meta.usage.period_seconds`	`integer`	Ja	`86400`	Duur van de periode van de IP-proefperiode in seconden; null voor accounts met een API-sleutel.

Landcontext en onbekende namen

Geef country alleen op als u over relevante context beschikt. De API kan een landspecifieke rij in de dataset selecteren of terugvallen op een wereldwijde rij. data.match.scope laat zien welke rij is geselecteerd; het teruggegeven land bepaalt niet waar de persoon woont.

Standaard gebruiken losse verzoeken de AI-fallback, voor in totaal 1 credit. Wilt u alleen de dataset gebruiken, stuur dan options: {"ai_mode": "off"}. Invoer zonder uitkomst kan gender: null teruggeven en wordt toch afgeschreven als de bewerking slaagt. Een volledige naam kan via een van de delen overeenkomen; data.match vermeldt de geselecteerde kandidaat en de matchmethode.

Voor name-waarden die op een bijnaam lijken, staat forceToGenderize: true een voorspelling zonder echte voornaam toe: een resultaat uit de dataset kost 1 credit, anders kost AI met bijnaaminterpretatie in totaal 2 credits. Een positief beginsaldo is voldoende en het resulterende saldo kan negatief worden.

Een volledige naam opzoeken zonder aan te nemen dat het eerste deel telt

Verstuur de oorspronkelijke naam in Unicode. De match met de dataset gebruikt NFKC-normalisatie, kleine letters en het opsplitsen van de naam in delen; u hoeft de naam niet naar ASCII om te zetten. Uit de beschikbare kandidaten kiest de API het item in de dataset met de hoogste opgeslagen totale telling. Die kandidaat kan een later deel van de naam zijn, dus ga er niet van uit dat het eerste deel of de voornaam is gekozen.

Dit verzoek gebruikt alleen de dataset, zodat het geselecteerde bewijs makkelijker te controleren is. Lees data.input.value voor de verstuurde volledige naam, data.match.name voor de opgezochte kandidaat en data.match.method voor de matchmethode. Het voorbeeld belooft geen specifiek geslacht en ook niet dat een bepaald deel van de naam wordt gekozen. Kandidaten in de dataset moeten langer zijn dan twee tekens en korte invoer kan zonder resultaat blijven. Gebruik de normale AI-fallback als de extra voorspelling past bij uw applicatie.

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

Voordat u het uitvoert: toegang en foutafhandeling

Handleiding voor fouten en nieuwe pogingen →

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": "Ayşe Yılmaz",
  "country": "TR",
  "options": {
    "ai_mode": "off"
  }
}'

cURL 7.76+ in een POSIX-shell. Voer uit in uw terminal. Documentatie van de runtime

// 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": "Ayşe Yılmaz",
  "country": "TR",
  "options": {
    "ai_mode": "off"
  }
};

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

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}")

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
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Ayşe Yılmaz","country":"TR","options":{"ai_mode":"off"}}', 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

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}";
        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

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}", 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

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}"
    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

Controleren welke landcontext echt heeft bijgedragen

Gebruik een ISO-landcode alleen als u over relevante context beschikt; leid die niet af uit het voorspelde resultaat. Per kandidaat gaat een bestaande rij voor het land voor op de wereldwijde rij van dezelfde kandidaat. Bestaat er geen rij voor het land, dan kan de kandidaat een wereldwijde rij gebruiken. Een rij voor het land met gelijke tellingen wordt niet vervangen door de wereldwijde rij: heeft de geselecteerde rij gelijke tellingen, dan is het resultaat uit de dataset unknown en kan een ingeschakelde AI-fallback worden gebruikt.

Bewijs in het antwoord	Interpretatie	Actie in uw applicatie
match.scope: country; match.country: TR	De geselecteerde kandidaat in de dataset komt uit de rij van het land dat in het verzoek is opgegeven.	Sla de geselecteerde kandidaat en het landbereik samen met de voorspelling op.
match.scope: global; match.country: null	De geselecteerde kandidaat komt uit een wereldwijde rij, ook al gaf het verzoek een land op.	Markeer het resultaat niet als landspecifieke match.
country_source: dataset of ai_association	Verklaart de herkomst van data.country, niet het bereik van de zoekopdracht in de dataset en niet de nationaliteit van de persoon.	Lees dit veld los van match.country; geen van beide bevestigt woonplaats of nationaliteit.
source: ai; match.scope: null	Het uiteindelijke antwoord komt van AI en bevat dus geen geselecteerde rij uit de dataset.	Volg de richtlijnen voor de betrouwbaarheidsscore van AI-resultaten en bewaar onbekende resultaten.

Voordat u het verzoek verstuurt

Geslacht op basis van een naam

Voorbeeldantwoord

Velden van het voorspellingsantwoord

Metadata over toegang, afschrijving en verzoek

Landcontext en onbekende namen

Een volledige naam opzoeken zonder aan te nemen dat het eerste deel telt

Controleren welke landcontext echt heeft bijgedragen

Gerelateerde handleidingen