A modern, type-safe Python client for the Gender-API.com service. Determine gender from first names, full names, or email addresses with high accuracy across 200+ countries.
- 🔍 Name Gender Detection - Detect gender from first names with 99%+ accuracy
- 🌍 Country Localization - Improve accuracy with country-specific results
- 📧 Email Analysis - Extract and analyze names from email addresses
- 🗺️ Country of Origin - Discover name origins and geographic distribution
- 📊 Batch Processing - Query multiple names in a single API call
- 🔒 Type-Safe - Full Python type hinting support with Pydantic models
- ⚡ Modern - Built on
requestsandpydantic
Install via pip:
pip install gender-api-clientGet your free API key at: gender-api.com/account
from gender_api import Client
client = Client(api_key="your_api_key")
# Simple gender lookup
result = client.get_by_first_name("Elisabeth")
if result.result_found:
print(result.gender) # "female"
print(result.accuracy) # 99For names that vary by country (e.g., "Andrea" is male in Italy, female in Germany):
# In Italy, Andrea is typically male
result = client.get_by_first_name("Andrea", country="IT")
print(result.gender) # "male"
# In Germany, Andrea is typically female
result = client.get_by_first_name("Andrea", country="DE")
print(result.gender) # "female"Detect country from IP address or browser locale:
# Localize by IP address
result = client.get_by_first_name("Jan", ip_address="178.27.52.144")
# Localize by browser locale
result = client.get_by_first_name("Jan", locale="de_DE")The API automatically splits full names and identifies the first name:
result = client.get_by_full_name("Sandra Miller")
print(result.first_name) # "Sandra"
print(result.last_name) # "Miller"
print(result.gender) # "female"With country:
result = client.get_by_full_name("Maria Garcia", country="ES")Extract and analyze names from email addresses:
result = client.get_by_email("elisabeth.smith@company.com")
print(result.gender) # "female"
print(result.first_name) # "Elisabeth" (extracted)
print(result.last_name) # "Smith"Query multiple names in a single API call for efficiency:
names = ["Michael", "Sarah", "Kim", "Jordan"]
results = client.get_by_multiple_names(names)
for result in results:
print(f"{result.first_name}: {result.gender} ({result.accuracy}% confidence)")
# Output:
# Michael: male (99% confidence)
# Sarah: female (99% confidence)
# Kim: female (72% confidence)
# Jordan: male (68% confidence)With country filter:
results = client.get_by_multiple_names(["Andrea", "Nicola"], country="IT")Discover where a name originates from:
result = client.get_country_of_origin("Giuseppe")
print(result.gender) # "male"
for country in result.country_of_origin:
print(f"{country.country_name} ({country.country}): {country.probability * 100:.0f}%")
# Output:
# Italy (IT): 89%
# Argentina (AR): 4%
# United States (US): 3%
# Get interactive map URL
print(result.country_of_origin_map_url)Monitor your API usage:
stats = client.get_stats()
print(stats.remaining_credits) # 4523
print(stats.is_limit_reached) # FalseFor enterprise or on-premise installations:
client = Client(api_key="your-key", api_url="https://custom-api.example.com/")- Python 3.7 or higher
# Clone the repository
git clone https://github.com/gender-api/gender-api-client-python.git
cd gender-api-client-python
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -e .[dev]# Run all tests
pytest| Property | Type | Description |
|---|---|---|
first_name |
str |
The queried name |
probability |
float |
Probability (e.g. 0.99) |
gender |
str |
"male", "female", or "unknown" |
accuracy |
int |
Confidence percentage (0-100) |
samples |
int |
Number of data samples |
country |
Optional[str] |
ISO 3166-1 country code |
result_found |
bool |
Whether a gender was determined |
| Property | Type | Description |
|---|---|---|
remaining_credits |
int |
API credits remaining |
is_limit_reached |
bool |
Whether quota is exhausted |
from gender_api import Client, GenderApiError, InvalidArgumentError, ApiError
try:
result = client.get_by_first_name("Elisabeth")
except InvalidArgumentError as e:
# Invalid input parameters
print(f"Invalid input: {e}")
except ApiError as e:
# API returned an error (e.g., invalid key, limit exceeded)
print(f"API Error {e.http_status}: {e}")
except GenderApiError as e:
# Other library errors (e.g. network)
print(f"Error: {e}")- Homepage: gender-api.com
- API Documentation: gender-api.com/api-docs
- FAQ: gender-api.com/faq
- Error Codes: gender-api.com/error-codes
- Support: gender-api.com/contact
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request