## 📍 **US Zip Code Radius & Lookup API**
**USPS-Verified US Zip Code Database for location intelligence, distance calculation, and geolocation services.**
Power your store locators, delivery range calculators, logistics platforms, and location-based applications with USPS-verified ZIP code data and distance matrix calculations. Updated monthly with official USPS data.
---
### 🚀 **Key Features**
* ✅ **USPS-Verified Data** – 43,600+ ZIP codes verified against official USPS standards. Updated monthly for accuracy and compliance.
* ✅ **Radius Search** – Find all ZIP codes within X miles/km of a location. Perfect for store locators and delivery range calculators.
* ✅ **Distance Calculation** – Calculate accurate distance between two ZIP codes for logistics and route planning.
* ✅ **ZIP Code Lookup** – Get city and state information for any valid U.S. ZIP code from our comprehensive database.
* ✅ **City to ZIP Codes** – Retrieve all ZIP codes for a specific city and state. Essential for geolocation services.
* ✅ **Smart Autocomplete** – Real-time ZIP code suggestions for better UX in forms and search interfaces.
* ✅ **Developer Friendly** – Always returns 200 OK (no 404 errors) for safer client-side integration and predictable error handling.
---
### 💡 **Top Use Cases**
* 🛒 **Store Locator** – Build store finder widgets that show nearby locations using radius search and distance matrix.
* 🚚 **Logistics & Delivery** – Define delivery zones, calculate shipping costs, and optimize routes based on ZIP code distance.
* 🧠 **Lead Routing** – Automatically assign sales or service territories using geolocation data.
* 📦 **E-commerce Checkout** – Validate ZIP codes, estimate delivery times, and show accurate shipping information.
* 📊 **Data Enrichment** – Enhance customer databases with location intelligence and geographic segmentation.
* 🗺️ **Service Area Mapping** – Define coverage areas for field services, delivery drivers, or sales territories.
---
### ⚙️ **Endpoints Overview**
| Endpoint | Method | Description |
| --------------------------------------- | ------ | ----------------------------------- |
| `/api/zipcode/{zip}` | `GET` | Get city, state info for ZIP |
| `/api/zipcodes/radius?zipcode={zipcode}&radius={radius}&unit={unit}` | `GET` | Get ZIP codes within a radius |
| `/api/distance?from={from_zip}&to={to_zip}&unit={unit}` | `GET` | Calculate distance between two ZIPs |
| `/api/zipcodes/by-city?city={city_name}&state={state_abbreviation}` | `GET` | List ZIP codes in a city/state |
| `/api/zipcodes/autocomplete?q={query_string}` | `GET` | Suggest ZIPs based on partial input |
---
### 🧰 **Technical Details**
* ✅ **Data Quality**: USPS-verified, updated monthly
* ✅ **Coverage**: 43,600+ active US ZIP codes
* ✅ **HTTP Method**: `GET` (fully RESTful)
* ✅ **Response**: JSON
* ✅ **Units**: `mi` or `km` supported
* ✅ **Latency**: < 300ms typical
* ✅ **Caching**: Safe for most use cases (read-heavy)
* ✅ **Reliability**: 100% - Returns 200 OK for all successful requests (even when data not found)
---
### 🌐 **Why Choose This API?**
* 🏛️ **USPS-Verified** – Official data source, updated monthly with high accuracy
* 📊 **Comprehensive Coverage** – 43,600+ active US ZIP codes
* 📈 **Developer-Friendly** – Intuitive response structure with clear `success` and `found` indicators
* 🚀 **Fast Response Times** – Sub-300ms latency for most queries
* 💡 **Easy Integration** – Plug-and-play for frontend apps and backends
* 🔄 **Modern Architecture** – Works seamlessly with serverless, Jamstack, and SaaS platforms
* 🎯 **Enterprise-Ready** – Consistent error handling and response formats across all endpoints
---
### 📦 **Response Structure**
Our API uses a standardized response format that makes client-side handling straightforward and predictable.
**For Successful Searches (Data Found):**
- Returns HTTP 200 with `success: true` and `found: true`
- Includes requested data with metadata (timestamp only)
- Consistent structure across all endpoints
**Example:**
```json
{
"metadata": {
"timestamp": "2025-01-10T12:34:56.789Z"
},
"success": true,
"found": true,
"data": {
"zipcode": "90210",
"cities": [
{
"city": "Beverly Hills",
"state": "California",
"stateAbbreviation": "CA"
}
]
}
}
```
**For Valid Searches (No Data Found):**
- Returns HTTP 200 with `success: true` and `found: false`
- Includes helpful message explaining what wasn't found
- Empty data field (null or empty array depending on endpoint)
**Example:**
```json
{
"metadata": {
"timestamp": "2025-01-10T12:34:56.789Z"
},
"success": true,
"found": false,
"data": null,
"message": "No information found for zip code: 99999"
}
```
**For Invalid Requests:**
- Returns HTTP 400 with error details
- Clear error messages explaining what's wrong
- Validation errors caught early
**Example:**
```json
{
"error": {
"message": "Invalid zip code format. Must be 5 digits.",
"status": 400,
"timestamp": "2025-01-10T12:34:56.789Z"
}
}
```
**Key Advantages:**
- **Simple Logic** – Just check `response.found` to see if data exists
- **No Exception Handling** – Missing data isn't an error, it's a valid result
- **Better UX** – Distinguish between "no results" and actual errors
- **Perfect Metrics** – Only real failures affect your reliability score
- **Type-Safe** – Predictable structure makes TypeScript/validation easy
---
**Build smarter location-based experiences with the US Zip Code Radius & Lookup API — start integrating in minutes.**