GenderAPI.io V2: odpowiedzi JSON i pewność

Poznaj strukturę odpowiedzi JSON

Pojedyncze prognozy GenderAPI.io V2 zwracają obiekt data z wynikiem i obiekt meta z informacjami o zapytaniu, dostępie i rozliczeniu. Odczytuj data.gender i data.confidence razem z data.confidence_kind i data.source. Poniższy przykład ze zbioru danych to prawdziwa odpowiedź pobrana 1 października 2026 r. z użyciem klucza API; zastąpiono jedynie saldo konta. Nie przedstawia zmierzonej dokładności produktu, a zapytanie na żywo może zwrócić inny wynik. Zapytania z kluczem API zwracają access.mode: api_key oraz null w polach limitu dotyczących wyłącznie próby; zapytania w ramach próby dla adresu IP zwracają ip_trial wraz z limitem próby i czasem jego odnowienia.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Krzysztof",
      "country": "PL"
    },
    "name": "krzysztof",
    "gender": "male",
    "country": "PL",
    "confidence": 0.9928131416837782,
    "confidence_kind": "observed_frequency",
    "sample_count": 974,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "krzysztof",
      "method": "normalized",
      "scope": "country",
      "country": "PL"
    }
  },
  "meta": {
    "request_id": "a03ce9f1-da34-4c69-9dac-363e861f9ade",
    "duration_ms": 11,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

• Pełne schematy odpowiedzi i przykłady partii

Pola odpowiedzi z prognozą

Zwracane pola wejściowe

Pola dopasowania w zbiorze danych

Metadane dostępu, rozliczenia i zapytania

Udany wynik nieznany

HTTP 200 oznacza, że operacja została zakończona; nie gwarantuje ustalenia płci. Zachowaj JSON null zamiast zamieniać go na male, female, pusty ciąg znaków lub zerową pewność. Sprawdzaj data.result_status i data.reason niezależnie od błędów HTTP.

Ten prawdziwy przykład korzystający tylko ze zbioru danych, pobrany 1 października 2026 r., zwraca source: none i reason: not_found, a mimo to kosztuje 1 kredyt. Wiersz zbioru danych z remisem może zwrócić reason: ambiguous z zachowanym sample_count. Nieznany wynik AI ma source: ai i 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
    }
  }
}

Interpretuj pewność i informacje o dopasowaniu

Pewność 0.9 jest wyrażona w skali 0–1. Dla observed_frequency oznacza liczbę wystąpień dominującej płci podzieloną przez sumę w wybranym wierszu zbioru danych; nie jest to zmierzona kompleksowa dokładność produktu. Wynik model_reported pochodzi od AI i nie jest kalibrowany względem częstości w zbiorze danych.

Dobierz progi w swojej aplikacji na podstawie własnych danych ewaluacyjnych i confidence_kind. Nie porównuj bezpośrednio wyników zbioru danych i AI, jakby mierzyły to samo. W wynikach AI match.name, match.scope i match.country mają wartość null, ponieważ nie wybrano żadnego wiersza zbioru danych; match.method ma wartość model_inference.

W przypadku imienia i nazwiska wynik ze zbioru danych może pochodzić z jednego składnika, a nie z całego ciągu. data.input zachowuje przesłaną wartość; data.name opisuje zwrócone imię, a data.match opisuje kandydata i zakres wyszukiwania.

Zdecyduj, co Twoja aplikacja ma zrobić dalej

Najpierw obsłuż błędy zapytania i elementów, a potem sprawdź result_status. W przypadku pojedynczej prognozy odczytaj data; w partii zastosuj tę samą decyzję do data każdego udanego elementu. Zachowuj wyniki unknown w aplikacji zamiast wymuszać etykietę male lub female.

• Odróżniaj awarie od wyników unknown
• Zastosuj te decyzje w partii

Dobierz progi na podstawie własnej oceny

Nie istnieje uniwersalny próg pewności, który sprawia, że prognoza jest poprawna. Oceniaj observed_frequency i model_reported osobno, na reprezentatywnych przykładach z Twojego przypadku użycia, oznaczonych niezależnie. Częstość w zbiorze danych i wynik zgłoszony przez AI to różne sygnały, nawet jeśli oba wynoszą akurat 0.9. Mierz, jak często Twoja reguła udziela odpowiedzi i jak często udzielone odpowiedzi są poprawne; dla pozostałych przypadków zachowaj ścieżkę unknown lub ręcznej weryfikacji.

Jeśli na przykład result_status to identified, ale confidence_kind to model_reported, zastosuj regułę ocenioną dla AI zamiast progu dla zbioru danych. Jeśli użyto forceToGenderize, name: null razem z gender o wartości innej niż null jest poprawne: alias może zostać zinterpretowany bez wyodrębnienia prawdziwego imienia. Aby ustalić, czy inferencja udzieliła odpowiedzi, sprawdzaj gender i result_status, a nie tylko name. Wynik pozostaje oszacowaniem, a nie weryfikacją tożsamości osoby.

• Metryki oceny i ograniczenia pewności
• Profil zbioru danych i ograniczenia danych
• Inferencja pseudonimów i name równe null

Powiązane przewodniki

• Odpowiedź dla partii i błędy elementów
• Status rozliczenia i pozostałe kredyty
• Zgodność odpowiedzi i ponawianie zapytań