parseapi 1.11.4__tar.gz → 1.13.0__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 (79) hide show
  1. {parseapi-1.11.4 → parseapi-1.13.0}/CHANGELOG.md +10 -3
  2. {parseapi-1.11.4 → parseapi-1.13.0}/PKG-INFO +71 -45
  3. {parseapi-1.11.4 → parseapi-1.13.0}/README.md +70 -44
  4. {parseapi-1.11.4 → parseapi-1.13.0}/api/public.json +262 -184
  5. {parseapi-1.11.4 → parseapi-1.13.0}/pyproject.toml +1 -1
  6. {parseapi-1.11.4 → parseapi-1.13.0}/src/parseapi/__init__.py +1 -1
  7. {parseapi-1.11.4 → parseapi-1.13.0}/src/parseapi/_client.py +90 -92
  8. parseapi-1.13.0/tests/fixtures/core-connectors.json +251 -0
  9. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/country-aq.json +30 -32
  10. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/country-corrected.json +43 -45
  11. parseapi-1.13.0/tests/fixtures/country-de.json +93 -0
  12. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/emoji-artwork.json +37 -39
  13. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/emoji-catalog.json +7 -9
  14. parseapi-1.13.0/tests/fixtures/ip-deep-expansion.json +26 -0
  15. parseapi-1.13.0/tests/fixtures/iso-contract.json +169 -0
  16. parseapi-1.13.0/tests/fixtures/noise-approved.json +654 -0
  17. parseapi-1.13.0/tests/fixtures/postal-weather.json +66 -0
  18. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-company-profile.json +5 -7
  19. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-emoji-catalog.json +5 -7
  20. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-provider.json +8 -10
  21. parseapi-1.13.0/tests/fixtures/response-fixtures/clean-time.json +76 -0
  22. parseapi-1.13.0/tests/fixtures/response-fixtures/standard-company-profile.json +15 -0
  23. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/standard-emoji-catalog.json +5 -7
  24. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/standard-provider.json +8 -10
  25. parseapi-1.13.0/tests/fixtures/response-fixtures/standard-time.json +82 -0
  26. parseapi-1.13.0/tests/fixtures/time-compact.json +2744 -0
  27. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_city_canonical.py +16 -16
  28. parseapi-1.13.0/tests/test_city_compact.py +18 -0
  29. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_city_query_parity.py +5 -6
  30. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_client.py +26 -4
  31. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_company_directory.py +6 -8
  32. parseapi-1.13.0/tests/test_core_connectors.py +25 -0
  33. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_country_corrected.py +11 -11
  34. parseapi-1.13.0/tests/test_county.py +30 -0
  35. parseapi-1.13.0/tests/test_domain_nullability.py +23 -0
  36. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_emoji.py +8 -8
  37. parseapi-1.13.0/tests/test_ip_deep_expansion.py +12 -0
  38. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_iso_contract.py +1 -0
  39. parseapi-1.13.0/tests/test_natural_contract.py +49 -0
  40. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_postal_weather.py +3 -3
  41. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_response_decoding.py +16 -1
  42. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_stack.py +1 -1
  43. parseapi-1.13.0/tests/test_time_compact.py +23 -0
  44. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_version.py +2 -1
  45. parseapi-1.11.4/tests/fixtures/country-de.json +0 -95
  46. parseapi-1.11.4/tests/fixtures/iso-contract.json +0 -93
  47. parseapi-1.11.4/tests/fixtures/postal-weather.json +0 -75
  48. parseapi-1.11.4/tests/fixtures/response-fixtures/clean-time.json +0 -78
  49. parseapi-1.11.4/tests/fixtures/response-fixtures/standard-company-profile.json +0 -17
  50. parseapi-1.11.4/tests/fixtures/response-fixtures/standard-time.json +0 -84
  51. {parseapi-1.11.4 → parseapi-1.13.0}/.github/workflows/publish.yml +0 -0
  52. {parseapi-1.11.4 → parseapi-1.13.0}/.github/workflows/test.yml +0 -0
  53. {parseapi-1.11.4 → parseapi-1.13.0}/.gitignore +0 -0
  54. {parseapi-1.11.4 → parseapi-1.13.0}/LICENSE +0 -0
  55. {parseapi-1.11.4 → parseapi-1.13.0}/scripts/public_api.py +0 -0
  56. {parseapi-1.11.4 → parseapi-1.13.0}/smoke/smoke.py +0 -0
  57. {parseapi-1.11.4 → parseapi-1.13.0}/src/parseapi/city.py +0 -0
  58. {parseapi-1.11.4 → parseapi-1.13.0}/src/parseapi/py.typed +0 -0
  59. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/measure-response.json +0 -0
  60. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-company-coverage.json +0 -0
  61. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-emoji-metadata.json +0 -0
  62. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-tariff-search.json +0 -0
  63. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-tariff.json +0 -0
  64. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/clean-timezones.json +0 -0
  65. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/standard-company-coverage.json +0 -0
  66. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/standard-emoji-metadata.json +0 -0
  67. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/standard-tariff-search.json +0 -0
  68. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/standard-tariff.json +0 -0
  69. {parseapi-1.11.4 → parseapi-1.13.0}/tests/fixtures/response-fixtures/standard-timezones.json +0 -0
  70. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_card_dx.py +0 -0
  71. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_city_quality.py +0 -0
  72. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_email_enrichment.py +0 -0
  73. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_language.py +0 -0
  74. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_name_formatting.py +0 -0
  75. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_postal_localities.py +0 -0
  76. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_public_api.py +0 -0
  77. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_time_complete.py +0 -0
  78. {parseapi-1.11.4 → parseapi-1.13.0}/tests/test_time_gaps.py +0 -0
  79. {parseapi-1.11.4 → parseapi-1.13.0}/tests/typing_company_directory.py +0 -0
