API DOKUMENTATION V2

Køn fra et navn med API v2

Forudsig køn ud fra et fornavn eller fulde navn med GenderAPI v2. Se syv sprogeksempler, JSON-svar, landekontekst, AI-reserve og kreditomkostninger.

Før du sender anmodningen

Send JSON til POST https://api.genderapi.io/api/v2/gender. Brug din eksisterende API nøgle i Authorization: Bearer YOUR_API_KEY og Content-Type: application/json. Hver anmodning behandles uafhængigt.

Vælg dit sprog i kodeeksemplet. Indstil GENDERAPI_API_KEY i procesmiljøet, før du kører det. Manglende eller ikke-genkendte nøgler kan bruge den delte IP-prøveversion, så bekræft, at meta.access.mode er api_key, når du integrerer en konto.

Køn fra et navn

ParameterTypePåkrævetStandardværdiBeskrivelse
typestringJa—Inputkategori: name, email eller username.
valuestringJa—Påkrævet. 1-254 tegn; ikke-blank, uden kontroltegn. E-mail-værdier skal være gyldig e-mail-syntaks.
countrystringNej—Valgfri ISO 3166-1 alpha-2-kode med store bogstaver, for eksempel TR eller US. Landespecifikt opslag kan falde tilbage til det globale datasæt.
forceToGenderizebooleanNejfalseSøger først i datasættet og derefter med AI for kaldenavne, hvis resultatet mangler. Understøtter name, email og username.
optionsobjectNej—Objekt med AI-indstillinger for hvert input.
options.ai_modestringNejfallbackTilladte værdier: off, fallback, always. Ved forceToGenderize: true skal feltet udelades eller være fallback.
idstringNej—Valgfri identifikator med 1–64 tegn i POST JSON-brødteksten. Det skal være unikt inden for en batch og returneres med sit batchresultat. Enkelte anmodninger accepterer denne identifikator, men inkluderer den ikke i svaret. GET-forespørgsler understøtter det ikke.

Brug type: name til at indsende et fornavn eller et fulde navn. Et vellykket svar kan indeholde gender: null. Enkelte anmodninger søger først i datasættet. Hvis intet køn kan bestemmes, bruger de AI som standard.

Vælg et programmeringssprog. Indstil din API nøgle, kør derefter eksemplet på din server.

Hver forudsigelsesanmodning er en ny fakturerbar operation, inklusive genforsøg. Disse eksempler forsøger ikke automatisk igen. Tjek faktureringsstatus, før du sender endnu en anmodning.

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

Kør disse eksempler på din server. Indstil GENDERAPI_API_KEY i procesmiljøet til din eksisterende API nøgle. Bekræft, at meta.access.mode er api_key: en ikke-genkendt nøgle kan falde tilbage til IP-prøveversionen.

HTTP 4xx og 5xx JSON-svar bevarer fejlteksten og returnerer en udgangsstatus, der ikke er nul. Tjek code, action og meta.usage.billing_status, før du prøver igen.

Fejl og forsøg igen guide →
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": "Onur",
  "country": "TR"
}'

cURL 7.76+ i en POSIX-skal. Kør i din terminal. Kørselsdokumentation

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": "Onur",
  "country": "TR"
};

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 apport. Gem som example.mjs og kør node example.mjs. Kørselsdokumentation

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\":\"Onur\",\"country\":\"TR\"}")

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+; standard bibliotek. Gem som example.py og kør python3 example.py. Kørselsdokumentation

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Onur","country":"TR"}', 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. Kørselsdokumentation

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\":\"Onur\",\"country\":\"TR\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+; standard HTTP klient. Gem som GenderApiExample.java og kør java GenderApiExample.java. Kørselsdokumentation

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\":\"Onur\",\"country\":\"TR\"}", 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+ konsolapplikation. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Kørselsdokumentation

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\":\"Onur\",\"country\":\"TR\"}"
    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+; standard bibliotek. Gem som main.go og kør go run main.go. Kørselsdokumentation

Eksempel svar

Denne syntetiske respons illustrerer JSON-formen, ikke målt nøjagtighed eller et garanteret liveresultat. Det viser IP-prøveadgang; en godkendt operation rapporterer meta.access.mode: api_key og null kun prøve-kvotefelter. Læs data for inferensen og meta.usage for operationens faktureringsresultat.

Illustrativt JSON-svar
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

Felter i forudsigelsessvaret

