GenderAPI.io V2: JSON-svar och konfidens

Förstå JSON-svaret

Enskilda prediktioner i GenderAPI.io V2 returnerar ett data-objekt för resultatet och ett meta-objekt med uppgifter om förfrågan, åtkomst och debitering. Läs data.gender och data.confidence tillsammans med data.confidence_kind och data.source. Exemplet från datamängden nedan är ett verkligt svar som hämtades den 1 oktober 2026 med en API-nyckel; endast kontosaldot har ersatts. Det återger inte uppmätt noggrannhet för produkten, och en liveförfrågan kan ge ett annat resultat. Förfrågningar med API-nyckel rapporterar access.mode: api_key och null i kvotfälten som bara gäller provperioden; förfrågningar via IP-provperioden rapporterar ip_trial med provperiodens gräns och tidpunkten för återställning.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Erik",
      "country": "SE"
    },
    "name": "erik",
    "gender": "male",
    "country": "SE",
    "confidence": 1,
    "confidence_kind": "observed_frequency",
    "sample_count": 412,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "erik",
      "method": "normalized",
      "scope": "country",
      "country": "SE"
    }
  },
  "meta": {
    "request_id": "bcc2b4f6-2d7a-44c7-82dd-03722827e390",
    "duration_ms": 12,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

• Fullständiga svarsscheman och batchexempel

Fält i prediktionssvaret

Returnerade indatafält

Fält för matchning i datamängden

Metadata om åtkomst, debitering och förfrågan

Ett lyckat okänt resultat

HTTP 200 betyder att åtgärden slutfördes, men garanterar inget kön. Behåll JSON null i stället för att omvandla det till male, female, en tom sträng eller konfidensen noll. Kontrollera data.result_status och data.reason separat från HTTP-fel.

Det här verkliga exemplet som bara använder datamängden, hämtat den 1 oktober 2026, returnerar source: none och reason: not_found och kostar ändå 1 kredit. En rad i datamängden med lika antal kan returnera reason: ambiguous, varvid sample_count behålls. Ett okänt AI-resultat använder source: ai och 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
    }
  }
}

Tolka konfidens och matchningsunderlag

En konfidens på 0.9 ligger på en skala från 0 till 1. För observed_frequency betyder den det dominerande antalet delat med totalen för den valda raden i datamängden; det är inte en uppmätt noggrannhet för produkten från början till slut. Ett värde med model_reported kommer från AI och är inte kalibrerat mot frekvenserna i datamängden.

Välj eventuella tröskelvärden för din applikation utifrån egna utvärderingsdata och confidence_kind. Rangordna inte värden från datamängden och från AI direkt mot varandra, som om de mätte samma sak. För AI är match.name, match.scope och match.country null eftersom ingen rad i datamängden valdes; match.method är model_inference.

För fullständiga namn kan ett resultat från datamängden komma från en del av namnet i stället för hela strängen. data.input innehåller det skickade värdet, data.name beskriver det returnerade namnet och data.match beskriver kandidaten och sökningens omfattning.

Bestäm vad din applikation ska göra härnäst

Hantera först fel i förfrågan och i enskilda poster och kontrollera sedan result_status. För en enskild prediktion läser du data; för en batch tillämpar du samma beslut på data i varje lyckad post. Behåll okända resultat i din applikation i stället för att tvinga fram etiketten male eller female.

• Skilj driftfel från okända resultat
• Tillämpa besluten på en batch

Välj tröskelvärden utifrån din egen utvärdering

Det finns inget universellt tröskelvärde för konfidens som gör en prediktion korrekt. Utvärdera observed_frequency och model_reported separat med representativa, oberoende märkta exempel från ditt användningsfall. En frekvens i datamängden och ett värde som AI själv rapporterar är olika signaler, även när båda råkar vara 0.9. Mät hur ofta din regel ger ett svar och hur ofta dessa svar är korrekta; behåll ett okänt resultat eller en manuell granskning för allt annat.

Om result_status till exempel är identified men confidence_kind är model_reported tillämpar du din utvärderade regel för AI, inte tröskelvärdet för datamängden. Om forceToGenderize användes är name: null tillsammans med ett kön som inte är null giltigt: ett alias kan tolkas utan att ett riktigt förnamn extraheras. Kontrollera gender och result_status, inte bara name, för att avgöra om prediktionen gav ett svar. Resultatet är fortfarande en uppskattning, ingen bekräftelse av en persons identitet.

• Mått för utvärdering och konfidensens begränsningar
• Datamängdens profil och underlagets gränser
• Tolkning av smeknamn och name med null

Relaterade guider

• Batchsvar och fel per post
• Debiteringsstatus och återstående krediter
• Svarskompatibilitet och nya försök