parseapi 1.11.3__tar.gz → 1.12.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 (77) hide show
  1. {parseapi-1.11.3 → parseapi-1.12.0}/CHANGELOG.md +8 -0
  2. {parseapi-1.11.3 → parseapi-1.12.0}/PKG-INFO +63 -42
  3. {parseapi-1.11.3 → parseapi-1.12.0}/README.md +62 -41
  4. {parseapi-1.11.3 → parseapi-1.12.0}/api/public.json +134 -184
  5. {parseapi-1.11.3 → parseapi-1.12.0}/pyproject.toml +1 -1
  6. {parseapi-1.11.3 → parseapi-1.12.0}/src/parseapi/__init__.py +1 -1
  7. {parseapi-1.11.3 → parseapi-1.12.0}/src/parseapi/_client.py +68 -86
  8. parseapi-1.12.0/tests/fixtures/core-connectors.json +251 -0
  9. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/country-aq.json +30 -32
  10. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/country-corrected.json +43 -45
  11. parseapi-1.12.0/tests/fixtures/country-de.json +93 -0
  12. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/emoji-artwork.json +37 -39
  13. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/emoji-catalog.json +7 -9
  14. parseapi-1.12.0/tests/fixtures/ip-deep-expansion.json +26 -0
  15. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/iso-contract.json +42 -10
  16. parseapi-1.12.0/tests/fixtures/noise-approved.json +654 -0
  17. parseapi-1.12.0/tests/fixtures/postal-weather.json +66 -0
  18. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-company-profile.json +5 -7
  19. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-emoji-catalog.json +5 -7
  20. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-provider.json +8 -10
  21. parseapi-1.12.0/tests/fixtures/response-fixtures/clean-time.json +76 -0
  22. parseapi-1.12.0/tests/fixtures/response-fixtures/standard-company-profile.json +15 -0
  23. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/standard-emoji-catalog.json +5 -7
  24. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/standard-provider.json +8 -10
  25. parseapi-1.12.0/tests/fixtures/response-fixtures/standard-time.json +82 -0
  26. parseapi-1.12.0/tests/fixtures/time-compact.json +2744 -0
  27. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_city_canonical.py +16 -16
  28. parseapi-1.12.0/tests/test_city_compact.py +18 -0
  29. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_city_query_parity.py +5 -6
  30. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_client.py +24 -2
  31. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_company_directory.py +6 -8
  32. parseapi-1.12.0/tests/test_core_connectors.py +25 -0
  33. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_country_corrected.py +11 -11
  34. parseapi-1.12.0/tests/test_domain_nullability.py +23 -0
  35. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_emoji.py +8 -8
  36. parseapi-1.12.0/tests/test_ip_deep_expansion.py +12 -0
  37. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_iso_contract.py +1 -0
  38. parseapi-1.12.0/tests/test_natural_contract.py +49 -0
  39. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_postal_weather.py +3 -3
  40. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_response_decoding.py +16 -1
  41. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_stack.py +1 -1
  42. parseapi-1.12.0/tests/test_time_compact.py +23 -0
  43. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_version.py +2 -1
  44. parseapi-1.11.3/tests/fixtures/country-de.json +0 -95
  45. parseapi-1.11.3/tests/fixtures/postal-weather.json +0 -75
  46. parseapi-1.11.3/tests/fixtures/response-fixtures/clean-time.json +0 -78
  47. parseapi-1.11.3/tests/fixtures/response-fixtures/standard-company-profile.json +0 -17
  48. parseapi-1.11.3/tests/fixtures/response-fixtures/standard-time.json +0 -84
  49. {parseapi-1.11.3 → parseapi-1.12.0}/.github/workflows/publish.yml +0 -0
  50. {parseapi-1.11.3 → parseapi-1.12.0}/.github/workflows/test.yml +0 -0
  51. {parseapi-1.11.3 → parseapi-1.12.0}/.gitignore +0 -0
  52. {parseapi-1.11.3 → parseapi-1.12.0}/LICENSE +0 -0
  53. {parseapi-1.11.3 → parseapi-1.12.0}/scripts/public_api.py +0 -0
  54. {parseapi-1.11.3 → parseapi-1.12.0}/smoke/smoke.py +0 -0
  55. {parseapi-1.11.3 → parseapi-1.12.0}/src/parseapi/city.py +0 -0
  56. {parseapi-1.11.3 → parseapi-1.12.0}/src/parseapi/py.typed +0 -0
  57. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/measure-response.json +0 -0
  58. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-company-coverage.json +0 -0
  59. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-emoji-metadata.json +0 -0
  60. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-tariff-search.json +0 -0
  61. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-tariff.json +0 -0
  62. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/clean-timezones.json +0 -0
  63. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/standard-company-coverage.json +0 -0
  64. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/standard-emoji-metadata.json +0 -0
  65. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/standard-tariff-search.json +0 -0
  66. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/standard-tariff.json +0 -0
  67. {parseapi-1.11.3 → parseapi-1.12.0}/tests/fixtures/response-fixtures/standard-timezones.json +0 -0
  68. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_card_dx.py +0 -0
  69. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_city_quality.py +0 -0
  70. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_email_enrichment.py +0 -0
  71. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_language.py +0 -0
  72. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_name_formatting.py +0 -0
  73. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_postal_localities.py +0 -0
  74. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_public_api.py +0 -0
  75. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_time_complete.py +0 -0
  76. {parseapi-1.11.3 → parseapi-1.12.0}/tests/test_time_gaps.py +0 -0
  77. {parseapi-1.11.3 → parseapi-1.12.0}/tests/typing_company_directory.py +0 -0
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.12.0 — 2026-11-02
4
+
5
+ - Select API `2.1.0` through the existing client factory. Requested profile detail uses natural field homes instead of a response `.deep` bag.
6
+ - **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.
7
+ - Use explicit Email verification; Carrier/HLR return their complete selected result. Preserve recorded Form/Bulk contracts and earlier saved results.
8
+ - 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.
9
+ - Keep optional fields absent when unrequested/unavailable and preserve `null`, `false` and `0`. See the API 2.1 upgrade section in the README.
10
+
3
11
  ## 1.11.3 — 2026-11-01
