GenderAPI.io V2: JSON-svar og konfidens

Forstå JSON-svaret

Gennemførte enkeltsvar indeholder data og meta. Det følgende eksempel fra datasættet er et rigtigt svar, der blev hentet den 1. oktober 2026 med en API-nøgle; kun kontosaldoen er erstattet. Det viser ikke produktets målte nøjagtighed, og en live-forespørgsel kan give et andet resultat. Forespørgsler med API-nøgle returnerer access.mode: api_key og null i de kvotefelter, der kun gælder IP-prøveadgangen; forespørgsler via IP-prøveadgangen returnerer ip_trial med prøvegrænsen og tidspunktet for nulstilling.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Mads",
      "country": "DK"
    },
    "name": "mads",
    "gender": "male",
    "country": "DK",
    "confidence": 0.9920318725099602,
    "confidence_kind": "observed_frequency",
    "sample_count": 502,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "mads",
      "method": "normalized",
      "scope": "country",
      "country": "DK"
    }
  },
  "meta": {
    "request_id": "d76fd0ca-5258-4f19-8690-c7eb975aba9d",
    "duration_ms": 16,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

• Komplette svarskemaer og batcheksempler

Felter i svaret på en forudsigelse

Returnerede inputfelter

Felter for matchet med datasættet

Metadata om adgang, opkrævning og forespørgslen

Et gennemført ukendt resultat

HTTP 200 betyder, at operationen er gennemført, men garanterer ikke et køn. Bevar JSON null i stedet for at konvertere det til male, female, en tom streng eller konfidensen nul. Kontrollér data.result_status og data.reason separat fra HTTP-fejl.

Dette rigtige eksempel, der kun bruger datasættet og blev hentet den 1. oktober 2026, returnerer source: none og reason: not_found og koster stadig 1 kredit. En række i datasættet med stemmelighed kan returnere reason: ambiguous og bevarer sin sample_count. Et ukendt AI-resultat bruger source: ai og 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
    }
  }
}

Fortolk konfidens og evidens for matchet

En konfidens på 0.9 ligger på en skala fra 0 til 1. For observed_frequency betyder den det dominerende antal divideret med det samlede antal i den valgte række i datasættet. Det er ikke produktets målte nøjagtighed fra ende til ende. En model_reported-værdi kommer fra AI og er ikke kalibreret mod frekvenserne i datasættet.

Vælg enhver tærskelværdi i din applikation ud fra dine egne evalueringsdata og confidence_kind. Sammenlign ikke værdier fra datasættet og fra AI direkte, som om de målte det samme. Ved AI er match.name, match.scope og match.country null, fordi der ikke er valgt en række i datasættet. match.method er model_inference.

For fulde navne kan et resultat fra datasættet komme fra en enkelt del i stedet for hele strengen. data.input bevarer den sendte værdi, data.name beskriver det returnerede navn, og data.match beskriver kandidaten og opslagets omfang.

Beslut, hvad din applikation skal gøre

Håndtér først fejl i forespørgslen og i de enkelte elementer, og kontrollér derefter result_status. For en enkelt forudsigelse læser du data. For en batch anvender du den samme beslutning på data for hvert gennemført element. Bevar ukendte resultater i din applikation i stedet for at tvinge mærkaten male eller female igennem.

• Skeln mellem driftsfejl og ukendte resultater
• Anvend beslutningerne på en batch

Vælg tærskelværdier ud fra din egen evaluering

Der findes ingen universel konfidensgrænse, der gør en forudsigelse korrekt. Evaluér observed_frequency og model_reported hver for sig med repræsentative, uafhængigt mærkede eksempler fra din egen anvendelse. En frekvens i datasættet og en værdi angivet af AI er forskellige signaler, også når begge er 0.9. Mål, hvor ofte din regel giver et svar, og hvor ofte disse svar er korrekte. I alle andre tilfælde bør du bevare et ukendt resultat eller planlægge en manuel gennemgang.

Hvis result_status for eksempel er identified, men confidence_kind er model_reported, skal du anvende den regel, du har vurderet for AI, og ikke tærskelværdien for datasættet. Hvis forceToGenderize blev brugt, er name: null sammen med et køn, der ikke er null, gyldigt: Et alias kan fortolkes uden at udtrække et egentligt fornavn. Kontrollér gender og result_status, ikke kun name, for at afgøre, om forudsigelsen gav et svar. Resultatet er stadig et estimat, ikke en bekræftelse af en persons identitet.

• Evalueringsmål og konfidensens begrænsninger
• Datasættets profil og evidensens begrænsninger
• Fortolkning af kaldenavne og name med værdien null

Relaterede guider

• Batchsvar og fejl pr. element
• Opkrævningsstatus og resterende kreditter
• Kompatibilitet i svar og nye forsøg