# Geslacht bepalen op basis van een gebruikersnaam of bijnaam

> Interpreteer een gebruikersnaam met GenderAPI.io V2. Probeer de normale naammatch of de optionele bijnaaminterpretatie, lees wat 1 of 2 credits kosten en bewaar onbekende resultaten.

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

Last reviewed: 2026-09-28

## Naamsignalen en de betekenis van bijnamen zijn verschillende dingen

Gebruik type: username voor een gebruikersnaam of bijnaam. Een optionele @ aan het begin wordt bij de match met de dataset verwijderd. Bij het zoeken naar kandidaten wordt rekening gehouden met scheidingstekens en cijfers en kunnen beperkte delen van tekenreeksen worden gecontroleerd. De bijnaammodus behoudt de match op hele delen, maar voegt deze kandidaten op basis van delen van tekenreeksen niet toe. Het geselecteerde opgeslagen item heeft de hoogste totale telling van de beschikbare kandidaten; dat zegt niets over de echte naam van de persoon achter het account.

De normale AI-fallback zoekt naar een herkenbare voornaam. forceToGenderize maakt daarnaast een koppeling via een persoonlijke bijnaam mogelijk als er geen echte naam kan worden gevonden. Beide wegen kunnen unknown teruggeven; een merk, een fictief personage of een gedeeld account staat niet per se voor één persoon.

| Voorbeeldinvoer | Aanpak | Wat u controleert |
| --- | --- | --- |
| `@alice.smith` | Begin met de normale fallback, die eerst de dataset raadpleegt. | Controleer de geselecteerde naam en de matchmethode; ga er niet van uit dat het eerste deel is gekozen. |
| `robert89` | Cijfers kunnen bij het zoeken naar kandidaten worden verwijderd. | Een overeenkomende naam is een koppeling, geen bevestigde identiteit. |
| `prenses` | Schakel forceToGenderize in om een AI-poging op basis van de bijnaam toe te staan als er geen resultaat wordt gevonden. | gender kan een waarde anders dan null hebben terwijl name null is. AI-waarden zijn model_reported. |
| `team_support` | Behandel functieaccounts en gedeelde accounts als accounts die mogelijk niet bij één persoon horen. | Bewaar unknown en ken aan een gedeeld account geen individuele identiteit toe. |

## Bijnaaminterpretatie in uw integratie uitproberen

Dit verzoek schakelt de bijnaaminterpretatie in. Eerst wordt de dataset geraadpleegd. Geeft die geen geslacht terug, dan kan AI de betekenis van de alias gebruiken. Laat forceToGenderize weg voor een normale zoekopdracht; losse verzoeken gebruiken standaard toch de normale AI-fallback.

Voor dit voorbeeld wordt de landcontext TR opgegeven. Gebruik relevante context uit uw eigen applicatie en controleer data.match.scope; een opgegeven land garandeert geen landspecifiek item. Het zegt niets over nationaliteit of woonplaats.

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.

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.

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.

**cURL**

cURL 7.76+ in een POSIX-shell. Voer uit in uw terminal.

```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+; ingebouwde fetch. Sla op als example.mjs en voer node example.mjs uit.

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

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

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

```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+-consoleapplicatie. Gebruik als Program.cs in een consoleproject en voer daarna dotnet run uit.

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

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

