Gender API
Change language22
Sign inGet started
Menu

API DOCUMENTATION V2

API v2 JSON responses and confidence

Understand GenderAPI v2 data and meta fields: gender, unknown reasons, confidence, dataset evidence, AI scores, access mode and billing metadata.

Understand the JSON response

Successful single responses contain data and meta. The following dataset example is synthetic and illustrative; it does not represent measured product accuracy or promise the same result for a live request. It shows IP-trial access. Authenticated requests report access.mode: api_key and null trial-only quota fields.

FieldMeaning
data.inputInput type, value and country. forceToGenderize is included when true.
data.nameMatched or extracted given name; null when none is available.
data.gendermale, female or JSON null. An inference, not verified personal identity.
data.result_status / reasonidentified with a null reason, or unknown with not_found, no_name_candidate, ambiguous or insufficient_evidence.
data.confidence0–1 score or null. Null gender has null confidence.
data.confidence_kindobserved_frequency: dominant dataset count / total. model_reported: AI score, not a calibrated probability. Null when unavailable.
data.sample_countDataset sample size or null. AI does not invent a sample count.
data.sourcedataset, ai or none.
data.country / country_sourceCountry association from dataset or ai_association, or null. Does not establish nationality, residence or ethnicity.
data.matchMatched dataset name, method (normalized, token, substring or model_inference), country/global scope and matched country. Unavailable evidence is null.
meta.request_id / duration_msOperation identifier and processing duration in milliseconds.
meta.accessHow access was granted and the reason for trial fallback, if any.
meta.usageNet charge, completion-time balance, billing status and trial reset information.
Illustrative JSON response
{
  "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
    }
  }
}

A successful unknown result

HTTP 200 means the operation completed; it does not guarantee a gender. Preserve JSON null rather than converting it to male, female, an empty string or zero confidence. Check data.result_status and data.reason separately from HTTP errors.

This synthetic dataset-only example returns source: none and reason: not_found and still costs 1 credit. A tied dataset row can return reason: ambiguous with its sample_count retained. An unknown AI result uses source: ai and reason: insufficient_evidence.

Illustrative JSON response
{
  "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
    }
  }
}

Interpret confidence and matching evidence

A confidence of 0.9 is on a 0–1 scale. For observed_frequency it means the dominant count divided by the selected dataset total; it is not measured end-to-end product accuracy. A model_reported score is provided by AI and is not calibrated against dataset frequencies.

Choose any application threshold using your own evaluation data and confidence_kind. Do not directly rank dataset and AI scores as if they measured the same thing. AI match.name, match.scope and match.country are null because no dataset row was selected; match.method is model_inference.

For full names, a dataset result may come from a component rather than the full string. data.input preserves the submitted value; data.name describes the returned name, and data.match describes the candidate and lookup scope.

Related guides