API 2.0.0

Location and identity stay in core. Population, area and the other statistical, regional and technical profile fields move into paid-plan deep. Country’s alternate identifiers and formal-name metadata move there too. Details previously returned in core are no longer included in a Free response.

country.population
state.area
city.elevation
district.population

// Request ?deep=true on a paid plan
country.deep.population
state.deep.area
city.deep.elevation
district.deep.population

API reference

Postal identity, place names, coordinates and timezone stay in core. Elevation, population, area, currency, tax fields, neighbors and metros move into paid-plan deep. Tax field names stay flat inside that bag. Neighbors remains an array of postal-code strings.

postal.population
postal.tax_rate
postal.neighbors
postal.metros

// Request ?deep=true on a paid plan
postal.deep.population
postal.deep.tax_rate
postal.deep.neighbors
postal.deep.metros

API reference

City search and nearby results put optional profiles in each city’s deep. State district lists put population in each district’s deep. Postal nearby puts metros in the origin’s deep and each result’s deep; Postal distance puts them in from.deep and to.deep. These profiles require paid deep. Distances and lookup context remain core; there is no extra charge per result.

cities[0].population
districts[0].population
from.metros

// Request ?deep=true on a paid plan
cities[0].deep.population
districts[0].deep.population
from.deep.metros

API reference

Population has a nullable population_period in Continent core and the paid geography profiles, including State district-list detail. Full US Postal and District paid deep add nullable property_tax with annual_median, currency and period: median annual tax on owner-occupied housing for the ZIP area or county, not an individual property bill. Compact nearby/distance responses do not include it. Missing observations stay null.

continent.population_period
postal.deep.population_period
postal.deep.property_tax // { annual_median, currency, period } or null

API reference

Country, State, City, Language, Holiday and Point’s city record rename local_name to name_local. The value is null when absent or identical to the primary name. Use name_local ?? name for display. Postal keeps city_local, state_name_local and district_name_local.

place.local_name ?? place.name
holiday.local_name ?? holiday.name

place.name_local ?? place.name
holiday.name_local ?? holiday.name

API reference

The timezone identifier moves to core and is determined at the input coordinates. Elevation, elevation_ft and resolution move to deep, included on every plan. The full nested time response is removed; deep.city becomes compact nearest-city context, not a full City profile. Use Time or City for those separate answers.

point.elevation
point.deep.timezone.timezone
point.deep.city.population

point.timezone
point.deep.elevation // ?deep=true, every plan
// Read a full city profile through /city with its own deep option

API reference

Parsing, validity, country, type and national/international formatting stay in core. State, state_name and timezone move into deep, included on every plan. The timezone still describes the numbering area, not the handset’s location.

phone.state
phone.state_name
phone.timezone

// Request ?deep=true
phone.deep.state
phone.deep.state_name
phone.deep.timezone

API reference

Carrier, line type and burner classification stay in core. City, state and state_name move to deep. Requesting that detail uses the same Carrier unit, including a Free allowance unit; it does not make another lookup or add a paid-plan gate.

carrier.city
carrier.state
carrier.state_name

// Request ?deep=true; same Carrier unit
carrier.deep.city
carrier.deep.state
carrier.deep.state_name

API reference

Core is phone, valid, country, live and connected. Roaming, roaming_network, roaming_country, network, original_network, mcc and mnc move to deep, included in the same HLR unit on every plan. Public checked_at is removed entirely. Verdict meanings and reuse behavior remain unchanged.

hlr.network
hlr.mcc
hlr.checked_at

// Request ?deep=true; same HLR unit
hlr.deep.network
hlr.deep.mcc
// checked_at is no longer returned

API reference

Gender and salutation move to paid deep alongside known and countries; expanded name evidence can change their values. Optional country must be two letters and affects evidence only, not parsing or the returned country list. A known name can have null gender; an exact compound’s null result does not borrow its first token’s gender. Single Han/Hangul names and leading-apostrophe spellings are now accepted, and display-direction controls are removed. Unknown names are distinct from an unavailable evidence lookup: the latter returns 503 for paid deep while core parsing remains available. Country associations do not establish nationality.

name.gender
name.salutation

// Request ?deep=true on a paid plan
name.deep.gender
name.deep.salutation
name.deep.known
name.deep.countries

API reference

Populated verification deep contains deliverable and catchall. The public deep.checked_at field is removed. Core email parsing and classification, verification billing and reuse behavior retain their existing purpose.

email.deep.deliverable
email.deep.catchall
email.deep.checked_at

email.deep.deliverable
email.deep.catchall
// deep.checked_at is no longer returned

API reference

Domain core remains domain and available. Paid deep contains registration only. The former a, aaaa, ns, mx, txt and mailhost fields are removed from Domain deep. Use DNS for records and MX for mail routing. Registration checks that cannot establish availability return null.

domain.deep.registration
domain.deep.mx
domain.deep.mailhost

domain.deep.registration
// Use /dns/{domain} for records
// Use /mx/{domain} for mail routing

API reference

Core keeps registration identity and address. Activity, state_name, country_name, vat, gst, acn, siren, siege, kind and invoice move to paid deep. The old deep.country, deep.postal and deep.city records are removed entirely. Use the dedicated geography APIs for those records; adding deep does not restore the embedded responses.

company.activity
company.vat
company.deep.country
company.deep.postal
company.deep.city

// Request ?deep=true on a paid plan
company.deep.activity
company.deep.vat
// Read related places through their dedicated APIs

VIN, validity, year, make, model, trim, body and type stay in core. Series, doors, cylinders, displacement, fuel, horsepower, drive, transmission, manufacturer, plant location and gvwr join recalls in paid deep. A Free response no longer includes those former core specifications.

