parseapi 0.3.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69e639b49f6986257ea0f5cf3b5424867fd563efd4d6762e06657c0349e2071b
-  data.tar.gz: 7212244b17194211f3a5a400a932df526dc4ff6ce04d7fc28ed94ede12486ebd
+  metadata.gz: 8229ca82d3288ebdae0032fc5d3d8865d12b241f1627b6ccf2409e568eb5501a
+  data.tar.gz: 70929f039ede8fa845145a3c3803c186d1a8dfb8dd2af4b45b6fcf058772cb1f
 SHA512:
-  metadata.gz: 255d9d9ae3fddb1bd3e35ba6fd5d9fb06a74c8d8a603bd24d29bc558f5d0b2587fdb5a60df2cf2bae3be703234febfa72c61c22e508d72b1e5ebc045eef74ab0
-  data.tar.gz: 6438c6a8761ecb4b5cbb77af884ebfb20b2e755d51f52ce1832d553e845322804b6c4184498eb49203c1d78ecdca608cc263a5a9606bc69cf91c9ea388a2c205
+  metadata.gz: 0b22da2a9cec679abc8ed1a8a60dcd2365cdb2776c49c58089df907653fd6971198d317348f72d4a5b8cf8d0c7ae8c8f51db34516aa3817cfe99df4fe830b983
+  data.tar.gz: 79894060499900eb0a2210fd36b260b68bba1b837a537274efe81e4aa0cc1353a4f29e89b19429486242b71993b3eb014c6109bd64a5caf2b4b6a1f21fbda87f

data/README.md

@@ -11,6 +11,39 @@ country = parse.country('US')
 
 Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEAPI_KEY` from the environment.
 
+## API versions
+
+Version 1.0.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
+
+Upgrade the dependency in staging, review the [release notes](https://parseapi.com/docs/releases), and test the application before deploying the same code and dependency version to production. Commit your dependency lockfile so the tested package travels with your deployment. Future major SDK upgrades can select a newer API contract.
+
+Previously published SDKs keep their existing behavior and use the team's default. Requests without `Parse-Version` also use that default, managed in [Dashboard API version](https://parseapi.com/dashboard/versions). Keep it unchanged while older applications depend on it. Rolling back to an SDK without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged.
+
+The package owns its supported API version. For direct HTTP integrations, an explicit `Parse-Version` header selects a supported contract. See [API versions and migration](https://parseapi.com/docs/versioning).
+
+## Weather from a postal code
+
+Start with the postal code, then pass its coordinates to weather. Reuse the client from the example above.
+
+```ruby
+place = parse.postal('28202', country: 'US')
+lat, lon = place.values_at('latitude', 'longitude')
+unless lat.nil? || lon.nil?
+  weather = parse.weather(lat, lon)
+  puts weather
+end
+```
+
+The coordinates represent the postal area. Weather is for that point. Missing coordinates skip the weather lookup. This composition performs two ordinary lookups when coordinates are available, with the retry policy below.
+
+## Supply the context you know
+
+Pass `country` when a postal code or national phone number needs disambiguation. A complete international phone number already carries its country context. For a numeric date such as `03/04/2026`, supply the intended `format`. Defaults resolve what the input establishes. Ambiguous input needs your context.
+
+Results are plain data. Pass a returned code or coordinate to another operation when the task needs it. Check nullable values before composing the next call.
+
+Use `parse.postal('28202', country: 'US', deep: true)` for US ZIP tax references. `deep.tax` names the levy and `deep.tax_rate` is a percentage, so `7.9` means 7.9%. The state, county, city and special components explain that combined rate. An exact address can differ. Country and state lookups provide their own geographic reference rates, which should not be added to the ZIP rate. `nil` means unknown and `0` means known zero. Country `deep.tax_id_format` and `deep.tax_id_regex` describe registration-number format only. Use `vat` for a metered registration check with `deep` explicitly enabled.
+
 ## Calls
 
 One method per endpoint, named after the route.
@@ -21,6 +54,7 @@ parse.ip_self
 parse.email('hello@gmail.com')
 parse.vat('DE136695976')
 parse.iban('DE89370400440532013000')
+parse.bin('424242')
 parse.npi('1881018208')
 parse.phone('+14155552671')
 parse.carrier('+14155552671')
@@ -52,9 +86,12 @@ parse.currency('USD')
 parse.currency_rate('USD', 'EUR')
 parse.language('en')
 parse.name('BILLY OSHALL')
-parse.timezone('America/New_York')
-parse.timezone('America/New_York', at: '2026-09-05T15:00', to: 'Europe/London')
-parse.timezone_at(35.2271, -80.8431)
+parse.name('Andrea', country: 'IT', deep: true)
+parse.name('Robert James Smith', deep: true, name_locale: 'en')
+parse.time # UTC now
+parse.time('America/New_York')
+parse.time('America/New_York', at: '2026-09-05T15:00', to: 'Europe/London')
+parse.time_at(35.2271, -80.8431)
 parse.date('03/04/2026', format: 'mdy')
 parse.date_today(to: '2026-12-25')
 parse.holiday('US', year: 2026)
@@ -67,23 +104,110 @@ parse.domain('example.com')
 parse.asn('AS13335')
 parse.mac('00:1B:63:84:45:E6')
 parse.mx('example.com')
+parse.dns('example.com')
+parse.dns('_dmarc.example.com', type: 'TXT')
 parse.useragent(ua_string)
 parse.vin('1HGCM82633A004352')
+parse.naics('541511')
+parse.naics_search('coffee shop', limit: 5)
 parse.tariff('8471.30.01.00', origin: 'CN', deep: true)
 parse.tariff_search('sunglasses')
 parse.emoji('rocket')
 parse.emoji_search('fire')
 ```
 
