parseapi 1.9.3__tar.gz → 1.10.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. {parseapi-1.9.3 → parseapi-1.10.1}/CHANGELOG.md +6 -0
  2. {parseapi-1.9.3 → parseapi-1.10.1}/PKG-INFO +72 -7
  3. {parseapi-1.9.3 → parseapi-1.10.1}/README.md +71 -6
  4. {parseapi-1.9.3 → parseapi-1.10.1}/api/public.json +2448 -958
  5. {parseapi-1.9.3 → parseapi-1.10.1}/pyproject.toml +1 -1
  6. {parseapi-1.9.3 → parseapi-1.10.1}/smoke/smoke.py +2 -6
  7. parseapi-1.10.1/src/parseapi/__init__.py +7 -0
  8. {parseapi-1.9.3 → parseapi-1.10.1}/src/parseapi/_client.py +197 -35
  9. parseapi-1.10.1/src/parseapi/city.py +31 -0
  10. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-company-coverage.json +12 -0
  11. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-company-profile.json +16 -0
  12. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-emoji-catalog.json +185 -0
  13. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-emoji-metadata.json +127 -0
  14. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-provider.json +31 -0
  15. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-tariff-search.json +15 -0
  16. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-tariff.json +10 -0
  17. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-time.json +78 -0
  18. parseapi-1.10.1/tests/fixtures/response-fixtures/clean-timezones.json +601 -0
  19. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-company-coverage.json +13 -0
  20. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-company-profile.json +17 -0
  21. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-emoji-catalog.json +189 -0
  22. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-emoji-metadata.json +131 -0
  23. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-provider.json +42 -0
  24. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-tariff-search.json +16 -0
  25. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-tariff.json +11 -0
  26. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-time.json +84 -0
  27. parseapi-1.10.1/tests/fixtures/response-fixtures/standard-timezones.json +602 -0
  28. parseapi-1.10.1/tests/test_city_canonical.py +132 -0
  29. parseapi-1.10.1/tests/test_city_quality.py +57 -0
  30. parseapi-1.10.1/tests/test_city_query_parity.py +54 -0
  31. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_client.py +4 -10
  32. parseapi-1.10.1/tests/test_response_decoding.py +31 -0
  33. parseapi-1.9.3/src/parseapi/__init__.py +0 -6
  34. {parseapi-1.9.3 → parseapi-1.10.1}/.github/workflows/publish.yml +0 -0
  35. {parseapi-1.9.3 → parseapi-1.10.1}/.github/workflows/test.yml +0 -0
  36. {parseapi-1.9.3 → parseapi-1.10.1}/.gitignore +0 -0
  37. {parseapi-1.9.3 → parseapi-1.10.1}/LICENSE +0 -0
  38. {parseapi-1.9.3 → parseapi-1.10.1}/scripts/public_api.py +0 -0
  39. {parseapi-1.9.3 → parseapi-1.10.1}/src/parseapi/py.typed +0 -0
  40. {parseapi-1.9.3 → parseapi-1.10.1}/tests/bank-fixtures.json +0 -0
  41. {parseapi-1.9.3 → parseapi-1.10.1}/tests/fixtures/emoji-artwork.json +0 -0
  42. {parseapi-1.9.3 → parseapi-1.10.1}/tests/fixtures/emoji-catalog.json +0 -0
  43. {parseapi-1.9.3 → parseapi-1.10.1}/tests/fixtures/measure-response.json +0 -0
  44. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_bank.py +0 -0
  45. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_card_dx.py +0 -0
  46. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_company_directory.py +0 -0
  47. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_email_enrichment.py +0 -0
  48. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_emoji.py +0 -0
  49. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_language.py +0 -0
  50. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_measure_response.py +0 -0
  51. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_name_formatting.py +0 -0
  52. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_postal_localities.py +0 -0
  53. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_public_api.py +0 -0
  54. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_stack.py +0 -0
  55. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_tariff.py +0 -0
  56. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_tariff_short_id.py +0 -0
  57. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_time_complete.py +0 -0
  58. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_time_gaps.py +0 -0
  59. {parseapi-1.9.3 → parseapi-1.10.1}/tests/test_version.py +0 -0
  60. {parseapi-1.9.3 → parseapi-1.10.1}/tests/typing_company_directory.py +0 -0
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.10.0 — 2026-10-15
4
+
5
+ - Add compatible City resource/list, spelling-search, geographic-filter, pagination, hierarchy, relationship and distance support.
6
+ - Keep existing City calls and response defaults compatible; expose ambiguity candidates when requested.
7
+ - Remove population observation periods from public examples; retain published typed members only for source compatibility.
8
+
3
9
  ## 1.9.1 — 2026-10-12
