# US ZIP Code API

Validate and enrich any US ZIP code.

| Field | Value |
| --- | --- |
| Provider | APIStead Labs |
| Category | Address & Location |
| Networks | Base |
| Price | $0.001-$0.002 per call |
| Base URL | https://apistead.qd.je/api/v1 |
| Verification | verified (2/2 routes) |
| Last verified | 2026-11-13T13:52:19.855Z |
| Receipt | https://basescan.org/tx/0x73b29cce8aa1258c1fbb2e89281e070df0456f00245e5f17cb9c2be161b3c69e |
| JSON | https://x402.apistead.qd.je/api/apis/us-zip-code-api |
| Markdown | https://x402.apistead.qd.je/api/apis/us-zip-code-api/md |
| MCP | https://apistead.qd.je/mcp |
| API reference | https://x402.apistead.qd.je/api |
| OpenAPI | https://x402.apistead.qd.je/openapi.json |

## For AI agents

Resolve a US ZIP code to a city, state and coordinates, or measure the distance between two ZIP centroids.

## Scope

US ZIP codes only. Does not validate street addresses, ZIP+4 delivery points or international postal codes.

## Agent intents

- look up a US ZIP code
- get city and state for a ZIP
- calculate distance between ZIP codes
- validate a US ZIP before delivery

US addresses are inconsistent. Agents see `10001`, `10001-1234`, `New York, NY 10001` and a dozen variants of the same place. This API normalizes the ZIP, validates it, and returns the city, state and coordinates.

Use it for delivery eligibility, address enrichment, property due diligence, territory assignment and any workflow where an agent needs to turn a ZIP into a place before it spends money on the next call.

The response includes a `source` and `retrieved_at` timestamp so the agent can carry evidence forward. The preview deployment uses a public ZIP source with a local fallback for common codes.

## Endpoints

### GET /us-zip/{zip}

Validate a US ZIP code and return city, state and coordinates.

- URL: https://apistead.qd.je/api/v1/us-zip/{zip}
- Price: $0.001 USDC per call
- Pay to: 0x2E9804240E493DD8daeBa4F341a5086b92cde235
- Verified: yes
- Last checked: 2026-11-14T04:35:10.420Z
- Latency: 5 ms
- Uptime (30d): 87%

Example request:

```http
GET https://apistead.qd.je/api/v1/us-zip/10001
```

Example response:

```json
{
  "zip": "10001",
  "city": "New York",
  "state": "NY",
  "source": "zippopotam.us",
  "latitude": 40.7484,
  "longitude": -73.9967,
  "retrieved_at": "2026-11-09T20:00:00Z"
}
```

### GET /us-zip/distance?from={zip1}&to={zip2}

Great-circle distance between two US ZIP centroids.

- URL: https://apistead.qd.je/api/v1/us-zip/distance?from={zip1}&to={zip2}
- Price: $0.002 USDC per call
- Pay to: 0x2E9804240E493DD8daeBa4F341a5086b92cde235
- Verified: yes
- Last checked: 2026-11-14T04:35:10.428Z
- Latency: 4 ms
- Uptime (30d): 87%

Example request:

```http
GET https://apistead.qd.je/api/v1/us-zip/distance?from=10001&to=90210
```

Example response:

```json
{
  "to": "90210",
  "from": "10001",
  "distance_km": 3944.2,
  "distance_miles": 2450.8
}
```

## Payment

Every paid route uses x402 over HTTP. Call the route without payment to receive a 402 challenge, then pay the quoted USDC amount and retry. The 402 challenge is the authoritative source for price, asset, network and pay-to address. Reading this record and the discovery API is free.

- Protocol: x402 v2
- Asset: USDC
- Networks: Base
- Price: $0.001-$0.002 per call

## Verification

- State: verified
- Routes verified: 2/2
- Last verified: 2026-11-13T13:52:19.855Z
- Receipt: https://basescan.org/tx/0x73b29cce8aa1258c1fbb2e89281e070df0456f00245e5f17cb9c2be161b3c69e

## Agent links

- JSON: https://x402.apistead.qd.je/api/apis/us-zip-code-api
- Markdown: https://x402.apistead.qd.je/api/apis/us-zip-code-api/md
- Routes: https://x402.apistead.qd.je/agent/routes?id=us-zip-code-api
- Receipts: https://x402.apistead.qd.je/agent/receipts?id=us-zip-code-api
- API reference: https://x402.apistead.qd.je/api
- MCP guide: https://x402.apistead.qd.je/mcp-docs
- Agent skill: https://x402.apistead.qd.je/skill
- OpenAPI: https://x402.apistead.qd.je/openapi.json
- MCP: https://apistead.qd.je/mcp
- Docs: https://apistead.qd.je/api


## Changelog

### 1.0.0 - Initial verified release

The route is live and settlement-verified on Base mainnet. Health checks, public receipts and agent-readable records are available.

release · 2026-11-11 · APIStead Labs