# API V2:n JSON-vastaukset ja luottamusarvot

> Ymmärrä GenderAPI v2 -data- ja meta-kentät: sukupuoli, tuntemattomat syyt, luottamus, tietojoukon todisteet, tekoälypisteet, käyttötila ja laskutuksen metatiedot.

Canonical HTML: https://www.genderapi.io/fi/docs/v2/responses

Last reviewed: 2026-09-25

## Ymmärrä JSON-vaste

Onnistuneet yksittäiset vastaukset sisältävät data ja meta. Alla oleva tietojoukon vastaus on havainnollistava esimerkki, ei tuotteen tarkkuuden mittaus tai lupaus samasta reaaliaikaisesta tuloksesta. Se näyttää IP-kokeilukäytön. Pyynnöt, jotka on todennettu tiliavaimella, palautus access.mode: api_key; kentillä, jotka koskevat vain kokeilua, on arvo null.

| Kenttä | Merkitys |
| --- | --- |
| data.input | Syöttötyyppi, arvo ja maa. forceToGenderize sisältyy hintaan true. |
| data.name | Vastaava tai poimittu etunimi; null, kun sellaista ei ole saatavilla. |
| data.gender | male, female tai JSON null. Tämä on ennustus, ei todiste henkilön henkilöllisyydestä. |
| data.result_status / reason | Kun result_status on identified, reason on null. Kun tila on unknown, syy on not_found, no_name_candidate, ambiguous tai insufficient_evidence. |
| data.confidence | 0–1 tulos tai null. Nollasukupuolella on null-luottamus. |
| data.confidence_kind | observed_frequency: hallitseva sukupuoli jaettuna valitun tietojoukon kokonaismäärällä. model_reported: AI-pistemäärä, ei kalibroitu todennäköisyys. Arvo on null, kun se ei ole saatavilla. |
| data.sample_count | Tietojoukon otoskoko tai null. Tekoäly ei keksi näytteiden laskentaa. |
| data.source | dataset, ai tai none. |
| data.country / country_source | Tietoaineistoon tai ai_association-arvoon perustuva maayhteys, tai null. Ei vahvista kansalaisuutta, asuinpaikkaa tai etnistä taustaa. |
| data.match | Tietoaineistosta löytynyt nimi, menetelmä (normalized, token, substring tai model_inference), laajuus (country tai global) ja vastaava maa. Puuttuvat tiedot ovat null. |
| meta.request_id / duration_ms | Toiminnon tunniste ja käsittelyn kesto millisekunteina. |
| meta.access | Miten käyttöoikeus myönnettiin ja tarvittaessa syy IP-kokeiluun siirtymiselle. |
| meta.usage | Nettoveloitus, valmistumisajan saldo, laskutuksen tila ja kokeilun nollaustiedot. |

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [Täydelliset vastausskeemat ja eräkyselyesimerkit](https://api.genderapi.io/api/v2/openapi.json)

## Onnistunut tuntematon tulos

HTTP 200 tarkoittaa, että toiminto on valmis; se ei takaa sukupuolta. Säilytä JSON null sen sijaan, että muuttaisit sen muotoon male, female, tyhjä merkkijono tai nolla luottamus. Tarkista data.result_status ja data.reason erikseen HTTP-virheistä.

Tämä vain tietojoukkoesimerkki palauttaa source: none ja reason: not_found ja maksaa silti yhden pisteen. Jos kahden sukupuolen tietojoukon määrät ovat samat, tulos voi sisältää reason: ambiguous säilyttäen kuitenkin sample_count. Tuntematon tekoälytulos käyttää source: ai ja reason: insufficient_evidence.

```json
{
  "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": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 8,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

## Tulkitse luottamusta ja vastaavia todisteita

Luottamusarvo 0,9 on asteikolla 0–1. observed_frequency:lle se tarkoittaa hallitsevaa määrää jaettuna valitun tietojoukon kokonaismäärällä; sitä ei mitata päästä päähän tuotteen tarkkuutta. Tekoäly tarjoaa model_reported-pisteen, eikä sitä ole kalibroitu tietojoukon taajuuksia vastaan.

Valitse mikä tahansa sovelluksen kynnysarvo käyttämällä omia arviointitietojasi ja confidence_kind:ta. Älä luokittele tietojoukon ja tekoälyn pisteitä suoraan ikään kuin ne mittasivat saman asian. AI match.name, match.scope ja match.country ovat null, koska tietojoukkoriviä ei valittu; match.method on model_inference.

Täydellisten nimien osalta tietojoukon tulos voi tulla komponentista koko merkkijonon sijaan. data.input säilyttää lähetetyn arvon; data.name kuvaa palautetun nimen, ja data.match kuvaa ehdokas- ja hakualueen.

## Aiheeseen liittyviä oppaita

- [Erävastaus ja tuotekohtaiset virheet](https://www.genderapi.io/fi/docs/v2/batch#batch-response)
- [Laskutuksen tila ja jäljellä olevat saldot](https://www.genderapi.io/fi/docs/v2/credits-and-usage)
- [Vastausten yhteensopivuus ja uudelleenyritykset](https://www.genderapi.io/fi/docs/v2/errors-and-retries#retries)