+NAICS paid deep records include classification `deep.exclusions`, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include `match`: the matched `field` (`name`, `term` or `naics`) and `text`, plus `corrections` with `from` and `to` tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit `match`. Older responses may omit it.
+
 Each lookup returns a plain hash with string keys. Related lookups are separate calls, such as `country_states('US')`. Reading the result makes no further requests. New response fields and `nil` values are preserved.
 
+DNS uses pooled requests on every plan. Omit `type` to check A, AAAA, CNAME, MX, NS, TXT, SOA, CAA, SRV and PTR. Records contain `name`, `type`, `ttl` in seconds and a DNS presentation `value`. TXT values retain quoting and chunk boundaries. A selected question can include its CNAME chain. Empty records mean no records. Lookup failures remain errors.
+
+Name paid deep includes flat `short`, `directory`, and `initials` fields beside `gender` and `salutation`. `name_locale` selects CLDR formatting rules and defaults to `en`. It changes formatting only. Country remains gender context, and unavailable formatting is null. Older responses may omit these fields.
+
+## Display language
+
+Choose display names for one request:
+
+```ruby
+parse.country('DE', lang: 'fr')
+```
+
+`lang` is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search, and unit discovery. IP, ASN, Company and NPI also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
+
+The next call keeps its usual default unless it also supplies `lang`. Existing `deep` rules still apply. Date `format` and measurement `locale` remain explicit input-parsing controls.
+
+## Time
+
+`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+
+## Measurements
+
+```ruby
+result = parse.measure('5 ft 11 in', to: 'cm')
+units = parse.measure_units(unit: 'm')
+```
+
+`amount` is a decimal string, such as `"180.34"`. Without `to`, the API returns the canonical unit for the measurement type. Pass `locale` for number formatting and `system` (`us` or `imperial`) when a customary unit needs context. Ambiguous input returns `valid: false`, a `reason`, and available `choices`. Invalid or incompatible target units use the normal API error.
+
+Unit discovery accepts optional `query`, `type`, and `unit` filters. `unit` selects compatible targets. Omit the filters for the reviewed catalog. Both operations use pooled requests.
+
+## Place statistics and optional detail
+
+Postal and District paid profiles include `deep.property_tax` where supported. It contains `annual_median`, `currency` and `period`: median annual property tax payable on owner-occupied homes in the statistical area. The amount is adjusted to the final year of the reporting period (`YYYY-YYYY`). This is an area statistic, not a rate or an individual property bill. Unsupported, missing and censored estimates are null.
+
+```ruby
+place = parse.postal('28202', country: 'US', deep: true)
+property_tax = place.dig('deep', 'property_tax')
+```
+
+Read `population_period` alongside `population`: a reporting year (`YYYY`) or period (`YYYY-YYYY`), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. Postal nearby and distance detail remains metropolitan associations only. Continent population stays in core.
+
+Country deep includes `land_area` and `water_area` in km2, `coastline` in km, and mean `elevation` in metres. `lowest_point` and `highest_point` contain a nullable `name` and an `elevation` in metres. Values below sea level are negative. Missing or null values stay unknown, and zero stays zero.
+
+Point returns the timezone ID with the core location. Its optional deep detail adds terrain and compact nearest-city context on every plan. A nearest city is null when none is within 200 km.
+
+Weather returns current conditions by default. Paid deep adds specialist current measurements, forecasts and related detail. A past `date` is a UTC day and requires deep: it adds `deep.history` alongside current conditions. Date alone does not request history.
+
+```ruby
+parse.weather(40.7128, -74.006, deep: true, date: '2026-08-15')
+```
+
+Tariff starts with the general schedule line. Paid deep adds units and the special and other schedule columns. An optional origin then resolves country-specific measures. The three calls below show those successive choices. Without origin, schedule detail is still returned and origin-dependent fields are null. A null effective rate is not a zero rate.
+
+```ruby
+parse.tariff('8471.30.01.00')
+parse.tariff('8471.30.01.00', deep: true)
+parse.tariff('8471.30.01.00', deep: true, origin: 'CN')
+```
+
+Address search uses context from the form: prefer postal, or city and state. An optional end-user `ip` is a locality hint for server-side calls. An empty result explains itself with `reason`: `more_input`, `missing_context` or `no_matches`. With suggestions, reason is null. Older responses may omit it, and future reasons remain strings. Catalog and lookup failures use the existing API errors.
+
+HLR reports status at the last check. `live` means assigned and `connected` means reachable at that check. Cached results may be returned. Null means unconfirmed. Deep diagnostics stay within the same metered lookup.
+
 ## Deep
 
-Pass `deep: true` to include the nested `deep` object with richer fields.
+Choose enrichment for the question you need answered.
+
+| Operation | What `deep` requests |
+|---|---|
+| IP | Richer IP fields included with a paid plan. No separate check meter. |
+| Domain | Registration dates, registrar, status and DNSSEC, included with a paid plan. Use `dns` for DNS records and `mx` for mail routing. |
+| Email | A metered deliverability check, using included email checks or enabled on-demand usage. |
+| VAT | A metered registry check where supported, using included VAT checks or enabled on-demand usage. |
+| Phone, Time, Date, Currency, Language, Emoji, IBAN, Point | Optional detail in the same pooled request on every plan. |
+| Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
+| Name, NAICS | Name evidence or the industry definition profile on paid plans. |
+| VIN, NPI, Tariff, Company | The complete product detail bag on paid plans. |
+| Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
+| Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
+
+Carrier, caller, and HLR are separate metered operations. Choose them explicitly when you need their answers. Ordinary lookups retry twice by default. Metered checks use one attempt by default. Setting retries explicitly can repeat paid usage.
+
+Without `deep`, the response omits that key. When requested, it is an empty object if access is locked or the operation has no deep fields. Otherwise it contains the available fields. A missing or null field means unknown.
 
 ```ruby
 ip = parse.ip('52.94.76.10', deep: true)