4
10
 
5
11
  - Add Emoji search/browse, categories, catalog, metadata, parsing and conversion; keep existing lookup calls and response decoding compatible.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: parseapi
3
- Version: 1.9.3
3
+ Version: 1.10.1
4
4
  Summary: Official ParseAPI client for Python. One key, minimal JSON, fast.
5
5
  Project-URL: Homepage, https://parseapi.com
6
6
  Project-URL: Documentation, https://parseapi.com/docs
@@ -163,7 +163,6 @@ parse.mx("example.com")
163
163
  parse.dns("example.com")
164
164
  parse.dns("_dmarc.example.com", type="TXT")
165
165
  parse.useragent(ua_string)
166
- parse.vehicle("1HGCM82633A004352")
167
166
  parse.industry("541511")
168
167
  parse.industry.search("coffee shop", limit=5)
169
168
  parse.tariff("8471.30.01.00")
@@ -275,7 +274,7 @@ place = parse.postal("28202", country="US", deep=True)
275
274
  property_tax = (place.get("deep") or {}).get("property_tax")
276
275
  ```
277
276
 
278
- 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.
277
+ 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.
279
278
 
280
279
  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.
281
280
 
@@ -329,7 +328,7 @@ Invalid input returns `valid: false` with unknown provider fields. A checksum-va
329
328
 
330
329
  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.
331
330
 
332
- 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.
331
+ 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.
333
332
 
334
333
  ## Deep
335
334
 
@@ -345,7 +344,7 @@ Choose enrichment for the question you need answered.
345
344
  | Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
346
345
  | Name, Industry | Name evidence or the industry definition profile on paid plans. |
347
346
  | NPI | Deactivation date, Medicare enrollment, opt-out and enrollment rows from stored sources on paid plans. Exclusion evidence stays core. |
348
- | Vehicle, Tariff, Company | The complete product detail bag on paid plans. |
347
+ | Tariff, Company | The complete product detail bag on paid plans. |
349
348
  | Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
350
349
  | Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
351
350
 
@@ -449,8 +448,6 @@ Successful checks may be reused for up to 24 hours. `pretty` optionally formats
449
448
 
450
449
  Stack defaults to a 35-second transport timeout so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout takes precedence.
451
450
 
452
- Vehicle lookups use `vin` as the input and response field. Existing VIN methods remain available for compatibility.
453
-
454
451
  ## Emoji catalog additions
455
452
 
456
453
  Resolve Unicode emoji or a named shortcode, search or browse a bounded catalog,
@@ -482,3 +479,71 @@ A device's emoji font remains the ordinary display.
482
479
 
483
480
  These additions are a local release candidate until the matching SDK and
484
481
  backend are published. Existing lookup and search contracts are preserved.
482
+
483
+
484
+ ## City scope and reviewed details
485
+
486
+ ```python
487
+ city = parse.city("Sakai", country="JP", state="27", grain="municipality",
488
+ aliases=True, ambiguity="error", hierarchy=True, deep=True)
489
+ ```
490
+
491
+ `type` selects the recorded country-specific place type. `grain` selects a reviewed `municipality`, `subdivision`, `locality` or `metropolitan_area`; unreviewed places do not match a grain filter. `aliases=True` enables reviewed name forms. `ambiguity="error"` rejects several eligible exact matches. Existing calls keep their defaults, and `AsyncParseAPI` accepts the same options.
492
+
493
+ `hierarchy=True` adds optional `grain` and `parent` fields using stable City IDs. A null parent means no relationship has been reviewed. Nearest lookup applies country, state, type and grain to eligible centers within 2,000 km; a nearest center does not establish boundary containment. Nearby type and grain select both the named anchor and its results.
494
+
495
+ Paid Deep can include `population_observed_on` and `population_basis` for a reviewed count at the same place layer. Download dates do not supply population observation dates. These options use current API 2.0.0; older responses can omit the new fields.
496
+
497
+ ```python
498
+ opts = dict(country="JP", min_population=100_000, sort="-population,+name",
499
+ limit=50)
500
+ first = parse.city.list(**opts)
501
+ for city in first["data"]:
502
+ print(city["id"], city.get("name"))
503
+ if first["next_cursor"]:
504
+ next_page = parse.city.list(**opts, cursor=first["next_cursor"])
505
+ parse.city.nearby_coordinates(48.2082, 16.3738, radius=40, unit="km")
506
+ parse.city.search("sa", page=True, timezone="Asia/Tokyo", bbox="130,30,145,45")
507
+ ```
508
+
509
+ Collections support inclusive `min_population`/`max_population`, `min_elevation`/`max_elevation`, `countries`, `exclude_countries`, `timezones`, exact `timezone` and center-coordinate `bbox` (`west,south,east,north`; west greater than east crosses the dateline). Unknown populations do not match a population range. Browse sorts by name or population; search also supports relevance; nearby also supports distance. `order` accepts `asc` or `desc` (relevance allows only `asc`); population defaults to descending with unknown counts last. Filtering and ordering use the same count as paid Deep.
510
+
511
+ `lang="de"` displays Vienna as Wien; `lang="ja"` supports 1,912 reviewed Japanese native names, and `lang="zh-Hant"` supports 377 reviewed Traditional Chinese names in Taiwan. Approved translations take precedence; missing or unsupported labels keep the source name. IDs and `name_local` stay unchanged. Name sorting uses the stored primary name, regardless of display language. Coordinate nearby defaults to 40 km, or 25 mi with `unit="mi"`, and caps the radius at 800 km or 500 mi.
512
+
513
+ `city.list` and `city.nearby_coordinates` return `{ "object": "list", "data": [...], "next_cursor": ... }`. Each item retains `id` and `object: "city"`. Existing lookup, search, nearest and named-nearby calls keep their classic responses. Add `format="list"` to search or named nearby for a canonical collection, or `format="resource"` to lookup, ID lookup or nearest for a canonical resource. Classic search and named nearby include `next_cursor` with `page=True` or `cursor`; old responses may omit it. Keep the original options, including `limit`, when continuing. An invalid cursor or changed query/order returns 400; restart without the cursor. Pages are not a historical snapshot. Named nearby applies population, timezone and bbox to results, while country/state select its anchor. Async methods accept the same arguments.
514
+
515
+ `city.children(id)`, `city.ancestors(id)` and `city.siblings(id)` return canonical lists with `coverage: "partial"`. An empty list does not prove the absence of relatives. Children and siblings support page continuation. `city.distance(from_id, to_id)` returns `object: "city_distance"`, `from`, `to`, `distance` in kilometers, `distance_mi` in miles and `method: "great_circle"`. It compares stored centers; unknown coordinates remain null and known zero remains zero. Async clients support the same calls.
516
+
517
+ Strict ambiguity returns HTTP 409. Catch `ParseAPIError` with `code == "ambiguous_city"` and read optional `error.candidates` for at most two safe City identity objects; `CityAmbiguityCandidate` is exported as a TypedDict. Choose an ID or narrow the filters for a new request. Other errors and retry behavior remain unchanged.
518
+
519
+
520
+ ## Canonical City operations
521
+
522
+ 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.
523
+
524
+ ```python
525
+ page = parse.city.search('Viena', format='list', match='fuzzy', max_distance=1)
526
+ ```
527
+
528
+ 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.
529
+
530
+ 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.
531
+
532
+ 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.
533
+
534
+ 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.
535
+
536
+
537
+
538
+ Reviewed name forms:
539
+
540
+ ```python
541
+ city = parse.city.id('city_7aj899nvwyku', format='resource', romanized=True)
542
+ ```
543
+
544
+ Coverage by country and available fields is described at https://parseapi.com/city#coverage.
545
+
546
+ `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.
547
+
548
+
549
+ 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.
@@ -144,7 +144,6 @@ parse.mx("example.com")
144
144
  parse.dns("example.com")
