• Repository

Meta

• License Expression: MIT
  SPDX License Expression
• Author: Demografix
• Tags agify , demografix , demographics , genderize , nationalize
• Requires: Python >=3.10
• Provides-Extra: dev

Classifiers

• Development Status
  • 4 - Beta
• Intended Audience
  • Developers
• License
  • OSI Approved :: MIT License
• Programming Language
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13

Demografix Python SDK

Run demographic analysis over names — predicted gender, age, and nationality — from one client. The package covers genderize.io, agify.io, and nationalize.io.

Install

pip install demografix

The SDK has zero runtime dependencies. It requires Python 3.10 or newer.

Quickstart

Construct a client, run a list of names through a batch call, read the predictions, and read the quota.

fromcollectionsimport Counter
fromdemografiximport Demografix

client = Demografix(api_key="YOUR_API_KEY")

names = ["michael", "matthew", "jane", "sofia", "lars"]

batch = client.genderize_batch(names)

split = Counter(r.gender or "unknown" for r in batch.results)
print(split) # Counter({'male': 3, 'female': 2})
print(batch.quota.remaining) # 24987

API keys

An API key is required. Creating one is free and includes 2,500 requests per month. Generate a key in your dashboard at genderize.io, agify.io, or nationalize.io. One key works across all three services.

Usage

Gender

result = client.genderize("peter")
result.gender # "male", "female", or None
result.probability # 1.0
result.count # 1352696

batch = client.genderize_batch(["michael", "matthew", "jane"])
gender_mix = Counter(r.gender or "unknown" for r in batch.results)

Age

result = client.agify("michael")
result.age # 57 or None
result.count # 311558

batch = client.agify_batch(["michael", "matthew", "jane"])
ages = [r.age for r in batch.results if r.age is not None]
average_age = sum(ages) / len(ages)

Nationality

result = client.nationalize("nguyen")
result.country[0].country_id # "VN"
result.country[0].probability # 0.891132

batch = client.nationalize_batch(["nguyen", "schmidt", "rossi"])
top_countries = Counter(
 r.country[0].country_id for r in batch.results if r.country
)

Each batch accepts at most 10 names. A batch of more than 10 raises ValidationError before any request goes out.

country_id

genderize and agify accept an optional country_id (ISO 3166-1 alpha-2) to scope the prediction to one country. Input is case-insensitive; the response echoes it uppercase. nationalize has no such parameter.

result = client.genderize("kim", country_id="us")
result.country_id # "US"

batch = client.agify_batch(["michael", "matthew"], country_id="us")

Quota

Every result and every raised error carries a quota read from the response headers. Quota is never cached on the client; read it from the returned value.

Field	Meaning
limit	names allowed in the current window
remaining	names left in the current window
reset	seconds until the window resets

batch = client.genderize_batch(["michael", "matthew"])
batch.quota.remaining

Errors

Non-2xx responses raise a typed exception. Transport failures raise TransportError. Every exception subclasses DemografixError and carries status, message, and quota (when the response included headers).

Exception	Status	Cause
AuthError	401	invalid or missing API key
SubscriptionError	402	expired freebie or inactive subscription
ValidationError	422	bad parameter, or a batch over 10 names (raised client-side)
RateLimitError	429	window exhausted; quota is always populated
DemografixError	other non-2xx	base class for the hierarchy
TransportError	none	network error, timeout, or non-JSON body

A RateLimitError carries quota, so reset tells you how long to wait before retrying.

importtime
fromdemografiximport Demografix, RateLimitError

client = Demografix(api_key="YOUR_API_KEY")
names = ["michael", "matthew", "jane"]

while True:
 try:
 batch = client.genderize_batch(names)
 break
 except RateLimitError as exc:
 time.sleep(exc.quota.reset)

Methods

Method	Returns	country_id
genderize(name, country_id=None)	GenderizeResult	yes
genderize_batch(names, country_id=None)	Batch of GenderizePrediction	yes
agify(name, country_id=None)	AgifyResult	yes
agify_batch(names, country_id=None)	Batch of AgifyPrediction	yes
nationalize(name)	NationalizeResult	no
nationalize_batch(names)	Batch of NationalizePrediction	no

A *Result exposes the prediction fields directly plus a quota. A Batch exposes results plus one quota for the whole response.

Reference

Full API reference: genderize.io/documentation/api.

Verified details

These details have been verified by PyPI

Project links

• Issues
• Repository

GitHub Statistics

Maintainers

👁 Avatar for Demografix from gravatar.com
Demografix

Unverified details

These details have not been verified by PyPI

Project links

• Documentation
• Homepage

• Download URL: demografix-0.1.0.tar.gz
• Upload date: Jun 26, 2026
• Size: 11.7 kB
• Tags: Source
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for demografix-0.1.0.tar.gz

Algorithm	Hash digest
SHA256	0df5aeefff0d668dfb3803c8292cc37b5ab53d142ffb68b07881efa1197b9678
MD5	8e1c420bdbbe1b4fc21c4d1da6201a25
BLAKE2b-256	775898966b71ac1ea2453d04bea59c6d4e64b86f3c325878cdbdeeb8f6348a0c

See more details on using hashes here.

• Download URL: demografix-0.1.0-py3-none-any.whl
• Upload date: Jun 26, 2026
• Size: 8.9 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? Yes
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for demografix-0.1.0-py3-none-any.whl

Algorithm	Hash digest
SHA256	dd0640016600f813cbbcbcf0068b157c2adbd1271a8adc64550adfbce51c86b3
MD5	14bdf68254ccf117b1e3e96eb5cb6911
BLAKE2b-256	8686642b5f6cd64cab1f73cf204e4ae63a4fb7ef7cb7cc0c0f2feae274280540

See more details on using hashes here.