Geslacht uit gebruikersnamen en bijnamen

Voorbeeldinvoer

Een bijnaam is geen identiteitscontrole

@alice_smith kan overeenkomen met een naamelement. Voor prenses met forceToGenderize kan een voorspelling worden teruggegeven terwijl de naam null blijft. user47291 kan onbekend blijven. Dit zijn voorbeeldinvoeren; wij kennen ze vooraf geen geslachtsresultaat toe.

Analyselogica

Hoe werkt het voorspellen van het geslacht uit een gebruikersnaam?

Het systeem zoekt naar herkenbare naamelementen en andere taalkundige aanwijzingen in de gebruikersnaam of de weergavenaam. De standaard AI-fallback zoekt naar een bruikbare echte voornaam; met forceToGenderize kan AI een bijnaam interpreteren zonder echte voornaam. Het resultaat wordt samen met de contextvelden teruggegeven; een willekeurige of onvoldoende invoer hoort niet tot een resultaat te worden gedwongen.

01GebruikersnaamBijnaam of weergavenaam

02Analyse van signalenNaam en context

03VoorspellingGeslacht en betrouwbaarheid

Gebruiksmogelijkheden

Kies de methode die bij uw gegevens past

Los verzoekAnalyseer één gebruikersnaam via de REST API.Bekijk de API-gids →BatchverzoekVerstuur meerdere items in één gestructureerd verzoek.Bekijk de gids voor batches →Excel- en CSV-workflowVerwerk een bestand zonder een integratie te ontwikkelen.Open de tool →

Grote datasets verwerken zonder code

Analyseer de gebruikersnamen in een Excel- of CSV-bestand in vier stappen

01
Open de Excel- en CSV-tool
Open de importtool van GenderAPI en upload het bestand dat u wilt verwerken.
02
Kies de bronkolom
Koppel de kolom met gebruikersnamen, bijnamen of weergavenamen.
03
Schakel bijnaaminterpretatie in
Schakel de optie in die aliassen en namen van sociale netwerken interpreteert.
04
Controleer een steekproef en exporteer daarna
Beoordeel eerst een representatieve steekproef van records, verwerk daarna het volledige bestand en download de verrijkte gegevens.

Nieuwe accounts bevatten 200 gratis API-credits per dag, zodat u de workflow op een steekproef kunt testen voordat u het volledige bestand verwerkt.

Toepassingen

Gebruik het als aanvullend signaal wanneer een echte voornaam ontbreekt

De analyse van gebruikersnamen kan nuttig zijn voor gegevens uit sociale netwerken, community’s, games en profielen die gebruikers zelf hebben aangemaakt, wanneer het naamveld leeg is. Beschikt u over een directere en toegestane bron, zoals een echte voornaam of een e-mailadres, gebruik dan het bijbehorende endpoint.

Beperkingen

Behandel het resultaat niet als een geverifieerde identiteit

Niet elke bijnaam bevat een echte voornaam, culturele associaties verschillen en dezelfde uitdrukking kan in verschillende talen iets anders betekenen. Is het signaal onvoldoende, accepteer dan een leeg resultaat in plaats van zwakke gegevens om te zetten in een definitieve conclusie.

V2-implementatiegids

Bewaar brongegevens en voorspelling afzonderlijk

Bewaar de oorspronkelijke identifier van het record. De API opent geen profiel, controleert niet wie de houder van een account is en bevestigt geen identiteit. Verstuur alleen landcontext als u over een betrouwbaar gegeven beschikt; leid het land niet af uit het domein of de taal van de website.

Voorbeeldinvoer	Veld of optie	Interpretatie
@alice_smith	data.name / data.match	Bewaar de oorspronkelijke gebruikersnaam; behandel het gevonden fragment niet als een geverifieerde naam.
prenses	forceToGenderize: true	Hiermee kan een bijnaam zonder echte voornaam worden geïnterpreteerd. Er kan een geslacht worden teruggegeven terwijl data.name null is; verzin geen naam voor de persoon.
user47291	data.result_status: unknown	Ambigue of onvoldoende invoer kan onbekend blijven. Dat is geen reden om het verzoek automatisch te herhalen.

