Veiledning for analyse av brukernavn

Les som Markdown

Estimer kjønn ut fra brukernavn og kallenavn

Analyser brukernavn og kallenavn med V2: forceToGenderize, KI per element, ukjente resultater og kostnaden ved nye forespørsler.

Filbehandling uten kode

Analyser kallenavnene i datasettet ditt

Last opp en Excel- eller CSV-fil, velg kolonnen med brukernavn, og slå på tolkning av kallenavn før postene behandles.

  • Excel- og CSV-filer
  • Kolonner med brukernavn og visningsnavn
  • Berikede resultater som kan eksporteres
Åpne Excel/CSV-verktøyet
Alternativer for analyse av brukernavn og kallenavn i filarbeidsflyten til GenderAPI
Tolkning av kallenavn i filarbeidsflyten til GenderAPI.

Eksempler på inndata

Et kallenavn er ingen bekreftelse av identitet

@alice_smith kan gi treff på et navneelement. For prenses med forceToGenderize kan et estimat returneres selv om navnet forblir null. user47291 kan forbli ukjent. Dette er bare eksempler på inndata; de har ikke noe forhåndsbestemt kjønnsresultat.

Analyselogikk

Hvordan fungerer kjønnsestimering ut fra brukernavn?

Systemet ser etter gjenkjennelige navneelementer og andre språklige holdepunkter i brukernavnet eller visningsnavnet. Vanlig KI-reserve ser etter et brukbart ekte fornavn; med forceToGenderize kan KI tolke et kallenavn uten et ekte fornavn. Resultatet returneres sammen med kontekstfeltene. Ikke tving frem et resultat for tilfeldige eller utilstrekkelige inndata.

01BrukernavnKallenavn eller visningsnavn
02SignalanalyseNavn og kontekst
03EstimatKjønn og konfidens

Bruksmåter

Velg metoden som passer dataene dine

Behandle store datasett uten kode

Analyser brukernavn i Excel eller CSV i fire trinn

  1. 01

    Åpne Excel/CSV-verktøyet

    Åpne filverktøyet til GenderAPI, og last opp filen som skal behandles.

  2. 02

    Velg kildekolonnen

    Tilordne kolonnen som inneholder brukernavn, kallenavn eller visningsnavn.

  3. 03

    Slå på tolkning av kallenavn

    Aktiver alternativet som tolker aliaser og navn fra sosiale medier.

  4. 04

    Kontroller et utvalg, og eksporter deretter

    Gå først gjennom et representativt utvalg av poster, behandle deretter hele filen, og last ned de berikede dataene.

Nye kontoer får 200 gratis kreditter per dag, så du kan teste arbeidsflyten på et utvalg før du behandler hele filen.

Bruksområder

Bruk det som et supplerende signal når et ekte fornavn mangler

Når navnefeltet er tomt, kan analyse av brukernavn være nyttig for data fra sosiale medier, fellesskap, spill og profiler som brukerne selv har opprettet. Hvis du har en mer direkte og pålitelig kilde, for eksempel et ekte fornavn eller en e-postadresse, bruker du det tilsvarende endepunktet.

Begrensninger

Ikke behandle resultatet som en bekreftet identitet

Ikke alle kallenavn inneholder et ekte fornavn, kulturelle assosiasjoner varierer, og samme uttrykk kan ha ulik betydning på forskjellige språk. Når signalet ikke er tilstrekkelig, bør du godta et tomt resultat i stedet for å trekke en sikker konklusjon av svake data.

Implementeringsveiledning for V2

Lagre kildedata og estimat hver for seg

Behold den opprinnelige identifikatoren for posten. API-et åpner ingen profil, kontrollerer ikke hvem som eier en konto, og bekrefter ingen identitet. Send bare landkontekst når du har pålitelig informasjon, og ikke utled den fra domenet eller språket på nettstedet.

