# OpenCMA Public API

> OpenCMA is a free comparative market-analysis platform for Ohio and
> California real estate. This file documents its token-free public API and
> map share-link format for LLM agents.

Base URL: /api/v1
Auth: none (no API key, no token). CORS open (*). Rate limit: 60 req/min/IP;
responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
(seconds), and Retry-After on 429. Successful GETs are edge-cached 24h.

## GET /api/v1/nightlife
Nightlife stats for a point, from precomputed grids (covered cities only).
Params: lat & lng OR address; optional band in {18,20,25,30} (default 20) = peer age cohort.
Returns: { query{lat,lng,band}, city{slug,name}, cell{lat,lng,distanceMiles},
components{go,stay,p18,p20,p25,p30} (each 0..1), composite (0..100 = round(go*stay*p<band>*100)),
tier (Vibrant|Strong|Solid|Some options|Quiet|Sleepy), nearestCluster{name,lat,lng,distanceMiles}|null }.
Covered city slugs: cleveland, columbus, bay-area, seattle.
404 {error,supportedRegions,hint} when outside coverage.
Example: /api/v1/nightlife?lat=41.4993&lng=-81.6919&band=25

## GET /api/v1/property
Curated property summary for a US street address. Supported states: Ohio, California.
Param: address (required).
Returns: { address, countyTier ("full"=dedicated county scraper | "basic"=limited/fallback data: Ohio OGRIP statewide, or any California county),
location{lat,lng,countyFips,tractCode},
parcel{parcelId,owner,yearBuilt,buildingSqft,lotAcres,beds,baths,useCode,useDescription},
value{assessedTotal,assessedLand,assessedBuilding,marketTotal} (USD; OH assessed ~=35% of market, CA Prop-13),
taxRate{municipal,schoolDistrict,schoolDistrictName} (decimals: 0.02=2%),
scores{location,environment,valueTrend,taxBurden,investment} (0..100, higher better),
flood{zone,riskLevel,isSpecialFloodHazardArea} (FEMA),
demographics{medianHouseholdIncome,population,medianAge,ownerOccupiedPct}|null (US Census ACS, tract-level),
nightlife{composite,tier,components,nearestCluster}? (present only in covered cities; computed at band=20 (20-34 cohort); full components included so callers can recompute other bands; use /api/v1/nightlife?...&band= for a specific cohort) }.
Numeric fields are null when unknown. 404 {error,supportedRegions,hint} for unsupported states.
Example: /api/v1/property?address=1619 Mistletoe Dr, Cleveland, OH

## Map share links
Deep-link the /map page with custom pins:
/map?pins=lat,lng[,label];...&center=lng,lat,zoom&city=<slug>
- pins: semicolon-delimited; optional 3rd field is a per-pin label, encodeURIComponent-encoded. Coords-only is also valid.
- city slugs: cleveland, columbus, bay-area, seattle.
Example: /map?city=cleveland&pins=41.4993,-81.6919,Tremont%20%24450k;41.50,-81.70,HQ

## Notes
- Informational data aggregated from public sources (county assessors, FEMA, US Census, OpenStreetMap); not a substitute for a licensed appraisal.
- Property coverage: OH, CA. Nightlife coverage: the four cities above.