genderapi 1.0.4

Official Python SDK for GenderAPI.io

genderapi-python

Official Python SDK for GenderAPI.io — determine gender from names, emails, and usernames using AI.

---

🚀 Installation

Install the required package:

pip install genderapi

---

📝 Usage

🔹 Get Gender by Name

from genderapi import GenderAPI

api = GenderAPI("YOUR_API_KEY")

# Basic usage
result = api.get_gender_by_name(name="Michael")
print(result)

# With askToAI set to True
result = api.get_gender_by_name(name="李雷", askToAI=True)
print(result)

---

🔹 Get Gender by Email

result = api.get_gender_by_email(email="[e-mail]")
print(result)

# With askToAI set to True
result = api.get_gender_by_email(email="[e-mail]", askToAI=True)
print(result)

---

🔹 Get Gender by Username

result = api.get_gender_by_username(username="michael_dev")
print(result)

# With askToAI set to True
result = api.get_gender_by_username(username="michael_dev", askToAI=True)
print(result)

---

📥 API Parameters

Common Parameters

Parameter	Type	Required	Description
country	String	No	Two-letter country code (e.g. "US"). Helps narrow down gender detection results by region.
askToAI	Boolean	No	Default is false. If true, sends the query directly to AI for maximum accuracy, consuming 3 credits per request. If false, GenderAPI first tries its internal database and uses AI only if necessary, without spending 3 credits. Recommended for non-latin characters or unusual strings.

---

Name Lookup

Parameter	Type	Required	Description
name	String	Yes	Name to query.
forceToGenderize	Boolean	No	Default is false. When true, analyzes even nicknames, emojis, or unconventional strings like "spider man" instead of returning null for non-standard names.

---

Email Lookup

Parameter	Type	Required	Description
email	String	Yes	Email address to query.

---

Username Lookup

Parameter	Type	Required	Description
username	String	Yes	Username to query.
forceToGenderize	Boolean	No	Default is false. When true, analyzes even nicknames, emojis, or unconventional strings like "spider man" instead of returning null for non-standard names.

---

✅ API Response

Example JSON response for all endpoints:

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "[e-mail]",
  "name": "Michael",
  "gender": "male",
  "country": "US",
  "total_names": 325,
  "probability": 98,
  "duration": "4ms"
}

---

Response Fields

Field	Type	Description
status	Boolean	true or false. Check errors if false.
used_credits	Integer	Credits used for this request.
remaining_credits	Integer	Remaining credits on your package.
expires	Integer (timestamp)	Package expiration date (in seconds).
q	String	Your input query (name, email, or username).
name	String	Found name.
gender	Enum[String]	"male", "female", or "null".
country	Enum[String]	Most likely country (e.g. "US", "DE", etc.).
total_names	Integer	Number of samples behind the prediction.
probability	Integer	Likelihood percentage (50-100).
duration	String	Processing time (e.g. "4ms").

---

⚠️ Error Codes

When status is false, check the following error codes:

errno	errmsg	Description
50	access denied	Unauthorized IP Address or Referrer. Check your access privileges.
90	invalid country code	Check supported country codes. ISO 3166-1 alpha-2
91	name not set || email not set	Missing name or email parameter on your request.
92	too many names || too many emails	Limit is 100 for names, 50 for emails in one request.
93	limit reached	The API key credit has been finished.
94	invalid or missing key	The API key cannot be found.
99	API key has expired	Please renew your API key.

Example error response:

{
  "status": false,
  "errno": 94,
  "errmsg": "invalid or missing key"
}

---

⚖️ License

MIT License