namegender 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a2b603dfdf3aa0427b5522c68d48ac4d0fcf706991d86b09abad77405e0fdd2
+  data.tar.gz: ec8a07ad241d2c98a6f2dce29f874e22799b42a80ee133ec8db329fb2c844722
+SHA512:
+  metadata.gz: f64cf15e7174a98e7ae334d4efc1f62f961ae8dfe0849308e53af49e37d2a07740d45b669a87e5123f86377a7eaa160bdd7856f9fc40a2918bc64db5389d21ae
+  data.tar.gz: b812e005bd8304610ccf7ece873bbf4d2933923fe53c5b4821fa8d55837545e3337094856e42ea34a3e56fd3cff58304d6f53ce94fc2756b473f7cd77de002d0

data/LICENSE

@@ -0,0 +1 @@
+MIT License. Copyright (c) 2026 NameGender. Permission is granted to use, copy, modify, merge, publish, distribute, sublicense, and/or sell this Software, provided this notice is included. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

data/README.md

@@ -0,0 +1,40 @@
+# NameGender Ruby
+
+```sh
+gem install namegender
+```
+
+```ruby
+client = NameGender::Client.new("YOUR_API_KEY")
+result = client.name("Ayşe", country: "TR")
+puts result["gender"], result["probability"], result["sample_size"]
+```
+
+## Options and response
+
+`name`, `email`, `username` and `bulk` accept `country:`, `ai_fallback:` and
+`best_guess:`:
+
+```ruby
+result = client.name("Andrea", country: "IT", best_guess: true)
+```
+
+A result carries `query`, `name`, `gender`, `country`, `probability`,
+`sample_size`, `took_ms`, `source`, `confidence` and `matched_as`, alongside
+`credits_charged`, `credits_remaining`, `data_version` and `request_id`.
+Success is the HTTP status: any non-2xx response raises `NameGender::Error`
+with `status` and `body` (`{"error", "message", "request_id", "docs"}`).
+Branch on `body["error"]`, not on the message.
+
+## Country distribution
+
+Which countries a name is recorded in. This is not a country-of-origin or
+ethnicity inference: `registrations` is counted volume, comparable only among
+the countries that publish counted birth statistics, and `attested_in` is
+presence with no weight attached. Show `basis["note"]` next to any percentage.
+
+```ruby
+result = client.countries("Mehmet", limit: 10)
+result["registrations"].each { |r| puts "#{r["country"]} #{r["share"]}%" }
+puts result["attested_in"].join(", ")
+```

data/lib/namegender.rb

@@ -0,0 +1,65 @@
+require "json"
+require "net/http"
+require "uri"
+
+module NameGender
+  class Error < StandardError
+    attr_reader :status, :body
+    def initialize(message, status = 0, body = nil)
+      super(message); @status = status; @body = body
+    end
+  end
+
+  class Client
+    def initialize(api_key, base_url: "https://namegender.com/api/v1")
+      raise ArgumentError, "api_key is required" if api_key.to_s.empty?
+      @api_key, @base_url = api_key, base_url.sub(%r{/$}, "")
+    end
+
+    # `options` are sent as-is: `ai_fallback: true` falls back to a language
+    # model for names not in the database (needs AI consent on the account),
+    # `best_guess: true` returns the most likely gender even below the
+    # probability threshold. Any non-2xx response raises NameGender::Error.
+    def name(value, country: nil, **options)
+      post("/gender", { name: value, country: country }.merge(options).compact)
+    end
+    def email(value, country: nil, **options)
+      post("/gender/email", { email: value, country: country }.merge(options).compact)
+    end
+    def username(value, country: nil, **options)
+      post("/gender/username", { username: value, country: country }.merge(options).compact)
+    end
+    def bulk(values, country: nil, type: "name", **options)
+      post("/gender/bulk", { names: values, country: country, type: type }.merge(options).compact)
+    end
+    # Country distribution of a name. Not a country-of-origin or ethnicity
+    # inference: "registrations" is counted volume, comparable only among the
+    # countries that publish counted birth statistics; "attested_in" is
+    # presence with no weight attached. `limit` caps "registrations" (1-100,
+    # server default 25).
+    def countries(value, limit: nil)
+      post("/gender/countries", { name: value, limit: limit }.compact)
+    end
+    def account
+      request(Net::HTTP::Get, "/me")
+    end
+
+    private
+    def post(path, body)
+      request(Net::HTTP::Post, path, body)
+    end
+    def request(klass, path, body = nil)
+      uri = URI(@base_url + path)
+      req = klass.new(uri)
+      req["Accept"] = req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{@api_key}"
+      req.body = JSON.generate(body) if body
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
+      parsed = JSON.parse(response.body)
+      raise Error.new(parsed["message"] || "HTTP #{response.code}", response.code.to_i, parsed) unless response.is_a?(Net::HTTPSuccess)
+      parsed
+    rescue JSON::ParserError
+      raise Error.new("NameGender returned invalid JSON", response&.code.to_i)
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: namegender
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- NameGender
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-16 00:00:00.000000000 Z
+dependencies: []
+description: A dependency-free Ruby client for name, email, username, bulk and country
+  distribution lookups through NameGender.
+email:
+- support@namegender.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/namegender.rb
+homepage: https://namegender.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://namegender.com
+  source_code_uri: https://github.com/anpekesen/namegender-ruby
+  bug_tracker_uri: https://github.com/anpekesen/namegender-ruby/issues
+  documentation_uri: https://namegender.com/docs
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby client for the NameGender API
+test_files: []