parseapi 0.4.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fae571978d7957f72ae69536a6d4c72e80ba58e7228acb0089e1344e54b8a0cf
-  data.tar.gz: 41bd5c285c7ec8c138f00d37a1378d61ece08374cc0df6a933ba41c9f457db11
+  metadata.gz: eea5dc559df5f4a2007ef9aedf6a4347ca9090258401a3ffc1e55111dce93dbd
+  data.tar.gz: 9c4594ac80967acf22f4e1d8f7b98072eee25e9729f2979632cc2307eeed755a
 SHA512:
-  metadata.gz: 394f8262c936d35b38f9947b8a41818bcc29bdb99fb3dfb348830c021f5e3be92ab9556b74262917598ef028d608be498c150f8574c2f8a266f6281d09d1240d
-  data.tar.gz: 01d9c5a27c4a415f061ce707992a5b277fe522e6b0fb01eda56aa6910d728908dc4f3cfa209cad20f30c174714c5619acac38202f6022a13793d210921cab2f1
+  metadata.gz: 3a950380627ddd9a7d98f47fde1405801a404144c75b01c1b3b15c696cb3e57f82dedf330984de6e05aaef646d6c030f1e9b54ec838cf8a053c4b134f6c7cdb2
+  data.tar.gz: e3f27a65ea6b8aed25a7f6a77d99fee5bef2d682ee883102983a31f1a192181be90d68a4cb4f602f1a3e5a1889ea9c97ac85319f7dfa2f8614297fd11c73b08a

data/README.md

@@ -13,11 +13,13 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Choose your team's API version in [Dashboard → API version](https://parseapi.com/dashboard/versions). One setting applies to every key, including new and replacement keys. Existing teams keep `1.0.0`; new teams start on `2.0.0`. Keep the same keys and lookup URLs. Installing or upgrading the package does not change the team's setting.
+Version 1.1.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.
 
-Published SDK `0.3.2` matches API `1.0.0`. The examples and response types in this source tree target API `2.0.0`, including changes that are not in `0.3.2`. Use a package release documented for your team's version. These types do not model every historical response; moving to `2.0.0` may require updating code that reads renamed, moved or removed fields.
+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.
 
-Test the target contract in a separate development team before changing your production team's version. A change applies to every integration in that team. See [API versions and migration](https://parseapi.com/docs/versioning).
+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
 
@@ -85,6 +87,7 @@ parse.currency_rate('USD', 'EUR')
 parse.language('en')
 parse.name('BILLY OSHALL')
 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')
@@ -119,6 +122,20 @@ Each lookup returns a plain hash with string keys. Related lookups are separate
 
 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.
@@ -143,7 +160,9 @@ 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 and its period remain in core.
+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.
 
@@ -173,7 +192,7 @@ Choose enrichment for the question you need answered.
 |---|---|
 | 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. |
+| Email | A metered mailbox check with deliverability, catch-all, status, reason and address hints, 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. |
@@ -182,6 +201,10 @@ Choose enrichment for the question you need answered.
 | 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. |
 
+Email deep includes mailbox status and the reason for the result, plus a suggested first name, no-reply flag, plus-address tag and mail service. The suggested name is not a verified identity. Unavailable details are null.
+
+Reasons include `accepted`, `invalid_format`, `invalid_domain`, `no_mail_server`, `mailbox_not_found`, `mailbox_disabled`, `mailbox_full`, `catchall`, `disposable`, `temporary_failure`, `rejected` and `unconfirmed`.
+
 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.

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
@@ -57,83 +59,83 @@ module ParseAPI
 
 
 		# Look up an IP. Deep enrichment is included with a paid plan, without a separate check meter.
-		def ip(ip, deep: false)
-			get("/ip/#{seg(ip)}", deep: deep)
+		def ip(ip, deep: false, lang: nil)
+			get("/ip/#{seg(ip)}", deep: deep, lang: lang)
 		end
 
 		# Look up the public IP making this request. On a server, this is the server's IP.
