namegender 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 658d4fb7a91170b0e2b2c61f23f172b259192bca6308113674e874057aa0adc1
-  data.tar.gz: a1272df8391d88b717b26494bf79bc16bbbc4c51a3db6bec6016177d8572828c
+  metadata.gz: 697eadb66c1e662a33a859ad917c8a094db92477df1687d5120ff4c6894dd466
+  data.tar.gz: fb5eb0a69ef1e910892b847be2dbd253b9e2b3bf596192aadcdbfc46bd21fcf0
 SHA512:
-  metadata.gz: c83e850168ffcdfdd3ad530f59df0cb3db34dbf6a7159e6bc9bdd230156bbb2343192b79701d42a1f2420c0bff379b9cf7c84cba7436a5bec2ffc532c1c14876
-  data.tar.gz: bb93bcc96d6651dd39e0bfe25a0c4464db382e5c310f3879160f8c747a468840b2e8cd8f7b60da17ea0e93d411e02f70da2b2be72a7160111595eba614ecfe2d
+  metadata.gz: f8b59ef517681af8a964f29430b8ae253f70afbffa58bc4a261c029c51655a351488b9698a898c9253bf32e4d54c4ccaea01b5bcadcb7cab730561a06e914e53
+  data.tar.gz: 566b094d3df1e8647a72571543c358798427442352fe579954f279b603426c3204d0be0341c4a5b4b903c835439eb7d00ac70ffc9bf2350ec283e4554a3213ed

data/README.md

@@ -113,6 +113,34 @@ 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

@@ -101,6 +101,26 @@ module NameGender
     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
@@ -113,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.7.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, salutation and name check lookups through NameGender.
+  distribution, salutation, name check and age lookups through NameGender.
 email:
 - support@namegender.com
 executables: []