International Postal Code API

Postal code lookup is the process of taking a postal code (plus country context) and returning verified structured metadata like:

• Locality (city)
• Administrative area (state/province/region)
• Super administrative area (when applicable)
• Country ISO codes
• Dependent locality (when available)

It also works in reverse, where you input the locality, administrative area, and country to find/validate the postal code.

Instead of relying on messy, inconsistent inputs, you get standardized, reliable data ready for downstream use.

Smarty’s API performs this lookup instantly using available postal datasets. No guesswork. No normalization headaches.

Here are a few real-world examples of how a simple request turns into structured, usable data:

Find/verify the postal code

Note: Output reduced and formatted for illustrative purposes.

Find/verify the administrative area and locality

Note: Output reduced and formatted for illustrative purposes.

Try it yourself:

Bulk address validation tool. (Choose “Validate province/region, & postal code combinations” when on step 3.)

International Postal Code API tool. For more information on the API, see the full api documentation.

Start your free, 42-day trial. (After creating your account, go to “Subscriptions” and pick the International Address Verification free trial.)

Clean postal data is one of the fastest ways to improve your entire data pipeline. This is where it starts.

1. Faster, cleaner form experiences

   Autofill city and region after a user enters a postal code—reducing friction and typos during checkout or onboarding.

2. Early-stage validation

   Validate postal codes before storing bad data. Catch mismatches between country and postal code instantly.

3. CRM and data enrichment

   Turn incomplete records into usable data by appending locality, region, and standardized formats.

4. Geographic segmentation

   Group customers, users, or patients by region for analytics, compliance, or operational routing.

5. Coverage and eligibility checks

   Determine whether a user falls within a serviceable region before moving forward.

User input is rarely clean. This API is designed to handle:

• Partial inputs (prefix search support)
• Formatting inconsistencies (spacing, casing, punctuation)
• Country-specific postal formats

Instead of guessing, the API returns:

• Clear matches
• Multiple suggestions (when appropriate)
• Explicit errors when inputs are invalid

That means fewer false positives—and more trust in your data pipeline.

Postal systems vary widely across countries:

• Some are numeric (e.g., Germany)
• Some are alphanumeric (e.g., UK, Canada)
• Some are highly granular (UK)
• Others cover entire regions or countries

Smarty distills all of that complexity into a single, consistent experience—so your team doesn’t have to manage country-specific logic.

Smarty’s Postal Code API is designed to get developers to a successful first call quickly—one REST request in, normalized postal data out. Send a country code + postal code and receive clean, standardized JSON fields such as postal code, locality, administrative area, and ISO country codes, so you can reduce downstream mapping logic and avoid ambiguity.

The integration flow stays intentionally lightweight: generate a secret key, run a curl request, and use the response immediately.

To help teams move from prototype to production with fewer surprises, Smarty supports implementation with clear documentation, SDKs, and standardized outputs built for predictable behavior and faster delivery—without the usual “looks easy until edge cases” pain.

Run into questions? Our support team stands at the ready.

Sample

Make a simple request:

curl "https://international-postal-code.api.smarty.com/lookup?auth-id=YOUR_ID&auth-token=YOUR_TOKEN&postal_code=SW1A2AA&country=GBR"

Response:

[
  {
    "administrative_area": "Greater London",
    "country_iso_3": "GBR",
    "locality": "London",
    "postal_code": "SW1A 2AA"
  }
]

No complex setup. No country-specific logic. Just clean results.