FeltTypeTillader null?EksempelBeskrivelse
data.inputobjectNej{"type":"name","value":"Onur","country":"TR"}Indtastningstype, værdi og land. forceToGenderize er inkluderet, når true.
data.namestringJa"onur"Matchet eller ekstraheret fornavn; null, når ingen er tilgængelig.
data.genderstringJa"male"male, female eller JSON null. Dette er en forudsigelse, ikke et bevis på en persons identitet.
data.result_statusstringNej"identified"identified, når et køn returneres; ellers unknown.
data.reasonstringJanullnull for identified. Årsager til ukendte resultater: not_found, no_name_candidate, ambiguous eller insufficient_evidence.
data.confidencenumberJa0.950–1 score eller null. Nul køn har null tillid.
data.confidence_kindstringJa"observed_frequency"observed_frequency: det dominerende kønstal divideret med det samlede antal i det valgte datasæt. model_reported: en AI-score, ikke en kalibreret sandsynlighed. Værdien er null, når den ikke er tilgængelig.
data.sample_countintegerJa1200Datasætprøvestørrelse eller null. AI opfinder ikke en prøvetælling.
data.sourcestringNej"dataset"dataset, ai eller none.
data.countrystringJa"TR"Landetilknytning fra datasæt eller ai_association eller null. Fastlægger ikke nationalitet, bopæl eller etnicitet.
data.country_sourcestringJa"dataset"Kilde til landetilknytningen: dataset, ai_association eller null.
data.matchobjectNej{"name":"onur","method":"normalized","scope":"country","country":"TR"}Matchende navn i datasættet, metode (normalized, token, substring eller model_inference), omfang (country eller global) og det matchende land. Manglende oplysninger har værdien null.

Adgang, afregning og anmodningsmetadata

FeltTypeTillader null?EksempelBeskrivelse
meta.request_idstringNej"550e8400-e29b-41d4-a716-446655440000"Unikt ID for dette HTTP-forsøg; sendes også i X-Request-ID.
meta.duration_msintegerNej42Anmodningens behandlingstid i millisekunder.
meta.access.modestringNej"api_key"api_key, ip_trial eller unauthenticated. Kontrollér api_key ved brug af en betalt konto.
meta.access.reasonstringJanullÅrsag til prøveadgang: api_key_missing, api_key_invalid eller api_key_not_found; ellers null.
meta.usage.charged_creditsintegerJa1Nettotræk af kreditter. Nul før træk eller efter bekræftet fuld tilbagebetaling; null hvis afregningen er ubekræftet.
meta.usage.remaining_creditsintegerJa99Saldo ved afslutning. Kan være negativ; null hvis saldoen ikke kendes, eller afregningen er ubekræftet.
meta.usage.billing_statusstringNej"confirmed"not_charged, confirmed eller unconfirmed. Kontrollér før en mislykket forudsigelse forsøges igen.
meta.usage.resets_atstringJa"2026-09-27T12:00:00.000Z"Nulstilling af IP-prøveperioden i UTC (ISO 8601); null for konti med API-nøgle eller ved ukendt tidspunkt.
meta.usage.limitintegerJa10IP-prøveperiodens kreditkvote; null for konti med API-nøgle.
meta.usage.period_secondsintegerJa86400IP-prøveperiodens længde i sekunder; null for konti med API-nøgle.

Landekontekst og ukendte navne

Forsyningsland kun, når du har relevant kontekst. API kan vælge en landespecifik datasætrække eller falde tilbage til en global række. data.match.scope viser, hvilken der blev valgt; det hjemvendte land fastslår ikke, hvor personen bor.

Som standard bruger en enkelt anmodning AI, når datasættet ikke kan bestemme et køn, for i alt 1 kredit. Send options: {"ai_mode": "off"} for kun at bruge datasættet. En gennemført anmodning koster stadig kreditter, hvis den returnerer gender: null. Et opslag med fuldt navn kan matche én del af navnet. data.match registrerer den valgte kandidat og matchningsmetode.

For et kaldenavn, der er angivet som et navn, tillader forceToGenderize: true AI-inferens uden et rigtigt fornavn. Et køn identificeret i datasættet koster 1 kredit. Hvis der er behov for AI, er de samlede omkostninger 2 kreditter. Enhver positiv startsaldo er tilstrækkelig; den endelige saldo kan være negativ.

Relaterede guider