namegender 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6579682547f30f447af4b578719b7ea7d4f907be742b6a51359f6ddf0d9732d7
-  data.tar.gz: a851e53689d40ec42beeffb8c4b71ffb826280b8e51935d0491994481f87e62a
+  metadata.gz: 5350923af9d635c3f939d1f25538c60b6accc0defeb05cf22039573ff89e10fe
+  data.tar.gz: 39dcaef2b09d1357e6a6bab9d47f4ac5136e936e4b3a1d1a66bea68ae315f583
 SHA512:
-  metadata.gz: c9dc314525be03ffaff2506f922e6529b6383dfff4c98a14270a525a8c5a5af157fb43d2aa2bcc41daa37845d71a59802dc19cdc7ed47ee73ef03ca1bfc6c55f
-  data.tar.gz: fc58d715c4215caefe358e9c726702e11621d717d7cf6dfd2c814a80488f9627d7ea01eea571979d2a4d142405147ec0b27b28e797c62082ceb62401a667e3d5
+  metadata.gz: fe4b4f3e318ebb9f6ff60ff3d8492cfd83d2e1fb068208563a966c3a5fc5dad1e84289956d31c47b9cd2edddadace69f6a216074922276e284689ba5c2ae3d97
+  data.tar.gz: 036b301d1b82c4443657cbaa9a38351de62bb15c47c7621741475a0e7fcc3c46c1085c7f2b3fde0ae0ff558de84383645341e5f35f0a78f8b2f7a36cdd3dbe4a

data/README.md

@@ -12,19 +12,33 @@ puts result["gender"], result["probability"], result["sample_size"]
 
 ## Options and response
 
-`name`, `email`, `username` and `bulk` accept `country:`, `ai_fallback:` and
-`best_guess:`:
+`name`, `email`, `username` and `bulk` accept `country:`, `locale:`, `ip:`,
+`ai_fallback:` and `best_guess:`:
 
 ```ruby
 result = client.name("Andrea", country: "IT", best_guess: true)
 ```
 
+When you do not know the country, pass what you have and the API works it out:
+`locale:` is a language tag such as `"it-IT"` or `"pt_BR"` (its region is used;
+a tag without one, `"en"`, sets no country), and `ip:` is your end user's IP
+address (looked up, not stored). `country:` wins over `locale:`, which wins
+over `ip:`. The response's `country_source` says which one was used:
+`"country"`, `"locale"`, `"ip"` or `nil`.
+
+```ruby
+result = client.name("Andrea", locale: request.env["HTTP_ACCEPT_LANGUAGE"].to_s[/\A[^,;]+/], ip: request.ip)
+puts result["country"], result["country_source"]
+```
+
 A result carries `query`, `name`, `first_name`, `middle_name`, `last_name`, `name_type`, `gender`, `country`, `probability`,
-`sample_size`, `took_ms`, `source`, `confidence` and `matched_as`, alongside
+`sample_size`, `took_ms`, `source`, `confidence`, `matched_as` and `country_source`, 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.
+Branch on `body["error"]`, not on the message. A `bulk` response carries
+`country_source` once, at the top level next to `summary`, not on each item
+in `results`.
 
 ## Country distribution
 

data/lib/namegender.rb

@@ -21,21 +21,28 @@ module NameGender
       @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)
+    # `country` is an ISO 3166-1 alpha-2 code. Without it, `locale` (a
+    # language tag such as "it-IT" or "pt_BR"; a tag without a region, "en",
+    # sets no country) and then `ip` (the end user's IP address, not stored by
+    # the API) supply one: country > locale > ip. The result's
+    # "country_source" says which was used ("country", "locale", "ip" or nil).
+    #
+    # Other `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, locale: nil, ip: nil, **options)
+      post("/gender", { name: value, country: country, locale: locale, ip: ip }.merge(options).compact)
     end
-    def email(value, country: nil, **options)
-      post("/gender/email", { email: value, country: country }.merge(options).compact)
+    def email(value, country: nil, locale: nil, ip: nil, **options)
+      post("/gender/email", { email: value, country: country, locale: locale, ip: ip }.merge(options).compact)
     end
-    def username(value, country: nil, **options)
-      post("/gender/username", { username: value, country: country }.merge(options).compact)
+    def username(value, country: nil, locale: nil, ip: nil, **options)
+      post("/gender/username", { username: value, country: country, locale: locale, ip: ip }.merge(options).compact)
     end
-    def bulk(values, country: nil, type: "name", **options)
-      post("/gender/bulk", { names: Array(values), country: country, type: type }.merge(options).compact)
+    # `country`, `locale` and `ip` apply to every name in the list.
+    def bulk(values, country: nil, locale: nil, ip: nil, type: "name", **options)
+      post("/gender/bulk", { names: Array(values), country: country, locale: locale, ip: ip, 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: namegender
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - NameGender
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-24 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies: []
 description: A dependency-free Ruby client for name, email, username, bulk and country
   distribution lookups through NameGender.