# Postal Code API
> Resolve postal and ZIP codes to city, state and geo-coordinates for around 60 countries — and the reverse, listing all postal codes of a city. Perfect for checkout and address-form autofill, shipping, store locators and geo-targeting.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/postalcode-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 5 req/s
- **Basic** ($12/Mo) — 75,000 calls/Mo, 15 req/s
- **Pro** ($39/Mo) — 400,000 calls/Mo, 30 req/s
- **Mega** ($99/Mo) — 1,500,000 calls/Mo, 50 req/s

## Endpoints

### Postal

#### `GET /v1/lookup` — Location for a postal code

**Parameters:**
- `country` (query, required, string) — 2-letter ISO country Example: `us`
- `postcode` (query, required, string) — Postal / ZIP code Example: `90210`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/postalcode-api/v1/lookup?country=us&postcode=90210"
```

**Response:**
```json
{
    "data": {
        "places": [
            {
                "state": "California",
                "latitude": 34.0901,
                "longitude": -118.4065,
                "place_name": "Beverly Hills",
                "state_code": "CA"
            }
        ],
        "country": "United States",
        "post_code": "90210",
        "country_code": "US"
    },
    "meta": {
        "timestamp": "2026-05-30T04:15:36.843Z",
        "request_id": "133755be-2944-40c1-939c-86b3d4dae267"
    },
    "status": "ok",
    "message": "Postal code resolved",
    "success": true
}
```

#### `GET /v1/places` — Postal codes for a place

**Parameters:**
- `country` (query, required, string) — 2-letter ISO country Example: `us`
- `state` (query, required, string) — State (US: 2-letter code) Example: `ca`
- `city` (query, required, string) — City / place name Example: `Beverly Hills`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/postalcode-api/v1/places?country=us&state=ca&city=Beverly+Hills"
```

**Response:**
```json
{
    "data": {
        "city": "Beverly Hills",
        "state": "California",
        "country": "United States",
        "post_codes": [
            {
                "latitude": 33.7866,
                "longitude": -118.2987,
                "post_code": "90209",
                "place_name": "Beverly Hills"
            },
            {
                "latitude": 34.0901,
                "longitude": -118.4065,
                "post_code": "90210",
                "place_name": "Beverly Hills"
            },
            {
                "latitude": 34.0652,
                "longitude": -118.383,
                "post_code": "90211",
                "place_name": "Beverly Hills"
            },
            {
                "latitude": 34.0619,
                "longitude": -118.3995,
                "post_code": "90212",
                "place_name": "Beverly Hills"
            },
            {
                "latitude": 33.7866,
                "longitude": -118.2987,
                "post_code": "90213",
                "place_name": "Beverly Hills"
            }
        ],
        "country_code": "US"
    },
    "meta": {
        "timestamp": "2026-05-30T04:15:37.320Z",
        "request_id": "d58f08f8-b20e-42c2-93f0-125c5ce42465"
    },
    "status": "ok",
    "message": "Places resolved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/postalcode-api
OpenAPI spec: https://www.oanor.com/api/postalcode-api/openapi.json