# Boardwalk Land Use Intelligence API

You have access to Boardwalk's land use project database containing hundreds of thousands of development projects extracted from city and county meeting minutes across the United States. This data includes zoning decisions, building permits, rezoning approvals, development proposals, and more.

## Authentication

All API calls require this header:
```
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with the Boardwalk API key provided to you.

**Base URL:** `https://data.civicstar.ai/api/v1`

## Geographic filters (numeric IDs only)

Location filters use **numeric IDs**, not state abbreviations, county names, or city names.

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

Use `stateIds`, `countyIds`, and `cityIds` in searches (legacy keys `state`, `county`, `city` accept the same **integer ID arrays**). Put place names in `search` / `query` text, or resolve IDs first.

## Available Endpoints

### 1. Search Projects (1 credit per project returned)
```
GET /api/v1/projects/search
```

Search for land use projects using structured filters.

**Parameters (all optional):**
- `search` or `query` (string) — Text search across project name, address, developer
- `stateIds` (int[] as JSON) — State IDs (e.g. `[1]` for Utah). Alias: `state=[1]`. Singular: `stateId=1`.
- `countyIds` (int[] as JSON) — County IDs from `/locations/states/{id}/counties`. Alias: `county=[26]`. Singular: `countyId=26`.
- `cityIds` (int[] as JSON) — City IDs from nested cities endpoint. Alias: `city=[43]`. Singular: `cityId=43`.
- `type` (string[] as JSON) — Land use types (e.g., `["Residential","Commercial"]`)
- `subtype` (string[] as JSON) — Land use subtypes (e.g., `["Multi-Family"]`)
- `assetClass` (string[] as JSON) — Asset classes (e.g., `["Apartments"]`)
- `status` (string[] as JSON) — Project status filters
- `decisionType` (string[] as JSON) — Action/decision types
- `dateFrom` (string) — Meeting date start, YYYY-MM
- `dateTo` (string) — Meeting date end, YYYY-MM
- `unitCountMin` / `unitCountMax` (int) — Unit count range
- `lotSizeMin` / `lotSizeMax` (float) — Lot size in sq ft
- `squareFootageMin` / `squareFootageMax` (float) — Building sq ft range
- `bounds` (JSON string) — Viewport: `{"north":41.8,"south":41.5,"east":-111.6,"west":-112.0}`
- `sort` (string) — `meeting_date`, `created_at`, `updated_at`, `data_richness` (default: meeting_date)
- `order` (string) — `asc` or `desc` (default: desc)
- `limit` (int) — 1-100, default 100
- `offset` (int) — Pagination offset, default 0
- `format` (string) — `json` (default) or `csv`

**Example:**
```
GET /api/v1/projects/search?stateIds=[1]&countyIds=[26]&type=["Residential"]&subtype=["Multi-Family"]&dateFrom=2025-06&limit=25
```

### 2. AI Search (2 credits per project returned)
```
POST /api/v1/projects/ai-search
Content-Type: application/json
```

Natural language search powered by AI. The query is parsed by an LLM to extract structured filters and then matched using semantic vector similarity plus text search.

**Request body:**
```json
{
    "query": "large apartment complexes near downtown Salt Lake City approved in the last 6 months",
    "limit": 50,
    "offset": 0,
    "sort": "meeting_date",
    "order": "desc"
}
```

Optional additional filters in the body: `stateIds`, `countyIds`, `cityIds` (arrays of integers), or legacy `state`, `county`, `city` with the same ID arrays; plus `type`, `dateFrom`, `dateTo`.

### 3. Taxonomy (Free)
```
GET /api/v1/taxonomy                     — Full taxonomy tree
GET /api/v1/taxonomy/project-types       — Top-level types
GET /api/v1/taxonomy/subtypes            — Subtypes (optional: ?projectType=Residential)
GET /api/v1/taxonomy/asset-classes       — Asset classes (optional: ?projectType=...&subType=...)
GET /api/v1/taxonomy/action-types        — Decision/action types
GET /api/v1/taxonomy/action-categories   — Action categories
```

### 4. Locations (Free)
```
GET /api/v1/locations/states                              — All states with IDs
GET /api/v1/locations/states/{id}                         — Single state
GET /api/v1/locations/states/{id}/counties                — Counties in a state
GET /api/v1/locations/states/{stateId}/counties/{countyId}/cities — Cities in a county
GET /api/v1/locations/counties/{id}                       — Single county
GET /api/v1/locations/cities/{id}                         — Single city
```

### 5. Credit Balance (Free)
```
GET /api/v1/account/credits
```

## Land Use Taxonomy (Key Types)

**Project Types:** Residential, Commercial, Industrial, Mixed-Use, Institutional, Infrastructure, Recreational, Agricultural, Utility, Transportation, Environmental

**Common Subtypes:**
- Residential: Single-Family, Multi-Family, Townhomes, Senior Living, Student Housing, Manufactured Housing
- Commercial: Retail, Office, Hospitality, Restaurant, Entertainment, Medical Office
- Industrial: Warehouse, Manufacturing, Data Center, Flex Space
- Mixed-Use: Residential/Commercial, Transit-Oriented Development

## Key Location IDs

Use the `/api/v1/locations/states` endpoint to get current IDs. Common ones:
- Utah = 1, Arizona = 54, California = 56, Colorado = 57, Florida = 61, Idaho = 64, Nevada = 80, Oregon = 89, Texas = 95, Washington = 98

## Project Response Schema

Each project in the response includes:
- `id` — Unique project ID
- `projectName` — Project title
- `landUseType`, `landUseSubtype`, `landUseSubsubtype` — Taxonomy classification
- `address1`, `city`, `county`, `state`, `zip` — Location
- `latitude`, `longitude` (or `lat`, `lng`) — Coordinates
- `unitCount` — Number of units
- `landSize` / `lotSizeSqft` — Land area
- `squareFootage` — Building size
- `status` — Current status
- `developer` — Developer name
- `meetingDate` — Most recent meeting date
- `createdAt`, `updatedAt` — Timestamps
- `webVisibilityScore` — Data quality score
- `actions` — Decision/action records with types, status, conditions
- `parties` — Related parties (developers, applicants, architects, etc.)
- `meetingDataGroups` — Meeting summaries, zoning details, public feedback
- `images` — Associated images

## Credit Awareness

- **Project search costs 1 credit per project returned.** A search returning 100 projects = 100 credits.
- **AI search costs 2 credits per project returned.** An AI search returning 50 projects = 100 credits.
- **Taxonomy and location lookups are free.**
- Always tell the user approximately how many credits a search might use.
- Check the user's remaining credits with `GET /api/v1/account/credits` if they ask.
- Maximum 100 results per page. Use `offset` for pagination (each page costs credits).

## Example Searches

1. **All residential projects in Utah from the last 3 months:**
```
GET /api/v1/projects/search?stateIds=[1]&type=["Residential"]&dateFrom=2025-12
```

2. **Multi-family apartments with 50+ units:**
```
GET /api/v1/projects/search?type=["Residential"]&subtype=["Multi-Family"]&unitCountMin=50
```

3. **AI: Natural language query:**
```json
POST /api/v1/projects/ai-search
{"query": "new hotel developments near ski resorts in Utah and Colorado"}
```

4. **Commercial projects in Salt Lake City (city ID 13):**
```
GET /api/v1/projects/search?cityIds=[13]&type=["Commercial"]
```