4
12
 
5
13
  - Correct Point and optional Deep documentation to describe existing access. Language facts remain in Core; request behavior and response JSON are unchanged.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: parseapi
3
- Version: 1.11.3
3
+ Version: 1.12.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,13 @@ 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
+ This SDK explicitly selects the API contract supported by this SDK. It sends `X-API-Version: 2.1.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
40
 
41
41
  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
42
 
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.
43
+ 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
44
 
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).
45
+ 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
46
 
47
47
  ## Weather from a postal code
48
48
 
@@ -64,7 +64,7 @@ Pass `country` when a postal code or national phone number needs disambiguation.
64
64
 
65
65
  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
66
 
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.
67
+ 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
68
 
69
69
  ## Company directory
70
70
 
@@ -78,22 +78,23 @@ if candidates["next"] is not None:
78
78
  next_page = parse.company.search(
79
79
  query="GitLab", country="US", limit=5, cursor=candidates["next"]
80
80
  )
81
- coverage = parse.company.coverage()
82
81
  ```
83
82
 
84
83
  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
84
 
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.
85
+ 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
86
 
88
- 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.
87
+ The public-directory service retires national-number Company lookups in both API versions. Use the directory methods with API 2.1.0.
89
88
 
90
- 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.
89
+ 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
90
 
92
- `AsyncParseAPI` exposes the same `company`, `company.id`, `company.search` and `company.coverage` calls with `await`.
91
+ 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.
92
+
93
+ `AsyncParseAPI` exposes the same `company`, `company.id` and `company.search` calls with `await`.
93
94
 
94
95
  Discovery example: `parse.company.search(country="US", industry="0700", industry_type="sic")`
95
96
 
96
- 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.
97
+ 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.
97
98
 
98
99
 
99
100
  ## ISO identifiers
@@ -129,7 +130,6 @@ parse.company.id("co_caczn6wf36hj", deep=True)
129
130
  parse.company.search(domain="about.gitlab.com")
130
131
  parse.company.search(ticker="GTLB", exchange="Nasdaq")
131
132
  parse.company.search(identifier="0001653482", authority="sec")
132
- parse.company.coverage()
133
133
  parse.city("charlotte", country="US")
134
134
  parse.city.id("city_mb8mbqrkz8zb")
135
135
  parse.city.search("char", country="US", limit=10)
@@ -174,7 +174,7 @@ parse.emoji.search("fire")
174
174
 
175
175
  The existing NAICS lookup and search methods remain available as compatibility names for Industry.
176
176
 
177
- 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.
177
+ 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.
178
178
 
179
179
  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.
180
180
 
@@ -191,7 +191,7 @@ async with AsyncParseAPI("your-api-key") as parse:
191
191
  country = await parse.country("US")
192
192
  ```
193
193
 
194
- 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.
194
+ 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.
195
195
 
196
196
  ## Display language
197
197
 
@@ -207,7 +207,7 @@ The next call keeps its usual default unless it also supplies `lang`. Existing `
207
207
 
