parseapi 1.9.2 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9305f04eec9c9f1ed484906fb69244df03127edae6b7466c023e5855631ec6dd
-  data.tar.gz: 2adccd9a7bfc7a456b7f0b4b5bab86f3d8b30bb4fa744b2c510a14933b99b4bf
+  metadata.gz: 668ab627de5bf1a6b476e54841045fe6e3110d1ccd91e861380ea21d5103be40
+  data.tar.gz: a9cf7d1cc8d1b28baa3a62f29355deff8cda22eb1ee27a95b328f78dc2efe646
 SHA512:
-  metadata.gz: 4f71799f8c0304a0281fd4b3e50c08d66e4123243515eb85d0077acedbd420bb753ac5a67040e73382005d88cb8f7fd891cc495af7c958c553b8206399e8bf7f
-  data.tar.gz: 98f12a7c2d8ef6886cd78587a9a2578c1858aa85bf33e1be6d2ba407d2185f705a0e385b1d6c1da010246b2750c9614850a8f9d7c3a1d580290aa47d8f396a4b
+  metadata.gz: 58883fd322a90aba10e64f12299b785313105d589f02cb627b5c41cb3870b8feedc80c9efefb061b8dc7779cbc34d4c941813ff49ad0e135f58ef10a5842dd5e
+  data.tar.gz: 81b76b6ffd9b1e35f320f59a553564671f74fb0275364503b77bce581ac8b07651e91a9d30fc4f0d22a9cfc4181d48616585dbee6597d6d0a6978c79973270f5

data/README.md

@@ -243,7 +243,7 @@ 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.
+Read `population` as the source’s count for that place boundary. Keep missing or null values unknown and preserve a known zero. State district lists include each district’s population. 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.
 
@@ -257,7 +257,7 @@ 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.
 
-Tariff lookup and search accept an optional `edition` fingerprint and `date` (`YYYY-MM-DD`). The edition pins exact immutable source bytes. A date is accepted only when verified source coverage exists. An edition without a date returns undated schedule context (`date: null`). Default requests use today. Paid detail exposes an open-string `reason` when `effective_rate` is null, including `incomplete_coverage`. A null rate never means zero. Explicit selections fail with `tariff_selection_mismatch` if an older server ignores the requested scope.
+Tariff lookup and search accept the `edition` ID returned by Tariff, such as `ted_3`, and an optional `date` (`YYYY-MM-DD`). The edition pins exact immutable source bytes. A date is accepted only when verified source coverage exists. An edition without a date returns undated schedule context (`date: null`). Default requests use today. Paid detail exposes an open-string `reason` when `effective_rate` is null, including `incomplete_coverage`. A null rate never means zero. Explicit selections fail with `tariff_selection_mismatch` if an older server ignores the requested scope.
 
 Origin means where the goods originate, not where they ship from. The effective rate covers matched stored schedule measures only. It is not complete duty or landed cost.
 
@@ -297,7 +297,7 @@ Invalid input returns `valid: false` with unknown provider fields. A checksum-va
 
 The default pooled lookup includes provider identity, specialty and practice contact where held. Paid `deep` adds `deactivated_at`, `medicare`, `opt_out` and `enrollments` from stored source files, with no separate check meter or live verification. `enrollments: null` means unavailable; `[]` means no enrollment rows are returned. The API omits unrequested `deep` and returns `{}` when requested on Free.
 
-Paid Deep also returns `taxonomies` in published order, with taxonomy code, specialty label, primary flag and provider-reported license number/state, plus `enumerated_at`, `updated_at` and `reactivated_at` record dates. Reported licenses are not verified licenses. Null lists mean unavailable; empty lists mean the edition contains no entries. Core `sources` is available on every plan: NPPES, LEIE, PECOS and opt-out each have nullable edition metadata (`edition`, `published_at`, `through`, `imported_at`). Provider record dates are separate from source publication and completed import dates. Older responses may omit these additions. Edition details remain null until a verified source is served.
+Paid Deep also returns `taxonomies` in published order, with taxonomy code, specialty label, primary flag and provider-reported license number/state, plus `enumerated_at`, `updated_at` and `reactivated_at` record dates. Reported licenses are not verified licenses. Null lists mean unavailable; empty lists mean the edition contains no entries. Provider record dates describe the provider record. Unknown dates stay null.
 
 ## Deep
 
@@ -453,3 +453,53 @@ A device's emoji font remains the ordinary display.
 
 These additions are a local release candidate until the matching SDK and
 backend are published. Existing lookup and search contracts are preserved.
