GenderAPI.io V2: Sökning på förnamn och fullständigt namn

Innan du skickar förfrågan

Skicka prediktionsförfrågningar till GenderAPI.io V2 med POST https://api.genderapi.io/api/v2/gender, med type och value i JSON-kroppen. Använd din befintliga GenderAPI.io-nyckel i Authorization: Bearer YOUR_API_KEY och Content-Type: application/json. Läs resultatet i data och uppgifterna om åtkomst och debitering i meta. Varje förfrågan behandlas separat.

Välj programmeringsspråk i kodexemplet. Sätt GENDERAPI_API_KEY i processmiljön innan du kör det. Nycklar som saknas eller inte känns igen kan använda den delade IP-provperioden, så kontrollera att meta.access.mode är api_key när du integrerar ett konto.

Kön utifrån ett namn

Parameter	Typ	Obligatorisk	Standardvärde	Beskrivning
`type`	`string`	Ja	`—`	Indatakategori: name, email eller username.
`value`	`string`	Ja	`—`	Krävs. 1–254 tecken, inte tomt och utan kontrolltecken. E-postvärden måste ha giltig e-postsyntax.
`country`	`string`	Nej	`—`	Valfri ISO 3166-1 alpha-2-kod med versaler, till exempel TR eller US. En landsspecifik sökning kan falla tillbaka på den globala datamängden.
`forceToGenderize`	`boolean`	Nej	`false`	Kontrollerar först datamängden och använder sedan AI med tolkning av smeknamn om inget resultat hittas. Stöds för name, email och username.
`options`	`object`	Nej	`—`	Objekt med AI-alternativ för respektive indata.
`options.ai_mode`	`string`	Nej	`fallback`	Tillåtna värden: off, fallback, always. Med forceToGenderize: true utelämnar du fältet eller använder fallback.
`id`	`string`	Nej	`—`	Valfri identifierare med 1–64 tecken i POST-JSON. Returneras bredvid respektive batchresultat och måste vara unik inom en batch. Godtas men returneras inte för enskilda prediktioner. Stöds inte i GET-frågor.

För ett förnamn eller fullständigt namn skickar du type: name och hela indatavärdet i value till POST https://api.genderapi.io/api/v2/gender. GenderAPI.io V2 använder samma förfrågningsfält för båda namnformaten. Även ett lyckat svar kan innehålla data.gender: null. Enskilda förfrågningar kontrollerar först datamängden och använder som standard AI när inget kön kan fastställas.

Välj ett programmeringsspråk. Konfigurera din API-nyckel, kör sedan exemplet på din server.

Varje prediktionsförfrågan är en ny debiterbar åtgärd, även vid nya försök. Exemplen gör inga automatiska nya försök. Kontrollera debiteringsstatus innan du skickar en ny förfrågan.

Innan du kör: åtkomst och felhantering

Kör exemplen på din server. Sätt GENDERAPI_API_KEY i processmiljön till din befintliga API-nyckel. Kontrollera att meta.access.mode är api_key: en nyckel som inte känns igen kan leda till IP-provperioden.

Vid JSON-svar med HTTP 4xx och 5xx behålls felinnehållet och exemplet avslutas med en slutstatus som inte är noll. Kontrollera code, action och meta.usage.billing_status innan du försöker igen.

Guide om fel och nya försö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": "Erik",
  "country": "SE"
}'

cURL 7.76+ i ett POSIX-skal. Kör i terminalen. Dokumentation för körmiljön

// 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": "Erik",
  "country": "SE"
};

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+; inbyggd fetch. Spara som example.mjs och kör node example.mjs. Dokumentation för körmiljön

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\":\"Erik\",\"country\":\"SE\"}")

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. Spara som example.py och kör python3 example.py. Dokumentation för körmiljön

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Erik","country":"SE"}', 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 tillägget cURL. Spara som example.php och kör php example.php. Dokumentation för körmiljön

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\":\"Erik\",\"country\":\"SE\"}";
        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+; inbyggd HTTP-klient. Spara som GenderApiExample.java och kör java GenderApiExample.java. Dokumentation för körmiljön

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\":\"Erik\",\"country\":\"SE\"}", 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.
}

Konsolapplikation med .NET 8+. Använd som Program.cs i ett konsolprojekt och kör sedan dotnet run. Dokumentation för körmiljön

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\":\"Erik\",\"country\":\"SE\"}"
    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. Spara som main.go och kör go run main.go. Dokumentation för körmiljön

Exempelsvar

