GenderAPI.io V2: kjønn fra et navn

Før du sender forespørselen

Send JSON til POST https://api.genderapi.io/api/v2/gender. Bruk din eksisterende API-nøkkel i Authorization: Bearer YOUR_API_KEY og Content-Type: application/json. Hver forespørsel behandles uavhengig.

Velg språk i kodeeksemplet. Sett GENDERAPI_API_KEY i prosessmiljøet før du kjører det. Nøkler som mangler eller ikke gjenkjennes, kan bruke den delte IP-prøveperioden, så bekreft at meta.access.mode er api_key når du integrerer en konto.

Kjønn fra et navn

Parameter	Type	Påkrevd	Standardverdi	Beskrivelse
`type`	`string`	Ja	`—`	Inndatakategori: name, email eller username.
`value`	`string`	Ja	`—`	Påkrevd. 1–254 tegn; ikke tom og uten kontrolltegn. E-postverdier må ha gyldig e-postsyntaks.
`country`	`string`	Nei	`—`	Valgfri ISO 3166-1 alpha-2-kode med store bokstaver, for eksempel TR eller US. Et landspesifikt oppslag kan falle tilbake til det globale datasettet.
`forceToGenderize`	`boolean`	Nei	`false`	Søk først i datasettet, deretter med KI som tolker kallenavn hvis det ikke finnes et resultat. Støttes for name, email og username.
`options`	`object`	Nei	`—`	Objekt for KI-alternativer per inndata.
`options.ai_mode`	`string`	Nei	`fallback`	Tillatte verdier: off, fallback, always. Med forceToGenderize: true utelater du feltet eller bruker fallback.
`id`	`string`	Nei	`—`	Valgfri identifikator på 1–64 tegn i POST-JSON. Returneres sammen med hvert resultat i en samleforespørsel og må være unik innenfor samleforespørselen. Godtas, men returneres ikke for enkeltprediksjoner. Støttes ikke i GET-spørringer.

Bruk type: name for et fornavn eller et fullt navn. Et vellykket svar kan likevel inneholde gender: null. Enkeltforespørsler søker først i datasettet og spør som standard KI når datasettet ikke kan fastslå et kjønn.

Velg et programmeringsspråk. Konfigurer API-nøkkelen, og kjør deretter eksemplet på serveren din.

Hver prediksjonsforespørsel er en ny operasjon som belastes, også nye forsøk. Disse eksemplene prøver ikke automatisk på nytt. Sjekk belastningsstatusen før du sender en ny forespørsel.

Før du kjører: tilgang og feilhåndtering

Kjør disse eksemplene på serveren din. Sett GENDERAPI_API_KEY i prosessmiljøet til din eksisterende API-nøkkel. Bekreft at meta.access.mode er api_key: en nøkkel som ikke gjenkjennes, kan føre til IP-prøveperioden.

Ved JSON-svar med HTTP 4xx og 5xx beholdes feilinnholdet, og eksemplet avsluttes med en exit-status som ikke er null. Sjekk code, action og meta.usage.billing_status før du prøver på nytt.

Veiledning om feil og nye forsøk →

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": "Henrik",
  "country": "NO"
}'

cURL 7.76+ i et POSIX-skall. Kjør i terminalen. Dokumentasjon for kjøretidsmiljøet

// 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": "Henrik",
  "country": "NO"
};

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+; innebygd fetch. Lagre som example.mjs og kjør node example.mjs. Dokumentasjon for kjøretidsmiljøet

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\":\"Henrik\",\"country\":\"NO\"}")

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. Lagre som example.py og kjør python3 example.py. Dokumentasjon for kjøretidsmiljøet

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Henrik","country":"NO"}', 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-utvidelsen. Lagre som example.php og kjør php example.php. Dokumentasjon for kjøretidsmiljøet

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\":\"Henrik\",\"country\":\"NO\"}";
        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. Lagre som GenderApiExample.java og kjør java GenderApiExample.java. Dokumentasjon for kjøretidsmiljøet

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\":\"Henrik\",\"country\":\"NO\"}", 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.
}

Konsollapplikasjon i .NET 8+. Bruk som Program.cs i et konsollprosjekt, og kjør deretter dotnet run. Dokumentasjon for kjøretidsmiljøet

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\":\"Henrik\",\"country\":\"NO\"}"
    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. Lagre som main.go og kjør go run main.go. Dokumentasjon for kjøretidsmiljøet

Eksempelsvar

