Køn fra brugernavne og kaldenavne

Eksempelinput

Et kaldenavn er ikke en verificering af identiteten

@alice_smith kan matche et navneelement. For prenses med forceToGenderize kan der returneres en forudsigelse, selvom navnet forbliver null. user47291 kan forblive ukendt. Der er tale om eksempelinput; vi tildeler dem ikke noget kønsresultat på forhånd.

Analyselogik

Hvordan fungerer forudsigelsen af køn ud fra et brugernavn?

Systemet leder efter genkendelige navneelementer og andre sproglige spor i brugernavnet eller visningsnavnet. Den almindelige AI-fallback leder efter et brugbart egentligt fornavn; med forceToGenderize kan AI fortolke et kaldenavn uden et egentligt fornavn. Resultatet returneres sammen med kontekstfelterne; et tilfældigt eller utilstrækkeligt input bør ikke tvinges til et resultat.

01BrugernavnKaldenavn eller visningsnavn

02Analyse af signalerNavn og kontekst

03ForudsigelseKøn og konfidens

Anvendelsesmuligheder

Vælg den metode, der passer til dine data

EnkeltforespørgselAnalysér ét brugernavn via REST API.Se API-guiden →BatchforespørgselSend flere elementer i én struktureret forespørgsel.Se guiden til batch →Arbejdsgang i Excel/CSVBehandl en fil uden at udvikle en integration.Åbn værktøjet →

Behandl store datasæt uden kode

Analysér brugernavnene i en Excel- eller CSV-fil i fire trin

01
Åbn Excel/CSV-værktøjet
Åbn GenderAPI's importværktøj, og upload den fil, der skal behandles.
02
Vælg kildekolonnen
Tilknyt den kolonne, der indeholder brugernavne, kaldenavne eller visningsnavne.
03
Slå fortolkning af kaldenavne til
Aktivér den indstilling, der fortolker aliasser og navne fra sociale netværk.
04
Kontrollér en stikprøve, og eksportér derefter
Gennemgå først en repræsentativ stikprøve af poster, behandl derefter hele filen, og download de berigede data.

Nye konti indeholder 200 gratis API-kreditter om dagen, så du kan prøve arbejdsgangen på en stikprøve, før du behandler hele filen.

Anvendelser

Brug det som et supplerende signal, når et egentligt fornavn mangler

Analyse af brugernavne kan være nyttig for data fra sociale netværk, communities, spil og profiler, som brugerne selv har oprettet, når navnefeltet er tomt. Hvis du har en mere direkte og tilladt kilde, for eksempel et egentligt fornavn eller en e-mailadresse, så brug det tilsvarende endpoint.

Begrænsninger

Behandl ikke resultatet som en verificeret identitet

Ikke alle kaldenavne indeholder et egentligt fornavn, kulturelle associationer varierer, og det samme udtryk kan betyde forskellige ting på forskellige sprog. Hvis signalet er utilstrækkeligt, så acceptér et tomt resultat i stedet for at gøre svage data til en endelig konklusion.

Implementeringsguide til V2

Gem kildedata og forudsigelse hver for sig

Bevar postens oprindelige identifikator. API'et åbner ingen profil, kontrollerer ikke, hvem der ejer en konto, og bekræfter ikke nogen identitet. Send kun en landekontekst, når du har en pålidelig oplysning; udled den ikke af domænet eller af webstedets sprog.

Eksempelinput	Felt eller indstilling	Fortolkning
@alice_smith	data.name / data.match	Bevar det oprindelige brugernavn; behandl ikke det fundne fragment som et verificeret navn.
prenses	forceToGenderize: true	Gør det muligt at fortolke et kaldenavn uden et egentligt fornavn. Der kan returneres et køn med data.name sat til null; opfind ikke et navn til personen.
user47291	data.result_status: unknown	Et tvetydigt eller utilstrækkeligt input kan forblive ukendt. Det er ikke en grund til automatisk at sende forespørgslen igen.