@@ -1,9 +1,16 @@
1
1
  # Changelog
2
2
 
3
- ## 1.11.4 — 2026-11-01
3
+ ## 1.13.0 - 2026-11-16
4
4
 
5
- - Correct documentation to match existing Deep access, complete Core reference data and retired national Company behavior.
6
- - Preserve all business response fields, models, methods, dependencies and access.
5
+ - Breaking State field-read migration: update `iso_subdivision` reads to `iso_code`, with the existing value or null. County and State county items add nullable `iso_code` for the exact place. Other ISO representations and package versions are unchanged.
6
+
7
+ ## 1.12.0 — 2026-11-02
8
+
9
+ - Select API `2.1.0` through the existing client factory. Requested profile detail uses natural field homes instead of a response `.deep` bag.
10
+ - **Breaking field-read migration:** update existing `.deep` reads, User-Agent identity objects and Postal/Weather detail reads with your application code. This minor version changes existing field reads; upgrade the SDK and application code together.
11
+ - Use explicit Email verification; Carrier/HLR return their complete selected result. Preserve recorded Form/Bulk contracts and earlier saved results.
12
+ - Time success returns a compact matched `location`; ambiguity choices remain explicit. Omit unused `resolution`, City match `source`/`edit_distance`, and Holiday JSON calendar fingerprints. Update readers that relied on those removed fields.
13
+ - Keep optional fields absent when unrequested/unavailable and preserve `null`, `false` and `0`. See the API 2.1 upgrade section in the README.
7
14
 
8
15
  ## 1.11.3 — 2026-11-01
9
16
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: parseapi
3
- Version: 1.11.4
3
+ Version: 1.13.0
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
@@ -36,13 +36,15 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
36
36
 
37
37
  ## API versions
38
38
 
39
- This SDK 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.
39
+ State and County use `iso_code` for the full ISO 3166-2 code of the exact returned place, including County items in State lists. A null means unassigned or unknown. National `state` and `county` identifiers are unchanged. Update State readers from `iso_subdivision` to `iso_code`. Responses keep the server's keys without adding legacy duplicates.
40
+
41
+ This SDK explicitly selects the API contract supported by this SDK. It sends `X-API-Version: 2.2.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. The API still accepts earlier `Parse-Version` request pins.
40
42
 
41
43
  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.
42
44
 
43
- 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.
45
+ Older SDKs keep their existing version selection. Requests without either version header 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.
44
46
 
45
- 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).
47
+ The package owns its supported API version. For direct HTTP integrations, an explicit `X-API-Version` header selects a supported contract. See [API versions and migration](https://parseapi.com/docs/versioning).
46
48
 
47
49
  ## Weather from a postal code
48
50
 
@@ -64,7 +66,7 @@ Pass `country` when a postal code or national phone number needs disambiguation.
64
66
 
65
67
  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.
66
68
 
67
- 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. `None` means unknown and `0` means known zero.
69
+ Use `parse.postal("28202", country="US", deep=True)` for US ZIP tax references. `tax.name` names the levy and `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. `None` means unknown and `0` means known zero.
68
70
 