+
+
+## City collections
+
+```ruby
+page = parse.city_list(country: 'JP', min_population: 100_000, sort: 'population', limit: 20)
+nearby = parse.city_nearby_coords(34.57, 135.48, radius: 20, unit: 'km', country: 'JP')
+search = parse.city_search('Sak', page: true)
+```
+
+Browse the curated City catalog or list cities around a supplied coordinate. These operations return `next_cursor`, which is null at the end. Treat it as opaque and reuse all filters, limit, language, hierarchy and deep settings for the next page. Existing name searches and named nearby calls include pagination metadata only when paging or a cursor is requested.
+
+Collection options include minimum and maximum population, an exact IANA timezone, and `bbox` in `west,south,east,north` order. A west bound greater than east crosses the dateline. Population filtering and sorting use the same count as paid Deep: an admitted observation when available, otherwise the stored count. Missing counts do not match a population range and sort last; legacy counts keep unknown dates. Coverage and observation dates vary by place.
+
+Collections support `name`, `population`, `country` and `elevation`; search also supports `relevance`, and nearby supports `distance`. Combine up to three signed terms, for example `sort=-population,name`. A signed multi-key sort does not also take `order`. Population defaults to descending order; other sorts default to ascending. Set `order` to `asc` or `desc`, except relevance only supports ascending. Named nearby uses country and state to select the anchor; population, timezone and bounding box filter the returned neighbors. Coordinate nearby applies country and state to its returned cities.
+
+
+
+## Canonical City operations
+
+Classic lookup, search, nearest and named-nearby methods retain their default envelopes and required-field models. Browse and coordinate-nearby use canonical lists: `object`, `data` and nullable `next_cursor` (camelCase properties in Swift/Kotlin). Keep all query options unchanged when continuing a page; no client fetches pages automatically.
+
+```ruby
+page = parse.city_search('Viena', format: 'list', match: 'fuzzy', max_distance: 1)
+children = parse.city_children('city_7aj899nvwyku')
+distance = parse.city_distance('city_7aj899nvwyku', 'city_7aj899nvwyku')
+```
+
+Select `format=resource` for one City or `format=list` for a collection. Country inclusion/exclusion sets, timezone sets, inclusive population and meter-elevation bounds, stored-center `bbox` and signed multi-key sorting are available for collections. Unknown numeric facts do not match range filters.
+
+Search defaults to prefix matching. Exact and fuzzy matching are explicit; fuzzy accepts maximum edit distance 1 or 2 and returns `match` evidence (`type`, `source`, `value`, `language`, `edit_distance`). Review a fuzzy choice before storing its ID.
+
+Reviewed children, ancestors and siblings use canonical lists with partial relationship coverage. Empty data does not prove there are no geographic relatives. Children/siblings accept page controls; ancestors do not. Distance reports great-circle kilometers and miles between stored centers: zero is known zero, null is unknown, and it does not imply travel time or containment.
+
+Strict `ambiguity=error` can return HTTP 409 `ambiguous_city` with up to two safe candidate identities. The existing error constructor and unrelated error metadata are preserved; candidates are retained only for that status/code and never contain Deep. GeoJSON is available through HTTP; these typed City list methods do not return GeoJSON.
+
+
+
+Reviewed name forms:
+
+```ruby
+city = parse.city_id('city_7aj899nvwyku', format: 'resource', romanized: true)
+```
+
+Coverage by country and available fields is described at https://parseapi.com/city#coverage.
+
+`romanized=true` requests reviewed official name forms as `name_romanized` and `romanization_language` (camelCase in Swift/Kotlin). Current reviewed forms cover 20 Japanese whole-city aliases in ja-Latn. Missing or conflicting forms stay null; ASCII folding is not substituted for an official form.
+
+
+Conditional `If-None-Match` reads and GeoJSON currently use HTTP directly. A matching City ETag returns 304 without a body; ordinary billing and rate limits apply. These JSON client methods do not supply conditional-cache handling.

data/lib/parseapi/client.rb

@@ -6,7 +6,7 @@ require 'time'
 module ParseAPI
 	# Every non-2xx response from the API. Branch on +code+, never on the message.
 	class Error < StandardError
-		attr_reader :status, :code, :docs, :request_id, :retry_after
+		attr_reader :status, :code, :docs, :request_id, :retry_after, :candidates
 
 		def initialize(status:, code:, message:, docs: nil, request_id: nil, retry_after: nil)
 			super(message)
@@ -106,28 +106,69 @@ module ParseAPI
 			get("/district/#{seg(code)}", country: country, state: state, deep: deep, lang: lang)
 		end
 
-		def city(name, country: nil, state: nil, deep: false, lang: nil)
-			get("/city/#{seg(name)}", country: country, state: state, deep: deep, lang: lang)
+		def city(name, country: nil, state: nil, deep: false, lang: nil, type: nil, grain: nil, hierarchy: false, aliases: false, ambiguity: nil, format: nil, romanized: false)
+			get("/city/#{seg(name)}", country: country, state: state, deep: deep, lang: lang, type: type, grain: grain, hierarchy: hierarchy, aliases: aliases, ambiguity: ambiguity, romanized: romanized, format: format)
 		end
 
