parseapi-mcp 1.12.3 → 1.13.0
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.
- package/README.md +52 -40
- package/dist/{chunk-W5DHLSD3.js → chunk-OY4MSQLL.js} +289 -466
- package/dist/http.js +1 -1
- package/dist/registry.js +1 -1
- package/dist/stdio.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
# parseapi-mcp
|
|
2
2
|
|
|
3
|
-
Official ParseAPI MCP server. Look up places, addresses,
|
|
3
|
+
Official ParseAPI MCP server. Look up places, addresses, companies, email, phone, weather, timezones, dates and more from your AI agent.
|
|
4
4
|
|
|
5
5
|
## Hosted
|
|
6
6
|
|
|
7
7
|
One URL, nothing to install. Add the server and sign in once in the browser. Free plan works.
|
|
8
8
|
|
|
9
|
+
The shared hosted service remains on API 2.0. Installing this package selects API 2.1 for your local server without changing the shared service.
|
|
10
|
+
|
|
9
11
|
```json
|
|
10
12
|
{
|
|
11
13
|
"mcpServers": {
|
|
@@ -38,7 +40,7 @@ CI and headless setups skip the browser with a key from [parseapi.com](https://p
|
|
|
38
40
|
"mcpServers": {
|
|
39
41
|
"parseAPI": {
|
|
40
42
|
"command": "npx",
|
|
41
|
-
"args": ["-y", "parseapi-mcp"],
|
|
43
|
+
"args": ["-y", "parseapi-mcp@1.13.0"],
|
|
42
44
|
"env": { "PARSEAPI_KEY": "your-api-key" }
|
|
43
45
|
}
|
|
44
46
|
}
|
|
@@ -47,7 +49,7 @@ CI and headless setups skip the browser with a key from [parseapi.com](https://p
|
|
|
47
49
|
|
|
48
50
|
## API versions
|
|
49
51
|
|
|
50
|
-
Since version 1.0.0, the package explicitly selects the API contract supported by this MCP package.
|
|
52
|
+
Since version 1.0.0, the package explicitly selects the API contract supported by this MCP package. This version sends `X-API-Version: 2.1.0` on every API tool request, matching its tool descriptions and SDK response types. The contract is fixed for local stdio and HTTP servers running this package, including retries. The shared hosted service remains on its existing API 2.0 release. Your key, OAuth identity and team's saved default stay the same. The API still accepts earlier `Parse-Version` request pins.
|
|
51
53
|
|
|
52
54
|
For local stdio, pin the MCP package version in your application configuration and test the new release before deploying it. A future major MCP upgrade can select a newer API contract. There is no version argument to add to individual tool calls. The hosted service uses the API contract supported by its deployed MCP release.
|
|
53
55
|
|
|
@@ -64,13 +66,13 @@ spellings. Use the existing lookup methods for each resource.
|
|
|
64
66
|
|
|
65
67
|
## Tools
|
|
66
68
|
|
|
67
|
-
Full mode provides
|
|
69
|
+
Full mode provides 65 local lookup tools and 64 hosted lookup tools, plus `discover` for local metadata and `preflight` for authenticated task estimates. `ip_self` is local only. `time` returns current local time and Unix seconds. It accepts a timezone or coordinates and defaults to UTC when both are omitted. `date` parses the supplied date, or returns today in UTC when omitted. Existing `timezone` calls remain supported with their original arguments. Every lookup returns the JSON the API serves.
|
|
68
70
|
|
|
69
|
-
Tools follow the lookup names: `country_states`, `city_search`, `postal_nearby`, `address`, `address_search`, `company`, `company_id`, `company_search`, `
|
|
71
|
+
Tools follow the lookup names: `country_states`, `city_search`, `postal_nearby`, `address`, `address_search`, `company`, `company_id`, `company_search`, `email`, `card`, `industry`, `industry_search`, `dns`, `asn`, `currency_rate`, and the rest. Text searches take `query`. Company directory search supports one name/domain/ticker/identifier selector or country/exact-SIC discovery filters.
|
|
70
72
|
|
|
71
73
|
The existing `naics` and `naics_search` tools remain available as compatibility names for Industry.
|
|
72
74
|
|
|
73
|
-
Industry paid deep records include classification `
|
|
75
|
+
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.
|
|
74
76
|
|
|
75
77
|
Example tool arguments:
|
|
76
78
|
|
|
@@ -85,10 +87,8 @@ Example tool arguments:
|
|
|
85
87
|
| `card` | `{"bin":"424242"}` |
|
|
86
88
|
| `country_states` | `{"code":"US"}` |
|
|
87
89
|
| `address_search` | `{"query":"1600 Pennsylvania","country":"US","city":"Washington","state":"DC"}` |
|
|
88
|
-
| `company` | `{"number":"552100554","country":"FR"}` |
|
|
89
90
|
| `company_search` | `{"query":"Cloudflare","country":"US"}` |
|
|
90
91
|
| `company_id` | `{"id":"co_xw3f22es6cjq","deep":true}` |
|
|
91
|
-
| `company_coverage` | `{}` |
|
|
92
92
|
| `time` | `{}` (UTC now) |
|
|
93
93
|
| `time` | `{"timezone":"America/New_York","at":"2026-09-05T09:00:00","to":"Asia/Tokyo"}` |
|
|
94
94
|
| `time` | `{"lat":40.71,"lon":-74.01}` |
|
|
@@ -97,40 +97,36 @@ Example tool arguments:
|
|
|
97
97
|
| `time` | `{"timezone":"America/New_York","at":"2026-11-01T01:30:00","to":"UTC","disambiguation":"later"}` |
|
|
98
98
|
| `date` | `{"date":"03/04/2026","format":"dmy"}` |
|
|
99
99
|
| `elevation` | `{"lat":35.2271,"lon":-80.8431}` |
|
|
100
|
-
| `elevation` | `{"points":"
|
|
101
|
-
| `elevation` | `{"path":"
|
|
102
|
-
|
|
103
|
-
Time uses `disambiguation` only for offsetless `at` with `to` or `targets`. The default `compatible` selects the earlier repeated time or advances a skipped time. `earlier` and `later` choose the respective instant. `reject` returns `ambiguous_time` for repeated times and `nonexistent_time` for skipped times. Prefer it for user-entered appointments. Ask for an explicit offset or the user's choice before retrying a rejected local time. Explicit offsets select an instant directly. Time Deep is available on paid plans in the same pooled request. Existing accounts retain their current Deep access.
|
|
100
|
+
| `elevation` | `{"points":"35.2271,-80.8431|40.7128,-74.006"}` |
|
|
101
|
+
| `elevation` | `{"path":"35.2271,-80.8431|35.5951,-82.5515","samples":100}` |
|
|
104
102
|
|
|
105
|
-
Time
|
|
103
|
+
Time uses `disambiguation` only for offsetless `at` with `to` or `targets`. The default `compatible` selects the earlier repeated time or advances a skipped time. `earlier` and `later` choose the respective instant. `reject` returns `ambiguous_time` for repeated times and `nonexistent_time` for skipped times. Prefer it for user-entered appointments. Ask for an explicit offset or the user's choice before retrying a rejected local time. Explicit offsets select an instant directly. Time deep is available in the same pooled request on every plan.
|
|
106
104
|
|
|
107
|
-
|
|
105
|
+
Time Deep includes `resolution` when a source wall time needs interpretation. Resolution reports `kind` (`unique`, `overlap` or `gap`), `policy`, signed `adjustment_seconds`, and chronological `alternatives` with exact local `at`, Unix seconds and UTC offset. Unique wall times have no alternatives. Explicit-offset timestamps, current clocks, non-conversion lookups and unknown source zones omit resolution.
|
|
108
106
|
|
|
109
|
-
|
|
107
|
+
Elevation accepts exactly one of `lat` and `lon`, `points`, or `path` with `samples`. A point list supports up to 512 coordinates as `lat,lon` pairs separated by `|`, or `enc:` followed by a Google encoded polyline, with at most 12000 characters. The `points` response array preserves input order and duplicate coordinates. Each sample includes meters, feet and grid resolution in meters. Unknown samples stay null. A list uses one pooled request, with JSON POST selected automatically for long URLs.
|
|
110
108
|
|
|
111
|
-
|
|
109
|
+
A path uses the same string formats with 2-512 vertices and a required integer `samples` count from 2 to 512. The response `points` include both endpoints, spaced uniformly by cumulative great-circle distance along the path. Each segment follows the shortest arc. A segment with antipodal endpoints is rejected because it does not define a unique arc. A path uses one pooled request. `samples` is invalid with a single coordinate or a point list.
|
|
112
110
|
|
|
113
111
|
Australian `postal` lookup returns core `localities` with suburb choices (`city`, `state`, `state_name`). Null or an omitted field means unknown, while `[]` means the reviewed reference has no eligible choices. A single choice can coexist with `city: null`. Ask for the user's suburb choice and preserve manual entry. These are geographic choices, not mailing-address verification. AU Postal tool results include a separate source notice after the JSON. [G-NAF source, adaptations and licence](https://parseapi.com/legal/attribution#postal-au).
|
|
114
112
|
|
|
115
|
-
Address lookup returns standardized components and registration status for the US and France. Its `deep` object is currently empty.
|
|
113
|
+
Address lookup returns standardized components and registration status for the US and France. Its `deep` object is currently empty. `address_search` also accepts `postal` and `ip` to narrow or rank matches. French search needs `country: "FR"` and either `postal` or `city`.
|
|
116
114
|
|
|
117
115
|
For the company directory, call `company_search` with at most one of `query`,
|
|
118
116
|
`domain`, `ticker` or `identifier`. Use `exchange` with a ticker and `authority`
|
|
119
117
|
with an identifier. Review the candidates, then pass the chosen `id` to
|
|
120
118
|
`company_id`. Send the returned `next` as `cursor` with the same selector,
|
|
121
|
-
filters and `limit` for another page. Directory
|
|
122
|
-
pooled request
|
|
119
|
+
filters and `limit` for another page. Directory Deep adds detail to each company result on paid plans in the same
|
|
120
|
+
pooled request. Existing accounts retain their current Deep access.
|
|
123
121
|
Selected website descriptions, logos, socials and founding claims are returned
|
|
124
122
|
where available. Logo URLs are returned without fetching images. Directory
|
|
125
|
-
tools do not accept `lang`.
|
|
126
|
-
|
|
127
|
-
|
|
123
|
+
tools do not accept `lang`. Empty listings do not establish private ownership. The `company` tool
|
|
124
|
+
remains listed for compatibility, but national-number lookups are retired on
|
|
125
|
+
the public API. Use `company_search` and `company_id` for maintained public-company records.
|
|
128
126
|
|
|
129
127
|
For discovery without an identity selector, supply `country` or both `industry` and `industry_type`. For example: `{ "country": "US", "industry": "0700", "industry_type": "sic" }`. SIC is the supported namespace; its exact four-digit code stays a string. Empty requests, incomplete industry pairs and multiple selectors are rejected. Country means the profile country. Filters intersect, unknown values do not match, and the same filters and limit must accompany a returned cursor. Filter-only candidates carry `match: { "field": "filters", "value": null }`.
|
|
130
128
|
|
|
131
129
|
|
|
132
|
-
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, not live verification.
|
|
133
|
-
|
|
134
130
|
Ordinary lookups retry up to twice after a transient failure. A valid `Retry-After` is honored when the wait is at most five seconds; longer waits return the API error immediately without retrying early. When the response supplies this header, the error includes `retry_after` with its original seconds or HTTP-date value. Metered lookups and address deep checks default to no retries. Cancelling a tool call cancels the pending SDK request.
|
|
135
131
|
|
|
136
132
|
Errors come back as JSON with a machine-readable `code`. Branch on `code`, never on message text. A miss is `not_found`. No key is `invalid_api_key`.
|
|
@@ -176,7 +172,7 @@ Set `PARSEAPI_KEY` in the process environment for lookups. Compact mode advertis
|
|
|
176
172
|
|
|
177
173
|
`lookup` uses the same input validation, cancellation, version pin, SDK and billing behavior as the named tools. It executes one operation and cannot run arbitrary code or request arbitrary URLs. Full mode is the default and preserves existing named lookup calls. The same process setting supports self-hosted HTTP.
|
|
178
174
|
|
|
179
|
-
The policy source is the API's `src/route/help/agent-catalog.json`.
|
|
175
|
+
The policy source is the API's `src/route/help/agent-catalog.json`. Mini guides contain ordinary HTTP instructions; MCP keeps the tool policies and schemas. Frozen API 1.0.0 help stays unchanged. In a ParseAPI workspace, run `npm run catalog:sync` to copy a reviewed policy change, then `npm run catalog:check`. An independent checkout can pass `-- --source /path/to/api`. Package builds use the checked-in copy and do not need the API checkout or a network request.
|
|
180
176
|
|
|
181
177
|
## Bulk files
|
|
182
178
|
|
|
@@ -234,11 +230,13 @@ MIT licensed.
|
|
|
234
230
|
|
|
235
231
|
## Optional detail
|
|
236
232
|
|
|
237
|
-
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 `
|
|
233
|
+
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.
|
|
234
|
+
|
|
235
|
+
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.
|
|
238
236
|
|
|
239
|
-
|
|
237
|
+
Make the ordinary tool call. API 2.1 paid plans include their profile detail automatically; Free returns the complete everyday answer. Existing `deep` inputs remain supported for compatibility. Time, Date, Emoji, Phone, Point and Card offer optional detail on paid plans; existing accounts retain their current Deep access. Language includes every reference fact in Core, and Deep adds no fields. Geographic profiles, Name evidence and NAICS definitions require a paid plan. Carrier and HLR detail stays inside the same metered core unit, including Free allowance units, with no additional charge or second gate.
|
|
240
238
|
|
|
241
|
-
Search detail belongs to each returned entity. Time conversion puts target display detail in `to
|
|
239
|
+
Search detail belongs to each returned entity. Time conversion puts target display detail in `to`; only the source returns `next_dst`. Name core parsing needs no dictionary lookup. Paid Name deep also returns flat `short`, `directory`, and `initials`. Optional `name_locale` selects CLDR formatting rules, defaults to `en`, and leaves parsing and gender context unchanged. Unavailable formatting is null, and older responses may omit these fields. Country, State and Postal tax references are in a root `tax` object when the optional detail is available.
|
|
242
240
|
|
|
243
241
|
## Stack API
|
|
244
242
|
|
|
@@ -252,7 +250,7 @@ Stack checks static homepage HTML and response headers. It returns the checked U
|
|
|
252
250
|
|
|
253
251
|
`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.
|
|
254
252
|
|
|
255
|
-
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.
|
|
253
|
+
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.
|
|
256
254
|
|
|
257
255
|
The `stack` tool allows 35 seconds per attempt for a first check. MCP cancellation still aborts the request.
|
|
258
256
|
|
|
@@ -264,10 +262,6 @@ Time `targets` accepts 1-10 destination IDs instead of `to`. Results retain the
|
|
|
264
262
|
`time_zones` can filter by country, IANA area, exact offset, abbreviation, DST at an instant or DST occurrence during the UTC calendar year. It preserves explicit false filters. `details` adds rich rows and the common evaluation instant, while the default identifier list remains compact. Abbreviations return candidate zones. Source deep exposes standard and signed seasonal offsets plus actual DST-season transition boundaries. Negative seasonal adjustments and null boundaries retain their meaning.
|
|
265
263
|
|
|
266
264
|
|
|
267
|
-
Bank tools send original IBAN, routing and account strings in POST JSON bodies, keeping account input out of URLs. `bank` retains optional country and deep controls. Deep directory evidence identifies the immutable source edition and actual match grain when a directory lookup ran; it does not prove country completeness or reachability. `bank_us_ach` takes routing/account strings and checks the ABA routing checksum plus account-field syntax. It has no deep option and cannot verify an account checksum, existence, ownership or ACH eligibility. Preserve all account characters and leading zeros. `bank_requirements` takes a country and optional format (`iban` by default, or `us_ach`) and returns accepted fields, check scope and limitations. Requirements are metadata, not bank coverage. Avoid logging tool arguments or request bodies containing banking input.
|
|
268
|
-
|
|
269
|
-
When US ACH returns a bank name, MCP includes a separate [routing reference attribution](https://parseapi.com/legal/attribution#routing-numbers) notice alongside the unchanged JSON result.
|
|
270
|
-
|
|
271
265
|
|
|
272
266
|
## Emoji catalog additions
|
|
273
267
|
|
|
@@ -283,14 +277,14 @@ GET /emoji/rocket
|
|
|
283
277
|
{"emoji":"🚀","name":"Rocket","shortcodes":[":rocket:","rocket"],"category":"Travel & Places"}
|
|
284
278
|
```
|
|
285
279
|
|
|
286
|
-
|
|
280
|
+
Paid plans include Unicode facts, keywords, tone families and available artwork automatically in API 2.1.
|
|
287
281
|
Core values stay unchanged. Text parsing returns `emojis` with UTF-16 `positions`;
|
|
288
282
|
conversion returns `text` and unresolved tokens with positions and reasons.
|
|
289
283
|
|
|
290
284
|
The compact JSON catalog contains offline identity, qualification-form and
|
|
291
|
-
shortcode indexes.
|
|
292
|
-
|
|
293
|
-
|
|
285
|
+
shortcode indexes. Use `lang` for localized names and keywords. Metadata and
|
|
286
|
+
shared source notices are included in the catalog. Read an individual emoji
|
|
287
|
+
with Deep for its artwork links. Artwork supports Google Noto, Twemoji
|
|
294
288
|
and OpenMoji, with real SVG/PNG availability and immutable first-party URLs.
|
|
295
289
|
A device's emoji font remains the ordinary display.
|
|
296
290
|
|
|
@@ -300,13 +294,13 @@ backend are published. Existing lookup and search contracts are preserved.
|
|
|
300
294
|
|
|
301
295
|
## Canonical City operations
|
|
302
296
|
|
|
303
|
-
Classic lookup, search, nearest and named-nearby methods retain their default envelopes and required-field models. Browse and coordinate-nearby
|
|
297
|
+
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.
|
|
304
298
|
|
|
305
299
|
```json
|
|
306
300
|
{"operation":"city_search","arguments":{"query":"Viena","format":"list","match":"fuzzy","max_distance":1}}
|
|
307
301
|
```
|
|
308
302
|
|
|
309
|
-
|
|
303
|
+
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.
|
|
310
304
|
|
|
311
305
|
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.
|
|
312
306
|
|
|
@@ -322,6 +316,8 @@ Coverage by country and available fields is described at https://parseapi.com/ci
|
|
|
322
316
|
|
|
323
317
|
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.
|
|
324
318
|
|
|
319
|
+
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.
|
|
320
|
+
|
|
325
321
|
## Capital coordinate migration
|
|
326
322
|
|
|
327
323
|
Country and State capital coordinates use `latitude` and `longitude`. Update
|
|
@@ -330,4 +326,20 @@ Country and State capital coordinates use `latitude` and `longitude`. Update
|
|
|
330
326
|
|
|
331
327
|
## Postal and Weather response corrections
|
|
332
328
|
|
|
333
|
-
|
|
329
|
+
In API 2.1, Postal `property_tax` contains `annual_median`; tax is grouped under `tax` with `name`, `rate` and component rates. Weather minute rows use `precipitation_rate` (mm/h) and `precipitation_rate_in` (in/h). Historical `history.precipitation` and `precipitation_in` remain daily totals. Unavailable Weather collections remain `null`; a known empty collection remains `[]`. MCP returns these API values unchanged. Existing clients reading the earlier minute keys must update those reads when using current API 2.1.0; frozen 1.0.0 is preserved.
|
|
330
|
+
|
|
331
|
+
## API 2.1 upgrade
|
|
332
|
+
|
|
333
|
+
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.
|
|
334
|
+
|
|
335
|
+
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.
|
|
336
|
+
|
|
337
|
+
Use the `email_verify` tool 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.
|
|
338
|
+
|
|
339
|
+
The 2.0 API is a temporary migration bridge for older installed clients. There is one maintained SDK line using the 2.1 structure.
|
|
340
|
+
|
|
341
|
+
## Upgrade to API 2.1
|
|
342
|
+
|
|
343
|
+
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 profile detail is automatic in API 2.1. Existing explicit depth requests remain supported; verification stays explicit.
|
|
344
|
+
|
|
345
|
+
**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`.
|