De oorspronkelijke naam gebruiken zonder uit te gaan van één schrift of een vaste volgorde
De demonstratie gebruikt een voorbeeld in Devanagari en de landcontext IN. Het is een voorbeeld van invoer en geen definitie van alle namen die in India worden gebruikt. De API accepteert Unicode-tekenreeksen, dus u kunt de spelling uit het record in uw applicatie versturen zonder die eerst naar het Latijnse schrift om te zetten.
De zoekopdracht gebruikt genormaliseerde delen. Er is geen algemene omzetting tussen schriften en er is geen garantie dat een Latijnse spelling en een spelling in het oorspronkelijke schrift naar hetzelfde item leiden. Bewaar de oorspronkelijke invoer samen met de teruggegeven naam. Dat een schrift wordt geaccepteerd, betekent niet dat er voor elke taal of gemeenschap een onafhankelijk gemeten nauwkeurigheid is.
Ga er niet van uit dat het eerste of laatste deel altijd dezelfde rol heeft. V2 kiest de beschikbare kandidaat met de hoogste opgeslagen totale telling en garandeert geen vaste positie van de voornaam. Initialen, korte delen en ontbrekende opgeslagen items kunnen het resultaat uit de dataset onopgelost laten; de AI-fallback kan de volledige verstuurde waarde interpreteren.
| Voorbeeldinvoer | Wat het voorstelt | Wat u controleert |
|---|---|---|
प्रिया शर्मा | Volledige naam in Devanagari | Meerdere delen kunnen kandidaten worden. Controleer de gekozen naam en de match in plaats van aan te nemen dat het eerste deel voorrang krijgt. |
Priya Sharma | Voorbeeld in Latijns schrift | Dit is een aparte spelling; een identieke match tussen schriften is niet gegarandeerd. |
A. Kumar | Initiaal en een ander deel | Een initiaal van één letter wordt geen kandidaat in de dataset. Een match op het andere deel bevestigt niet de bedoelde voornaam. |
country: IN | Voorbeeldcontext: India | Gebruik dit als uw record relevante landcontext heeft, niet alleen omdat de naam in deze handleiding voorkomt. |
De landcontext IN bewust kiezen
De live demo verstuurt country: IN (India). 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.
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.
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
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. |
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 |
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.
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.
Veelgestelde vragen
Accepteert de demo voor Indiase namen alleen Hindi-namen?
De demo gebruikt een voorbeeld in Devanagari, maar de API accepteert namen als Unicode-tekenreeksen. Dat betekent niet dat de dataset volledige dekking heeft of dat er voor elke taal in India een gemeten nauwkeurigheid is.
Geeft de Latijnse spelling hetzelfde resultaat als het oorspronkelijke schrift?
Dat is niet gegarandeerd. De huidige zoekopdracht kent geen algemene gelijkstelling van transliteraties. Bewaar elke verstuurde spelling samen met de teruggegeven gegevens voor source, match en confidence.
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.