69
71
  ## Company directory
70
72
 
@@ -78,30 +80,29 @@ if candidates["next"] is not None:
78
80
  next_page = parse.company.search(
79
81
  query="GitLab", country="US", limit=5, cursor=candidates["next"]
80
82
  )
81
- coverage = parse.company.coverage()
82
83
  ```
83
84
 
84
85
  Use at most one selector: `query` for a name, `domain`, `ticker`, or `identifier`; country or exact industry filters also allow discovery without a selector. The API validates selectors and filters. Use `country` to scope candidates, `exchange` with a ticker, and `authority` with an identifier. Search returns `companies` and an opaque `next` cursor. Review candidate identity and match details before choosing a stable Company ID. Pass `next` as `cursor` with the same selector, filters and limit to continue that result set.
85
86
 
86
- Directory profiles are plain JSON data. `deep` belongs to each company in search results and adds legal/reference detail plus nullable `description`, `logo`, `founded`, and the `social_profiles`, `phone_numbers`, `email_addresses`, `domains` and `sources` collections. A logo is a reported URL. `founded` has `value` and `precision`, distinct from incorporation. Sources identify the website, filing or business register, supported fields and observation/update timestamps. Employee observations retain count, measurement date, organization scope and approximation; null means unknown. Missing, null, empty and unknown fields retain their response values. An empty search is a successful result. Invalid inputs and unknown IDs raise the existing API error.
87
+ Directory profiles are plain JSON data. Optional detail belongs to each company in search results and adds legal/reference detail plus nullable `description`, `logo`, `founded`, and the `social_profiles`, `phone_numbers`, `email_addresses`, `domains` and `sources` collections. A logo is a reported URL. `founded` has `value` and `precision`, distinct from incorporation. Sources identify the website, filing or business register, supported fields and observation/update timestamps. Employee observations retain count, measurement date, organization scope and approximation; null means unknown. Missing, null, empty and unknown fields retain their response values. An empty search is a successful result. Invalid inputs and unknown IDs raise the existing API error.
87
88
 
88
- The public-directory service retires national-number Company lookups in both API versions. Use the directory methods with API 2.0.0.
89
+ The public-directory service retires national-number Company lookups in both API versions. Use the directory methods with API 2.1.0.
89
90
 
90
- Company directory social profiles contain `platform`, `url` and `handle`; unknown metadata stays null. Phone and email records use `type` for the source-reported purpose. Earlier response fields remain readable by the client.
91
+ Company directory social profiles include `platform` and `url`. Known handles are included when available; unknown handles may be omitted or returned as null by older servers. Phone and email records use `type` for the source-reported purpose. Earlier response fields remain readable by the client.
91
92
 
92
- The recipe requests one candidate page, one explicitly chosen profile and directory coverage, plus a second page when a cursor is returned. Each operation uses the existing retry settings. The number-validation call remains unchanged. `lang` applies to national company-number lookup, while directory calls use the source labels.
93
+ The recipe requests one candidate page, one explicitly chosen profile, plus a second page when a cursor is returned. Each operation uses the existing retry settings. The number-validation call remains unchanged. `lang` applies to national company-number lookup, while directory calls use the source labels.
93
94
 
94
- `AsyncParseAPI` exposes the same `company`, `company.id`, `company.search` and `company.coverage` calls with `await`.
95
+ `AsyncParseAPI` exposes the same `company`, `company.id` and `company.search` calls with `await`.
95
96
 
96
97
  Discovery example: `parse.company.search(country="US", industry="0700", industry_type="sic")`
97
98
 
98
- Supply `industry` and `industry_type` together. The supported namespace is `sic`, with an exact four-digit string such as `0700`; leading zeros are meaningful. Country-only discovery is also supported. Filters intersect and may narrow an existing selector. Country matches the profile country, not a headquarters or operating-presence claim. Unknown values do not match a requested filter. Filter-only candidates use `match.field: "filters"` and `match.value: null`; reuse the same filters and limit with a returned cursor. Counts describe this directory edition, not complete country coverage.
99
+ Supply `industry` and `industry_type` together. The supported namespace is `sic`, with an exact four-digit string such as `0700`; leading zeros are meaningful. Country-only discovery is also supported. Filters intersect and may narrow an existing selector. Country matches the profile country, not a headquarters or operating-presence claim. Unknown values do not match a requested filter. Filter-only candidates use `match.field: "filters"` and `match.value: null`; reuse the same filters and limit with a returned cursor.
99
100
 
100
101
 
101
102
  ## ISO identifiers
102
103
 
103
104
  Country uses `iso_alpha3` and `iso_numeric`, State uses the full
104
- `iso_subdivision` code such as `US-CA`, Language uses `iso_alpha3`, and Currency
105
+ `iso_code` code such as `US-CA`, Language uses `iso_alpha3`, and Currency
105
106
  uses `iso_numeric`. Primary `country`, `state`, `language` and `currency` codes
106
107
  keep their meaning. Results retain the selected API contract's exact keys,
107
108
  values, nulls and nesting. Earlier server contracts retain their earlier ISO
@@ -131,7 +132,6 @@ parse.company.id("co_caczn6wf36hj", deep=True)
131
132
  parse.company.search(domain="about.gitlab.com")
132
133
  parse.company.search(ticker="GTLB", exchange="Nasdaq")
133
134
  parse.company.search(identifier="0001653482", authority="sec")
134
- parse.company.coverage()
135
135
  parse.city("charlotte", country="US")
136
136
  parse.city.id("city_mb8mbqrkz8zb")
137
137
  parse.city.search("char", country="US", limit=10)
@@ -141,8 +141,8 @@ parse.country("US")
141
141
  parse.country.states("US")
142
142
  parse.state("colorado")
143
143
  parse.state("NC", country="US")
144
- parse.state.districts("NC", country="US")
145
- parse.district("37081")
144
+ parse.state.counties("NC", country="US")
145
+ parse.county("37081")
146
146
  parse.continent("NA")
147
147
  parse.continent.countries("NA")
148
148
  parse.currency("USD")
@@ -176,7 +176,7 @@ parse.emoji.search("fire")
176
176
 
177
177
  The existing NAICS lookup and search methods remain available as compatibility names for Industry.
178
178
 
179
- Industry 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.
179
+ Industry paid deep records include classification `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.
180
180
 
