Building Health Intelligence API

Validated to predict risk

The grade isn't descriptive — it's predictive. In a point-in-time, leakage-controlled backtest (grade as of a fixed date vs. what happened to each building afterward), the score strongly separates which buildings will have serious problems — the chronic, maintenance-driven conditions that drive attritional loss.

Validated across 11 independent outcomes and government distress lists (HPD Underlying Conditions, CONH, AEP). The score predicts chronic, maintenance-driven distress (water damage, habitability) — not acute catastrophes or financial default. Full methodology available to API clients.

Quick Start

Authenticate with your API key via the Authorization: Bearer header. All responses return JSON with a consistent envelope.

curl -H "Authorization: Bearer sk_live_your_key_here" \
  https://openstoop.com/api/v1/buildings/1004700039

{
  "data": {
    "bbl": "1004700039",
    "address": "120 ELIZABETH STREET",
    "city": "New York",
    "zipcode": "10013",
    "borough": 1,
    "borough_name": "Manhattan",
    "residential_units": 22,
    "total_units": 24,
    "year_built": 1900,
    "building_class": "C7",
    "owner_name": "JING CHENG REALTY INC.",
    "latitude": 40.7192123,
    "longitude": -73.9952489,
    "scores": {
      "total_score": 83,
      "health_score": 17,
      "grade": "F",
      "label": "Distressed",
      "scorer_id": "distress_v10_2",
      "peer_group": "large-pre-war",
      "data_quality": "corroborated",
      "components": {
        "living_conditions":    { "score": 44.2, "grade": "C" },
        "building_safety":      { "score": 53.1, "grade": "D" },
        "complaint_burden":     { "score": 22.1, "grade": "B" },
        "management_quality":   { "score": 20.0, "grade": "B" },
        "financial_distress":   { "score":  0.0, "grade": "A" },
        "deferred_maintenance": { "score":  0.0, "grade": "A" },
        "legal_enforcement":    { "score": 21.9, "grade": "B" }
      },
      "flags": ["fdny-vacate-active"]
    },
    "counts": {
      "hpd_violations_total": 82,
      "hpd_violations_open": 43,
      "hpd_class_c_open": 11,
      "dob_violations_total": 11,
      "complaints_311": 17,
      "permits": 2,
      "total_events": 303
    },
    "confidence": {
      "score": 78.03,
      "tier": "corroborated",
      "flags": [],
      "dimensions": {
        "coverage": 68.06,
        "freshness": 98.49,
        "corroboration": 71.43
      },
      "primary_sources": 8,
      "active_families": 5
    }
  },
  "meta": {
    "request_id": "req_70fb907e8223",
    "api_version": "v1",
    "timestamp": "2026-04-03T15:53:55.286Z"
  },
  "pagination": null,
  "_links": {
    "self": "/api/v1/buildings/1004700039",
    "events": "/api/v1/buildings/1004700039/events",
    "trajectory": "/api/v1/buildings/1004700039/trajectory"
  }
}

Authentication

API keys use the format sk_live_... for client keys. The playground below uses a public read-only sk_demo_... key. Keys are SHA-256 hashed before storage and never stored in plaintext. All traffic is encrypted via TLS 1.3.

curl -H "Authorization: Bearer sk_live_..." \
  https://openstoop.com/api/v1/buildings/1004700039

curl -H "X-API-Key: sk_live_..." \
  https://openstoop.com/api/v1/buildings/1004700039

Try It

Test the API live. A public, read-only demo key is pre-filled and rate-limited — or use your own.

API Reference

Base URL: https://openstoop.com/api/v1

Response Envelope

Every response uses a consistent envelope. All field names are snake_case.

Errors

Errors use the same envelope with a machine-readable code. No internal details are exposed.

{
  "error": {
    "code": "building_not_found",
    "message": "Building 1000000000 not found",
    "status": 404
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-30T12:00:00Z"
  }
}

Rate Limiting

Rate limits are per API key. Every response includes rate limit headers so your integration can adapt automatically.

Scoring

Each building receives a proprietary distress score (0-100) derived from multiple dimensions of building health. The model analyzes patterns across 25+ public data sources to produce a single grade from A (excellent) to F (distressed). Detailed methodology is available to API clients under NDA.

Data Sources

Scores are derived from 25+ NYC public data sources, cross-referenced and updated daily. The /sources endpoint is planned for source-level freshness data.

Integration Examples

The API returns standard JSON over HTTPS. No SDK required.

import requests

API_KEY = "sk_live_your_key_here"
BASE = "https://openstoop.com/api/v1"

# Look up a building
r = requests.get(f"{BASE}/buildings/1004700039",
    headers={"Authorization": f"Bearer {API_KEY}"})

building = r.json()["data"]
print(f"{building['address']}: Grade {building['scores']['grade']}")
# → 120 ELIZABETH STREET: Grade F

# Check components
for name, comp in building["scores"]["components"].items():
    print(f"  {name}: {comp['score']} ({comp['grade']})")

# Check confidence
conf = building["confidence"]
print(f"Confidence: {conf['score']} ({conf['tier']})")
print(f"  Coverage: {conf['dimensions']['coverage']}")
print(f"  Freshness: {conf['dimensions']['freshness']}")

Versioning

The API is versioned via URL path (/v1/). Breaking changes will only be introduced in new major versions. Existing versions remain supported with a minimum 12-month deprecation notice.