-		def city_id(id, deep: false, lang: nil)
-			get("/city/id/#{seg(id)}", deep: deep, lang: lang)
+		def city_id(id, deep: false, lang: nil, hierarchy: false, format: nil, romanized: false)
+			get("/city/id/#{seg(id)}", deep: deep, lang: lang, hierarchy: hierarchy, romanized: romanized, format: format)
 		end
 
-		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)
+		def city_search(query, country: nil, state: nil, limit: nil, deep: false, lang: nil, type: nil, grain: nil, hierarchy: false, aliases: false, min_population: nil, max_population: nil, timezone: nil, bbox: nil, sort: nil, order: nil, page: false, cursor: nil, format: nil, countries: nil, exclude_countries: nil, timezones: nil, min_elevation: nil, max_elevation: nil, match: nil, max_distance: nil, romanized: false)
+			spelling = !match.nil? || !max_distance.nil?
+			response = get(spelling ? '/city/search' : '/city', q: query, match: match, max_distance: max_distance, country: country, state: state, limit: limit, deep: deep, lang: lang, type: type, grain: grain, hierarchy: hierarchy, aliases: aliases, min_population: min_population, max_population: max_population, timezone: timezone, bbox: bbox, sort: sort, order: order, page: page, cursor: cursor, romanized: romanized, format: format, countries: city_csv(countries), exclude_countries: city_csv(exclude_countries), timezones: city_csv(timezones), min_elevation: min_elevation, max_elevation: max_elevation)
+			if spelling && format.nil?
+				classic = {"q"=>query, "cities"=>response.fetch("data"), "next_cursor"=>response["next_cursor"]}
+				classic["country"] = country unless country.nil?
+				classic["state"] = state unless state.nil?
+				return classic
+			end
+			response
 		end
 
-		def city_nearest(lat, lon, deep: false, lang: nil)
-			get('/city', lat: lat, lon: lon, deep: deep, lang: lang)
+		def city_nearest(lat, lon, deep: false, lang: nil, country: nil, state: nil, type: nil, grain: nil, hierarchy: false, format: nil, romanized: false)
+			get('/city', lat: lat, lon: lon, deep: deep, lang: lang, country: country, state: state, type: type, grain: grain, hierarchy: hierarchy, romanized: romanized, format: format)
 		end
 
-		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)
+		def city_nearby(name, radius: nil, unit: nil, country: nil, state: nil, limit: nil, deep: false, lang: nil, type: nil, grain: nil, hierarchy: false, aliases: false, ambiguity: nil, min_population: nil, max_population: nil, timezone: nil, bbox: nil, sort: nil, order: nil, page: false, cursor: nil, format: nil, countries: nil, exclude_countries: nil, timezones: nil, min_elevation: nil, max_elevation: nil, romanized: false)
+			get("/city/#{seg(name)}/nearby", radius: radius, unit: unit, country: country, state: state, limit: limit, deep: deep, lang: lang, type: type, grain: grain, hierarchy: hierarchy, aliases: aliases, ambiguity: ambiguity, min_population: min_population, max_population: max_population, timezone: timezone, bbox: bbox, sort: sort, order: order, page: page, cursor: cursor, romanized: romanized, format: format, countries: city_csv(countries), exclude_countries: city_csv(exclude_countries), timezones: city_csv(timezones), min_elevation: min_elevation, max_elevation: max_elevation)
 		end
 
 		# Look up a postal area. Pass country when known. Check nullable coordinates before another
 		# location lookup.