Verstuur de gebruikersnaam met type: username; verstuur geen profiel-URL. De zoekopdracht in de dataset verwijdert een @ aan het begin, normaliseert de tekst en vormt kandidaten op basis van scheidingstekens en cijfers. Een standaardverzoek kan een beperkt aantal matches op basis van voorvoegsel en achtervoegsel toevoegen; forceToGenderize gebruikt deze extra fragmenten niet. Komen meerdere items overeen, dan wordt het item met de hoogste opgeslagen telling gekozen. Gebruik type: email voor e-mailadressen en type: name voor echte namen.

Kies de verwerkingsmodus en de kosten in credits

Optie	Verwerking	Kosten per succesvol item
options.ai_mode: off	Alleen dataset	1 credit
options.ai_mode: fallback	Eerst de dataset; als daar geen geslacht wordt bepaald, de standaard AI-fallback	In totaal 1 credit, inclusief AI
options.ai_mode: always	Rechtstreeks naar AI	2 credits
forceToGenderize: true	Eerst de dataset, daarna de interpretatie van de bijnaam zonder dat een echte voornaam nodig is	1 als de dataset volstaat; in totaal 2 als AI wordt gebruikt

Voor een los verzoek is fallback de standaardwaarde, voor batchitems off. forceToGenderize is optioneel voor namen, e-mailadressen en gebruikersnamen; laat ai_mode in dat geval weg of gebruik fallback, want de optie kan niet worden gecombineerd met off en always. Ook succesvolle unknown-resultaten worden gefactureerd. Een positief beginsaldo is voldoende om te starten; na afloop van de bewerking kan het saldo negatief worden.

Geef elk item in een batch eigen opties

Voorbeeldinvoer garandeert geen bepaalde voorspelling. Stel GENDERAPI_API_KEY in de serveromgeving in en plaats de sleutel niet in openbare clientcode. V1 en V2 gebruiken dezelfde accountsleutel en hetzelfde saldo. Controleer de sleutel met /api/v2/usage en ga na dat meta.access.mode de waarde api_key heeft.

Kies een programmeertaal. Stel uw API-sleutel in, voer daarna het voorbeeld uit op uw server.

Elk voorspellingsverzoek is een nieuwe betaalde bewerking, ook als het een nieuwe poging is. Deze voorbeelden proberen het niet automatisch opnieuw. Controleer de afschrijvingsstatus voordat u een nieuw verzoek verstuurt.

Voordat u het uitvoert: toegang en foutafhandeling

Voer deze voorbeelden uit op uw server. Stel in de procesomgeving GENDERAPI_API_KEY in op uw bestaande API-sleutel. Controleer of meta.access.mode api_key is: een niet-herkende sleutel kan terugvallen op de IP-proefperiode.

Bij JSON-antwoorden met HTTP 4xx en 5xx blijft de body van de fout behouden en eindigt het voorbeeld met een afsluitcode die niet nul is. Controleer code, action en meta.usage.billing_status voordat u het opnieuw probeert. Controleer bij batchantwoorden met HTTP 200 ook data of error van elk item.

Handleiding voor fouten en nieuwe pogingen →

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+ in een POSIX-shell. Voer uit in uw terminal. Documentatie van de runtime

// 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+; ingebouwde fetch. Sla op als example.mjs en voer node example.mjs uit. Documentatie van de runtime

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+; standaardbibliotheek. Sla op als example.py en voer python3 example.py uit. Documentatie van de runtime

<?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+ met de cURL-extensie. Sla op als example.php en voer php example.php uit. Documentatie van de runtime

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+; standaard HTTP-client. Sla op als GenderApiExample.java en voer java GenderApiExample.java uit. Documentatie van de runtime

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

.NET 8+-consoleapplicatie. Gebruik als Program.cs in een consoleproject en voer daarna dotnet run uit. Documentatie van de runtime

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+; standaardbibliotheek. Sla op als main.go en voer go run main.go uit. Documentatie van de runtime