Dette er et ekte svar hentet 1. oktober 2026 med en API-nøkkel; bare kontosaldoen er byttet ut. Det er ikke et mål på nøyaktighet, og en forespørsel i sanntid kan gi et annet resultat. Forespørsler med API-nøkkel rapporterer meta.access.mode: api_key og null i kvotefeltene som bare gjelder IP-prøveperioden; forespørsler via IP-prøveperioden rapporterer ip_trial. Les data for estimatet og meta.usage for belastningen av operasjonen.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Henrik",
      "country": "NO"
    },
    "name": "henrik",
    "gender": "male",
    "country": "NO",
    "confidence": 1,
    "confidence_kind": "observed_frequency",
    "sample_count": 129,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "henrik",
      "method": "normalized",
      "scope": "country",
      "country": "NO"
    }
  },
  "meta": {
    "request_id": "ec48ee76-eaf5-424f-8ed5-b33841429438",
    "duration_ms": 10,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Svarfelt og konfidens

Felt i prediksjonssvaret

Felt	Type	Kan være null	Eksempel	Beskrivelse
`data.input`	`object`	Nei	`{"type":"name","value":"Henrik","country":"NO"}`	Inndatatype, verdi og land. forceToGenderize tas med når verdien er true.
`data.name`	`string`	Ja	`"henrik"`	Fornavnet som ga treff eller ble hentet ut; null når det ikke finnes noe.
`data.gender`	`string`	Ja	`"male"`	male, female eller JSON null. Et estimat, ikke en bekreftet personlig identitet.
`data.result_status`	`string`	Nei	`"identified"`	identified når et kjønn returneres; ellers unknown.
`data.reason`	`string`	Ja	`null`	null for identifiserte resultater. Årsaker til ukjente resultater: not_found, no_name_candidate, ambiguous eller insufficient_evidence.
`data.confidence`	`number`	Ja	`0.95`	Verdi fra 0 til 1 eller null. Når kjønnet er null, er konfidensen også null.
`data.confidence_kind`	`string`	Ja	`"observed_frequency"`	observed_frequency: det dominerende antallet i datasettet delt på totalen. model_reported: en verdi fra KI, ikke en kalibrert sannsynlighet. null når verdien ikke er tilgjengelig.
`data.sample_count`	`integer`	Ja	`1200`	Utvalgsstørrelse i datasettet eller null. KI finner ikke på et utvalgsantall.
`data.source`	`string`	Nei	`"dataset"`	dataset, ai eller none.
`data.country`	`string`	Ja	`"NO"`	Landtilknytning fra dataset eller ai_association, eller null. Viser ikke nasjonalitet, bosted eller etnisitet.
`data.country_source`	`string`	Ja	`"dataset"`	Kilden til landtilknytningen: dataset, ai_association eller null.
`data.match`	`object`	Nei	`{"name":"henrik","method":"normalized","scope":"country","country":"NO"}`	Navnet som ga treff i datasettet, metoden (normalized, token, substring eller model_inference), omfanget country/global og landet som ga treff. Grunnlag som ikke er tilgjengelig, er null.

Metadata om tilgang, belastning og forespørsel

Felt	Type	Kan være null	Eksempel	Beskrivelse
`meta.request_id`	`string`	Nei	`"550e8400-e29b-41d4-a716-446655440000"`	Unik ID for dette HTTP-forsøket; sendes også i X-Request-ID.
`meta.duration_ms`	`integer`	Nei	`42`	Behandlingstid for forespørselen i millisekunder.
`meta.access.mode`	`string`	Nei	`"api_key"`	api_key, ip_trial eller unauthenticated. Kontroller at verdien er api_key når du bruker en betalt konto.
`meta.access.reason`	`string`	Ja	`null`	Årsak til at IP-prøveperioden ble brukt: api_key_missing, api_key_invalid eller api_key_not_found; ellers null.
`meta.usage.charged_credits`	`integer`	Ja	`1`	Netto belastede kreditter. 0 før belastning eller etter en bekreftet full refusjon; null når belastningen ikke er bekreftet.
`meta.usage.remaining_credits`	`integer`	Ja	`99`	Saldo når operasjonen er fullført. Kan være negativ; null når saldoen ikke er tilgjengelig eller belastningen ikke er bekreftet.
`meta.usage.billing_status`	`string`	Nei	`"confirmed"`	not_charged, confirmed eller unconfirmed. Sjekk dette før du prøver en mislykket prediksjon på nytt.
`meta.usage.resets_at`	`string`	Ja	`"2026-09-27T12:00:00.000Z"`	Tidspunkt for tilbakestilling av IP-prøveperioden i UTC (ISO 8601); null for kontoer med API-nøkkel eller når tidspunktet er ukjent.
`meta.usage.limit`	`integer`	Ja	`10`	Kvoten i IP-prøveperioden; null for kontoer med API-nøkkel.
`meta.usage.period_seconds`	`integer`	Ja	`86400`	Lengden på IP-prøveperioden i sekunder; null for kontoer med API-nøkkel.

Landkontekst og ukjente navn

Angi country bare når du har relevant kontekst. API-et kan velge en landspesifikk rad i datasettet eller falle tilbake til en global rad. data.match.scope viser hvilken som ble valgt; det returnerte landet viser ikke hvor personen bor.

Enkeltforespørsler bruker som standard KI-reserve for 1 kreditt totalt. Hvis du bare vil bruke datasettet, sender du options: {"ai_mode": "off"}. Inndata uten resultat kan returnere gender: null og belastes likevel når operasjonen lykkes. Et fullt navn kan gi treff på én del av navnet; data.match viser den valgte kandidaten og treffmetoden.

For navneverdier som ligner kallenavn, tillater forceToGenderize: true et estimat uten et ekte fornavn: et resultat fra datasettet koster 1 kreditt; ellers koster KI som tolker kallenavn, 2 kreditter totalt. En positiv startsaldo er nok, og saldoen kan bli negativ etterpå.

Slå opp et fullt navn uten å anta at det første ordet teller

Send det opprinnelige navnet i Unicode. Treff i datasettet bruker NFKC-normalisering, små bokstaver og uttrekk av navnedeler; du trenger ikke å gjøre navnet om til ASCII. Blant de tilgjengelige kandidatene velger API-et oppføringen i datasettet med det høyeste lagrede totalantallet. Kandidaten kan være en senere del av navnet, så ikke anta at det første ordet eller fornavnet ble valgt.

Denne forespørselen bruker bare datasettet, slik at det er lettere å kontrollere grunnlaget som ble valgt. Les data.input.value for det fulle navnet som ble sendt, data.match.name for kandidaten som ble slått opp, og data.match.method for treffmetoden. Eksemplet lover ikke et bestemt kjønn eller at en bestemt del av navnet blir valgt. Kandidater i datasettet må ha mer enn to tegn, og korte inndata kan bli stående uten resultat. Bruk vanlig KI-reserve når den ekstra prediksjonen passer for applikasjonen din.