# Geslacht bepalen op basis van Chinese namen

> Probeer Chinese namen met GenderAPI.io V2. Lees hoe korte delen, het splitsen van volledige namen, de oorspronkelijke tekens en de landcontext CN de resultaten van de dataset en AI beïnvloeden.

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

Last reviewed: 2026-09-28

## Onderscheid maken tussen Unicode-invoer en het splitsen van volledige namen

U kunt een Chinese naam als Unicode-tekst versturen zonder die eerst naar het Latijnse schrift om te zetten. De huidige zoekopdracht controleert genormaliseerde delen; een volledige Chinese naam zonder spaties wordt niet automatisch gesplitst in achternaam en voornaam. 王静怡 is dus één kandidaat en geen gegarandeerde zoekopdracht naar 静怡.

Voor de gangbare Chinese tekens in de voorbeelden slaat het huidige kandidatenfilter van de dataset delen van één of twee tekens over. Een korte voornaam kan geldige invoer zijn en toch geen kandidaat opleveren. De normale AI-fallback kan de oorspronkelijk verstuurde waarde nog wel interpreteren; een verzoek dat alleen de dataset gebruikt, houdt het resultaat onbekend.

Unicode-normalisatie NFKC biedt geen algemene omzetting tussen vereenvoudigd en traditioneel Chinees en herleidt een Latijnse spelling niet tot één oorspronkelijke Chinese naam. Bewaar de verstuurde spelling en controleer de teruggegeven match. De positie van de achternaam, het schrift of de romanisering is niet genoeg om conclusies te trekken over het geslacht of het land van een persoon.

| Voorbeeldinvoer | Wat het voorstelt | Wat u controleert |
| --- | --- | --- |
| `王静怡` | Volledige naam zonder spaties | Eén kandidaat in de dataset. De huidige analyse splitst de achternaam niet af. |
| `静怡` | Voornaam van twee tekens | Wordt overgeslagen door de lengtegrens van het kandidatenfilter; de AI-fallback kan de oorspronkelijke waarde interpreteren. |
| `王 静怡` | Afzonderlijke korte delen | Een extra spatie omzeilt de lengtegrens niet. Beide delen in het voorbeeld zijn te kort voor de zoekopdracht in de dataset. |
| `Wang Jingyi` | Invoer in Latijns schrift | Wordt als aparte waarde behandeld en in eigen delen gesplitst. Het is niet gegarandeerd dat deze naar de oorspronkelijke tekens of hetzelfde item wordt herleid. |

## De landcontext CN bewust kiezen

De live demo verstuurt country: CN (China). De API kiest dit land niet op basis van het schrift waarin de naam is geschreven. Gebruik in uw integratie bekende, relevante landcontext of laat country weg. Maak van deze voorbeeldwaarde geen standaardwaarde voor alle records.

Per kandidaat kiest de zoekopdracht het landspecifieke item als dat bestaat en anders het globale item. Daarna wordt de beschikbare kandidaat met de hoogste opgeslagen totale telling gekozen. Het werkelijke bereik van de match staat in data.match.scope en data.match.country. Een landspecifiek item met gelijke frequenties wordt niet automatisch vervangen door het globale resultaat; als de fallback actief is, kan in plaats daarvan AI worden gebruikt.

data.input.country beschrijft de landcontext die in het verzoek is verstuurd. data.country en data.country_source beschrijven de teruggegeven koppeling met een land en de herkomst daarvan. Dit zijn verschillende velden en ze zeggen niets over nationaliteit, etnische afkomst of woonplaats.

- [Landcontext en matches](https://www.genderapi.io/nl/docs/v2/gender-from-name#country-evidence-workflow)

## Een V2-verzoek voor een naam versturen vanuit uw applicatie

Stel GENDERAPI_API_KEY in op uw bestaande sleutel en voer het voorbeeld uit op uw server. Het verzoek schakelt de normale AI-fallback expliciet in. Het laat de opbouw van het verzoek zien, geen gemeten nauwkeurigheid of bevestigde dekking. Stel voor een voorspelling die alleen de dataset gebruikt options.ai_mode: off in.

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": "name",
  "value": "王静怡",
  "country": "CN",
  "options": {
    "ai_mode": "fallback"
  }
}'
```

**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": "name",
  "value": "王静怡",
  "country": "CN",
  "options": {
    "ai_mode": "fallback"
  }
};

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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}")

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":"name","value":"王静怡","country":"CN","options":{"ai_mode":"fallback"}}', 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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}", 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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    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)
    }
}
```

- [Parameters voor verzoeken met namen](https://www.genderapi.io/nl/docs/v2/gender-from-name)
- [De API-sleutel instellen](https://www.genderapi.io/nl/docs/v2/authentication)

## 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)

## Een lijst met namen verwerken zonder de context te verliezen

Verstuur maximaal 50 items met een API-sleutel of 10 met de IP-proefperiode via POST /api/v2/gender/batch. Geef elk item een unieke id en bewaar de oorspronkelijke waarde van elke rij. Elk item kan eigen opties voor land en AI hebben; laat het land weg als het niet bekend is.

Anders dan losse verzoeken, die standaard de fallback gebruiken, gebruiken items in een batch standaard alleen de dataset. Stel options.ai_mode: fallback in voor elk item dat AI nodig heeft. Controleer elk resultaat, ook na HTTP 200, bewaar onbekende resultaten en controleer fouten en de afschrijving voordat u opnieuw verstuurt. Elk geslaagd normaal item kost 1 credit; één HTTP-verzoek voor een batch staat niet gelijk aan één credit per voorspelling.

- [Batchvoorbeelden en gedeeltelijke fouten](https://www.genderapi.io/nl/docs/v2/batch#batch-application-workflow)
- [Onbekende resultaten in uw applicatie verwerken](https://www.genderapi.io/nl/docs/v2/responses#application-decisions)

## 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)

## Waarom kan een Chinese voornaam van twee tekens onbekend blijven als alleen de dataset wordt gebruikt?

Het huidige kandidatenfilter slaat delen over waarvan de lengte als JavaScript-tekenreeks maximaal twee is. Voor de Chinese tekens die hier worden getoond, is een voornaam van twee tekens geldige invoer, maar wordt deze geen kandidaat in de dataset. De AI-fallback kan de oorspronkelijke waarde interpreteren.

## Splitst V2 de Chinese achternaam automatisch van de voornaam?

De zoekopdracht in de dataset splitst een volledige Chinese naam zonder spaties niet. AI kan uit de hele waarde een voornaam afleiden, maar geen van beide wegen garandeert dat de bedoelde voornaam wordt gekozen. Controleer source en match in het antwoord.

## Is er voor deze groep namen een onafhankelijke evaluatie van de nauwkeurigheid gepubliceerd?

Deze pagina publiceert zo'n evaluatie niet. Het accepteren van invoer, het tonen van opgeslagen frequenties of het teruggeven van een betrouwbaarheidsscore is geen onafhankelijke meting van de nauwkeurigheid. De methodologie beschrijft welke gegevens beschikbaar zijn en welke metingen nog niet zijn gepubliceerd.

## Kost een resultaat zonder voorspelling credits?

Een geslaagd onbekend resultaat wordt afgeschreven. De normale modus met de dataset of met de fallback kost in totaal 1 credit. Met forceToGenderize kost het verzoek 1 credit als het resultaat uit de dataset komt, of in totaal 2 als AI wordt gebruikt, ook bij een onbekend resultaat. Voor fouten gelden aparte afschrijvingsregels; controleer meta.usage.