-ip['deep']['datacenter'] # true
+ip.dig('deep', 'datacenter') # true, false, or nil
 ```
 
 ## Errors
@@ -124,3 +248,16 @@ Requires Ruby 3.0 or later. Standard library only, zero dependencies.
 ## Docs
 
 Full field reference for every endpoint: [parseapi.com/docs](https://parseapi.com/docs)
+
+BIN lookup accepts 6-11 digits as a string, including leading zeros. Spaces and hyphens are accepted. `prefix` is the actual longest match and can be shorter than the input. Unknown reference fields are null. `deep` adds an empty object on every plan.
+
+
+## Optional detail
+
+The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, NAICS and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep`; only the source has `deep.next_dst`.
+
+```ruby
+basic = parse.time('America/New_York')
+detail = parse.time('America/New_York', deep: true)
+puts basic['at'], detail.dig('deep', 'next_dst')
+```

data/lib/parseapi/client.rb

@@ -18,6 +18,8 @@ module ParseAPI
 	end
 
 	class Client
+		API_VERSION = '2.0.0'.freeze
+		private_constant :API_VERSION
 		DEFAULT_BASE_URL = 'https://api.parseapi.com'.freeze
 		DEFAULT_TIMEOUT = 10
 		DEFAULT_RETRIES = 2