Eksempel på inndataFelt eller alternativTolkning
@alice_smithdata.name / data.matchBehold det opprinnelige brukernavnet, og ikke behandle den gjenkjente delen som et verifisert navn.
prensesforceToGenderize: trueGjør det mulig å tolke et kallenavn uten et ekte fornavn. Et kjønn kan returneres mens data.name er null; ikke dikt opp et navn for personen.
user47291data.result_status: unknownTvetydige eller utilstrekkelige inndata kan forbli ukjente. Det er ingen grunn til å sende forespørselen automatisk på nytt.

Send brukernavnet med type: username, ikke en profil-URL. Oppslaget i datasettet fjerner en innledende @, normaliserer teksten og lager kandidater ut fra skilletegn og sifre. En standardforespørsel kan legge til et begrenset antall treff fra begynnelsen og slutten; forceToGenderize bruker ikke disse ekstra delene. Hvis flere rader gir treff, velges raden med flest registrerte forekomster. Bruk type: email for e-postadresser og type: name for ekte navn.

Velg behandlingsmodus og kostnad i kreditter

AlternativBehandlingKreditter per fullført element
options.ai_mode: offBare datasettet1 kreditt
options.ai_mode: fallbackFørst datasettet; vanlig KI-reserve hvis kjønnet ikke kan bestemmes1 kreditt totalt, inkludert KI
options.ai_mode: alwaysDirekte til KI2 kreditter
forceToGenderize: trueFørst datasettet, deretter tolkning av kallenavnet uten krav om et ekte fornavn1 hvis datasettet er nok, 2 totalt hvis KI brukes

Standard for en enkeltforespørsel er fallback, og for elementer i en samleforespørsel er det off. forceToGenderize er valgfritt for navn, e-postadresser og brukernavn; utelat da ai_mode eller bruk fallback, fordi alternativet ikke kan kombineres med off og always. Fullførte unknown-resultater belastes også. En positiv saldo er nok til å starte, og etter at behandlingen er fullført, kan saldoen bli negativ.

Gi hvert element i en samleforespørsel egne alternativer

Eksempler på inndata garanterer ikke et bestemt estimat. Sett GENDERAPI_API_KEY i servermiljøet, og ikke legg nøkkelen i offentlig kode på klientsiden. V1 og V2 bruker samme API-nøkkel og samme kontosaldo. Kontroller nøkkelen med /api/v2/usage, og bekreft at meta.access.mode har verdien api_key.

Velg et programmeringsspråk. Konfigurer API-nøkkelen, og kjør deretter eksemplet på serveren din.

Hver prediksjonsforespørsel er en ny operasjon som belastes, også nye forsøk. Disse eksemplene prøver ikke automatisk på nytt. Sjekk belastningsstatusen før du sender en ny forespørsel.

Før du kjører: tilgang og feilhåndtering

Kjør disse eksemplene på serveren din. Sett GENDERAPI_API_KEY i prosessmiljøet til din eksisterende API-nøkkel. Bekreft at meta.access.mode er api_key: en nøkkel som ikke gjenkjennes, kan føre til IP-prøveperioden.

Ved JSON-svar med HTTP 4xx og 5xx beholdes feilinnholdet, og eksemplet avsluttes med en exit-status som ikke er null. Sjekk code, action og meta.usage.billing_status før du prøver på nytt. Ved HTTP 200-svar på samleforespørsler må du også kontrollere data eller error for hvert element.

