# Outdex API

Outdoor recreation data API. Trails, weather, snowpack, campgrounds, national parks, elevation, hazards, and more from public sources.

Base URL: https://outdex.dev/api/v1
Auth: X-API-Key header (get a free key at https://outdex.dev)
Docs: https://outdex.dev/docs
OpenAPI spec: https://outdex.dev/api/api-docs/openapi.json

## Endpoints

### Trails
- GET /api/v1/trails — List trails. Filter by state, source, difficulty, surface_type, allowed_use, name, lat/lon radius, bbox, length range, elevation gain range. Params: state, source, difficulty, surface_type, allowed_use, name, latitude_deg, longitude_deg, radius_mi (default 25), min_length_mi, max_length_mi, min_gain_ft, max_gain_ft, include_geometry, bbox_sw_lat, bbox_sw_lon, bbox_ne_lat, bbox_ne_lon, limit (default 100), offset. A bbox with include_geometry=true returns all matching trails with map-optimized geometry, up to 25,000.
- GET /api/v1/trails/sources — List trail data sources with counts.
- GET /api/v1/trails/{trail_id} — Get single trail metadata.
- GET /api/v1/trails/{trail_id}/geometry — GeoJSON geometry. Params: max_points.
- GET /api/v1/trails/{trail_id}/gpx — Download GPX file.
- GET /api/v1/trails/{trail_id}/elevation — Elevation profile with gain/loss/min/max. Params: max_points (default 100).

### Weather
- GET /api/v1/weather — Current weather + optional forecast/historical. Params: latitude_deg, longitude_deg, include_forecast, include_historical.
- GET /api/v1/weather/forecast — NWS 7-day forecast. Params: latitude_deg, longitude_deg.
- GET /api/v1/weather/sun — Sunrise, sunset, twilight times. Params: latitude_deg, longitude_deg, date.

### Elevation
- GET /api/v1/elevation — Single point elevation. Params: latitude_deg, longitude_deg. Returns meters and feet.
- POST /api/v1/elevation/batch — Batch elevation for up to 500 points. Body: { "points": [{ "lat": N, "lon": N }] }.

### National Parks (NPS)
- GET /api/v1/nps/parks — List NPS parks. Params: state, designation, bbox, limit, offset. Returns images, activities, hours, fees.
- GET /api/v1/nps/parks/{park_code} — Get park details.
- GET /api/v1/nps/parks/{park_code}/boundary — Park boundary GeoJSON.
- GET /api/v1/nps/campgrounds — List NPS campgrounds. Params: park_code, bbox, limit, offset. Returns amenities, fees, reservation URLs.

### Hazards
- GET /api/v1/hazards/nps-alerts — NPS alerts/closures. Params: park_code, category (Danger/Park Closure/Caution/Information), limit, offset.
- GET /api/v1/hazards/weather-alerts — NWS weather alerts. Params: event, severity (Extreme/Severe/Moderate/Minor), bbox, limit, offset.
- GET /api/v1/hazards/wildfires — Active NIFC wildfires. Params: state (ISO 3166-2, e.g. US-CA), bbox, limit, offset.
- GET /api/v1/hazards/air-quality — Current AQI, pollutants, UV. Params: latitude_deg, longitude_deg.

### SNOTEL
- GET /api/v1/snotel/stations — Snow monitoring stations. Params: state, bbox, limit, offset.
- GET /api/v1/snotel/stations/{triplet}/measurements — Daily snow/weather readings. Params: start_date, end_date, limit, offset.

### Recreation.gov
- GET /api/v1/recgov/campgrounds — Federal campgrounds (USFS, BLM, etc). Params: state, bbox, limit, offset.
- GET /api/v1/recgov/campsite-types — Valid campsite type values.
- GET /api/v1/recgov/availability — Campsite availability for one campground/month. Params: entity_id, month (YYYY-MM-DD). Cached 15 min.
- GET /api/v1/recgov/availability/search — Multi-campground availability search. Params: month, entity_ids, state, bbox, dates, campsite_type, min_people, available_only, limit (max 25), offset.
- GET /api/v1/recgov/permits — Timed-entry permits. Params: state, entity_type, bbox, limit, offset.
- GET /api/v1/recgov/permits/availability — Permit slot availability. Params: entity_id, date (YYYY-MM-DD). Cached 15 min.

### Water & Geology
- GET /api/v1/water-sources — Springs and drinking water from OSM. Params: source_type, bbox, limit, offset.
- GET /api/v1/streamflow — USGS stream gauges with discharge, height, temp. Params: bbox, limit, offset.
- GET /api/v1/federal-lands — BLM/USFS land parcels. Params: agency, bbox, limit, offset.
- GET /api/v1/mvum — USFS motor vehicle use map routes. Params: route_type, forest_name, bbox, limit, offset.

## Common Patterns
- Pagination: limit (default 100) + offset. Response includes total, limit, offset.
- Bounding box: bbox_sw_lat, bbox_sw_lon, bbox_ne_lat, bbox_ne_lon.
- State filter: accepts abbreviation (CO) or full name (Colorado).
- Errors: { "error": "message" } with HTTP status 400/401/404/429/500.
- Rate limits: Demo 50/min, Beta 100/min, Enterprise 1000/min.