# 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

---

## 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.