genderapi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 155c4030fa35e5b879f2592488e408b6484ee8e1cbe8a9e85b5f512d426812bd
+  data.tar.gz: a6fbdbd6375727517f101e8d29b6bbbe9806e38b277e3ecdb3c161d948726972
+SHA512:
+  metadata.gz: 92b8a497590017a17a41d11cf453c4100b976ff098f4ea02503c9ae49a52268e205e1fc3b59ff5c6141d27a947ff6567dcc4f7cfa02caf6b7bce6c934c409601
+  data.tar.gz: 24008cc417d0780a7d4e2befe0924c231ade721c99719e8945a063c45f97810241fa3b797837e7b3b4033526e07be3aa34bd30e435e1efed6090000ae9dd228f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gender Api
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,208 @@
+# genderapi-ruby
+
+Official Ruby SDK for [GenderAPI.io](https://www.genderapi.io) — determine gender from **names**, **emails**, and **usernames** using AI.
+
+---
+
+Get your Free API Key: [https://app.genderapi.io](https://app.genderapi.io)
+
+---
+
+## 🚀 Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem 'genderapi'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it manually:
+
+```bash
+gem install genderapi
+```
+
+---
+
+## 📝 Usage
+
+### 🔹 Get Gender by Name
+
+```ruby
+require 'genderapi'
+
+api = GenderAPI::Client.new("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
+
+```ruby
+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
+
+```ruby
+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:
+
+```json
+{
+  "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](https://en.wikipedia.org/wiki/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:
+
+```json
+{
+  "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](https://www.genderapi.io)
+
+- **Determine gender from an email address:**  
+  [https://www.genderapi.io/determine-gender-from-email](https://www.genderapi.io/determine-gender-from-email)
+
+- **Determine gender from a username:**  
+  [https://www.genderapi.io/determine-gender-from-username](https://www.genderapi.io/determine-gender-from-username)
+
+---
+
+## 📚 Detailed API Documentation
+
+For the complete API reference, visit:
+
+[https://www.genderapi.io/api-documentation](https://www.genderapi.io/api-documentation)
+
+---
+
+## ⚖️ License
+
+MIT License

data/lib/genderapi/client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "json"
+
+module GenderAPI
+  ##
+  # 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
+  #
+  class Client
+    include HTTParty
+    base_uri "https://api.genderapi.io"
+
+    ##
+    # Initialize the GenderAPI client.
+    #
+    # @param api_key [String] Your API key as a Bearer token.
+    # @param base_url [String] Optional API base URL. Defaults to https://api.genderapi.io
+    #
+    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
+
+    ##
+    # Determine gender from a personal name.
+    #
+    # @param name [String] The name to analyze. (Required)
+    # @param country [String, nil] Optional two-letter country code (e.g. "US").
+    # @param ask_to_ai [Boolean] Whether to force AI lookup. Default: false
+    # @param force_to_genderize [Boolean] Whether to analyze nicknames or emojis. Default: false
+    #
+    # @return [Hash] JSON response as a Ruby Hash.
+    #
+    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
+
+    ##
+    # Determine gender from an email address.
+    #
+    # @param email [String] The email to analyze. (Required)
+    # @param country [String, nil] Optional two-letter country code (e.g. "US").
+    # @param ask_to_ai [Boolean] Whether to force AI lookup. Default: false
+    #
+    # @return [Hash] JSON response as a Ruby Hash.
+    #
+    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
+
+    ##
+    # Determine gender from a social media username.
+    #
+    # @param username [String] The username to analyze. (Required)
+    # @param country [String, nil] Optional two-letter country code (e.g. "US").
+    # @param ask_to_ai [Boolean] Whether to force AI lookup. Default: false
+    # @param force_to_genderize [Boolean] Whether to analyze nicknames or emojis. Default: false
+    #
+    # @return [Hash] JSON response as a Ruby Hash.
+    #
+    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
+
+    private
+
+    ##
+    # Internal helper to send POST requests to the GenderAPI.io API.
+    #
+    # Handles:
+    #   - Bearer authentication
+    #   - Removal of nil values in payload
+    #   - JSON parsing of responses
+    #   - Raising errors for non-200 responses
+    #
+    # @param endpoint [String] API endpoint path (e.g. "/api")
+    # @param payload [Hash] Request body data.
+    #
+    # @return [Hash] JSON response as Ruby Hash.
+    #
+    def _post_request(endpoint, payload)
+      # Remove nil values from payload
+      cleaned_payload = payload.reject { |_k, v| v.nil? }
+
+      response = self.class.post(
+        endpoint,
+        headers: @headers,
+        body: JSON.generate(cleaned_payload)
+      )
+
+      case response.code
+      when 200
+        parse_json(response.body)
+      when 404
+        # GenderAPI may return useful JSON for 404 too
+        parse_json(response.body)
+      else
+        raise "GenderAPI Error: HTTP #{response.code} - #{response.body}"
+      end
+    rescue HTTParty::Error => e
+      raise "GenderAPI Request failed: #{e.message}"
+    rescue JSON::ParserError
+      raise "GenderAPI Response is not valid JSON"
+    end
+
+    ##
+    # Parse JSON response safely.
+    #
+    # @param body [String] JSON string.
+    # @return [Hash] Parsed Hash.
+    #
+    def parse_json(body)
+      JSON.parse(body)
+    end
+  end
+end

data/lib/genderapi/version.rb

@@ -0,0 +1,5 @@
+# lib/genderapi/version.rb
+
+module GenderAPI
+  VERSION = "1.0.0"
+end

data/lib/genderapi.rb

@@ -0,0 +1,8 @@
+# lib/genderapi.rb
+
+require "genderapi/version"
+require "genderapi/client"
+
+module GenderAPI
+  # boş bırakabilirsin veya helper methodlar koyabilirsin
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: genderapi
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Onur Ozturk
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: "\n    Official Ruby SDK for GenderAPI.io.\n\n    This SDK allows determining
+  gender from:\n    - personal names\n    - email addresses\n    - social media usernames\n\n
+  \   Supports:\n    - country filtering\n    - direct AI queries\n    - forced genderization
+  for nicknames or unconventional strings\n\n    Built with HTTParty for easy HTTP
+  handling.\n  "
+email:
+- support@genderapi.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/genderapi.rb
+- lib/genderapi/client.rb
+- lib/genderapi/version.rb
+homepage: https://www.genderapi.io
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Ruby SDK for GenderAPI.io — determine gender from names, emails, and usernames
+  using AI.
+test_files: []