Veiledning om feil og nye forsøk →
cURL
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 et POSIX-skall. Kjør i terminalen. Dokumentasjon for kjøretidsmiljøet

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 = {
  "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+; innebygd fetch. Lagre som example.mjs og kjør node example.mjs. Dokumentasjon for kjøretidsmiljøet

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("{\"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. Lagre som example.py og kjør python3 example.py. Dokumentasjon for kjøretidsmiljøet

PHP
<?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-utvidelsen. Lagre som example.php og kjør php example.php. Dokumentasjon for kjøretidsmiljøet

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 = "{\"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-klient. Lagre som GenderApiExample.java og kjør java GenderApiExample.java. Dokumentasjon for kjøretidsmiljøet

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

Konsollapplikasjon i .NET 8+. Bruk som Program.cs i et konsollprosjekt, og kjør deretter dotnet run. Dokumentasjon for kjøretidsmiljøet

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 := "{\"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. Lagre som main.go og kjør go run main.go. Dokumentasjon for kjøretidsmiljøet

Håndter resultater fra lister og nye forsøk

POST /api/v2/gender/batch godtar opptil 50 elementer med en API-nøkkel og 10 i IP-prøveperioden. Gi hvert element egne verdier for type, value og options. Hvis du vil bruke vanlig KI-reserve, må du angi fallback uttrykkelig i hvert element. id må være unik i samleforespørselen, og index begynner på null i den innsendte samleforespørselen. Lagre dine egne jobb- og kilderad-ID-er separat.

HTTP 200 betyr ikke at alle elementer er fullført. Håndter resultatene identified, unknown og error hver for seg; meta.summary.succeeded teller både identified og unknown. Vurder data.gender, source, confidence_kind, confidence, match og reason samlet, og ikke behandle en KI-verdi og en frekvens i datasettet som det samme.

Hvis meta.usage.billing_status har verdien confirmed, skal du bare gjenta feilene som tillater et nytt forsøk. Hvis statusen er unconfirmed, eller svaret har gått tapt, må du stoppe og kontrollere belastningen. Hvis du sender det samme elementet på nytt, også et fullført unknown-resultat, belastes det som en ny handling; send aldri hele listen på nytt uten kontroll.

Regler for samleforespørsler · Svarfelt · KI-alternativer · Vurdering av nøyaktighet og konfidens · Personvernerklæring

Tilleggene for Excel og Google Sheets og de andre ferdige integrasjonene kan bruke egen tilkobling og eget resultatformat. Ikke gå ut fra at utdataene deres følger dette V2-JSON-skjemaet; les den gjeldende veiledningen for den aktuelle integrasjonen.

Vanlige spørsmål

Kjønn fra brukernavn og kallenavn

Kan kjønn estimeres ut fra et brukernavn?

Når forceToGenderize er slått på i V2, kontrolleres datasettet først. Hvis kjønnet ikke kan bestemmes, kan KI tolke kallenavnet uten at det kreves et ekte fornavn. Resultatet kan fortsatt være unknown og er ikke en bekreftet identitet. Vanlig KI-reserve krever derimot et brukbart ekte fornavn.

Hvilke brukernavn gir de mest nyttige resultatene?

Verdier som inneholder et ekte fornavn, en vanlig form av et kallenavn eller et tydelig navneelement, gir oftere et nyttig signal. Tilfeldige tegnstrenger og merkenavn gir ikke alltid et resultat.

Kan jeg analysere ett brukernavn via API-et?

Ja. Endepunktet for enkeltforespørsler analyserer én verdi, og et eget endepunkt for samleforespørsler håndterer flere elementer.

Kan jeg laste opp en Excel- eller CSV-fil?

Ja. Velg kolonnen med brukernavn eller visningsnavn i filverktøyet, og slå på tolkning av kallenavn.

Hvorfor bør konfidensfeltet og kildefeltet fra V2 lagres sammen?

I V2 ligger data.confidence mellom 0 og 1. En KI-verdi og en frekvens i datasettet måler ulike ting, så les verdien sammen med source og confidence_kind. Behold også unknown-resultatene og feltet reason.

Kan resultatet brukes til kundesegmentering?

Det kan være et supplerende signal i aggregerte analyser eller ved databerikelse, men bør ikke alene avgjøre spørsmål med stor betydning for en person eller brukes til å fastslå noens identitet.

Kan jeg teste gratis?

Nye GenderAPI-kontoer får 200 gratis kreditter per dag, som kan brukes til å teste et representativt utvalg via API-et eller filverktøyet.

Publisert: 16. juli 2025Sist gjennomgått:

Test integrasjonen

Analyser brukernavn med riktig API

Start med 200 gratis kreditter per dag, og koble til endepunktet som passer arbeidsflyten din.