181
181
  Responses are plain dicts, exactly the JSON the API returns. `country.states("US")` requests states directly; it does not fetch a country first. Required inputs are positional and optional behavior uses keyword arguments, leaving room for new options without changing existing calls. Reuse a client across calls. Use `with ParseAPI(...) as parse:` or call `parse.close()` when finished.
182
182
 
@@ -193,7 +193,7 @@ async with AsyncParseAPI("your-api-key") as parse:
193
193
  country = await parse.country("US")
194
194
  ```
195
195
 
196
- 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.
196
+ Name paid deep includes flat `short`, `directory`, and `initials` fields beside `gender`. `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.
197
197
 
198
198
  ## Display language
199
199
 
@@ -209,7 +209,7 @@ The next call keeps its usual default unless it also supplies `lang`. Existing `
209
209
 
210
210
  ## Time
211
211
 
212
- `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` or `targets`, 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.
212
+ `time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `offset_seconds` gives the numeric offset, while `offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to` or `targets`, 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.
213
213
 
214
214
  For an offsetless `at` with `to` or `targets`, choose how to handle a clock change with `disambiguation`. It applies to named-zone and coordinate Time calls.
215
215
 
@@ -228,7 +228,7 @@ result = parse.time("America/New_York", at="2026-11-01T01:30:00",
228
228
  print(result["to"]["at"]) # 2026-11-01T06:30:00+00:00
229
229
  ```
230
230
 
231
- Canonical Time `deep` includes the pinned rule edition in `deep.timezone_database_version` and source-wall resolution in `deep.resolution`. Resolution records `kind` (`unique`, `overlap` or `gap`), the selected policy, signed `adjustment_seconds`, and chronological alternatives with exact `at`, Unix seconds and UTC offset. Unique times have an empty alternatives list. Explicit instants, current time and lookups without conversion have null resolution. Destination detail stays compact.
231
+ Canonical Time `deep` includes the pinned rule edition in `timezone_database_version` and source-wall resolution in `resolution`. Resolution records `kind` (`unique`, `overlap` or `gap`), the selected policy, signed `adjustment_seconds`, and chronological alternatives with exact `at`, Unix seconds and UTC offset. Unique times have an empty alternatives list. Explicit instants, current time and lookups without conversion omit resolution. Destination detail stays compact.
232
232
 
233
233
  Search serving IANA IDs by city or region, or omit the query to list all (Go and Rust use an empty string). Discovery returns `timezone_database_version` and sorted `timezones`. No search matches returns `timezones: []`.
234
234
 
@@ -255,13 +255,15 @@ Source deep adds `standard_offset`, `standard_offset_seconds`, signed `dst_offse
255
255
 
256
256
  ## Place statistics and optional detail
257
257
 
258
- Country Core contains the everyday reference: `name`, `name_full`, `name_local`, demonym, `iso_alpha3` and `iso_numeric` country identifiers, continent, region and subregion, currency, calling code, `flag`, language and timezone codes, borders, bloc memberships and `capital: { name, latitude, longitude }`. Paid Deep adds specialist detail, including population, total area and national statistics. `gdp_usd` and `gdp_per_capita_usd` are current US dollars; `population_growth_percent`, `urban_population_percent` and `internet_users_percent` use a 0–100 percent scale (growth can be negative or exceed 100). GDP per person and these three percentages round once to two decimals in the API response. `elevation_average` is average terrain elevation in meters; `lowest_point.elevation` and `highest_point.elevation` keep their point-specific meaning. Unknown stays null and a known zero stays zero. Country tax references are grouped once as `deep.tax: { name, rate }`; the rate remains a percentage. Read capital from the Core object and read the tax name and rate from the Deep tax object.
258
+ Country Core contains the everyday reference: `name`, `name_full`, `name_local`, demonym, `iso_alpha3` and `iso_numeric` country identifiers, continent, region and subregion, currency, calling code, `flag`, language and timezone codes, borders, bloc memberships and `capital: { name, latitude, longitude }`. Paid Deep adds specialist detail, including population, total area and national statistics. `gdp_usd` and `gdp_per_capita_usd` are current US dollars; `population_growth_percent`, `urban_population_percent` and `internet_users_percent` use a 0–100 percent scale (growth can be negative or exceed 100). GDP per person and these three percentages round once to two decimals in the API response. `elevation_average` is average terrain elevation in meters; `lowest_point.elevation` and `highest_point.elevation` keep their point-specific meaning. Unknown stays null and a known zero stays zero. Country tax references are grouped once as `tax: { name, rate }`; the rate remains a percentage. Read capital from the Core object and read optional tax references from `tax.name` and `tax.rate` on that same resource.
259
+
260
+ Country includes `postal_format` and `postal_regex` on every plan without requesting Deep. `postal_format` is an input hint based on one example, not a complete mask. `postal_regex` checks syntax, not whether a code exists or receives mail. Unavailable values are null.
259
261
 
260
262
  Australian postal lookups include core `localities` with suburb choices (`city`, `state`, `state_name`) on every plan. Null or an omitted field means unknown, while `[]` means the reviewed reference has no eligible choices. `city` stays null when the source is ambiguous, even if there is only one eligible choice. Let the user select their suburb and keep manual entry available. These are geographic choices, not mailing-address verification. [G-NAF source, adaptations and licence](https://parseapi.com/legal/attribution#postal-au).
261
263
 
262
- Postal paid profiles include compact `deep.property_tax: { annual_median }` where supported; `deep.currency` supplies the currency. District keeps the richer property-tax record with `annual_median`, `currency` and `period` (`YYYY-YYYY`). Both are area estimates of annual tax payable on owner-occupied homes, not a rate or an individual property bill. Unsupported, missing and censored estimates are null. Earlier nested currency and period values remain available when returned.
264
+ Postal paid Deep includes `currency`, `neighbors`, grouped `tax` and `property_tax: { annual_median }`. Property-tax amounts use `currency`. Tax contains `name`, `rate` and the `rate_state`, `rate_county`, `rate_city` and `rate_special` components in percent. Core provides the postal location answer.
263
265
 
264
- Weather minute forecasts use `precipitation_rate` (mm/hour) and `precipitation_rate_in` (inches/hour); update earlier minute field reads to those names. History `precipitation` and `precipitation_in` remain accumulated amounts. These clients return the server JSON directly, preserving null collections, known empty arrays and earlier payload keys without translating them.
266
+ District paid profiles include `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.
265
267
 
266
268
  ```python
267
269
  place = parse.postal("28202", country="US", deep=True)
@@ -274,7 +276,7 @@ Country deep includes `land_area` and `water_area` in km2, `coastline` in km, an
274
276
 
275
277
  Point returns the timezone ID with the core location. Its optional Deep adds terrain, compact nearest-city context and supported electoral detail on paid plans. Existing accounts retain their current Deep access. A nearest city is null when none is within 200 km.
276
278
 
277
- 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.
279
+ Weather returns current conditions by default. Paid deep adds specialist current measurements, forecasts and related detail. On a paid plan, a past `date` adds history for that UTC day alongside current conditions in API 2.1. Earlier contracts require an explicit detail request.
278
280
 
279
281
  ```python
280
282
  parse.weather(40.7128, -74.006, deep=True, date="2026-08-15")
@@ -290,29 +292,29 @@ Bank inputs use `POST /bank` JSON bodies, keeping IBAN and account values out of
290
292
 
291
293
  ## Deep
292
294
 
293
- Choose enrichment for the question you need answered.
295
+ Call the API and get everything your plan includes. API 2.1 paid plans include their profile detail automatically; Free returns the complete everyday answer. Existing explicit `deep` options remain supported for compatibility. Mailbox verification is a separate explicit operation. An omitted or false SDK `deep` option follows the plan default; `true` remains an explicit compatibility request.
294
296
 
295
- | Operation | What `deep` requests |
297
+ | Operation | Included data and explicit checks |
296
298
  |---|---|
297
299
  | IP | Richer IP fields included with a paid plan. No separate check meter. |
298
300
  | Domain | Registration dates, registrar, status and DNSSEC, included with a paid plan. Use `dns` for DNS records and `mx` for mail routing. |
299
- | Email | A metered mailbox check with deliverability, catch-all, status, reason and address hints, using included email checks or enabled on-demand usage. |
301
+ | Email | Basic validation is separate. Call the explicit verification method for a metered mailbox check. |
300
302
  | Phone, Time, Date, Emoji, Point | Optional detail on paid plans in the same pooled request. Existing accounts retain their current Deep access. |
301
- | Language | All language facts are in Core; requested Deep is empty. |
302
- | Currency | Currency lookup facts are complete in Core; requested Deep is empty. Lookup and exchange-rate conversion use pooled requests. |
303
- | Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
303
+ | Language | All language facts are in Core; Deep adds no fields. |
304
+ | Currency | Currency lookup facts are complete in Core; Deep adds no fields. Lookup and exchange-rate conversion use pooled requests. |
305
+ | Country, State, County, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
304
306
  | Name, Industry | Name evidence or the industry definition profile on paid plans. |
305
307
  | Company | The complete product detail bag on paid plans. |
306
308
  | Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
307
- | Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
309
+ | Carrier, HLR | The selected metered operation returns its complete result by default. No deep option is required. |
308
310
 
309
- 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.
311
+ Explicit Email verification 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.
310
312
 
311
313
  Reasons include `accepted`, `invalid_format`, `invalid_domain`, `no_mail_server`, `mailbox_not_found`, `mailbox_disabled`, `mailbox_full`, `catchall`, `disposable`, `temporary_failure`, `rejected` and `unconfirmed`.
312
314
 
313
315
  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.
314
316
 
315
- 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.
317
+ With `deep=true`, available extra fields appear at their natural resource homes. Without it, or without access, those optional fields are absent. Included unknown values remain null; false and zero retain their meanings. There is no `deep` response object.
316
318
 
317
319
  ```python
318
320
  ip = parse.ip("52.94.76.10", deep=True)
@@ -366,7 +368,7 @@ generic logo; a known network without reviewed artwork also uses the generic log
366
368
  Optional Deep adds `prefix`, `issuer`, `country`, `type` and `prepaid` on paid plans
367
369
  in the same pooled request. Existing accounts retain their current Deep access.
368
370
  Requested but locked Deep is `{}`. Six or more digits enable directory
369
- matching. With Deep access, fewer digits return all-null Deep fields. Compare `deep.prefix` with
371
+ matching. With Deep access, fewer digits return all-null Deep fields. Compare `prefix` with
370
372
  `bin`: equal is an exact recorded match; shorter is broader; null is no match.
371
373
  The longest row wins, including null fields. `prepaid: null` means unknown, not
372
374
  false. This is partial reference data, not card validity or payment acceptance.
@@ -375,7 +377,7 @@ false. This is partial reference data, not card validity or payment acceptance.
375
377
  card = parse.card("51")
376
378
  print(card["brand"], card["logo"])
377
379
  details = parse.card("43737400", deep=True)
378
- print(details["deep"]["prefix"], details["deep"]["issuer"])
380
+ print(details.get("prefix"), details.get("issuer"))
379
381
  ```
380
382
 
381
383
  Leading zeros are preserved. Only ASCII spaces, tabs, CR, LF and hyphens are
@@ -384,7 +386,7 @@ before dispatch, accepted input is forwarded unchanged. Never send a full card n
384
386
 
385
387
  ## Optional detail
386
388
 
387
- The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Company directory, Industry 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` or each `targets` item; only the source has `deep.next_dst`.
389
+ The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Company directory, Industry and Emoji searches put detail at the root of each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to` or each `targets` item; only the source has `next_dst`.
388
390
 
389
391
  ```python
390
392
  basic = parse.time("America/New_York")
@@ -403,7 +405,7 @@ Stack checks static homepage HTML and response headers. It returns the checked U
403
405
 
404
406
  `cms`, `servers`, `frameworks`, `ecommerce`, `analytics`, `chat`, `payments` and `hosting` are arrays because a site can use several technologies in each category. Each entry contains `technology`, `name` and nullable `version`. Technology codes are open strings. A successful check uses empty arrays for categories with no matches. When no HTML page could be checked, `checked_at` and all categories are null. Unknown or conflicting versions are null. Detections describe the checked homepage.
405
407
 
406
- Successful checks may be reused for up to 24 hours. `pretty` optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.0.0 selected by this client.
408
+ Successful checks may be reused for up to 24 hours. `pretty` optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.1.0 selected by this client.
407
409
 
408
410
  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.
409
411
 
@@ -422,17 +424,17 @@ GET /emoji/rocket
422
424
  ```
423
425
 
424
426
  Use `deep=true` for Unicode facts, keywords, tone families and available artwork.
425
- Artwork is keyed by style: `deep.artwork.openmoji.svg` is the SVG URL, and
426
- `deep.artwork.openmoji.png["72"]` is the 72×72 PNG URL (use your language’s map
427
+ Artwork is keyed by style: `artwork.openmoji.svg` is the SVG URL, and
428
+ `artwork.openmoji.png["72"]` is the 72×72 PNG URL (use your language’s map
427
429
  access syntax). The same shape applies to `noto` and `twemoji`. Missing styles
428
430
  and formats are omitted. URLs pin immutable artwork editions and retain their bytes.
429
431
  Core values stay unchanged. Text parsing returns `emojis` with UTF-16 `positions`;
430
432
  conversion returns `text` and unresolved tokens with positions and reasons.
431
433
 
432
434
  The compact JSON catalog contains offline identity, qualification-form and
433
- shortcode indexes. Request `profile=full` when artwork is needed and `lang` when
434
- localized names and keywords are needed. `/emoji/metadata` carries dataset
435
- coverage and shared source notices once. Artwork supports Google Noto, Twemoji
435
+ shortcode indexes. Use `lang` for localized names and keywords. Metadata and
436
+ shared source notices are included in the catalog. Read an individual emoji
437
+ with Deep for its artwork links. Artwork supports Google Noto, Twemoji
436
438
  and OpenMoji, with real SVG/PNG availability and immutable first-party URLs.
437
439
  A device's emoji font remains the ordinary display.
438
440
 
@@ -451,7 +453,7 @@ city = parse.city("Sakai", country="JP", state="27", grain="municipality",
451
453
 
452
454
  `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.
453
455
 
454
- 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.
456
+ 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.1.0; older responses can omit the new fields.
455
457
 
456
458
  ```python
457
459
  opts = dict(country="JP", min_population=100_000, sort="-population,+name",
@@ -478,13 +480,13 @@ Strict ambiguity returns HTTP 409. Catch `ParseAPIError` with `code == "ambiguou
478
480
 
479
481
  ## Canonical City operations
480
482
 
481
- 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.
483
+ Classic lookup, search, nearest and named-nearby methods retain their default envelopes and required-field models. Browse uses `cities` and coordinate-nearby uses `nearby`, with nullable `next_cursor` (camelCase properties in Swift/Kotlin). Keep all query options unchanged when continuing a page; no client fetches pages automatically.
482
484
 
483
485
  ```python
484
486
  page = parse.city.search('Viena', format='list', match='fuzzy', max_distance=1)
485
487
  ```
486
488
 
487
- 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.
489
+ Each route retains its default response. 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.
488
490
 
489
491
  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.
490
492
 
@@ -506,8 +508,32 @@ Coverage by country and available fields is described at https://parseapi.com/ci
506
508
 
507
509
  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.
508
510
 
511
+ IP paid Deep includes supported approximate location, `state_name`, `postal`, `latitude`, `longitude`, `timezone`, routed `network`, `asn_type` and public `proxy` status. Missing facts remain null. Coordinates describe range geography, not device GPS. `asn_type` classifies the origin network, not subscriber connection technology. Proxy/VPN false means unlisted. Optional fields are omitted without the requested detail or access.
512
+
509
513
  ## Capital coordinate migration
510
514
 
511
515
  Country and State capital coordinates use `latitude` and `longitude`. Update
512
516
  `capital.lat` and `capital.lon` reads to `capital.latitude` and
513
517
  `capital.longitude` when adopting this release.
518
+
519
+ ## API 2.1 upgrade
520
+
521
+ API 2.1 Time returns the clock first and the matched place in `location`. Read that place directly; `location.candidates` is for unresolved choices. Unused `resolution` is absent. City matches keep the match kind, text and language without the source category or spelling score. Holiday JSON keeps scope and completeness without calendar hashes; explicitly selected work-profile pins remain.
522
+
523
+ This client targets ParseAPI 2.1.0. Upgrading requires response-reader changes: optional detail now lives on its resource. Read `population` instead of `deep.population`. Deep remains an explicit request for optional detail. Without the request or access, optional fields are absent. A returned null still means unknown. User-Agent device, OS and browser are objects in every mode. Postal tax is one `tax` object. Specialist Weather measurements live in `current`. Metered Carrier and HLR return the complete purchased result without a Deep switch.
524
+
525
+ Use `parse.email_verify(email)` (sync and async) for mailbox verification. It sends POST `/email/verify` with `{ "email": "person@example.com" }` and defaults to no automatic retries. The earlier Email deep argument is accepted only as a migration alias for that same operation. App keys receive `permission_denied`. Bulk exports retain their existing column names and saved-job recovery.
526
+
527
+ The 2.0 API is a temporary migration bridge for older installed clients. There is one maintained SDK line using the 2.1 structure.
528
+
529
+ ## Upgrade to API 2.1
530
+
531
+ This version selects API `2.1.0`. Update existing `.deep` property reads to the fields at their natural homes, such as `country.population`. User-Agent identities are objects; Postal tax and Weather observations keep their documented object homes. Paid plans include their profile detail automatically in API 2.1. Free keeps its complete routine answer, and existing explicit `deep` options remain supported. Mailbox verification stays explicit.
532
+
533
+ **This minor version changes existing field reads.** Upgrade the SDK and your application reads together. Existing factories remain. Email verification is explicit and includes basic validation; Carrier/HLR need no extra detail request. Preserve missing values, `null`, `false` and `0`.
534
+
535
+ ## County migration: HTTP API 2.2
536
+
537
+ This source selects HTTP API `2.2.0`. County is the public name for counties and comparable administrative areas internationally. Use `county` and the State counties operation. Read `county`, `county_name`, `county_name_local` and `counties` in affected geography results; City `capital_of` uses `county` for this administrative level. Actual local types such as `department` and `district` retain their meaning.
538
+
539
+ This is a breaking field-read upgrade from earlier contracts. Deprecated District callable names remain source aliases, but SDK results use the canonical County fields. Update property reads before upgrading. Older installed packages keep their existing API contract, and this client does not change an account's saved default.