Sukupuoli nimestä API V2:lla

Ennen pyynnön lähettämistä

Lähetä JSON-pyyntö: POST https://api.genderapi.io/api/v2/gender. Käytä nykyistä API-avaintasi otsakkeessa Authorization: Bearer YOUR_API_KEY ja lisää Content-Type: application/json. Jokainen pyyntö käsitellään erikseen.

Valitse kieli koodiesimerkistä. Aseta GENDERAPI_API_KEY prosessin ympäristöön ennen suorittamista. Puuttuva tai tunnistamaton avain voi käyttää jaettua IP-kokeilua, joten varmista tilin integroinnissa, että meta.access.mode on api_key.

Sukupuoli nimestä

Parametri	Tyyppi	Pakollinen	Oletusarvo	Kuvaus
`type`	`string`	Kyllä	`—`	Syötteen luokka: name, email tai username.
`value`	`string`	Kyllä	`—`	Pakollinen. 1–254 merkkiä; ei saa olla tyhjä eikä sisältää ohjausmerkkejä. Sähköpostiarvon on oltava syntaksiltaan kelvollinen sähköpostiosoite.
`country`	`string`	Ei	`—`	Valinnainen ISO 3166-1 alpha-2 -koodi isoilla kirjaimilla, esimerkiksi TR tai US. Maakohtainen haku voi siirtyä käyttämään globaalia tietoaineistoa.
`forceToGenderize`	`boolean`	Ei	`false`	Hakee ensin tietoaineistosta ja sitten tarvittaessa lempinimiä tulkitsevalla tekoälyllä. Tuettu tyypeille name, email ja username.
`options`	`object`	Ei	`—`	Kunkin syötteen tekoälyasetukset sisältävä objekti.
`options.ai_mode`	`string`	Ei	`fallback`	Sallitut arvot: off, fallback, always. Kun forceToGenderize: true, jätä kenttä pois tai käytä fallback-arvoa.
`id`	`string`	Ei	`—`	Valinnainen 1–64 merkin tunniste POST-pyynnön JSON-rungossa. Palautetaan kunkin erätuloksen yhteydessä, ja sen on oltava yksilöllinen erän sisällä. Yksittäisissä ennusteissa se hyväksytään, mutta sitä ei palauteta. Ei tuettu GET-kyselyissä.

Lähetä etunimi tai koko nimi asetuksella type: name. Onnistunut vastaus voi silti sisältää arvon gender: null. Yksittäinen pyyntö hakee ensin tietoaineistosta ja käyttää oletuksena tekoälyä, jos sukupuolta ei voida määrittää.

Valitse ohjelmointikieli. Määritä API-avain, suorita sitten esimerkki palvelimellasi.

Jokainen ennustepyyntö on uusi laskutettava toiminto, myös uudelleenyritys. Nämä esimerkit eivät yritä uudelleen automaattisesti. Tarkista laskutuksen tila ennen uuden pyynnön lähettämistä.

Ennen suorittamista: käyttöoikeus ja virheiden käsittely

Suorita esimerkit palvelimellasi. Aseta prosessin ympäristömuuttujan GENDERAPI_API_KEY arvoksi nykyinen API-avaimesi. Varmista, että meta.access.mode on api_key: tunnistamaton avain voi siirtää pyynnön IP-kokeiluun.

HTTP 4xx- ja 5xx-JSON-vastauksissa esimerkit säilyttävät virherungon ja palauttavat nollasta poikkeavan poistumiskoodin. Tarkista code, action ja meta.usage.billing_status ennen uutta yritystä.

Virhe- ja uudelleenyritysopas →

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": "Juha",
  "country": "FI"
}'

cURL 7.76+ POSIX-komentotulkissa. Suorita päätteessä. Suoritusympäristön dokumentaatio

