# Sukupuolen arviointi käyttäjänimestä tai lempinimestä

> Analysoi käyttäjänimi GenderAPI.io V2:lla. Kokeile tavallista nimihakua tai valinnaista lempinimipäättelyä, tutustu 1 tai 2 krediitin hintaan ja säilytä tuntemattomat tulokset.

Canonical HTML: https://www.genderapi.io/fi/determine-gender-from-username

Last reviewed: 2026-09-30

## Nimisignaalit ja lempinimien merkitykset ovat eri asioita

Käytä käyttäjänimelle tai lempinimelle asetusta type: username. Valinnainen alussa oleva @-merkki poistetaan tietoaineiston haussa. Ehdokkaiden poiminta ottaa huomioon erotinmerkit ja numerot ja voi kokeilla rajattua määrää merkkijonon osia. Lempinimitila säilyttää kokonaisten osien haun mutta ei lisää näitä merkkijonon osista muodostettuja ehdokkaita. Valitun tallennetun tietueen kokonaismäärä on suurin käytettävissä olevista ehdokkaista; se ei todista tilin omistajan oikeaa nimeä.

Tavallinen tekoäly varalla etsii tunnistettavaa etunimeä. forceToGenderize sallii lisäksi yhteyden henkilökohtaiseen lempinimeen, kun todellista nimeä ei voida poimia. Kumpikin tapa voi palauttaa arvon unknown; brändi, hahmo tai jaettu tili ei välttämättä edusta yhtä henkilöä.

| Esimerkkisyöte | Toimintatapa | Mitä tarkistetaan |
| --- | --- | --- |
| `@alice.smith` | Aloita tavallisella fallback-tilalla, joka hakee ensin tietoaineistosta. | Tarkista valittu nimi ja osumatapa; älä oleta, että ensimmäinen osa valittiin. |
| `robert89` | Numerot voidaan poistaa ehdokkaiden poiminnassa. | Vastaava nimi on päätelty yhteys, ei vahvistettu henkilöllisyys. |
| `prenses` | Ota forceToGenderize käyttöön, jotta tekoäly voi yrittää lempinimeen perustuvaa päätelmää, kun tietoaineisto ei tuota tulosta. | gender voi olla muu kuin null, vaikka name on null. Tekoälyn pistemäärät ovat tyyppiä model_reported. |
| `team_support` | Käsittele rooli- ja jaettuja tilejä tileinä, jotka eivät välttämättä kuulu yhdelle henkilölle. | Säilytä unknown äläkä liitä jaettuun tiliin yksittäisen henkilön identiteettiä. |

## Kokeile lempinimipäättelyä integraatiossasi

Tämä pyyntö ottaa lempinimipäättelyn käyttöön. Ensin tarkistetaan tietoaineisto. Jos se ei palauta sukupuolta, tekoäly voi käyttää aliaksen merkitystä. Jätä forceToGenderize pois tavallisesta hausta; yksittäiset pyynnöt käyttävät silti oletuksena tavallista tekoälyä varalla.

Tässä esimerkissä annetaan maakonteksti TR. Käytä sovelluksesi asiaankuuluvaa kontekstia ja tarkista data.match.scope; annettu maa ei takaa maakohtaista tietuetta. Se ei myöskään osoita kansalaisuutta tai asuinpaikkaa.

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.

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ä.

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ä.

**cURL**

cURL 7.76+ POSIX-komentotulkissa. Suorita päätteessä.

```bash
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
}'
```

**JavaScript / Node.js**

Node.js 22+; sisäänrakennettu fetch. Tallenna nimellä example.mjs ja suorita node example.mjs.

```javascript
// 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.
}
```

**Python**

Python 3.10+; standardikirjasto. Tallenna nimellä example.py ja suorita python3 example.py.

```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.
```

**PHP**

PHP 8+ cURL-laajennuksella. Tallenna nimellä example.php ja suorita php example.php.

```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.
```

**Java**

Java 17+; standardikirjaston HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita java GenderApiExample.java.