vin.doors
vin.fuel
vin.manufacturer

// Request ?deep=true on a paid plan
vin.deep.doors
vin.deep.fuel
vin.deep.manufacturer

API reference

Provider identity, credentials, specialty, practice contact, active status and excluded remain core. Deactivated_at moves into the existing paid Medicare/enrollment deep bag. An exclusion value of false remains a limited lookup result, not a clearance.

npi.deactivated_at
npi.excluded

npi.deep.deactivated_at // ?deep=true on a paid plan
npi.excluded

API reference

The normalized IBAN, validity, country, formatted value, bank, bank_name and bic remain core. Checksum digits, branch and account structure move to deep, included on every plan. The validity check still runs without deep.

iban.checksum
iban.branch
iban.account

// Request ?deep=true
iban.deep.checksum
iban.deep.branch
iban.deep.account

API reference

Code, description, lineage, general duty and revision remain core. Units, special and other move into paid deep. Deep can now return schedule detail without origin; origin-dependent effective_rate and measures remain null until origin is supplied. Conditional rates are not turned into an invented single percentage.

tariff.units
tariff.special
tariff.other

// Request ?deep=true on a paid plan
tariff.deep.units
tariff.deep.special
tariff.deep.other

API reference

Core is date, valid and unix. Year, month, weekday, week, week_year, quarter, leap and the other calendar facts move to deep, included on every plan. A requested date distance still returns to and days in core; it does not require deep.

date.year
date.weekday
date.week_year

// Request ?deep=true
date.deep.year
date.deep.weekday
date.deep.week_year

API reference

Currency keeps code, name, symbol, symbol_native and digits; numeric, name_plural and countries move to deep. Language keeps code, names, script and direction; iso3 and countries move to deep. Both detail bags are included on every plan. Currency conversion is unchanged.

currency.numeric
currency.countries
language.iso3

// Request ?deep=true
currency.deep.numeric
currency.deep.countries
language.deep.iso3

API reference

Emoji, name, shortcodes and category stay in core. Codepoints, hex, status, version, keywords and the complete skins array move to deep, included on every plan. Search uses the same projection for each result; read that result’s deep rather than expecting one shared bag.

emoji.codepoints
emoji.skins
results[0].keywords

// Request ?deep=true
emoji.deep.codepoints
emoji.deep.skins
results[0].deep.keywords

API reference

Dewpoint, wind gust, pressure and visibility, with their paired units, move from current to paid deep.current. Temperature, feels-like, humidity, wind speed/direction, conditions, observed_at and station remain core. The public source object is removed entirely; required attribution remains available.

weather.current.pressure
weather.current.wind_gust
weather.source

// Request ?deep=true on a paid plan
weather.deep.current.pressure
weather.deep.current.wind_gust
// source is no longer returned

API reference

Existing /timezone lookups in 2.0.0 return timezone, at, unix, offset, abbreviation and dst in core. Name, numeric offsets and next_dst belong in deep, included on every plan. Converted targets include the same instant as at and unix, with display detail in to.deep. The new /time route uses this contract on both supported API versions.

timezone.name
timezone.offset_minutes
timezone.next_dst

// Request ?deep=true
timezone.at
timezone.unix
timezone.deep.name
timezone.deep.offset_minutes
timezone.deep.next_dst

API reference

The 2.0.0 /timezone contract rejects impossible calendar dates and non-ISO at values; use two-digit hours and UTC years 0001 through 9999. Historical offsets can include seconds: deep.offset_minutes truncates toward zero, while deep.offset_seconds preserves the exact value. Coordinate lookups now honor and validate to. DST follows the zone’s actual rule, including negative seasonal adjustments. A repeated local time chooses the earlier instant unless an explicit offset identifies the later one; skipped local times resolve forward by the gap.

at=2026-02-29 // could normalize to another date
at=3/4/2026 // permissive date parsing

at=2026-02-28T12:00:00Z // valid ISO input
// Impossible dates and non-ISO values return invalid_request

API reference

Autocomplete adds a nullable reason: more_input, missing_context, no_matches or null, and echoes an explicit country. Treat reason as an open string and use it as a hint. Unavailable search data or a service failure returns service_unavailable with HTTP 503 rather than looking like a successful empty search. Handle that error separately from an honest no-match response.

// An empty suggestions list could also hide a service failure

// Successful empty search: inspect reason
// Service failure: handle HTTP 503 / service_unavailable

API reference

Carrier, HLR, Country lookup, State lookup/district lists, District, City lookup/search/ID/nearby and Postal distance/nearby now accept only literal deep=true. A formerly ignored deep=false on those operations returns 400; omit deep for core. This is operation-specific: Currency, Emoji and Language still accept false, while Phone, Date, Point, full Postal and Timezone already enforced true-only.

// On the newly validated operations
?deep=false // ignored

?deep=true // request detail
// Omit deep for core; deep=false returns HTTP 400 on these operations

API reference

This release adds BIN prefix lookup, NAICS lookup/search, DNS records, Measurement and Time to both supported versions. They do not require a switch to 2.0.0. NAICS keeps hierarchy and match context in core, with description, children and exclusions in paid deep. Version selection does not enable unreleased endpoints.

API reference

Both versions use current mail-routing and domain-registration observations. Public errors retain code, message, docs and request_id while private failure details stay private. An explicit User-Agent string is interpreted without borrowing the calling browser’s hints. VAT keeps registry-provided consultation timestamps, with unknown times null. These maintained corrections do not require a major-version switch; a contract version is not a historical copy of the data.

API reference