GenderAPI.io V2: JSON responses and confidence

Understand the JSON response

GenderAPI.io V2 single predictions return a data object for the result and a meta object for request, access and billing information. Read data.gender and data.confidence together with data.confidence_kind and data.source. The following dataset example is a real response captured on 1 October 2026 with an API key; only the account balance is replaced. It does not represent measured product accuracy, and a live request can return a different result. API-key requests report access.mode: api_key and null trial-only quota fields; IP-trial requests report ip_trial with the trial limit and reset time.

{
  "data": {
    "input": {
      "type": "name",
      "value": "James",
      "country": "US"
    },
    "name": "james",
    "gender": "male",
    "country": "US",
    "confidence": 0.9956045412377965,
    "confidence_kind": "observed_frequency",
    "sample_count": 45274,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "james",
      "method": "normalized",
      "scope": "country",
      "country": "US"
    }
  },
  "meta": {
    "request_id": "7b68043d-2656-4e2d-abcf-dabb4bbc6445",
    "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
    }
  }
}

• Complete response schemas and batch examples

Prediction response fields

Returned input fields

Dataset matching fields

Access, billing and request metadata

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 real dataset-only example, captured on 1 October 2026, 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.

{
  "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
    }
  }
}

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.

Decide what your application should do next

Handle request and item errors first, then inspect result_status. For a single prediction, read data; for a batch, apply the same decision to each successful item's data. Keep unknown outcomes in your application instead of forcing a male or female label.

• Distinguish operational failures from unknowns
• Apply these decisions to a batch

Choose thresholds using your own evaluation

There is no universal confidence cutoff that makes a prediction correct. Evaluate observed_frequency and model_reported separately on representative, independently labeled examples from your use case. A dataset frequency and an AI self-reported score are different signals, even when both happen to be 0.9. Measure how often your policy answers and how often its answered predictions are correct; retain an unknown or review path for everything else.

For example, if result_status is identified but confidence_kind is model_reported, apply your evaluated AI policy rather than the dataset threshold. If forceToGenderize was used, name: null with a non-null gender is valid: an alias can be inferred without extracting a real given name. Check gender and result_status, not name alone, to decide whether the inference answered. This remains an estimate, not verification of a person's identity.

• Evaluation metrics and confidence limitations
• Dataset profile and evidence boundaries
• Nickname inference and nullable names

Related guides

• Batch response and per-item errors
• Billing status and remaining credits
• Response compatibility and retries