```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.
    }
}
```

**C# / .NET**

.NET 8+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten dotnet run.

```csharp
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.
}
```

**Go**

Go 1.22+; standardikirjasto. Tallenna nimellä main.go ja suorita go run main.go.

```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)
    }
}
```

- [V2:n täydellinen käyttäjänimiviite](https://www.genderapi.io/fi/docs/v2/gender-from-username)

## Säilytä tulos ja sen perusteet yhdessä

Päätelty yhteys ei ole henkilön itse ilmoittama sukupuoli. Säilytä alkuperäinen syöte, palautetut perusteet ja henkilön itse antamat tiedot erillään. Tuntematon tulos on kelvollinen tulos, eikä siitä pidä tehdä sovelluksessasi arvattua luokkaa.

| Kenttä | Miten sitä käytetään |
| --- | --- |
| `data.gender / data.result_status` | Käytä arvoa male tai female vain, kun tulos on identified. Säilytä alkuperäinen JSON null -arvo, kun tulos on unknown. |
| `data.name / data.match` | Tarkista palautettu nimi ja valittu ehdokas. Osuma merkkijonon osaan ei todista, että syöte kuuluu henkilölle, jolla on kyseinen etunimi. |
| `data.confidence / data.confidence_kind` | Luottamusarvo on väliltä 0–1 tai null. observed_frequency perustuu tallennettuihin määriin; model_reported on tekoälyn pistemäärä. Arvioi kynnysarvot kummallekin tyypille erikseen. |
| `data.source / data.sample_count` | Erota arvot dataset, ai ja none. Tekoälytuloksilla ei ole tallennettua otoskokoa. Otoskoko ei ole mitattu tarkkuus. |
| `meta.access.mode` | Varmista tilin integraatiossa, että arvo on api_key. Puuttuva tai tunnistamaton avain voi sen sijaan käyttää yhteistä IP-kokeilua. |
| `meta.usage` | Lue charged_credits ja billing_status. Onnistunut tuntematon tulos veloitetaan. Kadonnut vastaus ei osoita, että pyyntö oli maksuton. |

- [Vastauskentät ja tuntemattomat tulokset](https://www.genderapi.io/fi/docs/v2/responses)
- [Tarkkuus ja luottamusarvo selitettynä](https://www.genderapi.io/fi/accuracy-methodology)
- [Tietolähteet ja päivätty tietoaineistoprofiili](https://www.genderapi.io/fi/data-provenance)

## Päätä, milloin tekoälyä käytetään

forceToGenderize on valinnainen nimille, sähköpostiosoitteille ja käyttäjänimille. Kun se on käytössä, jätä ai_mode pois tai käytä arvoa fallback; off ja always ovat ristiriidassa sen kanssa ja palauttavat 422-virheen. Positiivinen alkusaldo riittää pyynnön aloittamiseen, vaikka lopullinen veloitus painaisi saldon negatiiviseksi.

Lempinimitila voi palauttaa sukupuolen, vaikka tuloksessa on name: null. Se voi myös palauttaa tuntemattoman tuloksen. Tavallinen tekoäly varalla ja lempinimipäättely eivät takaa oikeaa vastausta eivätkä muuta kuin null-arvoista vastausta.

| Pyynnön asetus | Toiminta | Krediitit onnistuneesta hausta |
| --- | --- | --- |
| options.ai_mode: off | Käyttää vain tietoaineistoa. | 1, myös tuntemattomasta tuloksesta |
| options.ai_mode: fallback | Hakee ensin tietoaineistosta ja käyttää tavallista tekoälyä, jos sukupuolta ei saada. Tämä on yksittäisen pyynnön oletus. | Yhteensä 1, tekoäly varalla mukaan lukien |
| options.ai_mode: always | Käyttää suoraan tekoälyä. | 2 |
| forceToGenderize: true | Hakee ensin tietoaineistosta ja sallii sitten tekoälyn tulkita henkilökohtaisen lempinimen tai aliaksen myös ilman todellista etunimeä. | 1 tietoaineistosta ratkaistusta tuloksesta; yhteensä 2, jos tekoälyä käytetään |

- [Tekoälyasetukset ja lempinimipäättely](https://www.genderapi.io/fi/docs/v2/ai-options)
- [Krediitit ja käyttö](https://www.genderapi.io/fi/docs/v2/credits-and-usage)

## Säilytä jokaisen käyttäjänimen tulos luetteloa käsitellessäsi

Käytä reittiä POST /api/v2/gender/batch käyttäjänimiluetteloille tai sekaluetteloille, joissa on nimiä, sähköpostiosoitteita ja käyttäjänimiä. Enimmäismäärä on 50 kohdetta API-avaimella tai 10 IP-kokeilussa. Jokaisella kohteella on omat maa- ja tekoälyasetuksensa; valinnaisten tunnisteiden on oltava yksilöllisiä erän sisällä.

Eräpyynnön oletus on vain tietoaineisto. Ota fallback käyttöön kohdekohtaisesti, jos haluat tavallisen tekoälyn, tai aseta kohteelle forceToGenderize lempinimipäättelyä varten. Tarkista jokaisen tuloksen data tai error ja säilytä yhteys alkuperäiseen riviin id- tai index-arvon avulla. Onnistuneet tuntemattomat kohteet veloitetaan.

- [Muodosta eräpyyntö ja käsittele osittaiset virheet](https://www.genderapi.io/fi/docs/v2/batch)
- [Virheet, kadonneet vastaukset ja uudelleenyritykset](https://www.genderapi.io/fi/docs/v2/errors-and-retries)

## Tiedä, mitä lähetät

Reaaliaikainen demo lähettää syöttämäsi arvon GenderAPI.io-palveluun vain, kun lähetät sen itse. Jos tekoälyä käytetään, lähetetyt type, value ja maakonteksti välitetään ennusteisiin määritetylle palvelulle. Jos haluat ennusteen pelkästä tietoaineistosta, käytä integraatiossasi asetusta options.ai_mode: off ilman forceToGenderize-asetusta.

Tietosuojakäytäntö, tietojenkäsittelysopimus ja alikäsittelijäluettelo kuvaavat julkaistut käsittelyehdot. Tulos on päätelty yhteys; anna henkilön itse ilmoittamien tietojen mennä sen edelle. Älä käytä tulosta perusteena yksilöä koskeville merkittäville päätöksille.

- [Tietosuojakäytäntö](https://www.genderapi.io/fi/privacy-policy)
- [Tietojenkäsittelysopimus](https://www.genderapi.io/fi/data-processing-agreement)
- [Alikäsittelijäluettelo](https://www.genderapi.io/fi/subprocessors)

## Pitääkö käyttäjänimessä olla todellinen etunimi?

Tavallinen tekoälypäätelmä edellyttää käyttökelpoista etunimeä. forceToGenderize-asetuksella API voi lisäksi yrittää lempinimeen perustuvaa yhteyttä, kun tietoaineiston haku ei tuota tulosta. Tämä tila ei edellytä todellista etunimeä, ja se voi palauttaa arvon name: null.

## Takaako forceToGenderize sukupuolen?

Ei. Se sallii lempinimipäättelyn, mutta lopullinen tulos voi silti olla tuntematon. Säilytä alkuperäinen JSON null -arvo ja tarkista result_status ja reason.

## Tarkistaako API sosiaalisen median profiilin?

Tämä päätepiste analysoi lähetetyn arvon. Se ei hae tilin profiilia, julkaisuja tai kuvia varmistaakseen, kenelle tili kuuluu.

## Voinko käyttää forceToGenderize-asetusta myös nimille tai sähköpostiosoitteille?

Kyllä. Se on valinnainen syötetyypeille name, email ja username. Ensin käytetään tietoaineistoa ja sitten tarvittaessa lempinimiä tulkitsevaa tekoälyä: 1 krediitti tietoaineistosta ratkaistusta tuloksesta tai yhteensä 2, jos tekoälyä käytetään.