// 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": "Juha",
  "country": "FI"
};

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+; sisäänrakennettu fetch. Tallenna nimellä example.mjs ja suorita node example.mjs. Suoritusympäristön dokumentaatio

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\":\"Juha\",\"country\":\"FI\"}")

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+; standardikirjasto. Tallenna nimellä example.py ja suorita python3 example.py. Suoritusympäristön dokumentaatio

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Juha","country":"FI"}', 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+ cURL-laajennuksella. Tallenna nimellä example.php ja suorita php example.php. Suoritusympäristön dokumentaatio

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\":\"Juha\",\"country\":\"FI\"}";
        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+; standardikirjaston HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita java GenderApiExample.java. Suoritusympäristön dokumentaatio

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\":\"Juha\",\"country\":\"FI\"}", 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+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten dotnet run. Suoritusympäristön dokumentaatio

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\":\"Juha\",\"country\":\"FI\"}"
    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+; standardikirjasto. Tallenna nimellä main.go ja suorita go run main.go. Suoritusympäristön dokumentaatio

Esimerkkivastaus

Tämä on todellinen vastaus, joka haettiin 1. lokakuuta 2026 API-avaimella; vain tilin saldo on korvattu. Se ei ole tarkkuuden mitta, ja reaaliaikainen pyyntö voi palauttaa eri tuloksen. API-avaimella tehdyt pyynnöt palauttavat arvon meta.access.mode: api_key, ja vain kokeilua koskevat kiintiökentät ovat null; IP-kokeilun pyynnöt palauttavat arvon ip_trial. Lue päätelmä kohdasta data ja toiminnon laskutustulos kohdasta meta.usage.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Juha",
      "country": "FI"
    },
    "name": "juha",
    "gender": "male",
    "country": "FI",
    "confidence": 0.9988558352402745,
    "confidence_kind": "observed_frequency",
    "sample_count": 874,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "juha",
      "method": "normalized",
      "scope": "country",
      "country": "FI"
    }
  },
  "meta": {
    "request_id": "010b6440-a403-4d2e-bc0f-f44e6c03891c",
    "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
    }
  }
}

Vastauskentät ja luottamusarvo

Ennustevastauksen kentät

Kenttä	Tyyppi	Voi olla null	Esimerkki	Kuvaus
`data.input`	`object`	Ei	`{"type":"name","value":"Juha","country":"FI"}`	Syötteen tyyppi, arvo ja maa. forceToGenderize on mukana, kun sen arvo on true.
`data.name`	`string`	Kyllä	`"juha"`	Osumana löytynyt tai poimittu etunimi; null, jos sellaista ei ole.
`data.gender`	`string`	Kyllä	`"male"`	male, female tai JSON null. Päätelmä, ei vahvistettu henkilöllisyys.
`data.result_status`	`string`	Ei	`"identified"`	identified, kun sukupuoli palautetaan; muuten unknown.
`data.reason`	`string`	Kyllä	`null`	null identified-tuloksissa. Tuntemattoman tuloksen syyt: not_found, no_name_candidate, ambiguous tai insufficient_evidence.
`data.confidence`	`number`	Kyllä	`0.95`	Pistemäärä väliltä 0–1 tai null. Jos sukupuoli on null, myös luottamusarvo on null.
`data.confidence_kind`	`string`	Kyllä	`"observed_frequency"`	observed_frequency: hallitsevan sukupuolen määrä jaettuna tietoaineiston kokonaismäärällä. model_reported: tekoälyn pistemäärä, ei kalibroitu todennäköisyys. Null, jos arvoa ei ole saatavilla.
`data.sample_count`	`integer`	Kyllä	`1200`	Tietoaineiston otoskoko tai null. Tekoäly ei keksi otoskokoa.
`data.source`	`string`	Ei	`"dataset"`	dataset, ai tai none.
`data.country`	`string`	Kyllä	`"FI"`	Tietoaineistoon tai ai_association-arvoon perustuva maayhteys, tai null. Ei vahvista kansalaisuutta, asuinpaikkaa tai etnistä taustaa.
`data.country_source`	`string`	Kyllä	`"dataset"`	Maayhteyden lähde: dataset, ai_association tai null.
`data.match`	`object`	Ei	`{"name":"juha","method":"normalized","scope":"country","country":"FI"}`	Tietoaineistosta löytynyt nimi, menetelmä (normalized, token, substring tai model_inference), laajuus (country tai global) ja vastaava maa. Puuttuvat tiedot ovat null.

Käyttöoikeus, veloitus ja pyynnön metatiedot