- [Volledig V2-overzicht voor gebruikersnamen](https://www.genderapi.io/nl/docs/v2/gender-from-username)

## Het resultaat samen met het bewijs opslaan

Een afgeleide koppeling is niet het geslacht dat iemand zelf opgeeft. Sla de oorspronkelijke invoer, het teruggegeven bewijs en wat de persoon zelf heeft opgegeven apart op. Een onbekend resultaat is een geldig resultaat en mag in uw applicatie geen geraden categorie worden.

| Veld | Gebruik |
| --- | --- |
| `data.gender / data.result_status` | Gebruik male of female alleen bij identified. Bewaar bij een onbekend resultaat de oorspronkelijke JSON-waarde null. |
| `data.name / data.match` | Controleer de teruggegeven naam en de geselecteerde kandidaat. Een match op een deel van de tekenreeks bewijst niet dat de invoer bij een persoon met die naam hoort. |
| `data.confidence / data.confidence_kind` | De betrouwbaarheidsscore staat op een schaal van 0 tot 1 of is null. observed_frequency is gebaseerd op opgeslagen frequenties; model_reported is een waarde die AI opgeeft. Evalueer drempels per soort afzonderlijk. |
| `data.source / data.sample_count` | Maak onderscheid tussen dataset, ai en none. AI-resultaten hebben geen opgeslagen steekproefgrootte. Een steekproefgrootte is geen gemeten nauwkeurigheid. |
| `meta.access.mode` | Controleer bij een integratie met een account of api_key wordt vermeld. Ontbrekende of niet-herkende sleutels kunnen anders de gedeelde IP-proefperiode gebruiken. |
| `meta.usage` | Lees charged_credits en billing_status. Een geslaagd onbekend resultaat wordt afgeschreven. Een verloren antwoord bewijst niet dat het verzoek gratis was. |

- [Antwoordvelden en onbekende resultaten](https://www.genderapi.io/nl/docs/v2/responses)
- [Nauwkeurigheid en betrouwbaarheidsscore uitgelegd](https://www.genderapi.io/nl/accuracy-methodology)
- [Gegevensbronnen en gedateerd profiel van de database](https://www.genderapi.io/nl/data-provenance)

## Bepalen wanneer u AI gebruikt

forceToGenderize is optioneel voor namen, e-mailadressen en gebruikersnamen. Als het is ingeschakeld, laat ai_mode dan weg of gebruik fallback; off en always kunnen niet met deze optie worden gecombineerd en geven 422 terug. Een positief beginsaldo is genoeg om een verzoek te starten, ook als de uiteindelijke afschrijving het saldo negatief maakt.

De bijnaammodus kan een geslacht teruggeven samen met name: null. Ook een onbekend resultaat is mogelijk. Noch de normale AI-fallback noch de bijnaaminterpretatie garandeert een juist antwoord of een waarde anders dan null.

| Optie in het verzoek | Werking | Credits per geslaagde zoekopdracht |
| --- | --- | --- |
| options.ai_mode: off | Gebruikt alleen de dataset. | 1, ook bij een onbekend resultaat |
| options.ai_mode: fallback | Raadpleegt eerst de dataset en gebruikt daarna de normale AI als er geen geslacht wordt teruggegeven. Dit is de standaardwaarde voor losse verzoeken. | In totaal 1, inclusief AI-fallback |
| options.ai_mode: always | Gebruikt direct AI. | 2 |
| forceToGenderize: true | Raadpleegt eerst de dataset en laat daarna AI een persoonlijke bijnaam of alias interpreteren, ook zonder echte voornaam. | 1 voor een resultaat uit de dataset; in totaal 2 als AI wordt gebruikt |

- [AI-opties en bijnaaminterpretatie](https://www.genderapi.io/nl/docs/v2/ai-options)
- [Credits en gebruik](https://www.genderapi.io/nl/docs/v2/credits-and-usage)

## Het resultaat van elke gebruikersnaam bewaren wanneer u een lijst verwerkt

Gebruik POST /api/v2/gender/batch voor lijsten met gebruikersnamen of voor gemengde lijsten met namen, e-mailadressen en gebruikersnamen. De limiet is 50 items met een API-sleutel of 10 met de IP-proefperiode. Elk item heeft eigen opties voor land en AI, en optionele id's moeten uniek zijn binnen de batch.

Standaard gebruikt een batch alleen de dataset. Schakel fallback per item in als u de normale AI wilt gebruiken, of stel forceToGenderize per item in om bijnamen te interpreteren. Controleer data of error in elk resultaat en gebruik id of index om het resultaat aan de oorspronkelijke rij te koppelen. Geslaagde onbekende items worden afgeschreven.

- [Een batch opbouwen en gedeeltelijke fouten verwerken](https://www.genderapi.io/nl/docs/v2/batch)
- [Fouten, verloren antwoorden en nieuwe pogingen](https://www.genderapi.io/nl/docs/v2/errors-and-retries)

## Weten wat u verstuurt

De live demo verstuurt de ingevoerde waarde pas naar GenderAPI.io wanneer u die zelf verstuurt. Als AI wordt gebruikt, worden type, value en de verstuurde landcontext doorgegeven aan de dienst die voor voorspellingen is geconfigureerd. Stel voor een voorspelling die alleen de dataset gebruikt in uw integratie options.ai_mode: off in zonder forceToGenderize.

Het privacybeleid, de verwerkersovereenkomst en de lijst met subverwerkers beschrijven de gepubliceerde voorwaarden voor de verwerking. Een resultaat is een afgeleide koppeling en wat iemand zelf opgeeft, gaat altijd voor. Gebruik het niet als basis voor beslissingen met belangrijke gevolgen voor een persoon.

- [Privacybeleid](https://www.genderapi.io/nl/privacy-policy)
- [Verwerkersovereenkomst](https://www.genderapi.io/nl/data-processing-agreement)
- [Subverwerkers](https://www.genderapi.io/nl/subprocessors)

## Moet een gebruikersnaam een echte voornaam bevatten?

De normale AI-voorspelling vereist een bruikbare voornaam. Met forceToGenderize kan de API daarnaast een koppeling via een bijnaam proberen als de zoekopdracht in de dataset geen resultaat oplevert. Deze modus vereist geen echte voornaam en kan name: null teruggeven.

## Garandeert forceToGenderize een geslacht?

Nee. Het maakt bijnaaminterpretatie mogelijk, maar het uiteindelijke resultaat kan toch onbekend zijn. Bewaar de oorspronkelijke JSON-waarde null en controleer result_status en reason.

## Controleert de API het profiel op sociale media?

Dit endpoint interpreteert de verstuurde waarde. Het haalt geen profiel, berichten of foto's van het account op om te achterhalen wie de eigenaar is.

## Kan ik forceToGenderize ook gebruiken voor namen of e-mailadressen?

Ja. Het is optioneel voor invoer van het type name, email en username. Eerst wordt de dataset gebruikt en daarna, als er geen resultaat wordt gevonden, AI met bijnaaminterpretatie: 1 credit voor een resultaat uit de dataset of in totaal 2 als AI wordt gebruikt.