-		def ip_self(deep: false)
-			get('/ip', deep: deep)
+		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, deep: false)
-			get("/country/#{seg(code)}", deep: deep)
+		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, deep: false)
-			get("/state/#{seg(code)}", country: country, deep: deep)
+		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, deep: false)
-			get("/state/#{seg(code)}/districts", country: country, deep: deep)
+		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, deep: false)
-			get("/district/#{seg(code)}", country: country, state: state, deep: deep)
+		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, deep: false)
-			get("/city/#{seg(name)}", country: country, state: state, deep: deep)
+		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, deep: false)
-			get("/city/id/#{seg(id)}", deep: deep)
+		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, deep: false)
-			get('/city', q: query, country: country, state: state, limit: limit, deep: deep)
+		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, deep: false)
-			get('/city', lat: lat, lon: lon, deep: deep)
+		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, deep: false)
-			get("/city/#{seg(name)}/nearby", radius: radius, unit: unit, country: country, state: state, limit: limit, deep: deep)
+		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
 
 		# Look up a postal area. Pass country when known. Check nullable coordinates before another
 		# location lookup.
-		def postal(code, country: nil, deep: false)
-			get("/postal/#{seg(code)}", country: country, deep: deep)
+		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, deep: false)
-			get("/postal/#{seg(code)}/nearby", country: country, radius: radius, unit: unit, deep: deep)
+		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, deep: false)
-			get("/postal/#{seg(from)}/distance/#{seg(to)}", country: country, deep: deep)
+		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)
@@ -148,8 +150,8 @@ module ParseAPI
 			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
@@ -176,8 +178,8 @@ module ParseAPI
 		end
 
 
-		def npi(npi, deep: false)
-			get("/npi/#{seg(npi)}", deep: deep)
+		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
@@ -208,8 +210,8 @@ module ParseAPI
 			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)
@@ -256,45 +258,46 @@ module ParseAPI
 			get('/tariff', q: query)
 		end
 
-		def currency(code, deep: false)
-			get("/currency/#{seg(code)}", deep: deep)
+		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, deep: false)
-			get("/language/#{seg(code)}", deep: deep)
+		def language(code, deep: false, lang: nil)
+			get("/language/#{seg(code)}", deep: deep, lang: lang)
 		end
 
-		def name(name, country: nil, deep: false)
-			get("/name/#{seg(name)}", country: country, deep: deep)
+		# 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
 
 		# Current local time, UTC by default. With to, offsetless at is source wall time.
-		def time(timezone = nil, at: nil, to: nil, deep: false)
-			get(timezone.nil? ? '/time' : "/time/#{seg(timezone)}", at: at, to: to, deep: deep)
+		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 time_at(lat, lon, at: nil, to: nil, deep: false)
-			get('/time', lat: lat, lon: lon, at: at, to: to, deep: deep)
+		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 timezone(id, at: nil, to: nil, deep: false)
-			get("/timezone/#{seg(id)}", at: at, to: to, deep: deep)
+		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 timezone_at(lat, lon, at: nil, deep: false)
-			get('/timezone', lat: lat, lon: lon, at: at, deep: deep)
+		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)
-			get("/date/#{seg(date)}", format: format, to: to, deep: deep)
+		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)
-			get('/date', to: to, deep: deep)
+		def date_today(to: nil, deep: false, lang: nil)
+			get('/date', to: to, deep: deep, lang: lang)
 		end
 
 		def holiday(country, year: nil)
@@ -312,8 +315,8 @@ module ParseAPI
 		# 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)
-			get('/point', lat: lat, lon: lon, deep: deep)
+		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
@@ -323,12 +326,12 @@ module ParseAPI
 			get('/weather', lat: lat, lon: lon, deep: deep, date: date)
 		end
 
-		def emoji(emoji, deep: false)
-			get("/emoji/#{seg(emoji)}", deep: deep)
+		def emoji(emoji, deep: false, lang: nil)
+			get("/emoji/#{seg(emoji)}", deep: deep, lang: lang)
 		end
 
-		def emoji_search(query, limit: nil, deep: false)
-			get('/emoji', q: query, limit: limit, deep: deep)
+		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
@@ -338,8 +341,8 @@ module ParseAPI
 		end
 
 		# Discover reviewed units. unit filters compatible conversion targets.
-		def measure_units(query: nil, type: nil, unit: nil)
-			get('/measure/units', q: query, type: type, unit: unit)
+		def measure_units(query: nil, type: nil, unit: nil, lang: nil)
+			get('/measure/units', q: query, type: type, unit: unit, lang: lang)
 		end
 
 		private
@@ -380,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.4.0'.freeze
+	VERSION = '1.1.0'.freeze
 end

metadata

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