GenderAPI.io V2 · Guide

Bestäm kön utifrån japanska namn

Testa japanska namn i GenderAPI.io V2. Lär dig om korta delar med kanji, möjliga läsningar, kontexten JP, AI-reserv och hur du hanterar okända resultat.

Senast uppdaterad:

Testa V2-API:et

Analysera ett namn

Datamängd + AI

Skicka ett värde och granska hela svaret, inklusive okända resultat och förbrukade krediter.

Verktyget använder ett exempel på landskontext: Japan (JP). Det är varken ett standardvärde för alla namn på det här språket eller ett belägg för nationalitet.

Vanlig förfrågan: 1 kredit, inklusive AI som reserv och okända resultat. Med smeknamnstolkning: 1 kredit om datamängden ger resultatet, eller totalt 2 om AI används, även när resultatet är okänt.

Det skickade värdet (namnet) går till GenderAPI.io och kan vidarebefordras till den konfigurerade AI-tjänsten om AI behövs som reserv. Mer om databehandlingen.

Ingen API-nyckel sparad. Den delade IP-provperioden kan användas så länge den har krediter kvar.

Svaret nedan är ett illustrativt exempel. Klicka på Analysera för att skicka en förfrågan.

Exempel på V2-svar · inget liveresultat
Namn—
KönOkänt
Säkerhet—
KällaAI-modell
Använda krediter1

Frekvenser, värden och saldo i exemplet visar svarsformatet. Faktiska värden kan skilja sig. En prediktion är ingen bekräftad identitet.

Dölj inte osäkerheten kring stavning och läsning

Skicka den stavning som finns lagrad i din applikations register: med kanji, kana eller latinsk skrift. V2 tar emot Unicode men garanterar inte att olika läsningar eller stavningar kopplas till en likvärdig nyckel i datamängden. Sökningen omvandlar inte kanji till en läsning och skiljer inte efternamnet från förnamnet när det fullständiga namnet skrivs utan mellanslag.

För de vanliga japanska tecknen i exemplen hoppar det nuvarande kandidatfiltret över delar med ett eller två tecken. I demovärdet 葵 高橋 hoppas båda delarna, som skiljs åt av ett mellanslag, över. Den vanliga reserven kan skicka hela det ursprungliga värdet till AI; en förfrågan som bara använder datamängden behåller det okända resultatet med reason: no_name_candidate.

Om du tar bort mellanslaget uppstår en annan kandidat och ingen tillförlitlig lösning på uppdelningen. Behåll de faktiska indata och granska de returnerade uppgifterna source och match. En möjlig läsning, en namnkonvention eller kontexten JP bekräftar inte en persons könsidentitet.

Exempel på indataVad det visarVad du bör kontrollera
葵 高橋Separata korta delarIngen av delarna når den minsta längd som filtret kräver för de här tecknen. AI-reserven kan fortfarande tolka det ursprungliga värdet.
高橋葵Fullständigt namn utan mellanslagEn kandidat; sökningen avgör inte var efternamnet slutar.
あおいExempel med kana och tre teckenKan bli en kandidat tack vare sin längd, men det innebär varken att en post finns eller att ett kön returneras.
Aoi TakahashiIndata med latinsk skriftSeparata delar kan tolkas. Det fastställer ingen enda ursprunglig stavning och garanterar inte att det avsedda förnamnet väljs.

Välj landskontexten JP medvetet

Demon skickar country: JP (Japan). API:et väljer inte landet utifrån den skrift som namnet är skrivet med. Använd en känd och passande landskontext i din integration eller utelämna country. Gör inte det här exemplet till standardvärde för alla poster.

För varje kandidat väljer sökningen den landsspecifika posten om den finns och kontrollerar annars den globala posten. Därefter väljs den tillgängliga kandidaten med det största lagrade totala antalet. Träffens faktiska omfattning ser du i data.match.scope och data.match.country. En landsspecifik post med lika frekvenser ersätts inte automatiskt av det globala resultatet; om reserven är aktiverad kan AI användas i stället.

data.input.country beskriver den kontext som skickades i förfrågan. data.country och data.country_source beskriver den returnerade landskopplingen och dess ursprung. Det är olika fält; de visar varken medborgarskap, etniskt ursprung eller bostadsort.

Skicka en V2-förfrågan för namn från din applikation

Sätt GENDERAPI_API_KEY till din befintliga nyckel och kör exemplet på din server. Förfrågan aktiverar uttryckligen den vanliga AI-reserven. Den visar förfrågans format, inte någon uppmätt noggrannhet eller bekräftad täckning. För en prediktion som bara använder datamängden anger du options.ai_mode: off.

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
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": "葵 高橋",
  "country": "JP",
  "options": {
    "ai_mode": "fallback"
  }
}'

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

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": "葵 高橋",
  "country": "JP",
  "options": {
    "ai_mode": "fallback"
  }
};

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

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\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}")

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
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"葵 高橋","country":"JP","options":{"ai_mode":"fallback"}}', 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

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\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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

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\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}", 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

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\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}"
    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

Spara resultatet tillsammans med underlaget

En härledd koppling är inte det kön som en person själv uppger. Spara ursprungliga indata, det returnerade underlaget och det personen själv har angett separat. Ett okänt resultat är ett giltigt resultat och bör inte bli en gissad kategori i din applikation.

