namegender 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6579682547f30f447af4b578719b7ea7d4f907be742b6a51359f6ddf0d9732d7
-  data.tar.gz: a851e53689d40ec42beeffb8c4b71ffb826280b8e51935d0491994481f87e62a
+  metadata.gz: c4643c981f5be9a9a9e2e4ebd41d812b466c1e740918d01374daf75c9d1e60ae
+  data.tar.gz: b46fa7433ebbae2738c127a4b1446d13d1fa14f98ec3369ad3c6ac7184d1b316
 SHA512:
-  metadata.gz: c9dc314525be03ffaff2506f922e6529b6383dfff4c98a14270a525a8c5a5af157fb43d2aa2bcc41daa37845d71a59802dc19cdc7ed47ee73ef03ca1bfc6c55f
-  data.tar.gz: fc58d715c4215caefe358e9c726702e11621d717d7cf6dfd2c814a80488f9627d7ea01eea571979d2a4d142405147ec0b27b28e797c62082ceb62401a667e3d5
+  metadata.gz: 2fcce41ef6af0dab6bb88560310d56d8573d8f2267b95a3b9c669818f679f7b63a1b0f27dd9d77ec329d651b3f14a879d7eaae30f7a58cd5283165f15328e54b
+  data.tar.gz: 8a072d1a84da3868b1d170f98b8c90e7210716f91737fb9f3fb30515e50b166706c3d5801edf94e5a63010273beef31143fbe2c3e3da679a5065d35672ba2f3a

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
 
@@ -39,6 +53,37 @@ result["registrations"].each { |r| puts "#{r["country"]} #{r["share"]}%" }
 puts result["attested_in"].join(", ")
 ```
 
+## Salutation
+
+A ready-to-use salutation for a letter or an email, in `en`, `de`, `fr`, `es`,
+`it`, `pt`, `nl`, `tr`, `pl` or `ja` (and regional variants such as `de-AT`
+or `pt-BR`). Without `language:` it follows `locale:`, then the country, then
+English.
+
+```ruby
+result = client.salutation("Dr. Anna Müller", language: "de")
+puts result["salutation"]["formal"]     # Sehr geehrte Frau Dr. Müller,
+puts result["salutation"]["informal"]   # Liebe Anna,
+
+client.salutation("Ahmet Yılmaz", language: "tr")["salutation"]["formal"]   # Sayın Ahmet Bey,
+
+# Names stored in separate fields are used as they are, not parsed:
+client.salutation(first_name: "Anna", last_name: "Müller", title: "Dr.", language: "de")
+
+result = client.salutation_bulk(["Dr. Anna Müller", "Müller GmbH"], language: "de")
+result["results"].each { |r| puts r["salutation"]["formal"] }
+puts result["summary"]   # total, gendered, neutral, organization
+```
+
+One credit per name. When the gender is not certain enough (`min_probability:`,
+default 90), you get the neutral form rather than a guess: `form` is
+`"gendered"`, `"neutral"` or `"organization"`, and `reason` says why it is not
+gendered (`"gender_unknown"`, `"below_min_probability"`, ...). `best_guess`
+does not apply here. If you already know the gender, pass
+`gender: "female"`, `"male"` or `"neutral"`. `salutation_bulk` takes up to 100
+names and returns `results` in input order. An unsupported language raises
+`NameGender::Error` with status 422 and `body["supported"]`.
+
 ## File jobs
 
 Upload a CSV or XLSX file (up to 100 MB and 1,000,000 rows) and get it back

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
@@ -45,6 +52,34 @@ module NameGender
     def countries(value, limit: nil)
       post("/gender/countries", { name: value, limit: limit }.compact)
     end
+    # A salutation for a letter or an email: "Sehr geehrte Frau Dr. Müller,",
+    # "Sayın Ahmet Bey,". `value` is the full name, titles included; pass
+    # `first_name:` and `last_name:` instead when they are stored separately
+    # (they are not parsed). `language` defaults to the language of `locale`,
+    # then the main language of the country, then "en"; an unsupported one is
+    # a 422. `gender:` ("male", "female", "neutral") is a known gender and
+    # skips the lookup; `min_probability:` (50-100, server default 90) is the
+    # certainty below which the neutral form is used; `title:` is an academic
+    # title kept in a separate field ("Dr."). "form" and "reason" in the result
+    # say why a neutral form was chosen. One credit per name. `best_guess` and
+    # `ai_fallback` do not apply here and are not accepted.
+    def salutation(value = nil, first_name: nil, last_name: nil, language: nil, country: nil, locale: nil, ip: nil,
+                   gender: nil, min_probability: nil, title: nil)
+      post("/salutation", {
+        name: value, first_name: first_name, last_name: last_name, language: language, country: country,
+        locale: locale, ip: ip, gender: gender, min_probability: min_probability, title: title
+      }.compact)
+    end
+    # Up to 100 names; every option applies to all of them. "results" keeps
+    # the input order, "summary" counts the gendered, neutral and organization
+    # forms.
+    def salutation_bulk(values, language: nil, country: nil, locale: nil, ip: nil, gender: nil, min_probability: nil,
+                        title: nil)
+      post("/salutation/bulk", {
+        names: Array(values), language: language, country: country, locale: locale, ip: ip, gender: gender,
+        min_probability: min_probability, title: title
+      }.compact)
+    end
     def account
       request(Net::HTTP::Get, "/me")
     end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: namegender
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.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.
+description: A dependency-free Ruby client for name, email, username, bulk, country
+  distribution and salutation lookups through NameGender.
 email:
 - support@namegender.com
 executables: []