Het JSON-antwoord begrijpen
Losse voorspellingen van GenderAPI.io V2 geven een data-object terug voor het resultaat en een meta-object voor informatie over verzoek, toegang en afschrijving. Lees data.gender en data.confidence samen met data.confidence_kind en data.source. Het volgende voorbeeld uit de dataset is een echt antwoord dat op 1 oktober 2026 met een API-sleutel is opgehaald; alleen het accountsaldo is vervangen. Het is geen gemeten nauwkeurigheid van het product, en een live verzoek kan een ander resultaat geven. Verzoeken met een API-sleutel geven access.mode: api_key en null in de quotumvelden die alleen voor de proefperiode gelden; verzoeken via de IP-proefperiode geven ip_trial met de proeflimiet en het tijdstip van de reset.
{
"data": {
"input": {
"type": "name",
"value": "Daan",
"country": "NL"
},
"name": "daan",
"gender": "male",
"country": "NL",
"confidence": 0.9633838383838383,
"confidence_kind": "observed_frequency",
"sample_count": 792,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "daan",
"method": "normalized",
"scope": "country",
"country": "NL"
}
},
"meta": {
"request_id": "0a92fb23-a289-42dd-9102-ee40c0dcaad2",
"duration_ms": 8,
"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. |
Teruggegeven invoervelden
| Veld | Type | Kan null zijn | Voorbeeld | Beschrijving |
|---|---|---|---|---|
data.input.type | string | Nee | "name" | Invoercategorie: name, email of username. |
data.input.value | string | Nee | "Daan" | De verstuurde waarde voor de voorspelling. |
data.input.country | string | Ja | "NL" | Verstuurde landcontext; null als die is weggelaten. |
data.input.forceToGenderize | boolean | Nee | true | Alleen aanwezig als de bijnaammodus actief is; anders weggelaten. |
Velden van de match in de dataset
| Veld | Type | Kan null zijn | Voorbeeld | Beschrijving |
|---|---|---|---|---|
data.match.name | string | Ja | "daan" | Geselecteerde kandidaat in de dataset; null als er geen rij in de dataset is geselecteerd. |
data.match.method | string | Ja | "normalized" | normalized, token, substring of model_inference; null als het niet beschikbaar is. |
data.match.scope | string | Ja | "country" | country of global bij zoekopdrachten in de dataset; null bij AI of als bewijs ontbreekt. |
data.match.country | string | Ja | "NL" | Land van de geselecteerde rij in de dataset; null bij wereldwijde rijen of bij AI. |
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 geslaagd onbekend resultaat
HTTP 200 betekent dat de bewerking is voltooid; het garandeert geen geslacht. Behoud de JSON-waarde null in plaats van die om te zetten naar male, female, een lege tekenreeks of een betrouwbaarheidsscore van nul. Controleer data.result_status en data.reason los van HTTP-fouten.
Dit echte voorbeeld dat alleen de dataset gebruikt, opgehaald op 1 oktober 2026, geeft source: none en reason: not_found terug en kost toch 1 credit. Een rij in de dataset met gelijke tellingen kan reason: ambiguous teruggeven, waarbij sample_count behouden blijft. Een onbekend AI-resultaat gebruikt source: ai en reason: insufficient_evidence.
{
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
},
"meta": {
"request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Betrouwbaarheidsscore en matchbewijs interpreteren
Een betrouwbaarheidsscore van 0.9 staat op een schaal van 0 tot 1. Bij observed_frequency is dat de dominante telling gedeeld door het totaal van de geselecteerde rij in de dataset; het is geen end-to-end gemeten nauwkeurigheid van het product. Een model_reported-score wordt door AI opgegeven en is niet gekalibreerd op de frequenties in de dataset.
Bepaal de drempels van uw applicatie op basis van uw eigen evaluatiegegevens en confidence_kind. Zet scores uit de dataset en van AI niet rechtstreeks in één rangorde, alsof ze hetzelfde meten. Bij AI zijn match.name, match.scope en match.country null omdat er geen rij in de dataset is geselecteerd; match.method is model_inference.
Bij volledige namen kan een resultaat uit de dataset afkomstig zijn van een deel van de naam in plaats van de hele tekenreeks. data.input behoudt de verstuurde waarde; data.name beschrijft de teruggegeven naam en data.match de kandidaat en het zoekbereik.
Bepalen wat uw applicatie moet doen
Verwerk eerst de fouten van het verzoek en van afzonderlijke items en controleer daarna result_status. Lees bij een losse voorspelling data; pas bij een batch dezelfde beslissing toe op data van elk geslaagd item. Bewaar onbekende resultaten in uw applicatie in plaats van het label male of female af te dwingen.
| Resultaat | Wat het betekent | Aanbevolen verwerking |
|---|---|---|
| identified; gender: male of female | De voorspelling heeft een geslacht teruggegeven, op basis van de dataset of van AI. | Pas een regel toe die voor precies deze confidence_kind is geëvalueerd; bewaar source en het matchbewijs. |
| unknown; reason: not_found | Geen opgeslagen item in de dataset komt overeen met de geïnterpreteerde kandidaten. | Laat gender op null staan. Een bewust nieuw verzoek met andere AI-opties is een nieuwe betaalde bewerking. |
| unknown; reason: no_name_candidate | De interpretatie voor de dataset heeft geen bruikbare kandidaat voor een naam opgeleverd. | Bewaar null; controleer het invoertype en de waarde voordat u een extra voorspelling kiest. |
| unknown; reason: ambiguous | De geselecteerde rij in de dataset heeft evenveel mannelijke als vrouwelijke waarnemingen; sample_count kan toch aanwezig zijn. | Bepaal niet zelf welk geslacht geldt en zet een betrouwbaarheidsscore null niet om naar nul. |
| unknown; reason: insufficient_evidence | AI heeft het verzoek voltooid zonder voldoende bewijs om een geslacht terug te geven. | Behandel dit als een voltooid onbekend resultaat, niet als een fout van de provider en niet als kandidaat voor automatische nieuwe pogingen. |
| Problem Details of error van een item | De uitvoering is mislukt, bijvoorbeeld door ai_upstream_error of prediction_timeout. | Sla de foutcode en de verzoek-ID op, controleer de afschrijving en volg de richtlijnen voor nieuwe pogingen. |
Drempels kiezen op basis van uw eigen evaluatie
Er bestaat geen universele drempel voor de betrouwbaarheidsscore die een voorspelling juist maakt. Evalueer observed_frequency en model_reported afzonderlijk, met representatieve en onafhankelijk gelabelde voorbeelden uit uw eigen toepassing. Een frequentie in de dataset en een waarde die AI opgeeft, zijn verschillende signalen, ook als beide 0.9 zijn. Meet hoe vaak uw regel een antwoord oplevert en hoe vaak die antwoorden juist zijn; bewaar voor al het andere een onbekend resultaat of voorzie een handmatige controle.
Is result_status bijvoorbeeld identified maar confidence_kind model_reported, pas dan de regel toe die u voor AI hebt geëvalueerd en niet de drempel voor de dataset. Als forceToGenderize is gebruikt, is name: null samen met een geslacht anders dan null geldig: een alias kan worden geïnterpreteerd zonder dat er een echte voornaam wordt gevonden. Controleer gender en result_status, niet alleen name, om te bepalen of de voorspelling een antwoord heeft opgeleverd. Het resultaat blijft een schatting en geen bevestiging van iemands identiteit.