namegender 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4643c981f5be9a9a9e2e4ebd41d812b466c1e740918d01374daf75c9d1e60ae
-  data.tar.gz: b46fa7433ebbae2738c127a4b1446d13d1fa14f98ec3369ad3c6ac7184d1b316
+  metadata.gz: 697eadb66c1e662a33a859ad917c8a094db92477df1687d5120ff4c6894dd466
+  data.tar.gz: fb5eb0a69ef1e910892b847be2dbd253b9e2b3bf596192aadcdbfc46bd21fcf0
 SHA512:
-  metadata.gz: 2fcce41ef6af0dab6bb88560310d56d8573d8f2267b95a3b9c669818f679f7b63a1b0f27dd9d77ec329d651b3f14a879d7eaae30f7a58cd5283165f15328e54b
-  data.tar.gz: 8a072d1a84da3868b1d170f98b8c90e7210716f91737fb9f3fb30515e50b166706c3d5801edf94e5a63010273beef31143fbe2c3e3da679a5065d35672ba2f3a
+  metadata.gz: f8b59ef517681af8a964f29430b8ae253f70afbffa58bc4a261c029c51655a351488b9698a898c9253bf32e4d54c4ccaea01b5bcadcb7cab730561a06e914e53
+  data.tar.gz: 566b094d3df1e8647a72571543c358798427442352fe579954f279b603426c3204d0be0341c4a5b4b903c835439eb7d00ac70ffc9bf2350ec283e4554a3213ed

data/README.md

@@ -84,6 +84,63 @@ does not apply here. If you already know the gender, pass
 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.
+
+## Age from name
+
+The estimated age of the people who carry a first name, from birth records.
+It describes a group, not a person: never use it for decisions about an
+individual.
+
+```ruby
+result = client.age("Brittany")
+puts result["age"]            # 36 (median)
+puts result["age_range"]      # {"low"=>32, "high"=>38}, the middle half
+puts result["age_range_80"]   # {"low"=>28, "high"=>41}, the middle 80%
+puts result["birth_year"]     # 1990
+
+client.age("Brittany", gender: "female", country: "US")
+
+result = client.age_bulk(["Brittany", "Margaret"])
+result["results"].each { |r| puts "#{r["name"]} #{r["age"]}" }
+```
+
+It covers the US, France and Norway; with no country hint US data is used and
+`country_source` is `"default"`. For other countries `age` is `nil` and
+`reason` is `"country_not_covered"`, with no credit charged; `reason` can also
+be `"not_found"` or `"insufficient_data"`. These are normal answers, not
+errors. `gender:` (`"male"` or `"female"`) narrows the estimate to that
+gender's records. It takes `country:`, `locale:` and `ip:`, not `best_guess`
+or `ai_fallback`. One credit per name; `age_bulk` takes up to 100 names and
+returns `results` in input order. Age responses carry no `data_version`.
+
 ## 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

@@ -80,6 +80,47 @@ module NameGender
         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
+    # Estimated age of the people who carry a first name, from birth records:
+    # "age" is the median, "age_range" the middle half and "age_range_80" the
+    # middle 80 percent ({"low", "high"}), "birth_year" the median birth year.
+    # It describes a group, not a person: never use it for decisions about an
+    # individual. Covers the US, France and Norway; with no country hint US
+    # data is used and "country_source" is "default". When "age" is nil,
+    # "reason" says why ("not_found", "insufficient_data" or
+    # "country_not_covered"); that is a normal answer, not an error, and
+    # "country_not_covered" costs no credit. `gender:` ("male" or "female")
+    # narrows to that gender's records; `country`, `locale` and `ip` work as
+    # in #name. Options that are nil or empty are not sent. One credit per
+    # name. Age responses carry no "data_version".
+    def age(value, gender: nil, country: nil, locale: nil, ip: nil)
+      post("/age", present(name: value, gender: gender, country: country, locale: locale, ip: ip))
+    end
+    # Up to 100 names; every option applies to all of them. "results" keeps
+    # the input order.
+    def age_bulk(values, gender: nil, country: nil, locale: nil, ip: nil)
+      post("/age/bulk", present(names: Array(values), gender: gender, country: country, locale: locale, ip: ip))
+    end
     def account
       request(Net::HTTP::Get, "/me")
     end
@@ -92,6 +133,10 @@ module NameGender
     def post(path, body)
       request(Net::HTTP::Post, path, body)
     end
+    # The fields that are set: nil and empty strings are dropped.
+    def present(fields)
+      fields.reject { |_, v| v.nil? || v == "" }
+    end
     def request(klass, path, body = nil, raw: nil, headers: {})
       response = transmit(klass, path, body, raw: raw, headers: headers)
       # 204 (a cancelled job) has no body.

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: namegender
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - NameGender
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-09 00:00:00.000000000 Z
 dependencies: []
 description: A dependency-free Ruby client for name, email, username, bulk, country
-  distribution and salutation lookups through NameGender.
+  distribution, salutation, name check and age lookups through NameGender.
 email:
 - support@namegender.com
 executables: []