Class: GenderAPI::Client

Inherits:
Object
  • Object
show all
Includes:
HTTParty
Defined in:
lib/genderapi/client.rb

Overview

Ruby SDK for GenderAPI.io

This SDK allows determining gender from:

- personal names
- email addresses
- social media usernames

Supports advanced options like:

- country filtering
- direct AI queries
- forced genderization for nicknames or unconventional strings

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, base_url: nil) ⇒ Client

Initialize the GenderAPI client.

Parameters:

  • api_key (String) —

    Your API key as a Bearer token.

  • base_url (String) (defaults to: nil) —

    Optional API base URL. Defaults to api.genderapi.io



30
31
32
33
34
35
36
37
 
# File 'lib/genderapi/client.rb', line 30

def initialize(api_key:, base_url: nil)
  @api_key = api_key
  self.class.base_uri(base_url) if base_url
  @headers = {
    "Authorization" => "Bearer #{@api_key}",
    "Content-Type" => "application/json"
  }
end

Instance Method Details

#get_gender_by_email(email:, country: nil, ask_to_ai: false) ⇒ Hash

Determine gender from an email address.

Parameters:

  • email (String) —

    The email to analyze. (Required)

  • country (String, nil) (defaults to: nil) —

    Optional two-letter country code (e.g. “US”).

  • ask_to_ai (Boolean) (defaults to: false) —

    Whether to force AI lookup. Default: false

Returns:

  • (Hash) —

    JSON response as a Ruby Hash.



69
70
71
72
73
74
75
76
77
 
# File 'lib/genderapi/client.rb', line 69

def get_gender_by_email(email:, country: nil, ask_to_ai: false)
  payload = {
    email: email,
    country: country,
    askToAI: ask_to_ai
  }

  _post_request("/api/email", payload)
end

#get_gender_by_email_bulk(data:) ⇒ Hash

Bulk determine gender from multiple email addresses.

Allows sending up to 50 email records in a single request. This method is designed for scenarios such as bulk database cleaning, analytics, or personalization tasks where email data is available and high throughput is required.

Each email object can contain:

- email [String] The email address to analyze. (Required)
- country [String, nil] Optional two-letter country code (e.g. "US").
- id [String, Integer, nil] Optional custom identifier to correlate input and output.

Parameters:

  • data (Array<Hash>) —

    Array of email data hashes.

Returns:

  • (Hash) —

    JSON response as a Ruby Hash.



138
139
140
141
 
# File 'lib/genderapi/client.rb', line 138

def get_gender_by_email_bulk(data:)
  payload = { data: data }
  _post_request("/api/email/multi/country", payload)
end

#get_gender_by_name(name:, country: nil, ask_to_ai: false, force_to_genderize: false) ⇒ Hash

Determine gender from a personal name.

Parameters:

  • name (String) —

    The name to analyze. (Required)

  • country (String, nil) (defaults to: nil) —

    Optional two-letter country code (e.g. “US”).

  • ask_to_ai (Boolean) (defaults to: false) —

    Whether to force AI lookup. Default: false

  • force_to_genderize (Boolean) (defaults to: false) —

    Whether to analyze nicknames or emojis. Default: false

Returns:

  • (Hash) —

    JSON response as a Ruby Hash.



49
50
51
52
53
54
55
56
57
58
 
# File 'lib/genderapi/client.rb', line 49

def get_gender_by_name(name:, country: nil, ask_to_ai: false, force_to_genderize: false)
  payload = {
    name: name,
    country: country,
    askToAI: ask_to_ai,
    forceToGenderize: force_to_genderize
  }

  _post_request("/api", payload)
end

#get_gender_by_name_bulk(data:) ⇒ Hash

Bulk determine gender from multiple personal names.

Allows sending up to 100 name records in a single request. Useful for high-volume batch processing where performance and cost efficiency are critical.

Each name object can contain:

- name [String] The personal name to analyze. (Required)
- country [String, nil] Optional two-letter country code (e.g. "US").
- id [String, Integer, nil] Optional custom identifier to correlate input and output.

Parameters:

  • data (Array<Hash>) —

    Array of name data hashes.

Returns:

  • (Hash) —

    JSON response as a Ruby Hash.



116
117
118
119
 
# File 'lib/genderapi/client.rb', line 116

def get_gender_by_name_bulk(data:)
  payload = { data: data }
  _post_request("/api/name/multi/country", payload)
end

#get_gender_by_username(username:, country: nil, ask_to_ai: false, force_to_genderize: false) ⇒ Hash

Determine gender from a social media username.

Parameters:

  • username (String) —

    The username to analyze. (Required)

  • country (String, nil) (defaults to: nil) —

    Optional two-letter country code (e.g. “US”).

  • ask_to_ai (Boolean) (defaults to: false) —

    Whether to force AI lookup. Default: false

  • force_to_genderize (Boolean) (defaults to: false) —

    Whether to analyze nicknames or emojis. Default: false

Returns:

  • (Hash) —

    JSON response as a Ruby Hash.



89
90
91
92
93
94
95
96
97
98
 
# File 'lib/genderapi/client.rb', line 89

def get_gender_by_username(username:, country: nil, ask_to_ai: false, force_to_genderize: false)
  payload = {
    username: username,
    country: country,
    askToAI: ask_to_ai,
    forceToGenderize: force_to_genderize
  }

  _post_request("/api/username", payload)
end

#get_gender_by_username_bulk(data:) ⇒ Hash

Bulk determine gender from multiple social media usernames.

Allows sending up to 50 username records in a single request. Useful for bulk social media analytics, profiling, or marketing segmentation tasks where usernames are the primary identifier and high performance is required.

Each username object can contain:

- username [String] The social media username to analyze. (Required)
- country [String, nil] Optional two-letter country code (e.g. "US").
- id [String, Integer, nil] Optional custom identifier to correlate input and output.

Parameters:

  • data (Array<Hash>) —

    Array of username data hashes.

Returns:

  • (Hash) —

    JSON response as a Ruby Hash.



160
161
162
163
 
# File 'lib/genderapi/client.rb', line 160

def get_gender_by_username_bulk(data:)
  payload = { data: data }
  _post_request("/api/username/multi/country", payload)
end