demografix 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68a9654603c29db7c24af02f7daf2716a3159060dd596a11b300b83abe093d17
-  data.tar.gz: 42f4a7f8d7c1cef1ebbfdc0990660d7a96b67fc5861744bb017880553e4ac080
+  metadata.gz: e32fcb1768c53fe52e90ada47fe4d769670981532f6aea61084c5db7ec5fd636
+  data.tar.gz: 305dbff3f2b864435f09c6ade2bdf89f48e9140b5954aad39f6af4c9fe4293ad
 SHA512:
-  metadata.gz: 0c71e2fe5ea63acff9cc98c82061bf727bff9b4795252a31718698002cfa81fdc5628594a9efcf6af2fb8aa837e5c766ae7803fb2448c432006518536f68848c
-  data.tar.gz: 26415804ba554e64613ee930464a07a04c5e389b728582d39b7b2dda8de73496911b4f500f30f35c2a69030c56fbc8c227559312eb8abf8588ca2363c3dd5079
+  metadata.gz: d9adc3c9710b7c42c12c235048b8c10cf6ff1c3e073beee61019d251f415f9e68ef7c95b2f9c467c5956a083fe99eb0a49dd06e05997d3d23b0c633bedf59446
+  data.tar.gz: 6d2f866f2052e62e96d6e58e7bf58856a879159a8539c85181d8660ffab749805a12f8dc7e176a9d75c220cda9d2f86184a6ba7a54efcd7ef95c2ed5c08f7837

data/README.md

@@ -1,7 +1,13 @@
 # demografix (Ruby)
 