+		def city_ancestors(id, hierarchy: false, deep: false, lang: nil, romanized: false)
+			get("/city/id/#{seg(id)}/ancestors", romanized: romanized, hierarchy: hierarchy, deep: deep, lang: lang)
+		end
+
+
+
+
+		def city_children(id, limit: nil, cursor: nil, hierarchy: false, deep: false, lang: nil, romanized: false)
+			get("/city/id/#{seg(id)}/children", limit: limit, cursor: cursor, romanized: romanized, hierarchy: hierarchy, deep: deep, lang: lang)
+		end
+
+
+
+		def city_distance(from, to)
+			get("/city/id/#{seg(from)}/distance/#{seg(to)}")
+		end
+
+
+		def city_list(country: nil, state: nil, limit: nil, deep: false, lang: nil, type: nil, grain: nil, hierarchy: false, min_population: nil, max_population: nil, timezone: nil, bbox: nil, sort: nil, order: nil, cursor: nil, countries: nil, exclude_countries: nil, timezones: nil, min_elevation: nil, max_elevation: nil, romanized: false)
+			get('/city', browse: true, country: country, state: state, limit: limit, deep: deep, lang: lang, type: type, grain: grain, hierarchy: hierarchy, min_population: min_population, max_population: max_population, timezone: timezone, bbox: bbox, sort: sort, order: order, cursor: cursor, romanized: romanized, format: 'list', countries: city_csv(countries), exclude_countries: city_csv(exclude_countries), timezones: city_csv(timezones), min_elevation: min_elevation, max_elevation: max_elevation)
+		end
+
+
+		def city_nearby_coords(lat, lon, radius: nil, unit: nil, country: nil, state: nil, limit: nil, deep: false, lang: nil, type: nil, grain: nil, hierarchy: false, min_population: nil, max_population: nil, timezone: nil, bbox: nil, sort: nil, order: nil, cursor: nil, countries: nil, exclude_countries: nil, timezones: nil, min_elevation: nil, max_elevation: nil, romanized: false)
+			get('/city', lat: lat, lon: lon, nearby: true, radius: radius, unit: unit, country: country, state: state, limit: limit, deep: deep, lang: lang, type: type, grain: grain, hierarchy: hierarchy, min_population: min_population, max_population: max_population, timezone: timezone, bbox: bbox, sort: sort, order: order, cursor: cursor, romanized: romanized, format: 'list', countries: city_csv(countries), exclude_countries: city_csv(exclude_countries), timezones: city_csv(timezones), min_elevation: min_elevation, max_elevation: max_elevation)
+		end
+
+
+		def city_siblings(id, limit: nil, cursor: nil, hierarchy: false, deep: false, lang: nil, romanized: false)
+			get("/city/id/#{seg(id)}/siblings", limit: limit, cursor: cursor, romanized: romanized, hierarchy: hierarchy, deep: deep, lang: lang)
+		end
+
+
 		def postal(code, country: nil, deep: false, lang: nil)
 			get("/postal/#{seg(code)}", country: country, deep: deep, lang: lang)
 		end
@@ -465,8 +506,12 @@ module ParseAPI
 			targets.join(',')
 		end
 
+		def tariff_edition_id?(value)
+            value.is_a?(String) && (/\A[a-f0-9]{64}\z/.match?(value) || (/\Ated_[1-9][0-9]{0,19}\z/.match?(value) && (value.bytesize < 24 || value[4..-1] <= '18446744073709551615')))
+        end
+
 		def tariff_selection(result, edition, date)
-			if (!edition.nil? || !date.nil?) && (!result['edition'].is_a?(String) || !/\A[a-f0-9]{64}\z/.match?(result['edition']) || (!edition.nil? && result['edition'] != edition) || result['date'] != date)
+			if (!edition.nil? || !date.nil?) && (!tariff_edition_id?(result['edition']) || (!edition.nil? && result['edition'] != edition) || result['date'] != date)
 				raise Error.new(status: 0, code: 'tariff_selection_mismatch', message: 'Tariff response did not confirm the requested edition/date. The server may not support this selection.')
 			end
 			result
@@ -572,6 +617,11 @@ module ParseAPI
 			metered ? 0 : DEFAULT_RETRIES
 		end
 
+		def city_csv(value)
+			value.is_a?(Array) ? value.join(',') : value
+		end
+
+
 		def build_error(status, body, retry_after = nil)
 			parsed = begin
 				JSON.parse(body)
@@ -579,7 +629,7 @@ module ParseAPI
 				{}
 			end
 			parsed = {} unless parsed.is_a?(Hash)
-			Error.new(
+			error = Error.new(
 				status: status,
 				code: parsed['code'].is_a?(String) ? parsed['code'] : 'unknown_error',
 				message: parsed['message'].is_a?(String) ? parsed['message'] : "Request failed with status #{status}",
@@ -587,6 +637,19 @@ module ParseAPI
 				request_id: parsed['request_id'].is_a?(String) ? parsed['request_id'] : nil,
 				retry_after: retry_after
 			)
+			if status == 409 && error.code == 'ambiguous_city' && parsed['candidates'].is_a?(Array)
+				candidates = parsed['candidates'].first(2).map do |row|
+					next unless row.is_a?(Hash) && row['id'].is_a?(String) && /\Acity_[a-z0-9]{12}\z/.match?(row['id']) && row['object'] == 'city'
+					candidate = { 'id' => row['id'], 'object' => 'city' }
+					%w[name name_local country country_name state state_name type].each do |field|
+						value = row[field]
+						candidate[field] = value if row.key?(field) && (value.nil? || (value.is_a?(String) && value.length <= 255))
+					end
+					candidate
+				end.compact
+				error.instance_variable_set(:@candidates, candidates)
+			end
+			error
 		end
 	end
 end

data/lib/parseapi/version.rb

@@ -1,3 +1,3 @@
 module ParseAPI
-	VERSION = '1.9.2'.freeze
+	VERSION = '1.10.0'.freeze
 end

metadata

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