Gender API for Python

Install and make the first request

The Python client supports Python 3.9 and later. Keep the API key in an environment variable or secret manager rather than source control, create one reusable client per process, and pass the known country as an ISO two-letter code.

A result contains more than a label. Read probability, confidence, sample_size and source together. An unknown gender is a normal response that should flow through your type model as null rather than becoming an exception or a default category.

Pin a released client version in production. Client upgrades and data updates are separate events, so recording both your dependency version and enrichment date makes an unexpected output change much easier to investigate.

from namegender import NameGender

client = NameGender("YOUR_API_KEY")
result = client.name("Ayşe", country="TR")

print(result["gender"])
print(result["probability"])
print(result["sample_size"])

Use bulk calls in data jobs

Do not loop over individual HTTP requests when a job already has a list. The bulk method sends up to the documented request limit in one round trip. Chunk larger iterables, preserve input order and checkpoint completed chunks so a retry does not restart the whole file.

Deduplicate names together with their country context before sending them. Jordan in the US and Jordan in another market are different lookup keys, while one thousand identical country-name pairs only need one result that can be joined back to the original rows.

For a one-off dataframe, the managed CSV/XLSX upload may require less code and exposes column mapping before credits are spent. Use the API when enrichment belongs in a repeatable application or scheduled pipeline.

response = client.bulk(["Ayşe", "Mehmet", "Priya"])
for item in response["results"]:
    if item["gender"] is None:
        continue
    if item["probability"] >= 90:
        print(item["name"], item["gender"])

Make failure behaviour explicit

Set a finite network timeout and retry only transient failures such as connection errors, 429 responses and eligible server errors. Use bounded exponential backoff with jitter. Validation failures will not improve when retried and should be written to a review output with the original input.

Separate transport failure from an unknown result. A null gender means the request succeeded and the evidence was insufficient; a timeout means no answer was received. Collapsing both into an empty string makes operations and data quality impossible to distinguish.

Log request identifiers and status codes without logging API keys or entire customer rows. If names are personal data in your context, keep debug payloads out of general application logs and define a retention period for intermediate files.

Questions

Related pages