API V2:n JSON-vastaukset ja luottamusarvot

Tulkitse JSON-vastaus

Onnistuneet yksittäiset vastaukset sisältävät kentät data ja meta. Seuraava tietoaineistoesimerkki on todellinen vastaus, joka haettiin 1. lokakuuta 2026 API-avaimella; vain tilin saldo on korvattu. Se ei kuvaa tuotteen mitattua tarkkuutta, ja reaaliaikainen pyyntö voi palauttaa eri tuloksen. API-avaimella tehdyt pyynnöt palauttavat arvon access.mode: api_key, ja vain kokeilua koskevat kiintiökentät ovat null; IP-kokeilun pyynnöt palauttavat arvon ip_trial sekä kokeilun rajan ja nollausajan.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Juha",
      "country": "FI"
    },
    "name": "juha",
    "gender": "male",
    "country": "FI",
    "confidence": 0.9988558352402745,
    "confidence_kind": "observed_frequency",
    "sample_count": 874,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "juha",
      "method": "normalized",
      "scope": "country",
      "country": "FI"
    }
  },
  "meta": {
    "request_id": "010b6440-a403-4d2e-bc0f-f44e6c03891c",
    "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
    }
  }
}

• Täydelliset vastausskeemat ja eräpyyntöesimerkit

Ennustevastauksen kentät

Palautetut syötekentät

Tietoaineisto-osuman kentät

Käyttöoikeus, veloitus ja pyynnön metatiedot

Onnistunut tuntematon tulos

HTTP 200 tarkoittaa, että toiminto valmistui; se ei takaa sukupuolta. Säilytä JSON null -arvo äläkä muunna sitä arvoksi male tai female, tyhjäksi merkkijonoksi tai nollaluottamukseksi. Tarkista data.result_status ja data.reason erillään HTTP-virheistä.

Tämä todellinen, vain tietoaineistoa käyttävä esimerkki, joka haettiin 1. lokakuuta 2026, palauttaa arvot source: none ja reason: not_found ja maksaa silti 1 krediitin. Jos valitulla tietoaineiston rivillä on tasatilanne, tulos voi olla reason: ambiguous, ja sample_count säilyy. Tuntematon tekoälytulos käyttää arvoja source: ai ja 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
    }
  }
}

Tulkitse luottamusarvo ja osuman perusteet

Luottamusarvo 0,9 ilmoitetaan asteikolla 0–1. observed_frequency-arvossa se tarkoittaa hallitsevaa määrää jaettuna valitun tietoaineiston kokonaismäärällä; se ei ole tuotteen mitattu kokonaistarkkuus. model_reported-pistemäärän antaa tekoäly, eikä sitä ole kalibroitu tietoaineiston esiintymistiheyksiin.

Valitse sovelluksesi kynnysarvot omien arviointiaineistojesi ja confidence_kind-kentän perusteella. Älä järjestä tietoaineiston ja tekoälyn pistemääriä suoraan keskenään ikään kuin ne mittaisivat samaa asiaa. Tekoälytuloksissa match.name, match.scope ja match.country ovat null, koska tietoaineiston riviä ei valittu; match.method on model_inference.

Koko nimen tietoaineistotulos voi perustua nimen osaan eikä koko merkkijonoon. data.input säilyttää lähetetyn arvon; data.name kuvaa palautetun nimen ja data.match ehdokkaan sekä hakualueen.

Päätä, mitä sovelluksesi tekee seuraavaksi

Käsittele ensin pyyntö- ja kohdekohtaiset virheet ja tarkista sitten result_status. Yksittäisessä ennusteessa lue data; eräpyynnössä tee sama päätös jokaisen onnistuneen kohteen data-kentän perusteella. Säilytä tuntemattomat tulokset sovelluksessasi äläkä pakota niille merkintää male tai female.

• Erota toimintavirheet tuntemattomista tuloksista
• Sovella näitä päätöksiä eräpyyntöön

Valitse kynnysarvot oman arviointisi perusteella

Mikään yleinen luottamusarvon raja ei tee ennusteesta oikeaa. Arvioi observed_frequency ja model_reported erikseen edustavilla, toisistaan riippumatta luokitelluilla esimerkeillä omasta käyttötapauksestasi. Tietoaineiston esiintymistiheys ja tekoälyn itse ilmoittama pistemäärä ovat eri signaaleja, vaikka molempien arvo sattuisi olemaan 0,9. Mittaa, kuinka usein käytäntösi antaa vastauksen ja kuinka usein nämä vastaukset ovat oikein; säilytä kaikelle muulle tuntematon tulos tai manuaalinen tarkistus.

Jos esimerkiksi result_status on identified mutta confidence_kind on model_reported, käytä tekoälylle arvioitua käytäntöä äläkä tietoaineiston kynnysarvoa. Jos forceToGenderize oli käytössä, sukupuoli yhdessä arvon name: null kanssa on kelvollinen tulos: aliaksesta voidaan päätellä sukupuoli, vaikka todellista etunimeä ei poimittaisi. Päätä gender- ja result_status-kenttien perusteella, eikä pelkän name-kentän perusteella, antoiko päätelmä vastauksen. Kyse on edelleen arviosta, ei henkilöllisyyden vahvistuksesta.

• Arviointimittarit ja luottamusarvon rajoitukset
• Tietoaineiston profiili ja perusteiden rajat
• Lempinimipäättely ja null-arvoinen name

Aiheeseen liittyvät oppaat

• Eräpyynnön vastaus ja kohdekohtaiset virheet
• Laskutuksen tila ja jäljellä olevat krediitit
• Vastausten yhteensopivuus ja uudelleenyritykset