208
208
  ## Time
209
209
 
210
- `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.
210
+ `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.
211
211
 
212
212
  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.
213
213
 
@@ -226,7 +226,7 @@ result = parse.time("America/New_York", at="2026-11-01T01:30:00",
226
226
  print(result["to"]["at"]) # 2026-11-01T06:30:00+00:00
227
227
  ```
228
228
 
229
- 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.
229
+ 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.
230
230
 
231
231
  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: []`.
232
232
 
@@ -253,13 +253,15 @@ Source deep adds `standard_offset`, `standard_offset_seconds`, signed `dst_offse
253
253
 
254
254
  ## Place statistics and optional detail
255
255
 
256
- 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.
256
+ 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.
257
+
258
+ 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.
257
259
 
258
260
  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).
259
261
 
260
- 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.
262
+ 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.
261
263
 
262
- 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.
264
+ 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.
263
265
 
264
266
  ```python
265
267
  place = parse.postal("28202", country="US", deep=True)
@@ -272,7 +274,7 @@ Country deep includes `land_area` and `water_area` in km2, `coastline` in km, an
272
274
 
273
275
  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.
274
276
 
275
- 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.
277
+ 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.
276
278
 
277
279
  ```python
278
280
  parse.weather(40.7128, -74.006, deep=True, date="2026-08-15")
@@ -288,29 +290,29 @@ Bank inputs use `POST /bank` JSON bodies, keeping IBAN and account values out of
288
290
 
289
291
  ## Deep
290
292
 
291
- Choose enrichment for the question you need answered.
293
+ 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.
292
294
 
293
- | Operation | What `deep` requests |
295
+ | Operation | Included data and explicit checks |
294
296
  |---|---|
295
297
  | IP | Richer IP fields included with a paid plan. No separate check meter. |
296
298
  | Domain | Registration dates, registrar, status and DNSSEC, included with a paid plan. Use `dns` for DNS records and `mx` for mail routing. |
297
- | Email | A metered mailbox check with deliverability, catch-all, status, reason and address hints, using included email checks or enabled on-demand usage. |
299
+ | Email | Basic validation is separate. Call the explicit verification method for a metered mailbox check. |
298
300
  | Phone, Time, Date, Emoji, Point | Optional detail on paid plans in the same pooled request. Existing accounts retain their current Deep access. |
299
- | Language | All language facts are in Core; requested Deep is empty. |
300
- | Currency | Currency metadata on paid plans; lookup and exchange-rate conversion use pooled requests. |
301
+ | Language | All language facts are in Core; Deep adds no fields. |
302
+ | Currency | Currency lookup facts are complete in Core; Deep adds no fields. Lookup and exchange-rate conversion use pooled requests. |
301
303
  | Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
302
304
  | Name, Industry | Name evidence or the industry definition profile on paid plans. |
303
305
  | Company | The complete product detail bag on paid plans. |
304
306
  | Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
305
- | Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
307
+ | Carrier, HLR | The selected metered operation returns its complete result by default. No deep option is required. |
306
308
 
307
- 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.
309
+ 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.
308
310
 
309
311
  Reasons include `accepted`, `invalid_format`, `invalid_domain`, `no_mail_server`, `mailbox_not_found`, `mailbox_disabled`, `mailbox_full`, `catchall`, `disposable`, `temporary_failure`, `rejected` and `unconfirmed`.
310
312
 
311
313
  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.
312
314
 
313
- 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.
315
+ 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.
314
316
 
315
317
  ```python
316
318
  ip = parse.ip("52.94.76.10", deep=True)
@@ -361,9 +363,10 @@ and a CDN SVG `logo`. Brand detection uses reviewed network rules independently
361
363
  of issuer records. Unknown or ambiguous prefixes return null brand fields and a
362
364
  generic logo; a known network without reviewed artwork also uses the generic logo.
363
365
 
364
- Optional Deep adds `prefix`, `issuer`, `country`, `type` and `prepaid`, included
365
- in the same pooled request on every plan. Six or more digits enable directory
366
- matching. Fewer digits return all-null Deep fields. Compare `deep.prefix` with
366
+ Optional Deep adds `prefix`, `issuer`, `country`, `type` and `prepaid` on paid plans
367
+ in the same pooled request. Existing accounts retain their current Deep access.
368
+ Requested but locked Deep is `{}`. Six or more digits enable directory
369
+ matching. With Deep access, fewer digits return all-null Deep fields. Compare `prefix` with
367
370
  `bin`: equal is an exact recorded match; shorter is broader; null is no match.
368
371
  The longest row wins, including null fields. `prepaid: null` means unknown, not
369
372
  false. This is partial reference data, not card validity or payment acceptance.
@@ -372,7 +375,7 @@ false. This is partial reference data, not card validity or payment acceptance.
372
375
  card = parse.card("51")
373
376
  print(card["brand"], card["logo"])
374
377
  details = parse.card("43737400", deep=True)
375
- print(details["deep"]["prefix"], details["deep"]["issuer"])
378
+ print(details.get("prefix"), details.get("issuer"))
376
379
  ```
377
380
 
378
381
  Leading zeros are preserved. Only ASCII spaces, tabs, CR, LF and hyphens are
@@ -381,7 +384,7 @@ before dispatch, accepted input is forwarded unchanged. Never send a full card n
381
384
 
382
385
  ## Optional detail
383
386
 
384
- 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`.
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 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`.
385
388
 
386
389
  ```python
387
390
  basic = parse.time("America/New_York")
@@ -400,7 +403,7 @@ Stack checks static homepage HTML and response headers. It returns the checked U
400
403
 
401
404
  `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.
402
405
 
403
- 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.
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.1.0 selected by this client.
404
407
 
405
408
  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.
406
409
 
@@ -419,17 +422,17 @@ GET /emoji/rocket
419
422
  ```
420
423
 
421
424
  Use `deep=true` for Unicode facts, keywords, tone families and available artwork.
422
- Artwork is keyed by style: `deep.artwork.openmoji.svg` is the SVG URL, and
423
- `deep.artwork.openmoji.png["72"]` is the 72×72 PNG URL (use your language’s map
425
+ Artwork is keyed by style: `artwork.openmoji.svg` is the SVG URL, and
426
+ `artwork.openmoji.png["72"]` is the 72×72 PNG URL (use your language’s map
424
427
  access syntax). The same shape applies to `noto` and `twemoji`. Missing styles
425
428
  and formats are omitted. URLs pin immutable artwork editions and retain their bytes.
426
429
  Core values stay unchanged. Text parsing returns `emojis` with UTF-16 `positions`;
427
430
  conversion returns `text` and unresolved tokens with positions and reasons.
428
431
 
429
432
  The compact JSON catalog contains offline identity, qualification-form and
430
- shortcode indexes. Request `profile=full` when artwork is needed and `lang` when
431
- localized names and keywords are needed. `/emoji/metadata` carries dataset
432
- coverage and shared source notices once. Artwork supports Google Noto, Twemoji
433
+ shortcode indexes. Use `lang` for localized names and keywords. Metadata and
434
+ shared source notices are included in the catalog. Read an individual emoji
435
+ with Deep for its artwork links. Artwork supports Google Noto, Twemoji
433
436
  and OpenMoji, with real SVG/PNG availability and immutable first-party URLs.
434
437
  A device's emoji font remains the ordinary display.
435
438
 
@@ -448,7 +451,7 @@ city = parse.city("Sakai", country="JP", state="27", grain="municipality",
448
451
 
449
452
  `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.
450
453
 
451
- 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.
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.1.0; older responses can omit the new fields.
452
455
 
453
456
  ```python
454
457
  opts = dict(country="JP", min_population=100_000, sort="-population,+name",
@@ -475,13 +478,13 @@ Strict ambiguity returns HTTP 409. Catch `ParseAPIError` with `code == "ambiguou
475
478
 
476
479
  ## Canonical City operations
477
480
 
478
- 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.
481
+ 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.
479
482
 
480
483
  ```python
481
484
  page = parse.city.search('Viena', format='list', match='fuzzy', max_distance=1)
482
485
  ```
483
486
 
484
- 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.
487
+ 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.
485
488
 
486
489
  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.
487
490
 
@@ -503,8 +506,26 @@ Coverage by country and available fields is described at https://parseapi.com/ci
503
506
 
504
507
  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.
505
508
 
509
+ 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.
510
+
506
511
  ## Capital coordinate migration
507
512
 
508
513
  Country and State capital coordinates use `latitude` and `longitude`. Update
509
514
  `capital.lat` and `capital.lon` reads to `capital.latitude` and
510
515
  `capital.longitude` when adopting this release.
516
+
517
+ ## API 2.1 upgrade
518
+
519
+ 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.
520
+
521
+ 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.
522
+
523
+ 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.
524
+
525
+ The 2.0 API is a temporary migration bridge for older installed clients. There is one maintained SDK line using the 2.1 structure.
526
+
527
+ ## Upgrade to API 2.1
528
+
529
+ 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.
530
+
531
+ **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`.