Det här är ett verkligt svar som hämtades den 1 oktober 2026 med en API-nyckel; endast kontosaldot har ersatts. Det är inte ett mått på noggrannhet, och en liveförfrågan kan ge ett annat resultat. Förfrågningar med API-nyckel rapporterar meta.access.mode: api_key och null i kvotfälten som bara gäller provperioden; förfrågningar via IP-provperioden rapporterar ip_trial. Läs data för prediktionen och meta.usage för åtgärdens debitering.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Erik",
      "country": "SE"
    },
    "name": "erik",
    "gender": "male",
    "country": "SE",
    "confidence": 1,
    "confidence_kind": "observed_frequency",
    "sample_count": 412,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "erik",
      "method": "normalized",
      "scope": "country",
      "country": "SE"
    }
  },
  "meta": {
    "request_id": "bcc2b4f6-2d7a-44c7-82dd-03722827e390",
    "duration_ms": 12,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Svarsfält och konfidens

Fält i prediktionssvaret

Fält	Typ	Kan vara null	Exempel	Beskrivning
`data.input`	`object`	Nej	`{"type":"name","value":"Erik","country":"SE"}`	Indatatyp, värde och land. forceToGenderize ingår när det är true.
`data.name`	`string`	Ja	`"erik"`	Matchat eller extraherat förnamn; null när inget finns.
`data.gender`	`string`	Ja	`"male"`	male, female eller JSON null. En prediktion, ingen bekräftad personlig identitet.
`data.result_status`	`string`	Nej	`"identified"`	identified när ett kön returneras, annars unknown.
`data.reason`	`string`	Ja	`null`	null för identified. Orsaker till unknown: not_found, no_name_candidate, ambiguous eller insufficient_evidence.
`data.confidence`	`number`	Ja	`0.95`	Ett värde mellan 0 och 1 eller null. Om gender är null är även konfidensen null.
`data.confidence_kind`	`string`	Ja	`"observed_frequency"`	observed_frequency: det dominerande antalet i datamängden delat med totalen. model_reported: ett AI-värde, ingen kalibrerad sannolikhet. null när värdet saknas.
`data.sample_count`	`integer`	Ja	`1200`	Urvalsstorlek i datamängden eller null. AI hittar inte på något urvalsantal.
`data.source`	`string`	Nej	`"dataset"`	dataset, ai eller none.
`data.country`	`string`	Ja	`"SE"`	Landskoppling från dataset eller ai_association, eller null. Visar varken nationalitet, bosättning eller etnicitet.
`data.country_source`	`string`	Ja	`"dataset"`	Källa till landskopplingen: dataset, ai_association eller null.
`data.match`	`object`	Nej	`{"name":"erik","method":"normalized","scope":"country","country":"SE"}`	Matchat namn i datamängden, metod (normalized, token, substring eller model_inference), omfattning (country eller global) och matchat land. Underlag som saknas är null.

Metadata om åtkomst, debitering och förfrågan

Fält	Typ	Kan vara null	Exempel	Beskrivning
`meta.request_id`	`string`	Nej	`"550e8400-e29b-41d4-a716-446655440000"`	Unik identifierare för det här HTTP-försöket; skickas även i X-Request-ID.
`meta.duration_ms`	`integer`	Nej	`42`	Bearbetningstid för förfrågan i millisekunder.
`meta.access.mode`	`string`	Nej	`"api_key"`	api_key, ip_trial eller unauthenticated. Kontrollera att api_key rapporteras när du använder ett betalt konto.
`meta.access.reason`	`string`	Ja	`null`	Orsak till att IP-provperioden användes: api_key_missing, api_key_invalid eller api_key_not_found; annars null.
`meta.usage.charged_credits`	`integer`	Ja	`1`	Debiterade krediter netto. 0 före debitering eller efter en bekräftad fullständig återbetalning; null när debiteringen är obekräftad.
`meta.usage.remaining_credits`	`integer`	Ja	`99`	Saldo när åtgärden slutförs. Kan vara negativt; null om saldot saknas eller debiteringen är obekräftad.
`meta.usage.billing_status`	`string`	Nej	`"confirmed"`	not_charged, confirmed eller unconfirmed. Kontrollera detta innan du gör ett nytt försök med en misslyckad prediktion.
`meta.usage.resets_at`	`string`	Ja	`"2026-09-27T12:00:00.000Z"`	Tidpunkt i UTC (ISO 8601) då IP-provperioden återställs; null för konton med API-nyckel eller om tidpunkten är okänd.
`meta.usage.limit`	`integer`	Ja	`10`	Kvot för IP-provperioden; null för konton med API-nyckel.
`meta.usage.period_seconds`	`integer`	Ja	`86400`	IP-provperiodens tidsfönster i sekunder; null för konton med API-nyckel.

Landskontext och okända namn

Ange country bara när du har relevant kontext. API:et kan välja en landsspecifik rad i datamängden eller falla tillbaka på en global rad. data.match.scope visar vilken som valdes; det returnerade landet visar inte var personen bor.

Enskilda förfrågningar använder som standard AI-reserv för totalt 1 kredit. Om du bara vill använda datamängden skickar du options: {"ai_mode": "off"}. Olösta indata kan returnera gender: null och debiteras ändå när åtgärden lyckas. Ett fullständigt namn kan matchas via en av sina delar; data.match anger den valda kandidaten och matchningsmetoden.

För namnvärden som liknar smeknamn tillåter forceToGenderize: true en prediktion utan ett riktigt förnamn: ett resultat som fastställs i datamängden kostar 1 kredit, annars kostar AI med tolkning av smeknamn totalt 2. Ett positivt startsaldo räcker, och saldot efteråt kan bli negativt.

Slå upp ett fullständigt namn utan att anta att det första ordet avgör

Skicka det ursprungliga namnet i Unicode. Matchningen mot datamängden använder NFKC-normalisering, gemener och extrahering av namnets delar; du behöver inte omvandla namnet till ASCII. Bland de tillgängliga kandidaterna väljer API:et den post i datamängden som har det största lagrade totala antalet. Kandidaten kan vara en senare del av namnet, så utgå inte från att det första ordet eller förnamnet valdes.

Den här förfrågan använder bara datamängden, vilket gör det valda underlaget lättare att granska. Läs data.input.value för det skickade fullständiga namnet, data.match.name för kandidaten som söktes upp och data.match.method för matchningsmetoden. Exemplet utlovar varken ett visst kön eller en viss vald namndel. Kandidater i datamängden måste vara längre än två tecken, och korta indata kan förbli olösta. Använd vanlig AI-reserv när den extra prediktionen passar din applikation.