namegender 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5350923af9d635c3f939d1f25538c60b6accc0defeb05cf22039573ff89e10fe
-  data.tar.gz: 39dcaef2b09d1357e6a6bab9d47f4ac5136e936e4b3a1d1a66bea68ae315f583
+  metadata.gz: c4643c981f5be9a9a9e2e4ebd41d812b466c1e740918d01374daf75c9d1e60ae
+  data.tar.gz: b46fa7433ebbae2738c127a4b1446d13d1fa14f98ec3369ad3c6ac7184d1b316
 SHA512:
-  metadata.gz: fe4b4f3e318ebb9f6ff60ff3d8492cfd83d2e1fb068208563a966c3a5fc5dad1e84289956d31c47b9cd2edddadace69f6a216074922276e284689ba5c2ae3d97
-  data.tar.gz: 036b301d1b82c4443657cbaa9a38351de62bb15c47c7621741475a0e7fcc3c46c1085c7f2b3fde0ae0ff558de84383645341e5f35f0a78f8b2f7a36cdd3dbe4a
+  metadata.gz: 2fcce41ef6af0dab6bb88560310d56d8573d8f2267b95a3b9c669818f679f7b63a1b0f27dd9d77ec329d651b3f14a879d7eaae30f7a58cd5283165f15328e54b
+  data.tar.gz: 8a072d1a84da3868b1d170f98b8c90e7210716f91737fb9f3fb30515e50b166706c3d5801edf94e5a63010273beef31143fbe2c3e3da679a5065d35672ba2f3a

data/README.md

@@ -53,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

@@ -52,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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namegender
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - NameGender
@@ -10,8 +10,8 @@ bindir: bin
 cert_chain: []
 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: []