canonical: https://jentic.com/apis/postalcodecheck.com/postalcodecheck

# PostalCodeCheck Postal Code API

The PostalCodeCheck Postal Code API resolves a postal, ZIP, or postcode to the place names, regions, and coordinates it covers, drawing on GeoNames data (CC BY 4.0) for more than 887,000 codes across 95 countries. A lookup takes a two-letter country code and a postal code, ignores case, spaces, and hyphens, and returns each matching place with its admin1 and admin2 regions and latitude and longitude. A second operation lists the supported countries with their code counts and format patterns. No key is required; an optional key applies a plan allowance instead of the per-IP limits.

## For AI agents

Resolve a postal or ZIP code in one of 95 countries to its place names, regions, and coordinates, and list supported countries with their postal code formats.

## Scope

Does not geocode full street addresses, verify deliverability, or calculate shipping rates. Use for postal code to place and coordinate lookups only.

## Capabilities

- Resolve a postal code in a given country to its place names, admin1 and admin2 regions, and lat and lng coordinates
- Check whether a postal code exists for a country, getting a not_found reason when it does not
- List the countries covered with their code counts and postal format patterns such as NNNNN
- Normalise user-typed postcodes, since case, spaces, and hyphens are ignored on lookup
- Track remaining keyed allowance through the X-Credits-Remaining and X-Credits-Used response headers

## Use cases

### Agent address completion through Jentic

A developer's agent cleans up a list of shipping contacts where many rows have only a postal code. Through Jentic the agent finds the PostalCodeCheck lookup by intent and resolves each country and code pair to a place name, region, and coordinates. Because no key is required, the agent can start straight away, and if you add a key later your own instance attaches it at call time.

Example prompt: Call GET `/api/postal/US/90210` and fill the city with places[0].place, the state with places[0].admin1, and the coordinates with lat and lng

### Checkout postcode validation

A checkout form should catch a mistyped postcode before an order ships. A lookup on the shopper's country and code returns the matching places when the code exists and a 404 with reason not_found when it does not, so the form can prompt for a correction and prefill the town and region on success.

Example prompt: Call GET `/api/postal/GB/SW1A1AA` and report whether the code resolves, returning the place and admin1 values if it does

### Country coverage and format checks

Before accepting international addresses, a form needs to know which countries are supported and what a valid code looks like. GET `/api/countries` returns each country code, name, number of codes, and a format pattern in which N stands for a digit and A for a letter, which can drive client-side input masks.

Example prompt: Call GET `/api/countries` and return the format pattern and code count for DE, FR, and CA

## Key resources

- **Postal codes** — Look up a postal code by country to get places, regions, and coordinates
- **Countries** — List supported countries with code counts and format patterns

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 59 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 94 / 100
  - Security: 33 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/postalcodecheck.com/postalcodecheck/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring PostalCodeCheck by hand is light, but you still choose between anonymous per-IP limits and a key sent in X-Api-Key or the key query parameter, and handle the 429 rate_limit, daily_limit, and credits_exhausted reasons. Through Jentic you install once, import PostalCodeCheck from the API Directory, add a key if you have one, and your agent calls it.
- **Permission scoping:** PostalCodeCheck puts the country code in the URL path (`/api/postal/{cc}/{code}`), so a rule can pin your agent to one country's lookups. Both operations are reads, so the main thing a rule bounds here is which countries and how much of your allowance the agent can reach.
- **Credential handling:** If you use a PostalCodeCheck key, it is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find the city for a ZIP code' or 'validate a postcode', and Jentic returns the PostalCodeCheck lookup with its input schema, including the two-letter cc path parameter, so the agent builds the URL correctly.

## Related APIs

- **Zip Code Data API** — US ZIP code data with demographic and geographic detail
- **Geocodio** — Full-address geocoding for the US and Canada
- **OpenCage Geocoder** — Worldwide forward and reverse geocoding

## FAQ

### What authentication does the PostalCodeCheck API use?

Per its OpenAPI spec, a key is optional: both operations accept anonymous calls under per-IP limits. If you have a free api.ipnova.com key, send it in the X-Api-Key header or as the key query parameter to apply your plan allowance instead. Through Jentic the key, if you use one, is stored by your own instance and attached at call time.

### What are the rate limits for the PostalCodeCheck API?

The OpenAPI spec states that anonymous calls are limited to 30 per minute and 100 per day per IP, returned as rate_limit or daily_limit on a 429 response. With a key, a monthly allowance applies instead, and the X-Credits-Remaining and X-Credits-Used headers show what is left.

### Can I get coordinates for a postal code with the PostalCodeCheck API?

Yes. GET `/api/postal/{cc}/{code}` returns a places array in which each entry carries place, admin1, admin2, lat, and lng. One code can map to several places, so read every entry rather than only the first when the exact town matters.

### Is there a PostalCodeCheck MCP server?

You don't need an MCP server to give your agent PostalCodeCheck. Jentic connects it directly from the API Directory: import it, optionally add a key, and your agent calls the lookup and country operations on demand without loading another server's tool definitions into its context.

### Can I limit what my agent is allowed to do with PostalCodeCheck?

Yes. Both operations are reads, and the country code sits in the URL path, so you can write a rule that allows only GET `/api/postal/US/{code}` and the agent can look up US ZIP codes and nothing else. Every call it makes is logged, which helps you see how much of a keyed allowance a task used.

### How do I look up a postcode through Jentic?

Search Jentic for 'look up a postal code', load the GET `/api/postal/{cc}/{code}` operation, and execute it with a two-letter country code such as US and the code. To run it on your own infrastructure, install Jentic One from its GitHub repo.