@@ -30,6 +32,7 @@ module ParseAPI
 		].freeze
 
 		def initialize(api_key = nil, base_url: nil, timeout: nil, retries: nil, transport: nil)
+			# You found Dev. https://parseapi.com/dev
 			@api_key = api_key || ENV['PARSEAPI_KEY']
 			raise ArgumentError, 'parseapi: missing API key. Pass one or set PARSEAPI_KEY.' if @api_key.nil? || @api_key.empty?
 
@@ -54,140 +57,173 @@ module ParseAPI
 			"#<#{self.class} api_key=[REDACTED] timeout=#{@timeout} retries=#{@retries.nil? ? 'auto' : @retries}>"
 		end
 
-		# --- Lookup methods (one per endpoint, named after the route) ---
 
-		def ip(ip, deep: false)
-			get("/ip/#{seg(ip)}", deep: deep)
+		# Look up an IP. Deep enrichment is included with a paid plan, without a separate check meter.
+		def ip(ip, deep: false, lang: nil)
+			get("/ip/#{seg(ip)}", deep: deep, lang: lang)
 		end
 
-		def ip_self(deep: false)
-			get('/ip', deep: deep)
+		# Look up the public IP making this request. On a server, this is the server's IP.
+		def ip_self(deep: false, lang: nil)
+			get('/ip', deep: deep, lang: lang)
 		end
 
-		def continent(code)
-			get("/continent/#{seg(code)}")
+		def continent(code, lang: nil)
+			get("/continent/#{seg(code)}", lang: lang)
 		end
 
-		def continent_countries(code)
-			get("/continent/#{seg(code)}/countries")
+		def continent_countries(code, lang: nil)
+			get("/continent/#{seg(code)}/countries", lang: lang)
 		end
 
 		def bloc(code)
 			get("/bloc/#{seg(code)}")
 		end
 
-		def bloc_countries(code)
-			get("/bloc/#{seg(code)}/countries")
+		def bloc_countries(code, lang: nil)
+			get("/bloc/#{seg(code)}/countries", lang: lang)
 		end
 
-		def country(code)
-			get("/country/#{seg(code)}")
+		def country(code, deep: false, lang: nil)
+			get("/country/#{seg(code)}", deep: deep, lang: lang)
 		end
 
-		def country_states(code)
-			get("/country/#{seg(code)}/states")
+		def country_states(code, lang: nil)
+			get("/country/#{seg(code)}/states", lang: lang)
 		end
 
-		def state(code, country: nil)
-			get("/state/#{seg(code)}", country: country)
+		def state(code, country: nil, deep: false, lang: nil)
+			get("/state/#{seg(code)}", country: country, deep: deep, lang: lang)
 		end
 
-		def state_districts(code, country: nil)
-			get("/state/#{seg(code)}/districts", country: country)
+		def state_districts(code, country: nil, deep: false, lang: nil)
+			get("/state/#{seg(code)}/districts", country: country, deep: deep, lang: lang)
 		end
 
-		def district(code, country: nil, state: nil)
-			get("/district/#{seg(code)}", country: country, state: state)
+		def district(code, country: nil, state: nil, deep: false, lang: nil)
+			get("/district/#{seg(code)}", country: country, state: state, deep: deep, lang: lang)
 		end
 
-		def city(name, country: nil, state: nil)
-			get("/city/#{seg(name)}", country: country, state: state)
+		def city(name, country: nil, state: nil, deep: false, lang: nil)
+			get("/city/#{seg(name)}", country: country, state: state, deep: deep, lang: lang)
 		end
 
-		def city_id(id)
-			get("/city/id/#{seg(id)}")
+		def city_id(id, deep: false, lang: nil)
+			get("/city/id/#{seg(id)}", deep: deep, lang: lang)
 		end
 
-		def city_search(query, country: nil, state: nil, limit: nil)
-			get('/city', q: query, country: country, state: state, limit: limit)
+		def city_search(query, country: nil, state: nil, limit: nil, deep: false, lang: nil)
+			get('/city', q: query, country: country, state: state, limit: limit, deep: deep, lang: lang)
 		end
 