-Run demographic analysis over names — predicted gender, age, and nationality — from one Ruby client. The
-gem covers genderize.io, agify.io, and nationalize.io.
+Predict gender, age, and nationality from names. One Ruby client covers all three Demografix
+APIs — [genderize.io](https://genderize.io) (gender), [agify.io](https://agify.io) (age), and
+[nationalize.io](https://nationalize.io) (nationality) — with single-name lookups and batches of up
+to 100 names per request.
+
+[![Gem Version](https://img.shields.io/gem/v/demografix)](https://rubygems.org/gems/demografix)
+[![CI](https://github.com/DemografixGenderize/demografix-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/DemografixGenderize/demografix-ruby/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 ## Install
 
@@ -17,12 +23,8 @@ Then run `bundle install`. To install directly:
 gem install demografix
 ```
 
-The client uses the Ruby standard library (`net/http` and `json`) and has no runtime dependencies. It requires Ruby 3.2 or later.
-
-## Authentication
-
-An API key is required. Creating one is free and includes 2,500 requests per month. Generate a key in your
-dashboard at genderize.io, agify.io, or nationalize.io. One key works across all three services.
+The client uses the Ruby standard library (`net/http` and `json`) and has no runtime dependencies. It
+requires Ruby 3.2 or later.
 
 ## Quickstart
 
@@ -44,12 +46,13 @@ average_age = known.sum.to_f / known.length
 ages.quota.remaining # => 24987
 ```
 
-Each call returns prediction fields plus a `quota`. Batch calls return `results` (one prediction per input
-name, in input order) plus one `quota` for the response. Aggregate the results into a distribution.
+Each call returns prediction fields plus a `quota`. Batch calls return `results` (one prediction per
+input name, in input order) plus one `quota` for the response. Aggregate the results into a
+distribution.
 
 ## genderize
 
-Predict gender from a name.
+Predict gender from names.
 
 ```ruby
 result = client.genderize("peter")
@@ -68,12 +71,12 @@ end
 # => { "male" => 2, "female" => 2 }
 ```
 
-`gender` is `"male"`, `"female"`, or `nil`. A name with no match returns `nil` gender, `0.0` probability,
-and `0` count. That is a successful response, not an error.
+`gender` is `"male"`, `"female"`, or `nil`. A name with no match returns `nil` gender, `0.0`
+probability, and `0` count. That is a successful response, not an error.
 
 ## agify
 
-Predict age from a name.
+Predict age from names.
 
 ```ruby
 result = client.agify("michael")
@@ -94,7 +97,7 @@ buckets = ages.group_by { |age| (age / 10) * 10 }
 
 ## nationalize
 
-Predict nationality from a name.
+Predict nationality from names.
 
 ```ruby
 result = client.nationalize("nguyen")
@@ -113,24 +116,45 @@ end
 # => { "VN" => 1, "DE" => 1, "IT" => 1 }
 ```
 
-`country` holds up to five candidates in descending probability order. A name with no match returns an empty
-`country` array.
+`country` holds up to five candidates in descending probability order. A name with no match returns
+an empty `country` array.
+
+## Batch limit
+
+Each batch accepts at most 100 names. A batch of more than 100 raises `ValidationError` before any
+HTTP call is made. Chunk a longer list and aggregate across the chunks.
+
+```ruby
+split = roster.each_slice(100).each_with_object(Hash.new(0)) do |chunk, counts|
+  client.genderize_batch(chunk).results.each do |pred|
+    counts[pred.gender || "unknown"] += 1
+  end
+end
+```
 
 ## country_id
 
-`genderize` and `agify` accept an optional `country_id` (ISO 3166-1 alpha-2) to scope the prediction to a
-country. `nationalize` does not accept it.
+`genderize` and `agify` accept an optional `country_id` (ISO 3166-1 alpha-2) to scope the prediction
+to a country. `nationalize` does not accept it. The value is echoed back uppercase in `country_id` on
+every prediction.
 
 ```ruby
 result = client.genderize("kim", country_id: "US")
 result.country_id # => "US"
 result.gender     # => "female"
 
-client.agify_batch(%w[andrea andrea], country_id: "IT")
+client.agify_batch(%w[andrea giulia], country_id: "IT")
 ```
 
-The value is echoed back uppercase in `country_id` on each prediction. When the request sends no
-`country_id`, the field is `nil`.
+Scoping changes the prediction: `andrea` reads female with probability 0.99 in the United States and
+male with probability 0.79 in Italy.
+
+```ruby
+client.genderize("andrea", country_id: "US").gender # => "female"
+client.genderize("andrea", country_id: "IT").gender # => "male"
+```
+
+When the request sends no `country_id`, the field is `nil`.
 
 ## Quota
 
@@ -153,20 +177,18 @@ Read quota off the returned value or a raised error. The client does not cache i
 
 ## Errors
 
-Every error subclasses `Demografix::Error` and carries `status`, `message`, and `quota` (when the response
-included rate-limit headers).
+Every error subclasses `Demografix::Error` and carries `status`, `message`, and `quota` (when the
+response included rate-limit headers).
 
 | Error | Raised on |
 |---|---|
 | `Demografix::AuthError` | 401, invalid or missing API key |
 | `Demografix::SubscriptionError` | 402, subscription not active |
-| `Demografix::ValidationError` | 422, invalid parameters; also client-side for a batch over 10 names |
+| `Demografix::ValidationError` | 422, invalid parameters; also client-side for a batch over 100 names |
 | `Demografix::RateLimitError` | 429, request limit reached (quota always populated) |
 | `Demografix::TransportError` | network failure, timeout, or non-JSON body |
 | `Demografix::Error` | any other non-2xx status |
 
-A batch of more than 10 names raises `ValidationError` before any HTTP call is made.
-
 On a `RateLimitError`, read `quota.reset` for the seconds to wait before retrying:
 
 ```ruby
@@ -189,7 +211,21 @@ end
 | `nationalize(name)` | `NationalizeResult` | no |
 | `nationalize_batch(names)` | `Batch` of `NationalizePrediction` | no |
 
-`Demografix::Client.new` requires `api_key:` and accepts `timeout:` (optional, default 10 seconds). The
-host URLs and the User-Agent are fixed constants, not options.
+`Demografix::Client.new` requires `api_key:` and accepts `timeout:` (optional, default 10 seconds).
+The host URLs and the User-Agent are fixed constants, not options.
+
+## API keys
+
+An API key is required. Creating one is free and includes 2,500 names per month.
+
+Quota counts **names, not requests**. A single-name call costs 1. A batch of 100 names costs 100. The
+free tier therefore covers 2,500 names in a month however they are split across calls.
+
+Generate a key in your dashboard at [genderize.io](https://genderize.io),
+[agify.io](https://agify.io), or [nationalize.io](https://nationalize.io). One key works across all
+three services. Full reference:
+[genderize.io/documentation/api](https://genderize.io/documentation/api).
+
+## License
 
-Full API reference: https://genderize.io/documentation/api
+MIT. See [LICENSE](LICENSE).

data/lib/demografix/client.rb

@@ -18,7 +18,7 @@ module Demografix
 
     USER_AGENT = "demografix-ruby/#{VERSION}"
 
-    MAX_BATCH = 10
+    MAX_BATCH = 100
     DEFAULT_TIMEOUT = 10
 
     # @param api_key [String] required. The same key works across all three

data/lib/demografix/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Demografix
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: demografix
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Demografix
@@ -51,8 +51,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.18'
-description: One client for the three Demografix APIs — gender, age, and nationality
-  prediction from names — reporting the remaining quota carried on every response.
+description: 'One client for the three Demografix APIs: gender, age, and nationality
+  prediction from a name. Look up a single name or send a batch of up to 100 names
+  in one request for bulk demographic analysis, optionally scoped to a country, and
+  read the remaining quota carried on every response.'
 email:
 - info@genderize.io
 executables: []
@@ -90,5 +92,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Official Ruby client for the genderize, agify, and nationalize APIs.
+summary: Predict gender, age, and nationality from names — the official Ruby client
+  for genderize.io, agify.io, and nationalize.io.
 test_files: []