GenderAPI.io V2 -ohjeet
Usein kysytyt kysymykset
Vastauksia V2-pyynnöistä, luottamusarvosta, tuntemattomista tuloksista, krediiteistä, tietosuojasta ja tilistäsi. Jos ylläpidät aiemman version integraatiota, käytä V1-dokumentaatiota.
Tulokset ja luottamusarvo
Ymmärrä ennusteet ja niiden rajoitukset
Maakonteksti, luottamusarvot ja tuntemattomat tulokset API V2:ssa.
Kertooko GenderAPI-tulos henkilön sukupuolen?
Ei. GenderAPI päättelee sukupuolen nimeen liittyvistä signaaleista tai, kun asetus on käytössä, lempinimen signaaleista. Ennuste ei ole varmennettu tieto henkilöstä. Säilytä epävarmuus, kunnioita henkilön itse ilmoittamaa sukupuoli-identiteettiä äläkä tee merkittäviä seurauksia aiheuttavia päätöksiä pelkän ennusteen perusteella.
Miten maakonteksti vaikuttaa tulokseen?
Valinnainen ISO-maakoodi isoilla kirjaimilla antaa pyynnölle alueellisen kontekstin. Lähetä se vain, kun maa on tiedossa ja merkityksellinen. Samaa nimeä voidaan käyttää eri alueilla eri tavoin; palautettu maa kuvaa yhteyttä nimeen eikä todista kansalaisuutta tai asuinpaikkaa.
Mitä luottamusarvo tarkoittaa V2:ssa?
confidence on arvo väliltä 0–1 tai null, kun arvoa ei ole saatavilla. Tulkitse se yhdessä confidence_kind-kentän kanssa: observed_frequency on tietoaineiston yleisimmän luokan määrä jaettuna kokonaismäärällä; model_reported on tekoälyn ilmoittama arvo. Nämä arvot eivät ole henkilöä koskevia kalibroituja todennäköisyyksiä eivätkä mitattua tuotteen tarkkuutta. Määritä manuaalisen tarkistuksen raja-arvot edustavan datan perusteella.
Mitä gender: null tarkoittaa, ja veloitetaanko tällainen tulos?
Onnistunut V2-tulos, jossa on gender: null, tarkoittaa, että käytettävissä olevat signaalit eivät riittäneet sukupuolen määrittämiseen. Kyse on JSON-muodon natiivista null-arvosta, ei merkkijonosta "null". Onnistunut tuntematon tulos veloitetaan valitun tilan hinnalla. Käsittele se tuntemattomana; palveluntarjoajan tai pyynnön virhe on erillinen virhetilanne.
Voinko lähettää nimiä eri kirjoitusjärjestelmillä?
Kyllä. Lähetä nimet Unicode-muodossa alkuperäisine merkkeineen ja merkitystä kantavine diakriitteineen ja säilytä suomalaiset kirjaimet, kuten ä, ö ja å. Kattavuus ja luottamusarvo riippuvat nimestä, alueesta ja käytettävissä olevista signaaleista. Testaa siksi edustava otos niistä kirjoitusjärjestelmistä ja maista, joita sovelluksesi käsittelee.
API ja tekoäly
Valitse pyyntötyyppi ja tekoälyasetukset
V2:n pyyntötyypit, eräpyynnöt, tekoälyn käyttö ja rajoitukset.
Voinko analysoida nimiä, sähköpostiosoitteita ja käyttäjänimiä samassa eräpyynnössä?
Kyllä. POST /api/v2/gender/batch hyväksyy enintään 50 kohdetta API-avaimella tai enintään 10 IP-kokeilussa. Jokaisella kohteella on omat type- ja value-kentät, valinnainen country ja omat tekoälyasetukset. Oletuksena tekoäly on eräpyynnön kohteissa pois käytöstä. Tarkista jokainen tulos: eräpyyntö voi palauttaa HTTP 200 -vastauksen, vaikka osa kohteista olisi epäonnistunut. Krediitit veloitetaan jokaisesta onnistuneesti käsitellystä kohteesta, myös tuntemattomista tuloksista.
Miten sähköpostiosoitteella tehty pyyntö toimii?
Käytä type: email -arvoa ja kelvollista osoitetta. API etsii käyttökelpoista nimisignaalia @-merkkiä edeltävästä osasta; verkkotunnus ei kerro henkilön identiteetistä tai maasta mitään. Jaetut postilaatikot ja osoitteet, joissa ei ole nimisignaalia, voivat palauttaa tuntemattoman tuloksen. Yksittäinen pyyntö käyttää oletuksena tekoälyä, jos tietoaineisto ei tuota tulosta.
Miten käyttäjänimellä tehty pyyntö toimii?
Käytä type: username -arvoa. Tavallinen pyyntö etsii tunnistettavaa etunimeä käyttäjänimestä tai näyttönimestä. Abstraktit nimimerkit voivat palauttaa tuntemattoman tuloksen. Ota forceToGenderize käyttöön, jos haluat, että tuloksettoman tietoaineistohaun jälkeen käytetään tekoälyä ja lempinimianalyysia; sukupuoli voidaan silloin määrittää myös ilman oikean etunimen poimintaa.
Milloin V2 käyttää tekoälyä?
Yksittäiset pyynnöt käyttävät oletuksena asetusta options.ai_mode: fallback: ensin haetaan tietoaineistosta, ja jos sukupuolta ei voida määrittää, käytetään tekoälyä, yhteensä 1 krediitillä. off käyttää vain tietoaineistoa 1 krediitillä; always ohittaa tietoaineiston ja käyttää tekoälyä 2 krediitillä. Eräpyynnön kohteet käyttävät oletuksena off-tilaa, ja tekoälyn voi ottaa käyttöön kohdekohtaisesti. Mikään tila ei takaa muuta tulosta kuin null.
Mitä forceToGenderize tekee?
Tämä valinnainen lippu toimii nimien, sähköpostiosoitteiden ja käyttäjänimien kanssa, myös eräpyynnön yksittäisissä kohteissa. Tietoaineistosta määritetty tulos maksaa 1 krediitin. Muussa tapauksessa käytetään tekoälyä ja lempinimianalyysia, yhteensä 2 krediitillä, vaikka onnistunut tulos jäisi tuntemattomaksi. Oikeaa etunimeä ei tarvita. Jätä ai_mode pois tai käytä arvoa fallback; yhdistelmä off- tai always-arvon kanssa palauttaa virheen 422.
Miten krediitit veloitetaan V2:ssa?
Toiminnosta todellisuudessa veloitetut krediitit näet kentästä meta.usage.charged_credits, ja billing_status kertoo, onko veloitus vahvistettu. Tavalliset ennusteet tietoaineistosta ja fallback-tilassa maksavat 1 krediitin jokaista onnistuneesti käsiteltyä kohdetta kohden; always ja tekoälyä käyttävä lempinimianalyysi maksavat 2 krediittiä. Suoritettu puhelinnumeron tarkistus maksaa 1 krediitin myös virheellisellä tuloksella. Positiivinen alkusaldo riittää, joten lopullinen veloitus voi painaa saldon negatiiviseksi. Epäonnistuneiden ennusteiden krediitit palautetaan; vahvistamattoman veloituksen selvittää tuki.
Onko V2:ssa pyyntörajoja?
Kyllä. Nykyiset oletusarvot ovat 120 pyyntöä minuutissa tiliä kohden, 600 pyyntöä minuutissa IP-osoitetta kohden ja 2 samanaikaista toimintoa tiliä kohden. Lisäksi palvelun yhteinen kapasiteetti rajoittaa käyttöä. POST-pyyntöjen enimmäiskoko on 64 KiB; eräpyynnöissä voi olla 50 kohdetta avaimella tai 10 IP-kokeilussa. Käsittele HTTP 429 ja Retry-After äläkä oleta, että näiden rajojen sisällä olevat pyynnöt hyväksytään aina.
Voinko toistaa pyynnön, joka epäonnistui tai aikakatkaistiin?
Jokainen ennustepyyntö on uusi toiminto, ja se veloitetaan tavalliseen tapaan. Aikakatkaisu tai kadonnut vastaus ei todista, että krediittejä ei veloitettu. Tarkista billing_status ennen uutta yritystä; jos veloitusta ei ole vahvistettu, ota yhteyttä tukeen ja kerro request_id. Jos eräpyyntö epäonnistui osittain, lähetä veloituksen vahvistamisen jälkeen uudelleen vain epäonnistuneet kohteet. Kun saat vastauksen 429, noudata Retry-After-otsaketta.
Mistä löydän V2:n koodiesimerkit ja työkalut?
V2-ohjeissa on esimerkit kielillä cURL, JavaScript, Python, PHP, Java, C# ja Go. Swagger ja Postman käyttävät samaa V2-määrittelyä. Valitse syötteen tyyppi ja säilytä API-avain palvelinpuolen asetuksissa.
Voinko jatkaa V1:n käyttöä?
Kyllä. Nykyiset V1-integraatiot säilyttävät endpointinsa ja vastausmuotonsa. V1 ja V2 käyttävät samaa API-avainta ja samaa saldoa, mutta pyyntöjen kentät, vastaukset ja virheet eroavat toisistaan. Käytä erillistä V1-dokumentaatiota nykyisen asiakasohjelman ylläpitoon ja siirtymäohjetta, kun siirryt V2:een.
Tietosuoja ja tiedostot
Näin tietoja käsitellään
Mistä löydät ajantasaiset tiedot tietojen käsittelystä, säilyttämisestä ja poistamisesta.
Tallennetaanko onnistuneet GenderAPI-pyynnöt?
Tietosuojakäytäntö kertoo, mitä pyyntötietoja, käyttötietoja ja tietoturvalokeja voidaan säilyttää, mihin tarkoituksiin niitä käsitellään ja miten ne poistetaan. Tarkista nämä tiedot integraatiosi kannalta äläkä lähetä tarpeettomia henkilötietoja.
Tallennetaanko pyyntöjen sähköpostiosoitteet?
Tietosuojakäytäntö kuvaa, miten pyyntöjen sähköpostiosoitteita ja niihin liittyviä teknisiä tietoja käsitellään. Sähköpostiosoite voi olla henkilötieto: lähetä vain se, mitä pyyntö edellyttää, äläkä tallenna kokonaisia osoitteita omiin vianmäärityslokeihisi.
Kuinka kauan ladattuja Excel- tai CSV-tiedostoja säilytetään?
Ladattujen tiedostojen säilyttäminen, poistaminen ja varmuuskopiointi määritellään tietosuojakäytännössä. Vie tarvitsemasi tulokset ja poista tiedosto työtilan toiminnoilla, kun et enää tarvitse sitä. Jos organisaatiollasi on säilytystä koskevia vaatimuksia, ota yhteyttä tukeen.
Voivatko palveluntarjoajat käsitellä pyyntöjen tietoja tai ladattuja tiedostoja?
Tietosuojakäytäntö ja alikäsittelijöitä koskevat tiedot kuvaavat, miten palveluntarjoajat käsittelevät tietoja ja mitä suojatoimia sovelletaan. Kun arvioit, missä tietojasi käsitellään, tutustu näihin asiakirjoihin ja tiliäsi koskeviin sopimuksiin.
Tili ja tuki
Yhdistä avaimet ja hallitse tiliäsi
Maksuton käyttö, todennus, saldon tarkistus ja tuki.
Voinko kokeilla GenderAPI:a maksutta?
Kyllä. Rekisteröity maksuton tili saa 200 krediittiä päivässä. Tästä riippumatta V2:n IP-kokeilu antaa ilman avainta 10 krediittiä julkista IP-osoitetta kohden 24 tunnin välein; saldo on yhteinen V1:n ja saman IP-osoitteen muiden käyttäjien kanssa. Molemmissa tapauksissa sovelletaan tavallisia hintoja; krediittien määrä ei aina vastaa HTTP-pyyntöjen määrää.
Miten todennan pyynnöt ja suojaan API-avaimeni?
Käytä luotetussa palvelinpuolen koodissa otsaketta Authorization: Bearer YOUR_API_KEY; POST-pyynnöt edellyttävät lisäksi otsaketta Content-Type: application/json. Älä lisää oikeaa avainta selaimessa ajettavaan koodiin, julkisiin repositorioihin tai lokeihin. Puuttuva, virheellisesti muotoiltu tai tunnistamaton avain voi johtaa IP-kokeiluun; varmista siksi, että meta.access.mode-kentän arvo on api_key. Tunnistetut avaimet, jotka on poistettu käytöstä, jotka ovat vanhentuneet tai joita on rajoitettu, eivät siirry kokeiluun.
Miten tarkistan jäljellä olevat krediitit?
Kutsu GET /api/v2/usage -pyyntöä avaimellasi Bearer-otsakkeessa. Saldon tarkistus on maksuton ja palauttaa kentän data.remaining_credits. Ilman avainta luetaan IP-kokeilun yhteinen saldo. V1 ja V2 käyttävät samaa tilin saldoa; ennustevastauksen remaining_credits-arvo näyttää saldon toiminnon valmistumishetkellä.
Missä tilausta voi hallita tai sen voi peruuttaa?
Kirjaudu GenderAPI-sovellukseen ja hallitse API-avaimeesi liitettyä tilausta. Ajantasaisista tiliasetuksista näet pakettisi ja peruutusvaihtoehdot.
Missä laskutustietoja voi muokata?
Laskutus- ja maksuasetuksia hallitaan API-avain- tai tilauskohtaisesti, kun olet kirjautunut GenderAPI-sovellukseen.
Miten ilmoitan virheellisestä tuloksesta tai saan apua integraatioon?
Lähetä tuelle API-versio, endpoint, request_id ja lyhyt toistettava esimerkki. Mainitse mahdollinen virhekoodi, mutta poista API-avain ja arkaluonteiset henkilötiedot.
Tekninen tietopankki
Ohjeet käyttöönottoon ja vastuulliseen käyttöön
Vastauksia V2:n tuloksista, tietosuojasta ja käytöstä sekä linkit ohjeisiin ja jokaisen vastauksen Markdown-versioon.
Tulokset, luottamusarvo ja vastuullinen käyttö
Ratkaisematon V2-ennuste palauttaa gender-kenttään JSON-muodon natiivin null-arvon, ei merkkijonoa "null". Nimi voi olla monitulkintainen tai käytettävissä olevat signaalit eivät riitä; tarkista result_status ja reason, jos ne ovat saatavilla. Säilytä tuntematon tulos äläkä pakota sitä mihinkään luokkaan. Onnistunut ennuste ilman tulosta veloitetaan valitun tilan hinnalla. Pyynnön tai palveluntarjoajan virheet ovat erillisiä virhetilanteita; niiden veloitustiedot näet kentästä meta.usage.
Lue koko vastaus →Miten GenderAPI:n tarkkuutta arvioidaan?Mielekäs tarkkuuden arviointi kertoo tutkitun populaation, päivämäärän, otantamenetelmän, tuntemattomien tulosten osuuden sekä tulokset alueittain ja kirjoitusjärjestelmittäin. Ajantasainen menetelmäsivu kuvaa arviointiprotokollan, ei prosentteina mitattua tarkkuutta. V2:n confidence- ja confidence_kind-kentät kertovat, mihin signaaleihin tulos perustuu; ne eivät korvaa arviointia edustavalla datalla.
Lue koko vastaus →Tietolähteet, tietosuoja ja vaatimustenmukaisuus
Tietojen alkuperää käsittelevä sivu kuvaa kehyksen lähdeluokkien, valintakriteerien, lisenssien sekä alueisiin ja kirjoitusjärjestelmiin liittyvien rajoitusten dokumentointiin. Tarkistettua lähdeluetteloa ei ole toistaiseksi julkaistu. Lue sivu ja ota yhteyttä tukeen, jos integraatiollasi on lähteitä koskevia vaatimuksia; älä oleta lähteitä, tietoaineistojen kokoja tai kattavuuslukuja, joita ei ole dokumentoitu.
Lue koko vastaus →Kuinka usein nimitietoja päivitetään?Ajantasainen tietojen alkuperää käsittelevä sivu ei kerro yhteistä päivitysaikataulua kaikille nimitietueille tai käsittelysäännöille. Jos tietojen ajantasaisuus on käyttötarkoituksellesi tärkeää, kysy tuelta tietystä tietoaineistosta tai prosessista ja testaa edustavia tuloksia. Sivun tarkistuspäivä ei tarkoita, että kaikki taustalla olevat tietueet olisi päivitetty samana päivänä.
Lue koko vastaus →Mistä löydän tiedot GDPR:stä ja tietojenkäsittelysopimuksesta?Tietosuojakäytäntö, GDPR-tiedot, tietojenkäsittelysopimus ja alikäsittelijöiden luettelo kuvaavat julkaistut käsittelyehdot ja suojatoimet. Tutustu ajantasaisiin asiakirjoihin ja tiliäsi koskeviin sopimuksiin. Jos sinulla on organisaatiotasi koskevia kysymyksiä esimerkiksi käsittelyrooleista, tietojen siirroista tai rekisteröityjen pyynnöistä, ota yhteyttä GenderAPI:in; usein kysyttyjen kysymysten yleinen vastaus ei korvaa voimassa olevaa sopimusta.
Lue koko vastaus →API:n käyttö, virheet ja krediittien veloitus
Käytä luotetussa palvelinpuolen koodissa otsaketta Authorization: Bearer YOUR_API_KEY. V2:n POST-pyynnöt edellyttävät lisäksi otsaketta Content-Type: application/json. GET /api/v2/gender hyväksyy avaimen myös kyselyparametrina, mutta otsakkeen avulla tunnistetiedot eivät näy selaimen URL-osoitteissa. Puuttuva, virheellisesti muotoiltu tai tunnistamaton avain voi johtaa yhteiseen IP-kokeiluun; varmista tiliin perustuvassa integraatiossa, että meta.access.mode-kentän arvo on api_key. Tunnistetut avaimet, jotka on poistettu käytöstä, jotka ovat vanhentuneet tai joita on rajoitettu, eivät siirry kokeiluun.
Lue koko vastaus →Miten pyyntörajat ja uudelleenyritykset käsitellään?V2 rajoittaa pyyntöjen määrää ja samanaikaisia pyyntöjä; käsittele HTTP 429 ja Retry-After. Jokainen toistettu ennuste on uusi toiminto, ja se veloitetaan tavalliseen tapaan. Älä toista pyyntöjä automaattisesti aikakatkaisun, kadonneen vastauksen tai vahvistamattoman veloituksen jälkeen. Tarkista ensin code, action ja meta.usage.billing_status; jos arvo on billing_reconciliation_required, ota yhteyttä tukeen ja kerro request_id. Käytä rajattua backoff-viivettä vain, kun veloitus on vahvistettu ja dokumentoitu action sallii uuden yrityksen.
Lue koko vastaus →Miten V2:n virheitä tulkitaan?API V2:n virheet käyttävät HTTP-virhetilakoodeja ja RFC 9457:n mukaisia Problem Details -vastauksia, joissa on pysyvät code- ja action-kentät. Rakenna virheenkäsittely näiden kenttien varaan detail-tekstin vertailun sijaan ja säilytä request_id tukea varten. Onnistunut tuntematon tulos ei ole virhe. Eräpyyntöjen vastauksissa voi olla yksittäisten kohteiden virheitä myös HTTP 200 -tilalla. Välityspalvelin voi palauttaa virheen muussa kuin JSON-muodossa, eikä kadonnut tai lukukelvoton vastaus todista, että krediittejä ei veloitettu.
Lue koko vastaus →Miten tarkistan jäljellä olevat krediitit?Kutsu luotetusta palvelinpuolen koodista GET /api/v2/usage -pyyntöä niin, että API-avain on Bearer-otsakkeessa. Pyyntö on maksuton ja palauttaa kentän data.remaining_credits; ilman avainta luetaan yhteisen IP-kokeilun saldo. V1 ja V2 käyttävät samaa tilin saldoa. Ennustevastauksen meta.usage-kenttä näyttää toiminnon hinnan ja saldon sen valmistumishetkellä, ja arvo voi muuttua samanaikaisten pyyntöjen vuoksi. Pidä tunnistetiedot poissa lokeista äläkä pidä saldon tarkistusta todisteena siitä, että tiettyä pyyntöä, jonka vastaus katosi, ei veloitettu.
Lue koko vastaus →Miten siirryn V1:stä V2:een ilman katkoja?Rakenna uudet integraatiot V2:n varaan ja anna nykyisten V1-asiakasohjelmien käyttää dokumentoituja endpointejaan, kunnes haluat siirtyä V2:een. Molemmat versiot käyttävät samoja API-avaimia ja krediittejä, mutta pyyntöjen kentät, vastausten rakenne ja virhemuoto eroavat. Noudata siirtymäohjetta, testaa onnistuneet ja tuntemattomat tulokset sekä virheet ja päivitä vastausten käsittely ennen endpointin vaihtamista. V1-dokumentaatio on edelleen saatavilla nykyisiä integraatioita varten.
Lue koko vastaus →Miten tunnistan virheet ja seuraan palvelun saatavuutta?Kun pyynnöt epäonnistuvat, erottele palautetun virhekoodin avulla käyttökatkot, virheelliset syötteet, tilin käyttöoikeusongelmat, loppuneet krediitit ja pyyntörajat. Seuraa omassa integraatiossasi onnistuneiden pyyntöjen osuutta ja vasteaikoja. Jos virhe on selittämätön tai veloitus epäselvä, ota yhteyttä tukeen ja kerro request_id. Perusta saatavuutta koskevat väitteet mittauksiin; tämä vastaus ei lupaa mitään taattua saatavuusprosenttia.
Lue koko vastaus →Tarvitsetko lisää apua?
Lähetä meille toistettava esimerkki
Liitä viestiin endpoint, pyynnön parametrit ja palautettu virhe. Älä lähetä tuotannon API-avainta tai arkaluonteisia henkilötietoja.