Project

genderapi

0.0
The project is in a healthy, maintained state
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
 Dependencies

Development

~> 3.0

Runtime

~> 0.18
~> 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: "李雷", 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
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.

✅ 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