Send brugernavnet med type: username; send ikke en profil-URL. Opslaget i datasættet fjerner et indledende @, normaliserer teksten og danner kandidater ud fra skilletegn og cifre. En standardforespørgsel kan tilføje et begrænset antal match ud fra præfiks og suffiks; forceToGenderize bruger ikke disse ekstra fragmenter. Hvis flere rækker matcher, vælges den med det højeste antal registrerede forekomster. Brug type: email til e-mailadresser og type: name til egentlige navne.

Vælg behandlingstilstand og pris i kreditter

Indstilling	Behandling	Pris pr. gennemført element
options.ai_mode: off	Kun datasættet	1 kredit
options.ai_mode: fallback	Først datasættet; hvis der ikke kan bestemmes et køn, almindelig AI-fallback	1 kredit i alt, inklusive AI
options.ai_mode: always	Direkte til AI	2 kreditter
forceToGenderize: true	Først datasættet, derefter fortolkning af kaldenavnet uden krav om et egentligt fornavn	1, hvis datasættet er nok; 2 i alt, hvis AI bruges

For en enkeltforespørgsel er standarden fallback, for elementer i en batch off. forceToGenderize er valgfrit for navne, e-mailadresser og brugernavne; udelad i så fald ai_mode, eller brug fallback, fordi indstillingen ikke kan kombineres med off og always. Gennemførte unknown-resultater opkræves også. En positiv startsaldo er nok til at gå i gang; når operationen er afsluttet, kan saldoen blive negativ.

Giv hvert element i en batch sine egne indstillinger

Eksempelinput garanterer ikke en bestemt forudsigelse. Sæt GENDERAPI_API_KEY i servermiljøet, og læg ikke nøglen i offentlig kode på klientsiden. V1 og V2 bruger den samme kontonøgle og den samme saldo. Kontrollér nøglen med /api/v2/usage, og bekræft, at meta.access.mode har værdien api_key.

Vælg et programmeringssprog. Konfigurér din API-nøgle, og kør derefter eksemplet på din server.

Hver forespørgsel om en forudsigelse er en ny operation, der koster kreditter, også når den gentages. Eksemplerne prøver ikke automatisk igen. Kontrollér opkrævningsstatus, før du sender en ny forespørgsel.

Før du kører: adgang og fejlhåndtering

Kør eksemplerne på din server. Sæt GENDERAPI_API_KEY i procesmiljøet til din eksisterende API-nøgle. Bekræft, at meta.access.mode er api_key: En nøgle, der ikke genkendes, kan føre til IP-prøveadgangen.

JSON-svar med HTTP 4xx og 5xx bevarer fejlens body og returnerer en exitstatus, der ikke er nul. Kontrollér code, action og meta.usage.billing_status, før du prøver igen. Kontrollér også data eller error for hvert element i batchsvar med HTTP 200.