-		def city_nearest(lat, lon)
-			get('/city', lat: lat, lon: lon)
+		def city_nearest(lat, lon, deep: false, lang: nil)
+			get('/city', lat: lat, lon: lon, deep: deep, lang: lang)
 		end
 
-		def city_nearby(name, radius: nil, unit: nil, country: nil, state: nil, limit: nil)
-			get("/city/#{seg(name)}/nearby", radius: radius, unit: unit, country: country, state: state, limit: limit)
+		def city_nearby(name, radius: nil, unit: nil, country: nil, state: nil, limit: nil, deep: false, lang: nil)
+			get("/city/#{seg(name)}/nearby", radius: radius, unit: unit, country: country, state: state, limit: limit, deep: deep, lang: lang)
 		end
 
-		def postal(code, country: nil)
-			get("/postal/#{seg(code)}", country: country)
+		# Look up a postal area. Pass country when known. Check nullable coordinates before another
+		# location lookup.
+		def postal(code, country: nil, deep: false, lang: nil)
+			get("/postal/#{seg(code)}", country: country, deep: deep, lang: lang)
 		end
 
-		def postal_nearby(code, country: nil, radius: nil, unit: nil)
-			get("/postal/#{seg(code)}/nearby", country: country, radius: radius, unit: unit)
+		def postal_nearby(code, country: nil, radius: nil, unit: nil, deep: false, lang: nil)
+			get("/postal/#{seg(code)}/nearby", country: country, radius: radius, unit: unit, deep: deep, lang: lang)
 		end
 
-		def postal_distance(from, to, country: nil)
-			get("/postal/#{seg(from)}/distance/#{seg(to)}", country: country)
+		def postal_distance(from, to, country: nil, deep: false, lang: nil)
+			get("/postal/#{seg(from)}/distance/#{seg(to)}", country: country, deep: deep, lang: lang)
 		end
 
 		def address(address, country: nil, deep: false)
 			get("/address/#{seg(address)}", country: country, deep: deep)
 		end
 
+		# Find address suggestions using the context supplied. Prefer postal, or city and state, from
+		# the form; ip is an optional end-user locality hint for server-side calls. An empty result has
+		# reason more_input, missing_context or no_matches. Suggestions have reason null. Operational
+		# failures are errors.
 		def address_search(query, country: nil, postal: nil, city: nil, state: nil, ip: nil)
 			get('/address', q: query, country: country, postal: postal, city: city, state: state, ip: ip)
 		end
 
-		def company(number, country: nil, deep: false)
-			get("/company/#{seg(number)}", country: country, deep: deep)
+		def company(number, country: nil, deep: false, lang: nil)
+			get("/company/#{seg(number)}", country: country, deep: deep, lang: lang)
 		end
 
+		# Parse an email and check its format and domain. Deep explicitly requests a metered
+		# deliverability check. Deep checks use one attempt by default. An explicit retry count can
+		# repeat paid usage.
 		def email(email, deep: false)
 			get("/email/#{seg(email)}", deep: deep)
 		end
 
+		# Check VAT format and checksum. Deep requests a metered registry check where supported. Deep
+		# checks use one attempt by default. Supply your own VAT number for a consultation reference
+		# when supported.
 		def vat(number, country: nil, deep: false, from: nil)
 			get("/vat/#{seg(number)}", country: country, deep: deep, from: from)
 		end
 
-		def iban(iban, country: nil)
-			get("/iban/#{seg(iban)}", country: country)
+		def iban(iban, country: nil, deep: false)
+			get("/iban/#{seg(iban)}", country: country, deep: deep)
 		end
 
-		def npi(npi, deep: false)
-			get("/npi/#{seg(npi)}", deep: deep)
+		# Look up a 6-11 digit card prefix, preserving leading zeros.
+		def bin(bin, deep: false)
+			get("/bin/#{seg(bin)}", deep: deep)
 		end
 