FältAnvändning
data.gender / data.result_statusAnvänd male eller female bara vid identified. Behåll det inbyggda JSON-värdet null vid ett okänt resultat.
data.name / data.matchGranska det returnerade namnet och den valda kandidaten. En träff på en delsträng visar inte att indata tillhör en person med det förnamnet.
data.confidence / data.confidence_kindKonfidensen ligger på en skala från 0 till 1 eller är null. observed_frequency bygger på lagrade frekvenser; model_reported är ett AI-värde. Utvärdera tröskelvärden separat för varje typ.
data.source / data.sample_countSkilj mellan dataset, ai och none. AI-resultat har ingen lagrad urvalsstorlek. En urvalsstorlek är inget uppmätt noggrannhetsvärde.
meta.access.modeKontrollera att api_key rapporteras i en kontointegration. Nycklar som saknas eller inte känns igen kan i stället använda den delade IP-provperioden.
meta.usageLäs charged_credits och billing_status. Ett lyckat okänt resultat debiteras. Ett förlorat svar visar inte att förfrågan var kostnadsfri.

Bestäm när AI ska användas

forceToGenderize är valfritt för namn, e-postadresser och användarnamn. När det är aktiverat utelämnar du ai_mode eller använder fallback; off och always kan inte kombineras med det och ger 422. Ett positivt startsaldo räcker för att starta en förfrågan, även om den slutliga debiteringen gör saldot negativt.

Smeknamnsläget kan returnera ett kön tillsammans med name: null. Det kan också ge ett okänt resultat. Varken vanlig AI-reserv eller tolkning av smeknamn garanterar ett korrekt svar eller ett värde som inte är null.

Alternativ i förfråganBeteendeKrediter för en lyckad sökning
options.ai_mode: offAnvänd bara datamängden.1, även för ett okänt resultat
options.ai_mode: fallbackKontrollera datamängden först och använd sedan vanlig AI om inget kön returneras. Detta är standard för enskilda förfrågningar.Totalt 1, inklusive AI-reserv
options.ai_mode: alwaysAnvänd AI direkt.2
forceToGenderize: trueKontrollera datamängden först och låt sedan AI tolka ett personligt smeknamn eller alias, även utan ett riktigt förnamn.1 för ett resultat som fastställs i datamängden; totalt 2 om AI används

Bearbeta en namnlista utan att tappa kontexten

Skicka upp till 50 poster med en API-nyckel eller 10 med IP-provperioden via POST /api/v2/gender/batch. Ge posterna unika id och behåll det ursprungliga värdet för varje rad. Varje post kan ha egna alternativ för land och AI; utelämna landet när det är okänt.

Till skillnad från enskilda förfrågningar, som använder reserven som standard, använder poster i en batch som standard bara datamängden. Ange options.ai_mode: fallback i varje post som behöver AI. Kontrollera varje resultat, även efter HTTP 200, behåll okända resultat och granska fel och debitering innan du skickar igen. Varje lyckad vanlig post kostar 1 kredit; en HTTP-förfrågan med en batch motsvarar inte en kredit per prediktion.

Veta vad du skickar

Livedemon skickar det inmatade värdet till GenderAPI.io först när du skickar in det. Om AI används skickas den inskickade type, value och landskontexten till den konfigurerade tjänsten för prediktioner. För en prediktion som bara använder datamängden anger du options.ai_mode: off utan forceToGenderize i din integration.

Integritetspolicyn, personuppgiftsbiträdesavtalet och förteckningen över underbiträden beskriver de publicerade villkoren för behandlingen. Ett resultat är en härledd koppling, och det en person själv uppger har företräde. Använd det inte som grund för beslut med stora konsekvenser för en person.

Vanliga frågor

Varför behöver exemplet 葵 高橋 AI-reserven?

Båda delarna är för korta för det nuvarande kandidatfiltret. En förfrågan som bara använder datamängden returnerar därför unknown med reason: no_name_candidate. Reserven kan skicka hela det ursprungliga värdet till AI, men ett AI-svar är inte garanterat.

Fastställer V2 den exakta läsningen av ett japanskt namn?

V2 erbjuder ingen granskad tjänst för att fastställa läsningar. Sökningen omvandlar inte kanji till kana och garanterar inget likvärdigt resultat för en romaniserad stavning. Behåll indata och granska de returnerade uppgifter som resultatet bygger på.

Har en oberoende utvärdering av noggrannheten publicerats för den här namngruppen?

Den här sidan publicerar ingen sådan utvärdering. Att indata tas emot, att lagrade frekvenser visas eller att ett konfidensvärde returneras är ingen oberoende mätning av noggrannheten. Metodiken visar vilka uppgifter som finns och vilka mätningar som ännu inte har publicerats.

Förbrukar ett resultat utan prediktion krediter?

Ett lyckat okänt resultat debiteras. Vanligt läge med datamängden eller med reserv kostar totalt 1 kredit. Med forceToGenderize kostar förfrågan 1 kredit om datamängden ger resultatet, eller totalt 2 om AI används, även vid ett okänt resultat. För fel gäller egna debiteringsregler; kontrollera meta.usage.

Fortsätt testa

Använd din GenderAPI-nyckel

Klistra in API-nyckeln från ditt GenderAPI-konto för att fortsätta testa när de delade krediterna i IP-provperioden på 24 timmar är slut. Att spara nyckeln skickar ingen förfrågan – skicka förfrågan igen när du är redo.

Sparas endast i den här webbläsarfliken och raderas när fliken stängs.