Guide til fejl og nye forsøg →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "profile-001",
      "type": "username",
      "value": "@alice_smith",
      "options": {
        "ai_mode": "off"
      }
    },
    {
      "id": "profile-002",
      "type": "username",
      "value": "alexriver",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "profile-003",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ i en POSIX-shell. Kør i din terminal. Dokumentation for kørselsmiljøet

// 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 = {
  "items": [
    {
      "id": "profile-001",
      "type": "username",
      "value": "@alice_smith",
      "options": {
        "ai_mode": "off"
      }
    },
    {
      "id": "profile-002",
      "type": "username",
      "value": "alexriver",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "profile-003",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  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+, indbygget fetch. Gem som example.mjs, og kør node example.mjs. Dokumentation for kørselsmiljøet

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("{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"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/batch",
    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. Gem som example.py, og kør python3 example.py. Dokumentation for kørselsmiljøet

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"profile-001","type":"username","value":"@alice_smith","options":{"ai_mode":"off"}},{"id":"profile-002","type":"username","value":"alexriver","options":{"ai_mode":"fallback"}},{"id":"profile-003","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
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 cURL-udvidelsen. Gem som example.php, og kør php example.php. Dokumentation for kørselsmiljøet

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 = "{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"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/batch"))
            .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+, standard-HTTP-klienten. Gem som GenderApiExample.java, og kør java GenderApiExample.java. Dokumentation for kørselsmiljøet

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/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"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.
}

Konsolapplikation med .NET 8+. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Dokumentation for kørselsmiljøet

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 := "{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", 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. Gem som main.go, og kør go run main.go. Dokumentation for kørselsmiljøet

Håndtér resultater fra lister og gentagne forespørgsler

POST /api/v2/gender/batch accepterer op til 50 elementer med en API-nøgle og 10 med IP-prøveadgangen. Giv hvert element sine egne værdier for type, value og options. Hvis du vil bruge den almindelige AI-fallback, skal du angive fallback udtrykkeligt i hvert element. id skal være unikt inden for batchen; index starter ved nul inden for den sendte batch. Gem dine egne job- og kilderækkeidentifikatorer separat.

HTTP 200 betyder ikke, at alle elementer er gennemført. Håndtér resultaterne identified, unknown og error hver for sig; meta.summary.succeeded tæller både identified og unknown. Vurdér data.gender, source, confidence_kind, confidence, match og reason samlet. Behandl ikke en AI-score og en hyppighed i datasættet som ligeværdige.

Hvis meta.usage.billing_status har værdien confirmed, skal du kun gentage de driftsfejl, der tillader en ny forespørgsel. Hvis statussen er unconfirmed, eller svaret er gået tabt, skal du stoppe og kontrollere opkrævningen. Hvis du sender det samme element igen, også et gennemført unknown-resultat, oprettes en ny betalt operation; send aldrig hele listen igen i blinde.

Kontrakt for batchforespørgsler · Svarfelter · AI-indstillinger · Vurdering af nøjagtighed og konfidens · Privatlivspolitik

Tilføjelserne til Excel og Google Sheets og de andre færdige integrationer kan bruge deres egen forbindelse og deres eget resultatformat. Gå ikke ud fra, at deres output følger dette V2-JSON-skema; læs den aktuelle guide til den pågældende integration.

Ofte stillede spørgsmål

Køn ud fra et brugernavn eller et kaldenavn

Kan man bestemme køn ud fra et brugernavn?

Hvis du slår forceToGenderize til i V2, kontrolleres datasættet først; hvis der ikke kan bestemmes et køn, kan AI fortolke kaldenavnet, uden at der kræves et egentligt fornavn. Resultatet kan forblive unknown og er ikke en verificeret identitet. Den almindelige AI-fallback kræver derimod et brugbart egentligt fornavn.

Hvilke brugernavne giver de mest brugbare resultater?

Et mere brugbart signal kan komme fra værdier, der indeholder et egentligt fornavn, en genkendelig form af et kaldenavn eller et tydeligt navneelement. Tilfældige tegnfølger og varemærkenavne giver ikke altid et resultat.

Kan jeg analysere et enkelt brugernavn via API'et?

Ja. Endpointet til enkeltforespørgsler analyserer ét element. Til flere elementer findes et særskilt endpoint til batchforespørgsler.

Kan jeg importere en Excel- eller CSV-fil?

Ja. I filværktøjet kan du vælge kolonnen med brugernavne eller visningsnavne og slå fortolkning af kaldenavne til.

Hvorfor skal jeg gemme konfidens- og kildefelterne fra V2 sammen?

I V2 ligger data.confidence mellem 0 og 1. Vurdér værdien sammen med source og confidence_kind, fordi en AI-score og en hyppighed i datasættet er forskellige mål. Bevar unknown-resultaterne og feltet reason.

Er resultatet egnet til segmentering?

Det kan bruges som et supplerende signal i samlede analyser og til databerigelse, men bør ikke alene afgøre spørgsmål med stor betydning for en enkelt person eller fastslå personens identitet.

Kan jeg prøve tjenesten gratis?

Nye GenderAPI-konti indeholder 200 gratis API-kreditter om dagen, som du kan bruge til at teste repræsentative stikprøver via API'et eller filer.

Forudsig køn ud fra brugernavne og kaldenavne

Analysér kaldenavnene i dit datasæt