namegender 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5350923af9d635c3f939d1f25538c60b6accc0defeb05cf22039573ff89e10fe
-  data.tar.gz: 39dcaef2b09d1357e6a6bab9d47f4ac5136e936e4b3a1d1a66bea68ae315f583
+  metadata.gz: 658d4fb7a91170b0e2b2c61f23f172b259192bca6308113674e874057aa0adc1
+  data.tar.gz: a1272df8391d88b717b26494bf79bc16bbbc4c51a3db6bec6016177d8572828c
 SHA512:
-  metadata.gz: fe4b4f3e318ebb9f6ff60ff3d8492cfd83d2e1fb068208563a966c3a5fc5dad1e84289956d31c47b9cd2edddadace69f6a216074922276e284689ba5c2ae3d97
-  data.tar.gz: 036b301d1b82c4443657cbaa9a38351de62bb15c47c7621741475a0e7fcc3c46c1085c7f2b3fde0ae0ff558de84383645341e5f35f0a78f8b2f7a36cdd3dbe4a
+  metadata.gz: c83e850168ffcdfdd3ad530f59df0cb3db34dbf6a7159e6bc9bdd230156bbb2343192b79701d42a1f2420c0bff379b9cf7c84cba7436a5bec2ffc532c1c14876
+  data.tar.gz: bb93bcc96d6651dd39e0bfe25a0c4464db382e5c310f3879160f8c747a468840b2e8cd8f7b60da17ea0e93d411e02f70da2b2be72a7160111595eba614ecfe2d

data/README.md

@@ -53,6 +53,66 @@ 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"]`.
+
+## Name check
+
+Whether a name typed into a form looks like a real person's name, with the
+reasons. It never calls a name fake: use it to flag records for a closer look,
+not to reject people automatically.
+
+```ruby
+result = client.name_check("asdf qwerty")
+puts result["assessment"]   # implausible
+puts result["score"]        # 0 (0-100)
+result["signals"].each { |s| puts "#{s["code"]} #{s["severity"]} #{s["part"]}" }   # keyboard_pattern high first_name, ...
+
+client.name_check("Jennifer Null")["assessment"]   # plausible
+
+# Names stored in separate fields are used as they are, not parsed:
+client.name_check(first_name: "Jennifer", last_name: "Null", country: "US")
+
+result = client.name_check_bulk(["Jennifer Null", "asdf qwerty"])
+puts result["summary"]   # total, plausible, suspicious, implausible
+```
+
+One credit per name. `assessment` is `"plausible"`, `"suspicious"` or
+`"implausible"`; each signal has `code`, `severity` (`high`, `medium`, `low`,
+`info`, `positive`), `part` and `value` (either can be `nil`). `evidence`
+says whether the first name is counted, attested or not found. Surnames are
+judged by their shape only. It takes `country:`, `locale:` and `ip:`, not
+`best_guess` or `ai_fallback`. `name_check_bulk` takes up to 100 names and
+returns `results` in input order.
+
 ## 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,55 @@ 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
+    # Whether a name typed into a form looks like a real person's name, with
+    # reasons. It never calls a name fake: use it to flag records for a look,
+    # not to reject people automatically. "assessment" is "plausible",
+    # "suspicious" or "implausible", "score" is 0-100, and "signals" lists
+    # why ({"code", "severity", "part", "value"}; "part" and "value" can be
+    # nil). Surnames are judged by their shape only. `value` is the full name;
+    # pass `first_name:` and `last_name:` instead when they are stored
+    # separately (they are not parsed). `country`, `locale` and `ip` work as
+    # in #name. One credit per name. `best_guess`, `ai_fallback` and
+    # `language` do not apply here and are not accepted.
+    def name_check(value = nil, first_name: nil, last_name: nil, country: nil, locale: nil, ip: nil)
+      post("/name-check", {
+        name: value, first_name: first_name, last_name: last_name, country: country, locale: locale, ip: ip
+      }.compact)
+    end
+    # Up to 100 names; every option applies to all of them. "results" keeps
+    # the input order, "summary" counts the plausible, suspicious and
+    # implausible names.
+    def name_check_bulk(values, country: nil, locale: nil, ip: nil)
+      post("/name-check/bulk", { names: Array(values), country: country, locale: locale, ip: ip }.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.7.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, salutation and name check lookups through NameGender.
 email:
 - support@namegender.com
 executables: []