Voordat u het verzoek verstuurt
Verstuur voorspellingsverzoeken naar GenderAPI.io V2 met POST https://api.genderapi.io/api/v2/gender en geef type en value op in de JSON-body. Gebruik uw bestaande GenderAPI.io-sleutel in Authorization: Bearer YOUR_API_KEY en Content-Type: application/json. Lees het resultaat in data en de informatie over toegang en afschrijving in meta. Elk verzoek wordt afzonderlijk verwerkt.
Kies de programmeertaal in het codevoorbeeld. Stel GENDERAPI_API_KEY in de procesomgeving in voordat u het uitvoert. Ontbrekende of niet-herkende sleutels kunnen de gedeelde IP-proefperiode gebruiken: controleer daarom bij de koppeling van een account of meta.access.mode api_key is.
Geslacht op basis van een gebruikersnaam of bijnaam
| Parameter | Type | Verplicht | Standaardwaarde | Beschrijving |
|---|---|---|---|---|
type | string | Ja | — | Invoercategorie: name, email of username. |
value | string | Ja | — | Verplicht. 1–254 tekens; niet leeg en zonder besturingstekens. E-mailwaarden moeten een geldige e-mailsyntaxis hebben. |
country | string | Nee | — | Optionele ISO 3166-1 alpha-2-code in hoofdletters, bijvoorbeeld TR of US. Een landspecifieke zoekopdracht kan terugvallen op de wereldwijde dataset. |
forceToGenderize | boolean | Nee | false | Raadpleegt eerst de dataset en daarna AI met bijnaaminterpretatie als er geen resultaat is. Ondersteund voor name, email en username. |
options | object | Nee | — | Object met de AI-opties per invoer. |
options.ai_mode | string | Nee | fallback | Toegestane waarden: off, fallback, always. Laat dit veld bij forceToGenderize: true weg of gebruik fallback. |
id | string | Nee | — | Optionele identificatie van 1–64 tekens in de POST-JSON. Wordt naast het bijbehorende batchresultaat teruggegeven en moet uniek zijn binnen de batch. Wordt bij losse voorspellingen geaccepteerd maar niet teruggegeven. Niet ondersteund in GET-query's. |
Verstuur type: username en de gebruikersnaam of bijnaam in value naar POST https://api.genderapi.io/api/v2/gender. Stel forceToGenderize in op true als u een voorspelling wilt op basis van de betekenis van een bijnaam zoals prenses, ook wanneer er geen echte voornaam kan worden gevonden. GenderAPI.io V2 raadpleegt ook dan eerst de dataset. Een voorspelling op basis van een bijnaam kan een data.gender anders dan null teruggeven met data.name: null.
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.
Handleiding voor fouten en nieuwe pogingen →cURL 7.76+ in een POSIX-shell. Voer uit in uw terminal. Documentatie van de runtime
Node.js 22+; ingebouwde fetch. Sla op als example.mjs en voer node example.mjs uit. Documentatie van de runtime
Python 3.10+; standaardbibliotheek. Sla op als example.py en voer python3 example.py uit. Documentatie van de runtime
PHP 8+ met de cURL-extensie. Sla op als example.php en voer php example.php uit. Documentatie van de runtime
Java 17+; standaard HTTP-client. Sla op als GenderApiExample.java en voer java GenderApiExample.java uit. Documentatie van de runtime
.NET 8+-consoleapplicatie. Gebruik als Program.cs in een consoleproject en voer daarna dotnet run uit. Documentatie van de runtime
Go 1.22+; standaardbibliotheek. Sla op als main.go en voer go run main.go uit. Documentatie van de runtime
Voorbeeldantwoord
Dit is een echt antwoord dat op 1 oktober 2026 met een API-sleutel is opgehaald; alleen het accountsaldo is vervangen. Het is geen maatstaf voor nauwkeurigheid, en een live verzoek kan een ander resultaat geven. Verzoeken met een API-sleutel geven meta.access.mode: api_key en null in de quotumvelden die alleen voor de proefperiode gelden; verzoeken via de IP-proefperiode geven ip_trial. Lees data voor de voorspelling en meta.usage voor de afschrijving van de bewerking.
{
"data": {
"input": {
"type": "username",
"value": "prenses",
"country": "TR",
"forceToGenderize": true
},
"name": "prenses",
"gender": "female",
"country": "TR",
"confidence": 0.9456521739130435,
"confidence_kind": "observed_frequency",
"sample_count": 184,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "prenses",
"method": "normalized",
"scope": "country",
"country": "TR"
}
},
"meta": {
"request_id": "a799faa4-bc1a-4537-90b3-2c1b60205499",
"duration_ms": 15,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Velden van het voorspellingsantwoord
| Veld | Type | Kan null zijn | Voorbeeld | Beschrijving |
|---|---|---|---|---|
data.input | object | Nee | {"type":"name","value":"Daan","country":"NL"} | Invoertype, waarde en land. forceToGenderize wordt opgenomen als het true is. |
data.name | string | Ja | "daan" | Gevonden of afgeleide voornaam; null als er geen beschikbaar is. |
data.gender | string | Ja | "male" | male, female of JSON null. Een voorspelling, geen geverifieerde persoonlijke identiteit. |
data.result_status | string | Nee | "identified" | identified als er een geslacht wordt teruggegeven; anders unknown. |
data.reason | string | Ja | null | null bij identified resultaten. Redenen bij unknown: not_found, no_name_candidate, ambiguous of insufficient_evidence. |
data.confidence | number | Ja | 0.95 | Score van 0 tot 1 of null. Als gender null is, is ook de betrouwbaarheidsscore null. |
data.confidence_kind | string | Ja | "observed_frequency" | observed_frequency: dominante telling in de dataset gedeeld door het totaal. model_reported: score die AI opgeeft, geen gekalibreerde kans. null als die niet beschikbaar is. |
data.sample_count | integer | Ja | 1200 | Steekproefgrootte in de dataset of null. AI verzint geen steekproefgrootte. |
data.source | string | Nee | "dataset" | dataset, ai of none. |
data.country | string | Ja | "NL" | Koppeling aan een land via dataset of ai_association, of null. Bepaalt geen nationaliteit, woonplaats of etnische afkomst. |
data.country_source | string | Ja | "dataset" | Herkomst van de koppeling aan een land: dataset, ai_association of null. |
data.match | object | Nee | {"name":"daan","method":"normalized","scope":"country","country":"NL"} | Gevonden naam in de dataset, methode (normalized, token, substring of model_inference), bereik country of global en het bijbehorende land. Ontbrekend bewijs is null. |
Metadata over toegang, afschrijving en verzoek
| Veld | Type | Kan null zijn | Voorbeeld | Beschrijving |
|---|---|---|---|---|
meta.request_id | string | Nee | "550e8400-e29b-41d4-a716-446655440000" | Unieke identificatie van deze HTTP-poging; wordt ook verstuurd in X-Request-ID. |
meta.duration_ms | integer | Nee | 42 | Verwerkingstijd van het verzoek in milliseconden. |
meta.access.mode | string | Nee | "api_key" | api_key, ip_trial of unauthenticated. Controleer bij een betaald account of api_key wordt vermeld. |
meta.access.reason | string | Ja | null | Reden om naar de IP-proefperiode over te schakelen: api_key_missing, api_key_invalid of api_key_not_found; anders null. |
meta.usage.charged_credits | integer | Ja | 1 | Netto afgeschreven credits. Nul vóór de afschrijving of na een bevestigde volledige terugboeking; null als de afschrijving niet is bevestigd. |
meta.usage.remaining_credits | integer | Ja | 99 | Saldo bij voltooiing van de bewerking. Kan negatief zijn; null als het niet beschikbaar is of de afschrijving niet is bevestigd. |
meta.usage.billing_status | string | Nee | "confirmed" | not_charged, confirmed of unconfirmed. Controleer dit voordat u een mislukte voorspelling herhaalt. |
meta.usage.resets_at | string | Ja | "2026-09-27T12:00:00.000Z" | Tijdstip waarop de IP-proefperiode wordt hersteld, in UTC (ISO 8601); null voor accounts met een API-sleutel of als het onbekend is. |
meta.usage.limit | integer | Ja | 10 | Tegoed van de IP-proefperiode; null voor accounts met een API-sleutel. |
meta.usage.period_seconds | integer | Ja | 86400 | Duur van de periode van de IP-proefperiode in seconden; null voor accounts met een API-sleutel. |
Een voorspelling op basis van een bijnaam lezen
Het voorbeeld gebruikt forceToGenderize: true. Een zoekopdracht met een resultaat uit de dataset kost 1 credit. Anders laat de API AI de alias interpreteren en worden voor een geslaagde bewerking in totaal 2 credits afgeschreven, ook bij een onbekend resultaat. Laat ai_mode weg of stel het in op fallback; off en always zijn niet te combineren met forceToGenderize en geven 422 terug.
In de bijnaammodus is een voorspeld geslacht met name: null toegestaan. Dat betekent dat er geen echte voornaam is gevonden; het is geen verwerkingsfout. Als een geslacht wordt teruggegeven, hebben AI-resultaten sample_count: null en confidence_kind: model_reported. De score is geen gekalibreerde kans en geen geverifieerde identiteit.
Zonder forceToGenderize gebruikt ook een losse zoekopdracht op gebruikersnaam standaard de normale AI-fallback voor in totaal 1 credit, maar daarvoor is een bruikbare echte voornaam nodig. Gebruik options.ai_mode: off om alleen de dataset te gebruiken.