# Boardwalk Land Use Intelligence API — Cursor Skill

## What This Skill Does
Search Boardwalk's database of hundreds of thousands of land use projects extracted from city and county meeting minutes across the United States. Includes structured search and AI-powered natural language search.

## Authentication
All API calls need:
```
Authorization: Bearer YOUR_API_KEY
```
Base URL: `https://data.civicstar.ai/api/v1`

## Geographic filters (IDs only)

Resolve numeric IDs via the free location endpoints before filtering:

1. `GET /locations/states` → state `id`
2. `GET /locations/states/{stateId}/counties` → county `id`
3. `GET /locations/states/{stateId}/counties/{countyId}/cities` → city `id`

Use `stateIds`, `countyIds`, `cityIds` (or legacy `state`, `county`, `city` with the same **integer ID arrays**). Do not pass abbreviations or place names as filter values.

## How to Search

### Structured Search (1 credit/project)
Use `curl` to call the search endpoint:
```bash
curl -s -H "Authorization: Bearer YOUR_API_KEY" \
  "https://data.civicstar.ai/api/v1/projects/search?stateIds=[1]&type=[\"Residential\"]&limit=25"
```

Key parameters (all optional, pass as query params):
- `search` or `query` — text search
- `stateIds` — state IDs as JSON array (e.g. `[1]` for Utah); alias `state`; singular `stateId`
- `countyIds`, `cityIds` — location IDs as JSON arrays (aliases `county`, `city`)
- `type`, `subtype`, `assetClass` — taxonomy filters as JSON arrays
- `status`, `decisionType` — status/decision filters
- `dateFrom`, `dateTo` — date range (YYYY-MM)
- `unitCountMin/Max`, `lotSizeMin/Max`, `squareFootageMin/Max` — numeric ranges
- `sort` — `meeting_date`, `created_at`, `updated_at`, `data_richness`
- `order` — `asc` or `desc`
- `limit` — 1-100 (default 100), `offset` — pagination

### AI Search (2 credits/project)
```bash
curl -s -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"large apartment complexes approved in Salt Lake City","limit":25}' \
  "https://data.civicstar.ai/api/v1/projects/ai-search"
```

Optional body filters: `stateIds`, `countyIds`, `cityIds` (integer arrays only).

### Free Endpoints (no credits)
```bash
# Full taxonomy tree
curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://data.civicstar.ai/api/v1/taxonomy"

# All states with IDs
curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://data.civicstar.ai/api/v1/locations/states"

# Counties in a state
curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://data.civicstar.ai/api/v1/locations/states/1/counties"

# Check credit balance
curl -s -H "Authorization: Bearer YOUR_API_KEY" "https://data.civicstar.ai/api/v1/account/credits"
```

## Taxonomy (Project Types)
Residential, Commercial, Industrial, Mixed-Use, Institutional, Infrastructure, Recreational, Agricultural, Utility, Transportation, Environmental

Common subtypes: Single-Family, Multi-Family, Townhomes, Retail, Office, Hospitality, Warehouse, Manufacturing

## Key State IDs
Utah=1, Arizona=54, California=56, Colorado=57, Florida=61, Idaho=64, Nevada=80, Oregon=89, Texas=95, Washington=98

Use `/api/v1/locations/states` for the full list.

## Response Format
JSON with `data` (array of projects) and `meta` (total, limit, offset, creditsUsed, creditsRemaining).

Each project includes: id, projectName, landUseType/Subtype/Subsubtype, address fields, lat/lng, unitCount, squareFootage, status, developer, meetingDate, actions, parties, meetingDataGroups, images.

## Credit Rules
- Search: 1 credit per project returned
- AI Search: 2 credits per project returned
- Taxonomy/locations: free
- Max 100 results per page
- Credits reset monthly, no rollover