API-DOKUMENTAATIO V2

Sukupuoli käyttäjänimestä API V2:lla

Ennusta sukupuoli käyttäjänimistä ja lempinimistä GenderAPI.io V2:lla. Tutustu forceToGenderize-asetukseen, tietoaineistoa ensin käyttävään hakuun, tekoälyvastauksen kenttiin sekä 1 tai 2 krediitin hintaan.

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 käyttäjänimestä tai lempinimestä

ParametriTyyppiPakollinenOletusarvoKuvaus
typestringKyllä—Syötteen luokka: name, email tai username.
valuestringKyllä—Pakollinen. 1–254 merkkiä; ei saa olla tyhjä eikä sisältää ohjausmerkkejä. Sähköpostiarvon on oltava syntaksiltaan kelvollinen sähköpostiosoite.
countrystringEi—Valinnainen ISO 3166-1 alpha-2 -koodi isoilla kirjaimilla, esimerkiksi TR tai US. Maakohtainen haku voi siirtyä käyttämään globaalia tietoaineistoa.
forceToGenderizebooleanEifalseHakee ensin tietoaineistosta ja sitten tarvittaessa lempinimiä tulkitsevalla tekoälyllä. Tuettu tyypeille name, email ja username.
optionsobjectEi—Kunkin syötteen tekoälyasetukset sisältävä objekti.
options.ai_modestringEifallbackSallitut arvot: off, fallback, always. Kun forceToGenderize: true, jätä kenttä pois tai käytä fallback-arvoa.
idstringEi—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ä.

Käytä käyttäjänimille ja lempinimille asetusta type: username. Aseta forceToGenderize arvoon true, jos haluat yrityksen lempinimen merkityksen perusteella, kuten prenses, vaikka todellista nimeä ei voida poimia. Tietoaineisto tarkistetaan silti ensin. Lempinimiennuste voi palauttaa sukupuolen, vaikka tuloksessa on name: null.

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
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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
}'

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

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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
};

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

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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}")

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
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"username","value":"prenses","country":"TR","forceToGenderize":true}', 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

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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}";
        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

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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}", 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

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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}"
    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.

Havainnollistava JSON-vastaus
{
  "data": {
    "input": {
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    },
    "name": "prenses",
    "gender": "female",
    "country": "TR",
    "confidence": 0.9456521739130435,
    "confidence_kind": "observed_frequency",
    "sample_count": 184,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "prenses",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "a799faa4-bc1a-4537-90b3-2c1b60205499",
    "duration_ms": 15,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

Ennustevastauksen kentät

KenttäTyyppiVoi olla nullEsimerkkiKuvaus
data.inputobjectEi{"type":"name","value":"Juha","country":"FI"}Syötteen tyyppi, arvo ja maa. forceToGenderize on mukana, kun sen arvo on true.
data.namestringKyllä"juha"Osumana löytynyt tai poimittu etunimi; null, jos sellaista ei ole.
data.genderstringKyllä"male"male, female tai JSON null. Päätelmä, ei vahvistettu henkilöllisyys.
data.result_statusstringEi"identified"identified, kun sukupuoli palautetaan; muuten unknown.
data.reasonstringKyllänullnull identified-tuloksissa. Tuntemattoman tuloksen syyt: not_found, no_name_candidate, ambiguous tai insufficient_evidence.
data.confidencenumberKyllä0.95Pistemäärä väliltä 0–1 tai null. Jos sukupuoli on null, myös luottamusarvo on null.
data.confidence_kindstringKyllä"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_countintegerKyllä1200Tietoaineiston otoskoko tai null. Tekoäly ei keksi otoskokoa.
data.sourcestringEi"dataset"dataset, ai tai none.
data.countrystringKyllä"FI"Tietoaineistoon tai ai_association-arvoon perustuva maayhteys, tai null. Ei vahvista kansalaisuutta, asuinpaikkaa tai etnistä taustaa.
data.country_sourcestringKyllä"dataset"Maayhteyden lähde: dataset, ai_association tai null.
data.matchobjectEi{"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äTyyppiVoi olla nullEsimerkkiKuvaus
meta.request_idstringEi"550e8400-e29b-41d4-a716-446655440000"Tämän HTTP-yrityksen yksilöllinen tunniste; myös X-Request-ID-otsakkeessa.
meta.duration_msintegerEi42Pyynnön käsittelyaika millisekunteina.
meta.access.modestringEi"api_key"api_key, ip_trial tai unauthenticated. Tarkista api_key käyttäessäsi maksullista tiliä.
meta.access.reasonstringKyllänullKokeiluun siirtymisen syy: api_key_missing, api_key_invalid tai api_key_not_found; muuten null.
meta.usage.charged_creditsintegerKyllä1Veloitetut nettokrediitit. Nolla ennen veloitusta tai vahvistetun täyden palautuksen jälkeen; null, jos veloitusta ei ole vahvistettu.
meta.usage.remaining_creditsintegerKyllä99Saldo toiminnon valmistuessa. Voi olla negatiivinen; null, jos saldoa ei saada tai veloitusta ei ole vahvistettu.
meta.usage.billing_statusstringEi"confirmed"not_charged, confirmed tai unconfirmed. Tarkista ennen epäonnistuneen ennusteen uutta yritystä.
meta.usage.resets_atstringKyllä"2026-09-27T12:00:00.000Z"IP-kokeilun nollausaika UTC-ajassa (ISO 8601); null API-avaintileillä tai jos aika ei ole tiedossa.
meta.usage.limitintegerKyllä10IP-kokeilun krediittikiintiö; null API-avaintileille.
meta.usage.period_secondsintegerKyllä86400IP-kokeilujakson pituus sekunteina; null API-avaintileille.

Lempinimiennusteen tulkinta

Esimerkki käyttää asetusta forceToGenderize: true. Jos tietoaineisto ratkaisee sukupuolen, hinta on 1 krediitti. Muussa tapauksessa tekoäly tulkitsee aliaksen, ja onnistunut toiminto maksaa yhteensä 2 krediittiä, myös tuntemattomasta tuloksesta. Jätä ai_mode pois tai valitse fallback; off ja always ovat ristiriidassa forceToGenderize-asetuksen kanssa ja palauttavat 422-virheen.

Lempinimitilassa päätelty sukupuoli on sallittu, vaikka tuloksessa on name: null. Se tarkoittaa, ettei todellista etunimeä poimittu; kyse ei ole jäsennysvirheestä. Kun tekoäly palauttaa sukupuolen, tuloksessa on sample_count: null ja confidence_kind: model_reported. Pistemäärä ei ole kalibroitu todennäköisyys eikä vahvistettu henkilöllisyys.

Ilman forceToGenderize-asetusta yksittäinen käyttäjänimihaku käyttää silti oletuksena tavallista tekoälyä varalla, yhteensä 1 krediitillä, mutta se edellyttää käyttökelpoista todellista etunimeä. Käytä asetusta options.ai_mode: off, jos haluat käyttää vain tietoaineistoa.

Aiheeseen liittyvät oppaat