+
+		def npi(npi, deep: false, lang: nil)
+			get("/npi/#{seg(npi)}", deep: deep, lang: lang)
+		end
+
+		# Parse a phone number and its formats. Pass country for national numbers when needed. Deep
+		# adds numbering-plan geography on every plan. Carrier, caller, and HLR are separate metered lookups.
 		def phone(number, country: nil, deep: false)
 			get("/phone/#{seg(number)}", country: country, deep: deep)
 		end
 
-		def carrier(number, country: nil)
-			get("/carrier/#{seg(number)}", country: country)
+		# Request a metered carrier lookup. No automatic retries by default.
+		def carrier(number, country: nil, deep: false)
+			get("/carrier/#{seg(number)}", country: country, deep: deep)
 		end
 
+		# Request a metered caller-name lookup for a NANP number. No automatic retries by default.
 		def caller(number, country: nil)
 			get("/caller/#{seg(number)}", country: country)
 		end
 
-		def hlr(number, country: nil)
-			get("/hlr/#{seg(number)}", country: country)
+		# Look up phone status at the last check. Live means assigned and connected means reachable at
+		# that check. Cached results may be returned. Null means unconfirmed. Deep adds network
+		# diagnostics within the same metered lookup. No automatic retries by default.
+		def hlr(number, country: nil, deep: false)
+			get("/hlr/#{seg(number)}", country: country, deep: deep)
 		end
 
+		# Check whether a domain is registered. Deep adds registration dates, registrar, status and DNSSEC on paid plans.
 		def domain(domain, deep: false)
 			get("/domain/#{seg(domain)}", deep: deep)
 		end
 
-		def asn(asn)
-			get("/asn/#{seg(asn)}")
+		def asn(asn, lang: nil)
+			get("/asn/#{seg(asn)}", lang: lang)
 		end
 
 		def mac(mac)
 			get("/mac/#{seg(mac)}")
 		end
 
+		# Published DNS records with TTLs. Omit type to check all supported types.
+		# Type selects the question, including its CNAME chain. Pooled on every plan.
+		def dns(domain, type: nil)
+			get("/dns/#{seg(domain)}", type: type)
+		end
+
 		def mx(domain)
 			get("/mx/#{seg(domain)}")
 		end
@@ -200,6 +236,20 @@ module ParseAPI
 			get("/vin/#{seg(vin)}", deep: deep)
 		end
 
+		# US NAICS 2022 definition and hierarchy.
+		def naics(code, deep: false)
+			get("/naics/#{seg(code)}", deep: deep)
+		end
+
+		# Keyword search. Limit defaults to 10 and accepts 1-50.
+		def naics_search(query, limit: nil, deep: false)
+			get('/naics', q: query, limit: limit, deep: deep)
+		end
+
+		# Look up the general US duty schedule line. Paid deep adds units and the special and other
+		# schedule columns. Add origin with deep to resolve country-specific measures. Without origin,
+		# schedule detail remains available and origin-dependent fields are null. A null effective rate
+		# is not a zero rate.
 		def tariff(code, deep: false, origin: nil)
 			get("/tariff/#{seg(code)}", deep: deep, origin: origin)
 		end
@@ -208,36 +258,46 @@ module ParseAPI
 			get('/tariff', q: query)
 		end
 
-		def currency(code)
-			get("/currency/#{seg(code)}")
+		def currency(code, deep: false, lang: nil)
+			get("/currency/#{seg(code)}", deep: deep, lang: lang)
 		end
 
 		def currency_rate(base, quote, date: nil, amount: nil)
 			get("/currency/#{seg(base)}/#{seg(quote)}", date: date, amount: amount)
 		end
 
-		def language(code)
-			get("/language/#{seg(code)}")
+		def language(code, deep: false, lang: nil)
+			get("/language/#{seg(code)}", deep: deep, lang: lang)
 		end
 
-		def name(name)
-			get("/name/#{seg(name)}")
+		# Name locale selects CLDR formatting, default en, without changing parsing or gender context.
+		def name(name, country: nil, deep: false, name_locale: nil)
+			get("/name/#{seg(name)}", country: country, deep: deep, name_locale: name_locale)
 		end
 
-		def timezone(id, at: nil, to: nil)
-			get("/timezone/#{seg(id)}", at: at, to: to)
+		# Current local time, UTC by default. With to, offsetless at is source wall time.
+		def time(timezone = nil, at: nil, to: nil, deep: false, lang: nil)
+			get(timezone.nil? ? '/time' : "/time/#{seg(timezone)}", at: at, to: to, deep: deep, lang: lang)
 		end
 