Kenttä	Tyyppi	Voi olla null	Esimerkki	Kuvaus
`meta.request_id`	`string`	Ei	`"550e8400-e29b-41d4-a716-446655440000"`	Tämän HTTP-yrityksen yksilöllinen tunniste; myös X-Request-ID-otsakkeessa.
`meta.duration_ms`	`integer`	Ei	`42`	Pyynnön käsittelyaika millisekunteina.
`meta.access.mode`	`string`	Ei	`"api_key"`	api_key, ip_trial tai unauthenticated. Tarkista api_key käyttäessäsi maksullista tiliä.
`meta.access.reason`	`string`	Kyllä	`null`	Kokeiluun siirtymisen syy: api_key_missing, api_key_invalid tai api_key_not_found; muuten null.
`meta.usage.charged_credits`	`integer`	Kyllä	`1`	Veloitetut nettokrediitit. Nolla ennen veloitusta tai vahvistetun täyden palautuksen jälkeen; null, jos veloitusta ei ole vahvistettu.
`meta.usage.remaining_credits`	`integer`	Kyllä	`99`	Saldo toiminnon valmistuessa. Voi olla negatiivinen; null, jos saldoa ei saada tai veloitusta ei ole vahvistettu.
`meta.usage.billing_status`	`string`	Ei	`"confirmed"`	not_charged, confirmed tai unconfirmed. Tarkista ennen epäonnistuneen ennusteen uutta yritystä.
`meta.usage.resets_at`	`string`	Kyllä	`"2026-09-27T12:00:00.000Z"`	IP-kokeilun nollausaika UTC-ajassa (ISO 8601); null API-avaintileillä tai jos aika ei ole tiedossa.
`meta.usage.limit`	`integer`	Kyllä	`10`	IP-kokeilun krediittikiintiö; null API-avaintileille.
`meta.usage.period_seconds`	`integer`	Kyllä	`86400`	IP-kokeilujakson pituus sekunteina; null API-avaintileille.

Maakonteksti ja tuntemattomat nimet

Anna country vain, jos sinulla on asiaankuuluva konteksti. API voi valita tietoaineistosta maakohtaisen rivin tai käyttää globaalia riviä. data.match.scope kertoo, kumpi valittiin; palautettu maa ei osoita, missä henkilö asuu.

Yksittäinen pyyntö käyttää oletuksena tekoälyä, jos tietoaineistosta ei voida päätellä sukupuolta. Kokonaishinta on 1 krediitti. Jos haluat käyttää vain tietoaineistoa, lähetä options: {"ai_mode": "off"}. Onnistuneesti käsitelty pyyntö veloitetaan myös silloin, kun tulos on gender: null. Koko nimen sijasta osuma voi löytyä sen osasta; data.match kertoo valitun ehdokkaan ja täsmäytystavan.

Kun nimiarvo muistuttaa lempinimeä, forceToGenderize: true sallii päättelyn ilman todellista etunimeä: tietoaineistosta ratkaistu tulos maksaa 1 krediitin, muuten lempinimiä tulkitseva tekoäly maksaa yhteensä 2. Positiivinen alkusaldo riittää, ja loppusaldo voi jäädä negatiiviseksi.

Hae koko nimellä olettamatta, että ensimmäinen sana ratkaisee

Lähetä alkuperäinen nimi Unicode-muodossa. Tietoaineiston haku käyttää NFKC-normalisointia, pienaakkosiksi muuntamista ja nimen jakamista osiin; nimeä ei tarvitse muuntaa ASCII-muotoon. Käytettävissä olevista ehdokkaista API valitsee tietueen, jonka tallennettu kokonaismäärä on suurin. Ehdokas voi olla nimen myöhempi osa, joten älä oleta, että valituksi tuli ensimmäinen sana tai etunimi.

Tämä pyyntö käyttää vain tietoaineistoa, joten tuloksen perusteet on helpompi tarkistaa. Kentästä data.input.value näet lähetetyn koko nimen, kentästä data.match.name haetun ehdokkaan ja kentästä data.match.method osumatavan. Esimerkki ei lupaa tiettyä sukupuolta eikä tietyn nimen osan valintaa. Tietoaineiston ehdokkaiden on oltava yli kahden merkin pituisia; lyhyet syötteet voivat jäädä ilman tulosta. Käytä tavallista tekoälyä varalla, kun tällainen lisäpäätelmä sopii sovellukseesi.