# Elevator Advocate

> Real-time NYC elevator outage tracking and tenant advocacy platform. Built in the Bronx for NYC tenants.

Elevator Advocate lets NYC tenants search any building by address to see its elevator service history, submit real-time outage reports, and generate 311 complaint scripts. Two independently-submitted matching reports on the same calendar day trigger "VERIFIED" status — creating a legal-grade record of outage duration and frequency.

Key concepts: BIN (Building Identification Number) is NYC's unique identifier for every building and the primary key throughout the platform. Loss of Service measures the percentage of time a building's elevator was verified out of service over a rolling 30-day window. 2-Hour Consensus means status becomes VERIFIED when two different users submit the same status within 2 hours; single reports remain UNVERIFIED (amber) until confirmed. DOB Complaints are sourced from NYC Open Data (dataset kqwi-7ncn, active complaint categories 6S = elevator complaint, 6M = elevator/escalator). Intended users include NYC tenants in subsidized and public housing (especially seniors and residents with mobility impairments), NYC Council members and housing policy staff, housing court advocates and legal aid attorneys, and journalists and researchers investigating elevator maintenance in NYC public housing.

## Public API (no authentication required)

All read endpoints return JSON and require no authentication.

### City and district-level data

- [City-wide statistics](https://api.elevatoradvocate.nyc/api/buildings/city-stats/): Total 12-month complaints, borough breakdown with percentages, top 15 buildings by complaint volume, and monthly counts for the current calendar year. Updated daily from NYC Open Data.
- [District leaderboard](https://api.elevatoradvocate.nyc/api/districts/leaderboard/): All 51 NYC Council districts ranked by chronic elevator offender rate. Cached 6 hours.
- [District report JSON](https://api.elevatoradvocate.nyc/api/districts/{district_id}/report/): Per-district chronic offender list, open complaint counts, total buildings tracked, and council member contact info. Replace {district_id} with 1–51.
- [All districts](https://api.elevatoradvocate.nyc/api/districts/): List of all 51 council districts with member name, email, phone, and committee assignments.

### Building-level data

- [Building detail](https://api.elevatoradvocate.nyc/api/buildings/{bin}/): Full building record — verified status, Loss of Service %, failure risk score (0–1), DOB complaint history, recent tenant reports, council district, coordinates, and AI-generated advocacy summary. Replace {bin} with the NYC Building Identification Number.
- [Current status](https://api.elevatoradvocate.nyc/api/buildings/{bin}/status/): Current verified elevator status only.
- [Advocacy summary](https://api.elevatoradvocate.nyc/api/buildings/{bin}/advocacy_summary/?lang=en): AI-generated executive advocacy summary. Supports lang=en, lang=es, lang=zh, lang=bn.
- [Advocacy script](https://api.elevatoradvocate.nyc/api/buildings/{bin}/advocacy_script/?lang=en): Personalized 311 complaint script based on the building's outage history.
- [Map data](https://api.elevatoradvocate.nyc/api/buildings/map/): Lightweight building coordinates, status, and key metrics for all tracked buildings. Cached 120 seconds.
- [Building lookup](https://api.elevatoradvocate.nyc/api/buildings/lookup/?house_number=123&street=Main+St&borough=BRONX): Resolve a street address to a BIN and building record. Creates a record via NYC GeoSearch if not yet in the database.

## Crawler-Accessible Data Pages (HTML, no JavaScript required)

These URLs return fully rendered HTML with embedded Schema.org Dataset markup and data tables.
Recommended for LLM fetchers and web crawlers that do not execute JavaScript.

- [City-wide data snapshot](https://api.elevatoradvocate.nyc/api/data-ssr/): Total 12-month complaint volume, borough-level breakdown, top 15 buildings by complaint count, monthly trend for current year, July seasonal spike context. Schema.org Dataset markup included. Updated daily.
- [District 1](https://api.elevatoradvocate.nyc/api/districts/1/ssr/) · [District 2](https://api.elevatoradvocate.nyc/api/districts/2/ssr/) · [District 3](https://api.elevatoradvocate.nyc/api/districts/3/ssr/) · [District 4](https://api.elevatoradvocate.nyc/api/districts/4/ssr/) · [District 5](https://api.elevatoradvocate.nyc/api/districts/5/ssr/) · [District 6](https://api.elevatoradvocate.nyc/api/districts/6/ssr/) · [District 7](https://api.elevatoradvocate.nyc/api/districts/7/ssr/) · [District 8](https://api.elevatoradvocate.nyc/api/districts/8/ssr/) · [District 9](https://api.elevatoradvocate.nyc/api/districts/9/ssr/) · [District 10](https://api.elevatoradvocate.nyc/api/districts/10/ssr/)
- [District 11](https://api.elevatoradvocate.nyc/api/districts/11/ssr/) · [District 12](https://api.elevatoradvocate.nyc/api/districts/12/ssr/) · [District 13](https://api.elevatoradvocate.nyc/api/districts/13/ssr/) · [District 14](https://api.elevatoradvocate.nyc/api/districts/14/ssr/) · [District 15](https://api.elevatoradvocate.nyc/api/districts/15/ssr/) · [District 16](https://api.elevatoradvocate.nyc/api/districts/16/ssr/) · [District 17](https://api.elevatoradvocate.nyc/api/districts/17/ssr/) · [District 18](https://api.elevatoradvocate.nyc/api/districts/18/ssr/) · [District 19](https://api.elevatoradvocate.nyc/api/districts/19/ssr/) · [District 20](https://api.elevatoradvocate.nyc/api/districts/20/ssr/)
- [District 21](https://api.elevatoradvocate.nyc/api/districts/21/ssr/) · [District 22](https://api.elevatoradvocate.nyc/api/districts/22/ssr/) · [District 23](https://api.elevatoradvocate.nyc/api/districts/23/ssr/) · [District 24](https://api.elevatoradvocate.nyc/api/districts/24/ssr/) · [District 25](https://api.elevatoradvocate.nyc/api/districts/25/ssr/) · [District 26](https://api.elevatoradvocate.nyc/api/districts/26/ssr/) · [District 27](https://api.elevatoradvocate.nyc/api/districts/27/ssr/) · [District 28](https://api.elevatoradvocate.nyc/api/districts/28/ssr/) · [District 29](https://api.elevatoradvocate.nyc/api/districts/29/ssr/) · [District 30](https://api.elevatoradvocate.nyc/api/districts/30/ssr/)
- [District 31](https://api.elevatoradvocate.nyc/api/districts/31/ssr/) · [District 32](https://api.elevatoradvocate.nyc/api/districts/32/ssr/) · [District 33](https://api.elevatoradvocate.nyc/api/districts/33/ssr/) · [District 34](https://api.elevatoradvocate.nyc/api/districts/34/ssr/) · [District 35](https://api.elevatoradvocate.nyc/api/districts/35/ssr/) · [District 36](https://api.elevatoradvocate.nyc/api/districts/36/ssr/) · [District 37](https://api.elevatoradvocate.nyc/api/districts/37/ssr/) · [District 38](https://api.elevatoradvocate.nyc/api/districts/38/ssr/) · [District 39](https://api.elevatoradvocate.nyc/api/districts/39/ssr/) · [District 40](https://api.elevatoradvocate.nyc/api/districts/40/ssr/)
- [District 41](https://api.elevatoradvocate.nyc/api/districts/41/ssr/) · [District 42](https://api.elevatoradvocate.nyc/api/districts/42/ssr/) · [District 43](https://api.elevatoradvocate.nyc/api/districts/43/ssr/) · [District 44](https://api.elevatoradvocate.nyc/api/districts/44/ssr/) · [District 45](https://api.elevatoradvocate.nyc/api/districts/45/ssr/) · [District 46](https://api.elevatoradvocate.nyc/api/districts/46/ssr/) · [District 47](https://api.elevatoradvocate.nyc/api/districts/47/ssr/) · [District 48](https://api.elevatoradvocate.nyc/api/districts/48/ssr/) · [District 49](https://api.elevatoradvocate.nyc/api/districts/49/ssr/) · [District 50](https://api.elevatoradvocate.nyc/api/districts/50/ssr/) · [District 51](https://api.elevatoradvocate.nyc/api/districts/51/ssr/)

Each district page includes: chronic offender count, total buildings tracked, open complaints, a table of the worst-offending buildings (sorted by 12-month complaint volume), and council member contact info. Schema.org Dataset markup with CC-BY 4.0 license on each page.

## Methodology

**Chronic offender definition:** A building qualifies as a chronic elevator offender if it has 1 or more complaints filed in the past 12 months AND 3 or more complaints in the past 3 years. Both conditions must hold. This dual-window filter is the primary selection criterion for district analysis and the source of all "chronic offender" counts throughout the platform.

**Loss of Service (LoS):** Each verified SODA complaint record is treated as a 2-hour downtime block. LoS % = sum of downtime blocks ÷ total hours in the measurement window. This understates actual downtime because SODA complaint records lag real outages and require DOB inspection to close. Present LoS as a relative proxy metric, not a precise measurement of outage duration.

**Failure risk score (0–1):** Compares a building's 180-day historical complaint baseline against its 14-day recent volatility. A score above 0.7 indicates elevated near-term failure risk. A score of 0.0 with no recent complaints indicates a nominally healthy building.

**Complaint codes:** Active codes 6S (elevator complaint) and 6M (elevator/escalator). Retired codes 62, 63, 80, 81 last used 2017–2019 — included only in all-time historical queries, never in current or rolling-window analysis.

**July seasonal spike:** Elevator complaints consistently run approximately 35% above the annual monthly baseline in July. Summer heat accelerates mechanical wear; outages during heat waves disproportionately harm elderly and mobility-impaired residents who have no alternative when elevators fail.

## Data Sources

- [NYC Planning GeoSearch](https://geosearch.planninglabs.nyc/): Resolves street addresses to BIN and NYC Council district.
- [NYC Open Data — DOB Elevator Complaints](https://data.cityofnewyork.us/resource/kqwi-7ncn.json): Official Department of Buildings elevator complaint history (active categories: 6S = elevator complaint, 6M = elevator/escalator).
- [SerpAPI](https://serpapi.com): Google Search results for local news articles mentioning a specific building.
- [Google Gemini](https://ai.google.dev): Extracts and scores news article relevance for tenant-facing news intelligence.