Use GenderAPI.io V2 with Python

Set up a server-side Python project

This guide calls the GenderAPI.io V2 endpoint https://api.genderapi.io/api/v2/gender with a Bearer API key. Use Python 3.10 or later and download genderapi_v2.py into your project. The example uses urllib.request and json from Python’s standard library; no pip package is required.

Set GENDERAPI_API_KEY in your server environment. The placeholder below is not a working key. Keep real credentials out of committed files, notebooks you share and client-side applications. Importing the module or running it without a demo flag does not send a request.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Download genderapi_v2.py →
• Verify your key with the free usage endpoint →

Make one explicit dataset-only request

Save the following as single.py beside the downloaded file and run python3 single.py. The helper sends type: name, value: Alice and options.ai_mode: off as JSON. Read the estimate from data and the request and billing details from meta. A successful call uses 1 credit, including an unknown result; the sample name does not guarantee a prediction.

make_item accepts name, email or username and requires an explicit AI mode. Add country only when you have relevant context. The helper requires a 24-character hexadecimal API key before sending. This validates format, not whether the key exists. It also rejects successful IP-trial responses as an access mismatch; that check occurs after the response and cannot undo a trial charge.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• All single-request fields →

Keep the result and its evidence together

An inferred association is not a person's self-declared gender. Keep the original input, the returned evidence and any information provided by the person separate. An unknown result is a valid outcome; it should not become a guessed category in your application.

• Response fields and unknown outcomes →
• Accuracy and confidence explained →
• Data sources and the dated database profile →

Process a mixed batch and keep row IDs

GenderAPI.io V2 uses POST https://api.genderapi.io/api/v2/gender/batch for mixed batches: up to 50 items with an account key or 10 for the IP trial. These examples require an account key. Give every item a stable, unique id and explicit AI mode. A batch can mix names, emails and usernames, with optional country context on each item.

Read every item in data and the summary in meta.summary. HTTP 200 can include item errors; an all-failed batch can be a top-level Problem response containing the results. Successful unknowns count as succeeded. The original index and id let you attach an outcome to the correct source row.

For larger jobs, divide input into groups of at most 50 and submit sequentially at first. Save each response and its usage before advancing. Stop on transport, account or unconfirmed-billing failures and reconcile the current group. Add concurrency only after checking your account limits; a batch-size limit is not a throughput guarantee.

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• Batch input, results and billing →

Choose when to use AI

forceToGenderize is optional for names, email addresses and usernames. With it enabled, omit ai_mode or use fallback; off and always conflict with it and return 422. A positive starting balance is enough to begin a request even if its final charge takes the balance below zero.

Nickname mode can return a gender with name: null. It can also return an unknown result. Neither ordinary fallback nor nickname inference guarantees a correct or non-null answer.

This Python helper always requires ai_mode. To allow nickname inference, use make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). The helper maps force_to_genderize to the JSON field forceToGenderize.

• AI options and nickname inference →
• Credits and usage →

Decide what to do after a failure

The examples send each operation once. They do not retry automatically: a new submission is a new billable operation. A timeout or connection failure means the client did not receive a complete response; it does not prove that the server stopped or that no credits were charged.

Keep the returned request ID and billing state with your job record. The error object retains the response for controlled inspection, but it can contain the original input; do not put the whole object, response or API key into routine logs.

• Problem Details and retry decisions →
• Credits and billing confirmation →

Understand this example’s transport behavior

The urllib timeout is 10 seconds for blocking socket operations, not a guaranteed total wall-clock deadline for the entire request. The example disables HTTP redirects, parses successful JSON and retains HTTP Problem responses. It never retries automatically.

Local tests use synthetic transport fixtures for success, unknowns, partial batches, account access and failures. They verify the example’s control flow; they do not measure live API availability, inference accuracy or production latency.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Python urllib.request reference →
• Python HTTPError reference →

Frequently asked questions