genderapi-ruby
Official Ruby SDK for GenderAPI.io — determine gender from names, emails, and usernames using AI.
Get your Free API Key: https://app.genderapi.io
🚀 Installation
Add this line to your Gemfile:
gem 'genderapi'
Then execute:
bundle install
Or install it manually:
gem install genderapi
📝 Usage
🔹 Get Gender by Name
require 'genderapi'
api = GenderAPI::Client.new(api_key: "YOUR_API_KEY")
# Basic usage
result = api.get_gender_by_name(name: "Michael")
puts result
# With askToAI set to true
result = api.get_gender_by_name(name: "李雷", askToAI: true)
puts result
🔹 Get Gender by Email
result = api.get_gender_by_email(email: "michael.smith@example.com")
puts result
# With askToAI set to true
result = api.get_gender_by_email(email: "michael.smith@example.com", askToAI: true)
puts result
🔹 Get Gender by Username
result = api.get_gender_by_username(username: "michael_dev")
puts result
# With askToAI set to true
result = api.get_gender_by_username(username: "michael_dev", askToAI: true)
puts result
📥 API Parameters
All API methods accept parameters as keyword arguments. All fields are optional except the primary identifier (name, email, or username).
Name Lookup
Parameter | Type | Required | Description |
---|---|---|---|
name | String | Yes | Name to query. |
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. |
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 |
---|---|---|---|
String | Yes | Email address to query. | |
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. |
Username Lookup
Parameter | Type | Required | Description |
---|---|---|---|
username | String | Yes | Username to query. |
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. |
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": "michael.smith@example.com",
"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"
}
🔗 Live Test Pages
You can try live gender detection directly on GenderAPI.io:
-
Determine gender from a name:
www.genderapi.io -
Determine gender from an email address:
https://www.genderapi.io/determine-gender-from-email -
Determine gender from a username:
https://www.genderapi.io/determine-gender-from-username
📚 Detailed API Documentation
For the complete API reference, visit:
https://www.genderapi.io/api-documentation
⚖️ License
MIT License