Verwerk lijstresultaten en herhaalde verzoeken

POST /api/v2/gender/batch accepteert maximaal 50 items met een API-sleutel en 10 met de IP-proefperiode. Geef elk item eigen waarden voor type, value en options. Wilt u de standaard AI-fallback gebruiken, geef fallback dan bij elk item expliciet op. id moet binnen de batch uniek zijn; index begint binnen de verstuurde batch bij nul. Bewaar uw eigen identifiers voor de taak en de bronrij afzonderlijk.

HTTP 200 betekent niet dat alle items zijn geslaagd. Verwerk identified-, unknown- en error-resultaten afzonderlijk; meta.summary.succeeded telt zowel identified als unknown. Beoordeel data.gender, source, confidence_kind, confidence, match en reason in samenhang. Behandel een AI-score en een frequentie in de dataset niet als gelijkwaardig.

Heeft meta.usage.billing_status de waarde confirmed, herhaal dan alleen operationele fouten die een nieuw verzoek toestaan. Is de status unconfirmed of is het antwoord verloren gegaan, stop dan en controleer de afschrijving. Hetzelfde item opnieuw versturen, ook een succesvol unknown-resultaat, is een nieuwe betaalde bewerking; verstuur nooit blindelings de hele lijst opnieuw.

Contract voor batchverzoeken · Velden in het antwoord · AI-opties · Nauwkeurigheid en betrouwbaarheid beoordelen · Privacybeleid

De add-ons voor Excel en Google Sheets en andere kant-en-klare integraties kunnen een eigen verbinding en een eigen resultaatformaat gebruiken. Ga er niet van uit dat hun uitvoer dit V2-JSON-schema volgt; raadpleeg de actuele handleiding van de betreffende integratie.

Veelgestelde vragen

Het geslacht uit een gebruikersnaam of bijnaam

Kan het geslacht uit een gebruikersnaam worden bepaald?

Als u in V2 forceToGenderize inschakelt, wordt eerst de dataset geraadpleegd; als daar geen geslacht wordt bepaald, kan AI de bijnaam interpreteren zonder dat een echte voornaam nodig is. Het resultaat kan unknown blijven en is geen geverifieerde identiteit. De standaard AI-fallback vereist daarentegen een bruikbare echte voornaam.

Welke gebruikersnamen leveren de bruikbaarste resultaten op?

Een bruikbaarder signaal kan komen van waarden met een echte voornaam, een herkenbare vorm van een bijnaam of een duidelijk naamelement. Willekeurige tekenreeksen en merknamen leveren mogelijk geen resultaat op.

Kan ik één gebruikersnaam via de API analyseren?

Ja. Het endpoint voor losse verzoeken analyseert één item. Voor meerdere items is een afzonderlijk endpoint voor batchverzoeken beschikbaar.

Kan ik een Excel- of CSV-bestand importeren?

Ja. In de tool voor bestanden kiest u de kolom met gebruikersnamen of weergavenamen en schakelt u bijnaaminterpretatie in.

Waarom moet ik de V2-velden voor betrouwbaarheid en bron samen bewaren?

In V2 ligt data.confidence tussen 0 en 1. Beoordeel de waarde samen met source en confidence_kind, want een AI-score en een frequentie in de dataset zijn verschillende maatstaven. Bewaar unknown-resultaten en het veld reason.

Is het resultaat geschikt voor segmentatie?

Het kan dienen als aanvullend signaal in geaggregeerde analyses en bij dataverrijking, maar mag niet op zichzelf beslissen over zaken met grote gevolgen voor een individuele persoon en stelt geen identiteit vast.

Kan ik de dienst gratis proberen?

Nieuwe GenderAPI-accounts bevatten 200 gratis API-credits per dag, waarmee u representatieve steekproeven via de API of via bestanden kunt testen.

Geslacht voorspellen uit gebruikersnamen en bijnamen

Analyseer bijnamen in uw dataset