a615b7ebfd
Closes leeworks-agents/api-company#5 (docs-site Astro scaffold) Closes leeworks-agents/api-company#9 (metrics instrumentation standard) Closes leeworks-agents/api-company#10 (Gitea Actions openapi aggregation pipeline) Closes leeworks-agents/api-company#11 (docs-site Flux HelmRelease) Closes leeworks-agents/api-company#12 (SEO blog posts x3) Closes leeworks-agents/api-company#13 (legal docs ToS/Privacy/AUP) Closes leeworks-agents/api-company#14 (DNS documentation) ## Changes ### docs/legal/ - terms-of-service.md — API usage, liability, account termination, governing law - privacy-policy.md — request log retention (90d), no PII sold, data sharing - acceptable-use-policy.md — rate limit abuse, scraping prohibition, resale ban ### docs/metrics-standard.md - Defines api_requests_total, api_response_duration_seconds, api_data_freshness_seconds - Fastify (TypeScript) and FastAPI (Python) reference middleware implementations - Prometheus scrape config and Grafana dashboard guidance ### docs/registry.md - Decision: use Gitea built-in container registry (no new infra) - Image naming convention, auth, Kubernetes imagePullSecrets, ingress config ### docs/dns.md - Required A records for all 6 subdomains - cert-manager ClusterIssuer and Ingress TLS examples - Verification commands and human-operator action items ### docs-site/ - Astro 4 + MDX + sitemap scaffold - Base layout with nav linking all APIs, blog, RapidAPI, status - Landing page with API cards - Per-API Redoc viewer pages (zip-enrichment, holidays, air-quality) - Blog index + 3 SEO blog posts (~1000 words each with JSON-LD) - Dockerfile (multi-stage: node build + nginx serve) - nginx.conf with gzip, caching, health endpoint ### flux/ - gitea-runner/: gitea-act-runner HelmRelease (org-scope, dind) - monitoring/: kube-prometheus-stack + Gatus HelmReleases - Prometheus with pod annotation scraping - Grafana at grafana.leeworks.dev with persistence - Gatus status page at status.leeworks.dev, 90-day retention - docs-site/: Deployment + Service + Ingress via raw chart - api-company-source/: GitRepository + Kustomization reference manifests - kustomization.yaml: root kustomize entry point (build validated) ### .gitea/workflows/build-docs.yaml - Aggregates openapi.yaml from zip-enrichment, holidays, air-quality repos - Builds Astro docs-site - Pushes image to registry.leeworks.dev/leeworks-agents/docs-site - Triggered on push to main, schedule daily 02:00 UTC, workflow_dispatch
159 lines
5.3 KiB
Plaintext
159 lines
5.3 KiB
Plaintext
---
|
|
title: "ZIP Code Enrichment API: Add Location Intelligence to Your App in Minutes"
|
|
description: "Learn how to use the leeworks.dev ZIP Code Enrichment API to add city, state, timezone, and demographic data to any postal code lookup."
|
|
date: "2026-05-24"
|
|
author: "leeworks.dev"
|
|
tags: ["zip-enrichment", "api", "tutorial"]
|
|
---
|
|
|
|
import Base from '../../layouts/Base.astro';
|
|
|
|
<Base title="ZIP Code Enrichment API Guide" description="Learn how to use the leeworks.dev ZIP Code Enrichment API to add city, state, timezone, and demographic data to any postal code lookup.">
|
|
|
|
<article style="max-width: 800px; margin: 0 auto; padding: 2rem; line-height: 1.75;">
|
|
|
|
<script type="application/ld+json" set:html={JSON.stringify({
|
|
"@context": "https://schema.org",
|
|
"@type": "Article",
|
|
"headline": "ZIP Code Enrichment API: Add Location Intelligence to Your App in Minutes",
|
|
"datePublished": "2026-05-24",
|
|
"author": { "@type": "Organization", "name": "leeworks.dev" },
|
|
"publisher": { "@type": "Organization", "name": "leeworks.dev", "url": "https://docs.leeworks.dev" }
|
|
})} />
|
|
|
|
# ZIP Code Enrichment API: Add Location Intelligence to Your App in Minutes
|
|
|
|
Every time a user types their ZIP code, there's a wealth of data waiting to be unlocked — city name, state, county, timezone, latitude, longitude, and more. The **leeworks.dev ZIP Code Enrichment API** makes it trivially easy to retrieve all of that in a single API call.
|
|
|
|
## What Is a ZIP Code Enrichment API?
|
|
|
|
A **postal code demographics API** (or ZIP enrichment API) takes a 5-digit US ZIP code as input and returns structured data about that location. This is useful for:
|
|
|
|
- **E-commerce** — display the user's city/state after they type a ZIP, skip the state dropdown
|
|
- **Shipping calculators** — determine timezone and region for delivery estimates
|
|
- **Analytics dashboards** — group customers by region, state, or county
|
|
- **Lead scoring** — enrich CRM contacts with location data automatically
|
|
- **Form UX** — auto-fill city/state fields for a smoother checkout experience
|
|
|
|
## Why Build on leeworks.dev?
|
|
|
|
Unlike scraping Google Maps or paying for expensive enterprise solutions, the leeworks.dev ZIP Enrichment API:
|
|
|
|
- Returns **sub-50ms responses** (SQLite-backed, no external dependencies)
|
|
- Provides **100% US ZIP code coverage** using the free USPS/Census dataset
|
|
- Is available on **RapidAPI** with a generous free tier
|
|
- Has a **simple, well-documented REST API** following the OpenAPI 3.1 standard
|
|
|
|
## Quick Start
|
|
|
|
### 1. Get Your API Key
|
|
|
|
Sign up on [RapidAPI](https://rapidapi.com/leeworks/api/zip-enrichment) and subscribe to a plan. The Free tier gives you 500 requests/month.
|
|
|
|
### 2. Make Your First Call
|
|
|
|
```bash
|
|
curl -X GET "https://zip.leeworks.dev/v1/lookup?zip=90210" \
|
|
-H "X-RapidAPI-Key: YOUR_API_KEY" \
|
|
-H "X-RapidAPI-Host: zip.leeworks.dev"
|
|
```
|
|
|
|
### 3. Parse the Response
|
|
|
|
```json
|
|
{
|
|
"zip": "90210",
|
|
"city": "Beverly Hills",
|
|
"state": "CA",
|
|
"state_full": "California",
|
|
"county": "Los Angeles",
|
|
"timezone": "America/Los_Angeles",
|
|
"latitude": 34.0901,
|
|
"longitude": -118.4065,
|
|
"population": 20124
|
|
}
|
|
```
|
|
|
|
## Code Examples
|
|
|
|
### JavaScript / Node.js
|
|
|
|
```javascript
|
|
const response = await fetch('https://zip.leeworks.dev/v1/lookup?zip=10001', {
|
|
headers: {
|
|
'X-RapidAPI-Key': process.env.RAPIDAPI_KEY,
|
|
'X-RapidAPI-Host': 'zip.leeworks.dev',
|
|
},
|
|
});
|
|
const data = await response.json();
|
|
console.log(`${data.city}, ${data.state} (${data.timezone})`);
|
|
// → "New York, NY (America/New_York)"
|
|
```
|
|
|
|
### Python
|
|
|
|
```python
|
|
import httpx
|
|
|
|
resp = httpx.get(
|
|
"https://zip.leeworks.dev/v1/lookup",
|
|
params={"zip": "60601"},
|
|
headers={
|
|
"X-RapidAPI-Key": "YOUR_API_KEY",
|
|
"X-RapidAPI-Host": "zip.leeworks.dev",
|
|
},
|
|
)
|
|
data = resp.json()
|
|
print(f"{data['city']}, {data['state']}")
|
|
# → "Chicago, IL"
|
|
```
|
|
|
|
## Pricing
|
|
|
|
| Plan | Requests/mo | Price | Best for |
|
|
|------|------------|-------|---------|
|
|
| Free | 500 | $0 | Prototyping |
|
|
| Basic | 10,000 | $9/mo | Small apps |
|
|
| Pro | 100,000 | $19/mo | Growing products |
|
|
| Ultra | 1,000,000 | $49/mo | High volume |
|
|
|
|
**[Subscribe on RapidAPI →](https://rapidapi.com/leeworks/api/zip-enrichment)**
|
|
|
|
## Use Case: Auto-fill City/State on Checkout
|
|
|
|
Here's a complete React component that auto-fills city and state when a user enters their ZIP:
|
|
|
|
```tsx
|
|
import { useState } from 'react';
|
|
|
|
export function ZipField() {
|
|
const [zip, setZip] = useState('');
|
|
const [location, setLocation] = useState<{ city: string; state: string } | null>(null);
|
|
|
|
const handleZipChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
|
|
const value = e.target.value.replace(/\D/g, '').slice(0, 5);
|
|
setZip(value);
|
|
if (value.length === 5) {
|
|
const res = await fetch(`/api/zip-lookup?zip=${value}`);
|
|
if (res.ok) setLocation(await res.json());
|
|
}
|
|
};
|
|
|
|
return (
|
|
<div>
|
|
<input value={zip} onChange={handleZipChange} placeholder="ZIP Code" maxLength={5} />
|
|
{location && <p>📍 {location.city}, {location.state}</p>}
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
## Conclusion
|
|
|
|
The leeworks.dev **ZIP code enrichment API** is the fastest way to add location intelligence to any application. With a simple GET request, you get city, state, county, timezone, and coordinates — no geocoding, no rate-limit headaches.
|
|
|
|
**[Get started for free →](https://rapidapi.com/leeworks/api/zip-enrichment)**
|
|
|
|
</article>
|
|
</Base>
|