145
145
  parse.dns("_dmarc.example.com", type="TXT")
146
146
  parse.useragent(ua_string)
147
- parse.vehicle("1HGCM82633A004352")
148
147
  parse.industry("541511")
149
148
  parse.industry.search("coffee shop", limit=5)
150
149
  parse.tariff("8471.30.01.00")
@@ -256,7 +255,7 @@ place = parse.postal("28202", country="US", deep=True)
256
255
  property_tax = (place.get("deep") or {}).get("property_tax")
257
256
  ```
258
257
 
259
- 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.
258
+ 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.
260
259
 
261
260
  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.
262
261
 
@@ -310,7 +309,7 @@ Invalid input returns `valid: false` with unknown provider fields. A checksum-va
310
309
 
311
310
  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.
312
311
 
313
- 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.
312
+ 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.
314
313
 
315
314
  ## Deep
316
315
 
@@ -326,7 +325,7 @@ Choose enrichment for the question you need answered.
326
325
  | Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
327
326
  | Name, Industry | Name evidence or the industry definition profile on paid plans. |
328
327
  | NPI | Deactivation date, Medicare enrollment, opt-out and enrollment rows from stored sources on paid plans. Exclusion evidence stays core. |
329
- | Vehicle, Tariff, Company | The complete product detail bag on paid plans. |
328
+ | Tariff, Company | The complete product detail bag on paid plans. |
330
329
  | Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
331
330
  | Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
332
331
 
@@ -430,8 +429,6 @@ Successful checks may be reused for up to 24 hours. `pretty` optionally formats
430
429
 
431
430
  Stack defaults to a 35-second transport timeout so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout takes precedence.
432
431
 
433
- Vehicle lookups use `vin` as the input and response field. Existing VIN methods remain available for compatibility.
434
-
435
432
  ## Emoji catalog additions
436
433
 
437
434
  Resolve Unicode emoji or a named shortcode, search or browse a bounded catalog,
@@ -463,3 +460,71 @@ A device's emoji font remains the ordinary display.
463
460
 
464
461
  These additions are a local release candidate until the matching SDK and
465
462
  backend are published. Existing lookup and search contracts are preserved.
463
+
464
+
465
+ ## City scope and reviewed details
466
+
467
+ ```python
468
+ city = parse.city("Sakai", country="JP", state="27", grain="municipality",
469
+ aliases=True, ambiguity="error", hierarchy=True, deep=True)
470
+ ```
471
+
472
+ `type` selects the recorded country-specific place type. `grain` selects a reviewed `municipality`, `subdivision`, `locality` or `metropolitan_area`; unreviewed places do not match a grain filter. `aliases=True` enables reviewed name forms. `ambiguity="error"` rejects several eligible exact matches. Existing calls keep their defaults, and `AsyncParseAPI` accepts the same options.
473
+
474
+ `hierarchy=True` adds optional `grain` and `parent` fields using stable City IDs. A null parent means no relationship has been reviewed. Nearest lookup applies country, state, type and grain to eligible centers within 2,000 km; a nearest center does not establish boundary containment. Nearby type and grain select both the named anchor and its results.
475
+
476
+ Paid Deep can include `population_observed_on` and `population_basis` for a reviewed count at the same place layer. Download dates do not supply population observation dates. These options use current API 2.0.0; older responses can omit the new fields.
477
+
478
+ ```python
479
+ opts = dict(country="JP", min_population=100_000, sort="-population,+name",
480
+ limit=50)
481
+ first = parse.city.list(**opts)
482
+ for city in first["data"]:
483
+ print(city["id"], city.get("name"))
484
+ if first["next_cursor"]:
485
+ next_page = parse.city.list(**opts, cursor=first["next_cursor"])
486
+ parse.city.nearby_coordinates(48.2082, 16.3738, radius=40, unit="km")
487
+ parse.city.search("sa", page=True, timezone="Asia/Tokyo", bbox="130,30,145,45")
488
+ ```
489
+
490
+ Collections support inclusive `min_population`/`max_population`, `min_elevation`/`max_elevation`, `countries`, `exclude_countries`, `timezones`, exact `timezone` and center-coordinate `bbox` (`west,south,east,north`; west greater than east crosses the dateline). Unknown populations do not match a population range. Browse sorts by name or population; search also supports relevance; nearby also supports distance. `order` accepts `asc` or `desc` (relevance allows only `asc`); population defaults to descending with unknown counts last. Filtering and ordering use the same count as paid Deep.
491
+
492
+ `lang="de"` displays Vienna as Wien; `lang="ja"` supports 1,912 reviewed Japanese native names, and `lang="zh-Hant"` supports 377 reviewed Traditional Chinese names in Taiwan. Approved translations take precedence; missing or unsupported labels keep the source name. IDs and `name_local` stay unchanged. Name sorting uses the stored primary name, regardless of display language. Coordinate nearby defaults to 40 km, or 25 mi with `unit="mi"`, and caps the radius at 800 km or 500 mi.
493
+
494
+ `city.list` and `city.nearby_coordinates` return `{ "object": "list", "data": [...], "next_cursor": ... }`. Each item retains `id` and `object: "city"`. Existing lookup, search, nearest and named-nearby calls keep their classic responses. Add `format="list"` to search or named nearby for a canonical collection, or `format="resource"` to lookup, ID lookup or nearest for a canonical resource. Classic search and named nearby include `next_cursor` with `page=True` or `cursor`; old responses may omit it. Keep the original options, including `limit`, when continuing. An invalid cursor or changed query/order returns 400; restart without the cursor. Pages are not a historical snapshot. Named nearby applies population, timezone and bbox to results, while country/state select its anchor. Async methods accept the same arguments.
495
+
496
+ `city.children(id)`, `city.ancestors(id)` and `city.siblings(id)` return canonical lists with `coverage: "partial"`. An empty list does not prove the absence of relatives. Children and siblings support page continuation. `city.distance(from_id, to_id)` returns `object: "city_distance"`, `from`, `to`, `distance` in kilometers, `distance_mi` in miles and `method: "great_circle"`. It compares stored centers; unknown coordinates remain null and known zero remains zero. Async clients support the same calls.
497
+
498
+ Strict ambiguity returns HTTP 409. Catch `ParseAPIError` with `code == "ambiguous_city"` and read optional `error.candidates` for at most two safe City identity objects; `CityAmbiguityCandidate` is exported as a TypedDict. Choose an ID or narrow the filters for a new request. Other errors and retry behavior remain unchanged.
499
+
500
+
501
+ ## Canonical City operations
502
+
503
+ 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.
504
+
505
+ ```python
506
+ page = parse.city.search('Viena', format='list', match='fuzzy', max_distance=1)
507
+ ```
508
+
509
+ 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.
510
+
511
+ 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.
512
+
513
+ 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.
514
+
515
+ 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.
516
+
517
+
518
+
519
+ Reviewed name forms:
520
+
521
+ ```python
522
+ city = parse.city.id('city_7aj899nvwyku', format='resource', romanized=True)
523
+ ```
524
+
525
+ Coverage by country and available fields is described at https://parseapi.com/city#coverage.
526
+
527
+ `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.
528
+
529
+
530
+ 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.