Hvad fortæller en e-mailadresse?
Send en syntaktisk gyldig e-mailadresse med type: email. GenderAPI.io leder efter et navnesignal i delen før @ og returnerer derefter en struktureret forudsigelse. Postkassen bliver ikke verificeret eller knyttet til en ejer, og ejerens kønsidentitet bliver ikke fastslået.
Matchet med datasættet udleder kandidater fra adressens dele og kan kontrollere begrænsede delstrenge. Kaldenavnstilstanden matcher stadig hele dele, men tilføjer ikke disse delstrengskandidater. Hvis flere poster matcher, vælges kandidaten med det højeste lagrede samlede antal, og det er ikke nødvendigvis det tilsigtede fornavn. Kontrollér data.name og data.match, før du bruger et udtrukket navn i en kontaktliste.
| Eksempel på input | Fortolkning |
|---|---|
alice.smith@example.com | Den lokale del indeholder mulige navnedele. Et match er muligt, men inputtet alene afgør ikke, hvilken kandidat der vælges. |
alice+news@example.com | Opslaget i datasættet fjerner suffikset efter plustegnet for sine egne kandidater. AI bliver bedt om at ignorere det, men modtager den sendte værdi. |
support@example.com | En rolleadresse giver ikke et pålideligt signal om et personnavn. Tildel ikke hele den delte postkasse én persons køn. |
prenses@example.com | Den valgfrie indstilling forceToGenderize tillader et forsøg ud fra et kaldenavns betydning, når datasættet ikke giver et resultat. Denne tilstand kræver ikke et egentligt navn. |
not-an-email | Ugyldig syntaks returnerer en valideringsfejl i stedet for et gennemført ukendt resultat. |
Send en forespørgsel med en e-mailadresse fra din applikation
Eksemplet bruger din eksisterende API-nøgle i Bearer-headeren og angiver fallback eksplicit. Erstat eksempeladressen med et input, du har ret til at behandle. Angiv kun country, hvis du har en relevant kontekst. E-maildomænet viser ikke, hvor en person befinder sig. Udelad feltet, hvis du ikke har en landekontekst.
Kør eksemplet på din server, når du har angivet GENDERAPI_API_KEY. Med POST holdes e-mailadressen uden for forespørgslens URL. Live-resultatet kan afvige fra demoens eksempelsvar.
Vælg et programmeringssprog. Konfigurér din API-nøgle, og kør derefter eksemplet på din server.
Hver forespørgsel om en forudsigelse er en ny operation, der koster kreditter, også når den gentages. Eksemplerne prøver ikke automatisk igen. Kontrollér opkrævningsstatus, før du sender en ny forespørgsel.
Før du kører: adgang og fejlhåndtering
Kør eksemplerne på din server. Sæt GENDERAPI_API_KEY i procesmiljøet til din eksisterende API-nøgle. Bekræft, at meta.access.mode er api_key: En nøgle, der ikke genkendes, kan føre til IP-prøveadgangen.
JSON-svar med HTTP 4xx og 5xx bevarer fejlens body og returnerer en exitstatus, der ikke er nul. Kontrollér code, action og meta.usage.billing_status, før du prøver igen.
Guide til fejl og nye forsøg →cURL 7.76+ i en POSIX-shell. Kør i din terminal. Dokumentation for kørselsmiljøet
Node.js 22+, indbygget fetch. Gem som example.mjs, og kør node example.mjs. Dokumentation for kørselsmiljøet
Python 3.10+, standardbiblioteket. Gem som example.py, og kør python3 example.py. Dokumentation for kørselsmiljøet
PHP 8+ med cURL-udvidelsen. Gem som example.php, og kør php example.php. Dokumentation for kørselsmiljøet
Java 17+, standard-HTTP-klienten. Gem som GenderApiExample.java, og kør java GenderApiExample.java. Dokumentation for kørselsmiljøet
Konsolapplikation med .NET 8+. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Dokumentation for kørselsmiljøet
Go 1.22+, standardbiblioteket. Gem som main.go, og kør go run main.go. Dokumentation for kørselsmiljøet
Gem resultatet sammen med evidensen
En udledt sammenhæng er ikke det køn, en person selv har oplyst. Gem det oprindelige input, den returnerede evidens og det, personen selv har oplyst, hver for sig. Et ukendt resultat er et gyldigt resultat og bør ikke blive til en gættet kategori i din applikation.
| Felt | Sådan bruger du det |
|---|---|
data.gender / data.result_status | Brug kun male eller female, når status er identified. Bevar den native JSON-værdi null, når resultatet er ukendt. |
data.name / data.match | Kontrollér det returnerede navn og den valgte kandidat. Et match på en delstreng beviser ikke, at inputtet tilhører en person med det navn. |
data.confidence / data.confidence_kind | Konfidensen ligger på en skala fra 0 til 1 eller er null. observed_frequency bygger på lagrede frekvenser, mens model_reported er en værdi angivet af AI. Vurdér tærskelværdier separat for hver type. |
data.source / data.sample_count | Skeln mellem dataset, ai og none. AI-resultater har ingen lagret stikprøvestørrelse. En stikprøvestørrelse er ikke en målt nøjagtighed. |
meta.access.mode | Kontrollér i en integration med konto, at api_key returneres. Manglende eller ukendte nøgler kan i stedet bruge den delte IP-prøveadgang. |
meta.usage | Læs charged_credits og billing_status. Et gennemført ukendt resultat koster kreditter. Et mistet svar beviser ikke, at forespørgslen var gratis. |
Beslut, hvornår AI skal bruges
forceToGenderize er valgfrit for navne, e-mailadresser og brugernavne. Når det er slået til, skal du udelade ai_mode eller bruge fallback. off og always kan ikke kombineres med denne indstilling og returnerer 422. En positiv startsaldo er nok til at starte en forespørgsel, også selvom den endelige opkrævning gør saldoen negativ.
Kaldenavnstilstanden kan returnere et køn sammen med name: null. Den kan også give et ukendt resultat. Hverken den almindelige automatiske AI-fallback eller fortolkningen af kaldenavne garanterer et korrekt svar eller en værdi, der ikke er null.
| Indstilling i forespørgslen | Adfærd | Kreditter for en gennemført forespørgsel |
|---|---|---|
| options.ai_mode: off | Bruger kun datasættet. | 1, også for et ukendt resultat |
| options.ai_mode: fallback | Slår først op i datasættet og bruger derefter almindelig AI, hvis der ikke returneres et køn. Det er standarden for enkeltforespørgsler. | 1 i alt, inklusive automatisk AI-fallback |
| options.ai_mode: always | Bruger AI direkte. | 2 |
| forceToGenderize: true | Slår først op i datasættet og lader derefter AI fortolke et personligt kaldenavn eller alias, også uden et egentligt fornavn. | 1 for et resultat fra datasættet, 2 i alt, hvis AI bruges |
Behandl en liste med e-mailadresser i en batch
Brug POST /api/v2/gender/batch med et items-array af elementer med type: email. Adgang med en registreret API-nøgle understøtter op til 50 elementer, IP-prøveadgangen op til 10. Giv hvert element et unikt id, så du kan knytte resultaterne til den oprindelige række. Svaret følger desuden inputrækkefølgen og angiver index.
Som standard bruger elementer i en batch kun datasættet. Angiv options.ai_mode: fallback for hvert element, der skal have den almindelige automatiske AI-fallback. To gennemførte elementer med fallback koster 2 kreditter i alt, også når resultaterne er ukendte. Én HTTP-forespørgsel svarer ikke til én kredit pr. forudsigelse.
Kontrollér hvert element, også når batchen returnerer HTTP 200. Gem gennemførte og ukendte resultater, og kontrollér derefter fejl og bekræftet opkrævning, før du sender mislykkede elementer igen. Send ikke en gennemført batch igen i sin helhed efter en timeout uden først at have kontrolleret opkrævningen.
Vid, hvad du sender
Live-demoen sender kun den indtastede værdi til GenderAPI.io, når du selv sender den. Hvis AI bruges, videregives type, value og den sendte landekontekst til den tjeneste, der er konfigureret til forudsigelser. Hvis du kun vil have en forudsigelse fra datasættet, skal du i din integration angive options.ai_mode: off uden forceToGenderize.
Privatlivspolitikken, databehandleraftalen og listen over underdatabehandlere beskriver de offentliggjorte vilkår for behandlingen. Et resultat er en udledt sammenhæng, og det, en person selv oplyser, har forrang. Brug det ikke som grundlag for beslutninger, der har betydelige konsekvenser for en person.
Ofte stillede spørgsmål
Kan API'et udtrække et fornavn fra en e-mailadresse?
Det kan returnere en navnekandidat, når den lokale del indeholder et brugbart signal. Både match på hele dele og på delstrenge er mulige, så kontrollér data.match. Resultatet angiver ikke fornavnet på den person, der ejer postkassen.
Returnerer en info@- eller support@-adresse et køn?
Delte rolleadresser giver som regel ingen evidens for et personnavn. Et ukendt resultat er gyldigt. AI eller kaldenavnstilstanden må ikke betragtes som en bekræftelse for de personer, der bruger en delt postkasse.
Koster et ukendt resultat for en e-mailadresse kreditter?
Ja. En almindelig gennemført forespørgsel med en e-mailadresse koster 1 kredit, inklusive automatisk AI-fallback og ukendte resultater. Tvungen fortolkning af kaldenavne koster 1 kredit for et resultat fra datasættet eller 2 i alt, hvis AI bruges. Ved en fejl angives opkrævningen separat i meta.usage.
Fjernes e-maildomænet, før AI behandler adressen?
Det er ikke garanteret. Kandidaterne fra datasættet kommer fra den lokale del, mens AI modtager den sendte værdi med en instruktion om at ignorere domænet og suffikset efter plustegnet. Brug tilstanden, der kun bruger datasættet, hvis din arbejdsgang kræver det.