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

# Metadapi Zip Code Data API

The Metadapi Zip Code Data API provides a comprehensive United States zip code dataset in JSON over a REST surface. Agents can validate a zip code, look up city and county metadata, calculate the distance between two zip codes, search by radius, and traverse Metropolitan and Micropolitan Statistical Area (MSA) groupings. The dataset is keyed by zip code so it works as a fast enrichment layer for forms, shipping flows, and territory-mapping tools that need authoritative US postal data.

## For AI agents

Validate US zip codes and enrich them with city, county, distance, radius, and MSA data via 7 REST endpoints.

## Scope

Does not handle international postal codes, full-address geocoding, or street validation - use for US zip code lookups, distance, radius, and MSA data only.

## Capabilities

- Validate a US zip code and return its city, state, and county attributes
- Calculate the distance between two zip codes for shipping or service-area logic
- Find every zip code within a given radius of a target zip for territory expansion
- Look up the Metropolitan or Micropolitan Statistical Area for a given MSA code
- List all MSA groups in the dataset for region-level analytics rollups
- Confirm that an API license key is active before issuing high-volume traffic

## Use cases

### Address Form Validation

When a user enters a US zip code on a checkout or signup form, agents call the zip code lookup to validate the entry and auto-fill the corresponding city, state, and county fields. This reduces typos at submission and speeds up form completion. The dataset is keyed by zip so the lookup is a single GET against `/zipc/v1/zipcodes/{zipcode}.`

Example prompt: GET `/zipc/v1/zipcodes/{zipcode}` on form submission and pre-fill the city, state, and county fields with the returned values

### Service-Area and Radius Search

Local-services platforms (cleaners, contractors, dental clinics) need to surface providers within a customer's distance threshold. Use the radius endpoint to retrieve every zip code within N miles of the customer's zip, then filter the provider directory by those zips. Combine with the distance endpoint to sort results by proximity.

Example prompt: GET `/zipc/v1/radius` for the customer's zip with a 25-mile radius, then filter the provider directory by the returned zip list

### Territory and MSA Analytics

Sales and marketing teams roll up performance metrics by Metropolitan or Micropolitan Statistical Area. Agents use the MSA endpoints to map each customer zip to its MSA, then aggregate metrics by MSA name. Listing all MSA groups makes it easy to seed a dashboard or pivot table with the canonical region set.

Example prompt: GET `/zipc/v1/msagroups` to seed the MSA dimension, then map each customer zip to its MSA via `/zipc/v1/zipcodes/{zipcode}`

### AI Agent Integration via Jentic

An AI agent uses Jentic to discover the Zip Code Data API by intent search ('look up a US zip code'). Jentic returns the matching operation with its input schema, so the agent enriches an address record in a single load-and-execute step. The Metadapi subscription key lives in your Jentic One instance and never enters the agent's prompt.

Example prompt: Use Jentic to search 'look up a US zip code', load the zipcodes schema, and execute it to enrich an inbound order record

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/zipc/v1/zipcodes/{zipcode}` | Get details for a single zip code |
| GET | `/zipc/v1/zipcodes` | List zip codes |
| GET | `/zipc/v1/distance` | Distance between two zip codes |
| GET | `/zipc/v1/radius` | Find zip codes within a radius |
| GET | `/zipc/v1/msagroups` | List MSA groups |
| GET | `/zipc/v1/msagroups/{msaCode}` | Get MSA group details |
| GET | `/zipc/v1` | Validate API license key |

## Key resources

- **Zip Codes** — Per-zip metadata including city, state, and county attributes
- **Distance** — Computed mile distance between two zip codes
- **Radius** — Set of zip codes within a given radius of a target zip
- **MSA Groups** — Metropolitan and Micropolitan Statistical Area definitions and details
- **License** — API license key validation endpoint

## Why Jentic

- **Setup:** Wiring the Zip Code Data API by hand means reading its Ocp-Apim-Subscription-Key header scheme and building each zip, distance, and radius query yourself. Through Jentic you install once, import the Zip Code Data API from the API Directory, store the subscription key once, and your agent calls it.
- **Permission scoping:** This API is read-only US zip code data, so limit the agent to the operations it needs, such as a zip lookup, distance, or radius query. You choose which of those operations it may call, and none of them change data on your account.
- **Credential handling:** Your Metadapi subscription key is stored once, encrypted, by your own Jentic One instance and injected into the Ocp-Apim-Subscription-Key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a US zip code' or 'find zip codes within a radius', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Smarty US Zip Code API** — Smarty's US zip code lookup with city, state, and ZIP+4 enrichment
- **Geocodio** — US and Canada geocoding with batch zip lookups and rich administrative data
- **ZipCodeAPI** — Lightweight US zip code lookups with distance and radius search
- **ShipStation** — Shipping platform that consumes validated zip codes for label generation

## FAQ

### What authentication does the Metadapi Zip Code Data API use?

An API subscription key in the `Ocp-Apim-Subscription-Key` header, issued from your Metadapi subscription. Through Jentic the key is stored in your Jentic One instance and injected at request time, so it never enters the agent's prompt.

### Can I look up city and county data for a zip code?

Yes. GET `/zipc/v1/zipcodes/{zipcode}` returns the metadata associated with a specific zip, and GET `/zipc/v1/zipcodes` lists the dataset for bulk enumeration.

### How do I calculate the distance between two zip codes?

Call GET `/zipc/v1/distance` with the two zip codes as parameters. The response returns the computed mile distance.

### Does the API support radius searches around a zip?

Yes. GET `/zipc/v1/radius` returns every zip code within a given distance of a target zip, suitable for service-area or store-locator features.

### How do I look up a US zip through Jentic?

Search Jentic for `look up a US zip code`, load the GET `/zipc/v1/zipcodes/{zipcode}` operation, and execute it with the zip. Jentic returns the structured response with city, state, and county fields.

### Are there published rate limits?

The OpenAPI spec does not declare quantitative rate limits. Limits are tied to your Metadapi subscription tier - check the dashboard or contact Metadapi support before bulk traffic.

### Can I limit what my agent is allowed to do with the Zip Code Data API?

Yes. Because you run your own self-hosted Jentic One instance, your rules decide which of this read-only API's operations the agent may call, so you can allow only a zip lookup at GET `/zipc/v1/zipcodes/{zipcode}` while withholding the distance, radius, or MSA endpoints. None of these operations change data on your account, and the Metadapi subscription key stays with your instance rather than the agent's prompt. You scope both the callable operations and the credential to exactly what a given task needs.