API-DOCUMENTATIE V2

GenderAPI.io V2: zoeken op gebruikersnaam en bijnaam

Verstuur type: username en value naar GenderAPI.io V2. Gebruik forceToGenderize om bijnamen te interpreteren en lees hoe u onbekende resultaten en credits verwerkt.

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 gebruikersnaam of bijnaam

ParameterTypeVerplichtStandaardwaardeBeschrijving
typestringJa—Invoercategorie: name, email of username.
valuestringJa—Verplicht. 1–254 tekens; niet leeg en zonder besturingstekens. E-mailwaarden moeten een geldige e-mailsyntaxis hebben.
countrystringNee—Optionele ISO 3166-1 alpha-2-code in hoofdletters, bijvoorbeeld TR of US. Een landspecifieke zoekopdracht kan terugvallen op de wereldwijde dataset.
forceToGenderizebooleanNeefalseRaadpleegt eerst de dataset en daarna AI met bijnaaminterpretatie als er geen resultaat is. Ondersteund voor name, email en username.
optionsobjectNee—Object met de AI-opties per invoer.
options.ai_modestringNeefallbackToegestane waarden: off, fallback, always. Laat dit veld bij forceToGenderize: true weg of gebruik fallback.
idstringNee—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 type: username en de gebruikersnaam of bijnaam in value naar POST https://api.genderapi.io/api/v2/gender. Stel forceToGenderize in op true als u een voorspelling wilt op basis van de betekenis van een bijnaam zoals prenses, ook wanneer er geen echte voornaam kan worden gevonden. GenderAPI.io V2 raadpleegt ook dan eerst de dataset. Een voorspelling op basis van een bijnaam kan een data.gender anders dan null teruggeven met data.name: null.

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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
}'

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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
};

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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}")

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":"username","value":"prenses","country":"TR","forceToGenderize":true}', 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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}";
        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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}", 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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}"
    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.

Voorbeeld van een JSON-antwoord
{
  "data": {
    "input": {
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    },
    "name": "prenses",
    "gender": "female",
    "country": "TR",
    "confidence": 0.9456521739130435,
    "confidence_kind": "observed_frequency",
    "sample_count": 184,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "prenses",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "a799faa4-bc1a-4537-90b3-2c1b60205499",
    "duration_ms": 15,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Velden van het voorspellingsantwoord

VeldTypeKan null zijnVoorbeeldBeschrijving
data.inputobjectNee{"type":"name","value":"Daan","country":"NL"}Invoertype, waarde en land. forceToGenderize wordt opgenomen als het true is.
data.namestringJa"daan"Gevonden of afgeleide voornaam; null als er geen beschikbaar is.
data.genderstringJa"male"male, female of JSON null. Een voorspelling, geen geverifieerde persoonlijke identiteit.
data.result_statusstringNee"identified"identified als er een geslacht wordt teruggegeven; anders unknown.
data.reasonstringJanullnull bij identified resultaten. Redenen bij unknown: not_found, no_name_candidate, ambiguous of insufficient_evidence.
data.confidencenumberJa0.95Score van 0 tot 1 of null. Als gender null is, is ook de betrouwbaarheidsscore null.
data.confidence_kindstringJa"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_countintegerJa1200Steekproefgrootte in de dataset of null. AI verzint geen steekproefgrootte.
data.sourcestringNee"dataset"dataset, ai of none.
data.countrystringJa"NL"Koppeling aan een land via dataset of ai_association, of null. Bepaalt geen nationaliteit, woonplaats of etnische afkomst.
data.country_sourcestringJa"dataset"Herkomst van de koppeling aan een land: dataset, ai_association of null.
data.matchobjectNee{"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

VeldTypeKan null zijnVoorbeeldBeschrijving
meta.request_idstringNee"550e8400-e29b-41d4-a716-446655440000"Unieke identificatie van deze HTTP-poging; wordt ook verstuurd in X-Request-ID.
meta.duration_msintegerNee42Verwerkingstijd van het verzoek in milliseconden.
meta.access.modestringNee"api_key"api_key, ip_trial of unauthenticated. Controleer bij een betaald account of api_key wordt vermeld.
meta.access.reasonstringJanullReden om naar de IP-proefperiode over te schakelen: api_key_missing, api_key_invalid of api_key_not_found; anders null.
meta.usage.charged_creditsintegerJa1Netto afgeschreven credits. Nul vóór de afschrijving of na een bevestigde volledige terugboeking; null als de afschrijving niet is bevestigd.
meta.usage.remaining_creditsintegerJa99Saldo bij voltooiing van de bewerking. Kan negatief zijn; null als het niet beschikbaar is of de afschrijving niet is bevestigd.
meta.usage.billing_statusstringNee"confirmed"not_charged, confirmed of unconfirmed. Controleer dit voordat u een mislukte voorspelling herhaalt.
meta.usage.resets_atstringJa"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.limitintegerJa10Tegoed van de IP-proefperiode; null voor accounts met een API-sleutel.
meta.usage.period_secondsintegerJa86400Duur van de periode van de IP-proefperiode in seconden; null voor accounts met een API-sleutel.

Een voorspelling op basis van een bijnaam lezen

Het voorbeeld gebruikt forceToGenderize: true. Een zoekopdracht met een resultaat uit de dataset kost 1 credit. Anders laat de API AI de alias interpreteren en worden voor een geslaagde bewerking in totaal 2 credits afgeschreven, ook bij een onbekend resultaat. Laat ai_mode weg of stel het in op fallback; off en always zijn niet te combineren met forceToGenderize en geven 422 terug.

In de bijnaammodus is een voorspeld geslacht met name: null toegestaan. Dat betekent dat er geen echte voornaam is gevonden; het is geen verwerkingsfout. Als een geslacht wordt teruggegeven, hebben AI-resultaten sample_count: null en confidence_kind: model_reported. De score is geen gekalibreerde kans en geen geverifieerde identiteit.

Zonder forceToGenderize gebruikt ook een losse zoekopdracht op gebruikersnaam standaard de normale AI-fallback voor in totaal 1 credit, maar daarvoor is een bruikbare echte voornaam nodig. Gebruik options.ai_mode: off om alleen de dataset te gebruiken.

Gerelateerde handleidingen