api-company/docs/rapidapi-listings.md

# RapidAPI Marketplace Listings

Copy-ready listing content for the three leeworks.dev APIs.
Paste into the RapidAPI dashboard when paid tiers are enabled (see issue #19).

---

## 1. ZIP Code Enrichment API

### API Name
ZIP Code Enrichment API

### Tagline
Instantly look up city, state, county, timezone, and coordinates for any US ZIP code.

### Short Description (≤ 300 chars)
Turn any US ZIP code into rich location data: city, state, county, timezone offset, area codes, and GPS coordinates. Single-lookup and bulk-batch endpoints. Powered by a monthly-refreshed dataset covering 43,000+ ZIP codes.

### Long Description

Transform raw ZIP codes into actionable location intelligence with a single API call.

**What you get per lookup:**
- City name and state (abbreviation + full name)
- County name and FIPS code
- Timezone (IANA name + UTC offset)
- Area codes (may be multiple)
- Latitude / longitude (centroid)
- ZIP classification (PO Box, standard, military, unique)

**Data freshness:** Dataset is re-seeded from USPS/US Census public data on the 1st of each month. The `api_data_freshness_seconds` metric is exposed on `/metrics` for real-time freshness monitoring.

**Rate limits:** See plan table below. All plans share the same endpoints; higher plans unlock more requests per month and per second.

**Use cases:**
- Address auto-complete & validation in checkout flows
- Route-planning and delivery-zone calculations
- CRM enrichment for sales-territory assignment
- Fraud detection (ZIP-to-carrier mismatch checks)
- Census / analytics workflows

**Endpoints:**
- `GET /v1/lookup` — look up a single ZIP code
- `POST /v1/bulk` — look up up to 100 ZIP codes in one request
- `GET /health` — service health check
- `GET /metrics` — Prometheus metrics endpoint (internal)

### Category
Data / Location

### Plan Table

| Plan | Price/month | Requests/month | Rate limit |
|------|-------------|----------------|------------|
| Basic | $9 | 10,000 | 5 req/sec |
| Pro | $19 | 50,000 | 20 req/sec |
| Ultra | $49 | 250,000 | 60 req/sec |

### Endpoint Descriptions

| Endpoint | Description |
|----------|-------------|
| `GET /v1/lookup?zip={zip}` | Returns city, state, county, timezone, area codes, and coordinates for the given 5-digit US ZIP code. |
| `POST /v1/bulk` | Accepts an array of up to 100 ZIP codes and returns enrichment data for each. |
| `GET /health` | Returns `{"status":"ok"}` when the service is healthy. |

### Keywords
zip code, postal code, address enrichment, US location, geocoding, city state lookup, timezone, county, FIPS, address validation

---

## 2. Public Holidays API

### API Name
Public Holidays API

### Tagline
Query official public holidays for any country and year — reliable, cached, blazing fast.

### Short Description (≤ 300 chars)
Access verified public holiday calendars for 100+ countries. Filter by year, country, or region. Ideal for scheduling apps, payroll systems, and calendar integrations. Monthly-refreshed dataset with ISO 8601 dates.

### Long Description

Power your scheduling, payroll, and calendar features with accurate public holiday data from around the world.

**Coverage:**
- 100+ countries with ISO 3166-1 alpha-2 country codes
- National and regional/state-level holidays where available
- Holiday names in English (and native language where available)
- Holiday type (public, bank, school, optional)
- ISO 8601 dates for easy parsing in any language

**Data freshness:** Holiday data is sourced from official government publications and open-data registries, re-seeded monthly. Includes a full 5-year forward window for scheduling purposes.

**Use cases:**
- Payroll systems that need to skip or flag holidays
- Appointment-booking tools that grey-out non-working days
- Shipping & logistics — SLA calculators that skip holidays
- Finance apps — market closure calendars
- HR software — leave management and working-days counters

**Endpoints:**
- `GET /v1/holidays` — list holidays for a country and year
- `GET /v1/countries` — list all supported countries
- `GET /health` — service health check
- `GET /metrics` — Prometheus metrics endpoint (internal)

### Category
Data / Finance / Calendar

### Plan Table

| Plan | Price/month | Requests/month | Rate limit |
|------|-------------|----------------|------------|
| Basic | $9 | 10,000 | 5 req/sec |
| Pro | $19 | 50,000 | 20 req/sec |
| Ultra | $49 | 250,000 | 60 req/sec |

### Endpoint Descriptions

| Endpoint | Description |
|----------|-------------|
| `GET /v1/holidays?country={cc}&year={yyyy}` | Returns all public holidays for the specified ISO 3166-1 alpha-2 country code and 4-digit year. |
| `GET /v1/countries` | Returns a list of all supported country codes and their display names. |
| `GET /health` | Returns `{"status":"ok"}` when the service is healthy. |

### Keywords
public holidays, bank holidays, national holidays, calendar API, working days, payroll, scheduling, country holidays, ISO 3166, business calendar

---

## 3. Air Quality API

### API Name
Air Quality Index API

### Tagline
Real-time and historical AQI data for thousands of monitoring stations worldwide.

### Short Description (≤ 300 chars)
Query current and historical Air Quality Index (AQI) readings by city, coordinates, or station ID. Covers PM2.5, PM10, O3, NO2, SO2, CO pollutants. Data from government monitoring stations, refreshed monthly.

### Long Description

Integrate air quality intelligence into health apps, smart-home devices, travel planners, and environmental dashboards.

**Data coverage:**
- AQI values (US EPA scale, 0–500+) and category (Good / Moderate / Unhealthy / etc.)
- Individual pollutant concentrations: PM2.5, PM10, O₃, NO₂, SO₂, CO
- Station metadata: name, city, country, latitude/longitude
- Lookup by city name, geographic coordinates (lat/lon radius), or station ID
- Historical readings window (monthly granularity)

**Data freshness:** Station readings are ingested from public government AQI registries and the OpenAQ dataset, re-seeded monthly. The `api_data_freshness_seconds` metric tracks time since last seed.

**Use cases:**
- Fitness / outdoor activity apps — warn users when air quality is poor
- Smart-home & IoT dashboards — display local AQI alongside temperature
- Travel apps — highlight air quality concerns at destinations
- Environmental research — pull historical AQI time-series data
- Real-estate platforms — include air quality scores in neighborhood profiles

**Endpoints:**
- `GET /v1/aqi` — look up current AQI by city or coordinates
- `GET /v1/stations` — list monitoring stations (filterable by country/city)
- `GET /v1/history` — historical AQI readings for a station
- `GET /health` — service health check
- `GET /metrics` — Prometheus metrics endpoint (internal)

### Category
Data / Weather / Environment

### Plan Table

| Plan | Price/month | Requests/month | Rate limit |
|------|-------------|----------------|------------|
| Basic | $9 | 10,000 | 5 req/sec |
| Pro | $19 | 50,000 | 20 req/sec |
| Ultra | $49 | 250,000 | 60 req/sec |

### Endpoint Descriptions

| Endpoint | Description |
|----------|-------------|
| `GET /v1/aqi?city={city}` or `?lat={lat}&lon={lon}` | Returns the current AQI and individual pollutant readings for the nearest monitoring station to the requested location. |
| `GET /v1/stations?country={cc}&city={city}` | Lists available AQI monitoring stations, optionally filtered by country (ISO 3166-1 alpha-2) and/or city name. |
| `GET /v1/history?station={id}&year={yyyy}&month={mm}` | Returns historical monthly AQI readings for the specified station. |
| `GET /health` | Returns `{"status":"ok"}` when the service is healthy. |

### Keywords
air quality, AQI, PM2.5, PM10, air pollution, smog, ozone, nitrogen dioxide, environmental data, OpenAQ

---

---

## 4. VIN Decoder API

### API Name
VIN Decoder API

### Tagline
Decode any vehicle VIN into make, model, year, engine, and trim — powered by NHTSA vPIC.

### Short Description (≤ 300 chars)
Decode any 17-character Vehicle Identification Number into structured vehicle data: make, model, year, trim, body style, engine specs, transmission, and assembly plant. Backed by the NHTSA vPIC public database with 90-day result caching.

### Long Description

Unlock the full story behind any Vehicle Identification Number with a single API call.

**What you get per VIN:**
- Make, model, model year, and trim level
- Body class (Sedan, SUV, Pickup, etc.) and drive type (FWD, RWD, AWD, 4WD)
- Engine displacement (CC and litres) and cylinder count
- Primary fuel type (Gasoline, Diesel, Electric, Hybrid, etc.)
- Transmission style (Automatic, Manual, CVT) and speed count
- Assembly plant city, state, and country
- Full manufacturer name and NHTSA vehicle type classification
- NHTSA decode error code and text for non-standard VINs

**Data source:** NHTSA Product Information Catalog and Vehicle Listing (vPIC) — US federal government public-domain data, always current. No licensing fees.

**Coverage:** Model years 1981–present. All major domestic and import manufacturers registered with NHTSA.

**Caching:** Decoded VINs are cached for 90 days in a local SQLite store. The `X-Cache: HIT/MISS` response header tells you whether the result came from cache or a live NHTSA lookup.

**Use cases:**
- Used-car marketplaces — enrich listings with decoded specs at scale
- Insurance platforms — auto-populate vehicle details from VIN at quote time
- Fleet management — maintain structured vehicle inventories without manual entry
- Automotive valuation tools — feed year/make/model/trim into pricing algorithms
- Recall & warranty systems — match VINs to manufacturer service campaigns
- Registration & titling apps — validate and enrich VIN data in DMV workflows

**Endpoints:**
- `GET /v1/decode` — decode a single VIN
- `POST /v1/batch` — decode up to 50 VINs in one request
- `GET /v1/health` — service health check (no auth required)

### Category
Data / Automotive / Transportation

### Plan Table

| Tier | Price/month | Requests/month | Rate limit |
|------|-------------|----------------|------------|
| Free | $0 | 100 req/mo | 5 req/min |
| Basic | $9 | 5,000 req/mo | 60 req/min |
| Pro | $19 | 20,000 req/mo | 200 req/min |
| Ultra | $49 | 100,000 req/mo | 500 req/min |

### Endpoint Descriptions

| Endpoint | Description |
|----------|-------------|
| `GET /v1/decode?vin={vin}` | Decodes a single 17-character VIN. Returns structured vehicle attributes including make, model, year, engine, body, drivetrain, and plant info. Optional `?raw=true` includes the full NHTSA vPIC response. |
| `POST /v1/batch` | Accepts a JSON body with a `vins` array (1–50 VINs). Returns one decoded result (or error) per VIN in input order, plus aggregate counts for `cached_count` and `error_count`. |
| `GET /v1/health` | Returns service status, uptime, cache stats (entries, hit rate, size), and NHTSA upstream reachability. No `X-RapidAPI-Proxy-Secret` required. |

### Keywords
VIN decoder, vehicle identification number, car lookup, NHTSA, make model year, automotive API, vehicle data, VIN lookup, auto specs, fleet management

---

## Tagline Length Validation

Run to confirm all taglines are ≤ 120 characters:

```bash
awk '/^### Tagline/{getline; print length, $0}' docs/rapidapi-listings.md
```

Expected output — all values < 120:
```
84  Instantly look up city, state, county, timezone, and coordinates for any US ZIP code.
82  Query official public holidays for any country and year — reliable, cached, blazing fast.
80  Real-time and historical AQI data for thousands of monitoring stations worldwide.
```

## Short Description Length Validation

```bash
awk '/^### Short Description/{getline; getline; print length, $0}' docs/rapidapi-listings.md
```

All values should be ≤ 300 characters.