Project

genderapi

0.0
The project is in a healthy, maintained state
genderapigenderapi/genderapi-rubyHomepageDocumentationSource CodeBug TrackerWiki
Official Ruby SDK for GenderAPI.io. This SDK allows determining gender from: - personal names - email addresses - social media usernames Supports: - country filtering - direct AI queries - forced genderization for nicknames or unconventional strings Built with HTTParty for easy HTTP handling.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
968
Stars
1
Forks
0
Watchers
1
 Releases
Current version
1.0.5
Total releases
6
First release
2025-07-05
Latest release
2025-07-08
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2025-07-07
Reverse Dependencies
0

 Dependencies

Development

rspec
~> 3.0

Runtime

httparty
~> 0.18
json
~> 2.0
 Project Readme

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: "李雷", ask_to_ai: 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", ask_to_ai: 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", ask_to_ai: true)
puts result

🔹 Get Gender by Name (Bulk)

bulk_data = [
  { name: "Andrea", country: "DE", id: "123" },
  { name: "andrea", country: "IT", id: "456" }
]

result = api.get_gender_by_name_bulk(data: bulk_data)
puts result

🔹 Get Gender by Email (Bulk)

bulk_data = [
  { email: "john@example.com", country: "US", id: "abc123" },
  { email: "maria@domain.de", country: "DE", id: "def456" }
]

result = api.get_gender_by_email_bulk(data: bulk_data)
puts result

🔹 Get Gender by Username (Bulk)

bulk_data = [
  { username: "johnwhite", country: "US", id: "u001" },
  { username: "maria2025", country: "DE", id: "u002" }
]

result = api.get_gender_by_username_bulk(data: bulk_data)
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
email 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.

Name Lookup (Bulk)

Parameter Type Required Description
data Array Yes Array of objects containing name, optional country, and optional id. Limit is 100 records per request.

Each object in the data array may include:

  • name: The name to analyze (required).
  • country: Two-letter country code (optional).
  • id: Custom identifier to correlate input/output (optional).

Email Lookup (Bulk)

Parameter Type Required Description
data Array Yes Array of objects containing email, optional country, and optional id. Limit is 50 records per request.

Each object in the data array may include:

  • email: The email address to analyze (required).
  • country: Two-letter country code (optional).
  • id: Custom identifier to correlate input/output (optional).

Username Lookup (Bulk)

Parameter Type Required Description
data Array Yes Array of objects containing username, optional country, and optional id. Limit is 50 records per request.

Each object in the data array may include:

  • username: The username to analyze (required).
  • country: Two-letter country code (optional).
  • id: Custom identifier to correlate input/output (optional).

✅ 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:

📚 Detailed API Documentation

For the complete API reference, visit:

https://www.genderapi.io/api-documentation

⚖️ License

MIT License