-		def timezone_at(lat, lon, at: nil)
-			get('/timezone', lat: lat, lon: lon, at: at)
+		def time_at(lat, lon, at: nil, to: nil, deep: false, lang: nil)
+			get('/time', lat: lat, lon: lon, at: at, to: to, deep: deep, lang: lang)
 		end
 
-		def date(date, format: nil, to: nil)
-			get("/date/#{seg(date)}", format: format, to: to)
+		def timezone(id, at: nil, to: nil, deep: false, lang: nil)
+			get("/timezone/#{seg(id)}", at: at, to: to, deep: deep, lang: lang)
 		end
 
-		def date_today(to: nil)
-			get('/date', to: to)
+		def timezone_at(lat, lon, at: nil, deep: false, lang: nil)
+			get('/timezone', lat: lat, lon: lon, at: at, deep: deep, lang: lang)
+		end
+
+		def date(date, format: nil, to: nil, deep: false, lang: nil)
+			get("/date/#{seg(date)}", format: format, to: to, deep: deep, lang: lang)
+		end
+
+		def date_today(to: nil, deep: false, lang: nil)
+			get('/date', to: to, deep: deep, lang: lang)
 		end
 
 		def holiday(country, year: nil)
@@ -252,20 +312,37 @@ module ParseAPI
 			get('/elevation', lat: lat, lon: lon)
 		end
 
-		def point(lat, lon, deep: false)
-			get('/point', lat: lat, lon: lon, deep: deep)
+		# Resolve the country, state, district and timezone at coordinates. Deep adds terrain and
+		# compact nearest-city context on every plan. The timezone ID stays in core. The nearest city is
+		# null when none is within 200 km.
+		def point(lat, lon, deep: false, lang: nil)
+			get('/point', lat: lat, lon: lon, deep: deep, lang: lang)
 		end
 
+		# Get current conditions in metric and imperial units. Paid deep adds specialist current
+		# measurements, forecasts and related detail. With deep, date selects a past UTC day (YYYY-MM-
+		# DD) in deep.history alongside current conditions. Date alone does not request history.
 		def weather(lat, lon, deep: false, date: nil)
 			get('/weather', lat: lat, lon: lon, deep: deep, date: date)
 		end
 
-		def emoji(emoji)
-			get("/emoji/#{seg(emoji)}")
+		def emoji(emoji, deep: false, lang: nil)
+			get("/emoji/#{seg(emoji)}", deep: deep, lang: lang)
+		end
+
+		def emoji_search(query, limit: nil, deep: false, lang: nil)
+			get('/emoji', q: query, limit: limit, deep: deep, lang: lang)
+		end
+
+		# Parse or convert a measurement. Amount is a decimal string. Without to, use the
+		# type's canonical unit. Locale and system (us or imperial) resolve explicit ambiguity.
+		def measure(measure, to: nil, locale: nil, system: nil)
+			get("/measure/#{seg(measure)}", to: to, locale: locale, system: system)
 		end
 
-		def emoji_search(query, limit: nil)
-			get('/emoji', q: query, limit: limit)
+		# Discover reviewed units. unit filters compatible conversion targets.
+		def measure_units(query: nil, type: nil, unit: nil, lang: nil)
+			get('/measure/units', q: query, type: type, unit: unit, lang: lang)
 		end
 
 		private
@@ -306,7 +383,7 @@ module ParseAPI
 		end
 
 		def request_headers(extra)
-			{ 'X-API-Key' => @api_key, 'User-Agent' => "parseapi-ruby/#{VERSION}" }.merge(extra)
+			{ 'X-API-Key' => @api_key, 'User-Agent' => "parseapi-ruby/#{VERSION}" }.merge(extra).merge('Parse-Version' => API_VERSION)
 		end
 
 		# Returns [status, headers_hash, body_string]. Overridden in tests.

data/lib/parseapi/version.rb

@@ -1,3 +1,3 @@
 module ParseAPI
-	VERSION = '0.3.2'.freeze
+	VERSION = '1.0.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parseapi
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 1.0.0
 platform: ruby
 authors:
 - ParseAPI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies: []
 description:
 email: