{
  "service": "postal",
  "title": "Postal API",
  "description": "Postal / ZIP lookup, distance, and nearby. Country is optional when the code exists in exactly one covered country.",
  "endpoints": {
    "lookup": "GET /postal/{code}?country={country}",
    "distance": "GET /postal/{code}/distance/{other}?country={country}",
    "nearby": "GET /postal/{code}/nearby?country={country}&radius={n}"
  },
  "examples": {
    "basic": "/postal/33139?country=US",
    "charlotte": "/postal/28202?country=US",
    "milwaukee": "/postal/53202?country=US",
    "territory": "/postal/00901?country=PR",
    "bare_gb": "/postal/SW1A 1AA",
    "japan": "/postal/100-0001?country=JP",
    "brazil": "/postal/01001-000?country=BR",
    "faroe": "/postal/100?country=FO",
    "monaco": "/postal/98000?country=MC",
    "morocco": "/postal/22052?country=MA",
    "peru": "/postal/01131?country=PE",
    "north_macedonia": "/postal/1220?country=MK",
    "moldova": "/postal/2000?country=MD",
    "distance": "/postal/28202/distance/10001?country=US",
    "nearby": "/postal/28202/nearby?country=US&radius=40",
    "nearby_mi": "/postal/28202/nearby?country=US&radius=25&unit=mi",
    "albania": "/postal/1501?country=AL",
    "guernsey": "/postal/GY10 1AA?country=GG",
    "jersey": "/postal/JE1 0BD?country=JE",
    "isle_of_man": "/postal/IM1 1AD?country=IM",
    "deep": "/postal/33139?country=US&deep=true",
    "property_tax": "/postal/28202?country=US&deep=true"
  },
  "response": {
    "postal": "Postal or ZIP code",
    "city": "Primary city name (English or romanized when available, native locale otherwise)",
    "city_local": "Native-locale city name (null when absent or same as city)",
    "district": "District code (US county FIPS, FR INSEE department, GB GSS)",
    "district_name": "District / ADM2 name (English or romanized when available, native locale otherwise)",
    "district_name_local": "Native-locale district name (null when absent or same as the original district_name before lang is applied)",
    "state": "State or province code",
    "state_name": "State or province name (English or romanized when available, native locale otherwise)",
    "state_name_local": "Native-locale state or province name (null when absent or same as the original state_name before lang is applied)",
    "country": "ISO2 country code",
    "country_name": "Country name",
    "latitude": "Approximate latitude",
    "longitude": "Approximate longitude",
    "timezone": "Timezone identifier",
    "deep": "With ?deep=true: paid profile, or {} when the plan is locked; omitted otherwise"
  },
  "metros": {
    "code": "Five-digit statistical-area code",
    "name": "Statistical-area name",
    "type": "metropolitan or micropolitan",
    "share": "Fraction of all addresses in the ZIP associated with this area, from 0 to 1; null when unavailable",
    "residential_share": "Fraction of residential addresses in the ZIP associated with this area, from 0 to 1; null when unavailable or the ZIP has no residential addresses",
    "business_share": "Fraction of business addresses in the ZIP associated with this area, from 0 to 1; null when unavailable or the ZIP has no business addresses",
    "other_share": "Fraction of other addresses in the ZIP associated with this area, from 0 to 1; null when unavailable or the ZIP has no other-category addresses"
  },
  "distance": {
    "country": "ISO2 country code",
    "from": "Origin { postal, city }; ?deep=true adds from.deep.metros on paid plans, or from.deep: {} when locked",
    "to": "Destination { postal, city }; ?deep=true adds to.deep.metros on paid plans, or to.deep: {} when locked",
    "distance": "Straight-line kilometers",
    "distance_mi": "Straight-line miles"
  },
  "nearby": {
    "postal": "Origin postal code",
    "country": "ISO2 country code",
    "radius": "Search radius (default 40 km / 25 mi)",
    "unit": "km (default) or mi",
    "nearby": "Array of { postal, city, state, country, distance, distance_mi }; each row owns its optional deep: { metros }",
    "deep": "Origin { metros } on paid deep, {} on locked deep, omitted otherwise"
  },
  "parameters": {
    "country": "?country=US — ISO2, ISO3, or a country name ('?country=japan'). Optional: a globally unique code resolves without it; a collision 404s asking for it (we never guess US)",
    "radius": "?radius=40 — nearby radius in unit (?miles= still accepted, implies mi)",
    "unit": "?unit=km|mi — radius unit for nearby (default km)",
    "deep": "?deep=true adds the whole profile on paid plans. Pooled requests; no separate per-field or per-record charge",
    "lang": "Optional display language: one BCP 47 tag, up to 64 characters. Supports 41 language, script and regional choices. Missing translations keep existing display names; no lang preserves existing behavior. Invalid or empty tags return 400."
  },
  "tips": [
    "Coverage: US, GB, FR, JP, AU, MX, CH, LI, DK, AT, NO, FI, LU, CZ, BE, NL, SI, LV, HU, IS, EE, LT, MY, CY, MU, SK, KR, CO, UY, ES, IT, PT, HR, BG, CR, LK, NP, BR, FO, MC, MA, PE, MK, MD, AL, GG, JE, IM; also Åland (AX) and Svalbard/Jan Mayen (SJ)",
    "Bare codes work when unique: /postal/SW1A 1AA. Pass ?country=JP for /postal/100-0001: its seven digits also occur in Portugal. Shared codes return a 404 asking for ?country=",
    "MY, MU, KR, CR, LK, NP, SI, MC, MA, MK and MD currently have names without coordinates. Elsewhere, coordinates are approximate and may be unavailable for individual codes. MX coordinates describe matched business locations. Distance and nearby require coordinates.",
    "ES includes locality and administrative names where unambiguous. IT, PT, HR, BG and UY have geographic postal coordinates with locality names null. Geographic datasets may omit special and newly issued codes; HR and BG have partial coverage.",
    "NL covers 468,408 codes, combining geographic postal areas with address codes recorded on September 5, 2026. Locality names appear where unambiguous; the 2,473 additional address codes have approximate coordinates derived from their address locations.",
    "LT covers eight counties; Vilnius and Utena postcodes are unavailable in the current edition. MU covers Mauritius island. CO coordinates use the published 2013 postal areas.",
    "NP supports the current five-digit local-government codes and seven-digit ward codes. PT accepts full seven-digit codes with or without the hyphen.",
    "BR covers codes recorded in the 2022 census, with approximate coordinates from original address locations; later codes may be missing. FO covers a geographic subset with approximate village centres. MC covers the ordinary code 98000. MA covers 1,666 locality codes from September 2018, with city and province names; neighborhood codes and southern postal regions are excluded.",
    "PE covers 2,669 published codes from March 2018, with locality, province, and department names where unambiguous. Coordinates for 2,129 codes are approximate points derived from their recorded localities; several urban codes may share a point. MK covers 202 corroborated codes; city names describe postal destinations where the published names agree. MD covers 1,063 ordinary office codes, with locality and region names where their served areas agree.",
    "AL covers 532 published codes, with approximate postal-area coordinates for 383; city names describe postal destinations where the label is unambiguous. GG, JE and IM cover 11,106 active codes from August 2026, with country, timezone and currency; names are unavailable. JE has approximate coordinates for 42 codes from facility locations recorded in 2018. Other island codes have no coordinates.",
    "GB covers England, Scotland and Wales, plus partial Northern Ireland coverage. Northern Ireland coordinates represent recorded premises locations, not postcode centroids. Guernsey (GG), Jersey (JE) and Isle of Man (IM) use their own country codes.",
    "US ZIP+4 (33139-1234) resolves to the 5-digit ZIP — coordinates describe approximate postal areas",
    "area / land_area / water_area are available for covered US and Australian postal areas; null elsewhere",
    "Paid deep returns a combined ZIP sales tax reference in tax_rate plus state, county, city, and special components. Those pieces are already included in the total. An exact address can have a different rate",
    "Country, state and ZIP tax rates describe different geographic scopes. Do not add their responses together. Tax rates are references, not an order tax calculation",
    "PO box and unique ZIPs can have tax without coordinates. Nearby and distance need a point",
    "city / state_name / district_name are English or romanized when an official romanization is available, native locale otherwise. city_local / state_name_local / district_name_local carry the native form when it differs",
    "deep.neighbors is a short surrounding-ZIP list. Use /nearby for radius search with distances",
    "For US ZIP codes and supported territories, deep.metros includes both metropolitan and micropolitan statistical areas; null means unknown or unsupported, while [] means a complete observation outside all such areas.",
    "Metro shares describe addresses within the ZIP, not probability, population or land area. Shares are not rescaled; they may sum to less than 1 when addresses lie outside the listed areas. Associations sort by descending share, then code; unknown shares sort last.",
    "Distance and /nearby are available on all plans"
  ],
  "deep": {
    "elevation": "Elevation in meters",
    "elevation_ft": "Elevation in feet",
    "population": "Population estimate",
    "population_period": "Observation year or multi-year period for this estimate (YYYY or YYYY-YYYY). Null when unknown; never the import date",
    "area": "Total area in km² (null when the source has no water split)",
    "land_area": "Land area in km² (null where the source has none)",
    "water_area": "Water area in km² (null where the source has none)",
    "currency": "ISO currency code",
    "tax": "Levy name for the US ZIP reference (Sales tax, General excise tax). A local levy can apply where the state has none. Null when unavailable or no levy is named",
    "tax_rate": "Combined ZIP sales tax reference in percent: 7.9 means 7.9%. 0 is a known zero rate; null is unavailable. An exact address can have a different rate",
    "tax_rate_state": "State component of tax_rate, percent",
    "tax_rate_county": "County component of tax_rate, percent",
    "tax_rate_city": "City component of tax_rate, percent",
    "tax_rate_special": "Special district component of tax_rate, percent",
    "neighbors": "Short list of surrounding postal codes (like country borders)",
    "metros": "Metro and micro statistical-area associations; null when unobserved or unsupported, [] for a complete observation outside all such areas",
    "property_tax": "Median annual real-estate tax payable on owner-occupied housing: { annual_median, currency, period }. US ZIP-area or county estimate in dollars adjusted to the final year of period. Null when missing, censored or unsupported; not a percentage or individual property bill"
  },
  "headers": {
    "Content-Language": "Languages used by translated display labels and known English reference fallbacks; unchanged native place text is not assigned an inferred language"
  },
  "localization": {
    "fields": [
      "country_name",
      "state_name and district_name when sourced by stable identity"
    ],
    "native_names": "Native names, registered/legal/person/provider names, addresses, codes, enums and numeric facts retain their existing values. Native-name equality is evaluated before lang is applied, so a preserved native name can equal the translated display name.",
    "selection": "Explicit lang only; Accept-Language does not select translations. Unknown languages or unsupported explicit scripts use English.",
    "source": "Maintained display labels seeded from Unicode CLDR; missing individual labels use the existing base value."
  },
  "credits": [
    {
      "countries": [
        "FI",
        "AX"
      ],
      "source": "Posti postal-code services",
      "terms": "https://www.posti.fi/mzj3zpe8qb7p/1eKbwM2WAEY5AuGi5TrSZ7/c76a865cf5feb2c527a114b8615e9580/posti-postal-code-services-service-description-and-terms-of-use-20150101.pdf",
      "downloaded": "2026-09-15"
    },
    {
      "countries": [
        "ES"
      ],
      "source": "CartoCiudad Continua",
      "credit": "Obra derivada de CartoCiudad Continua CC-BY 4.0 scne.es",
      "url": "https://www.cartociudad.es/web/portal",
      "terms": "https://www.ign.es/resources/licencia/Condiciones_licenciaUso_IGN.pdf",
      "downloaded": "2026-09-06"
    }
  ]
}