API

The HeatCheck API

Public market endpoints need no key; an Investor API key opens every venue, market, compare and report endpoint.

Overview

Base URL: https://api.heatcheck.tech
Format: JSON (UTF-8); CSV for report downloads
Versions: In the path (/v1, /public/v1); /health, /public/pulse and /public/heatmap are unversioned
Dates: New York local YYYY-MM-DD; instants in UTC ISO 8601
Period: grain (day, the default, or month), from and to (inclusive dates, not before 2026-10-24; to defaults to yesterday). At most 92 days or 24 months.
Money: Integer USD cents (6500 = $65.00)
Unknown: null, never 0
Examples: Illustrative values, long arrays trimmed
Estimates: low (P10), mid (P50 for revenue, the mean otherwise), high (P90), ci: 0.8, an A–D grade, drivers

Figures follow the methodology.

Authentication

Authenticated request

export HEATCHECK_API_KEY="hc_live_…"
curl -H "Authorization: Bearer $HEATCHECK_API_KEY" "https://api.heatcheck.tech/v1/venues"

Investor owners and admins create keys under Account → API keys, up to 5 per account. A key looks like hc_live_<8-character prefix>_<32-character secret>, is shown once and is stored only as a SHA-256 hash; revoking it is immediate.
Keys reach /v1/* only. A missing, unknown or revoked key is 401 invalid_api_key; an account no longer on Investor gets 403 plan_required. With an Authorization header, cookies are ignored.
Public endpoints need no key and allow any origin (CORS, without credentials).

Endpoints

Endpoints
Endpoint	Returns	Access
`GET /public/v1/markets`	Markets with public insights	Public, no key
`GET /public/v1/markets/nyc/insights`	Weekly market insights	Public, no key
`GET /public/heatmap`	Weekday × half-hour market heatmap	Public, no key
`GET /public/pulse`	Live counts across every market	Public, no key
`GET /health`	Service status	Public, no key
`GET /v1/venues`	Every venue with its figures	Investor API key
`GET /v1/venues/{id}`	One venue in full	Investor API key
`GET /v1/venues/{id}/timeline`	Contraction timeline of one date	Investor API key
`GET /v1/compare`	2–6 venues side by side	Investor API key
`GET /v1/market`	Market and borough totals	Investor API key
`POST /v1/reports`	A new CSV report	Investor API key
`GET /v1/reports`	Your account’s reports	Investor API key
`GET /v1/reports/{id}/download`	The CSV file	Investor API key

Public endpoints · no key

GET `/public/v1/markets`

The 17 markets with insights and a heatmap (at least 3 public venues), deepest first, with venue counts and the latest completed ISO week.

Request · GET /public/v1/markets

curl "https://api.heatcheck.tech/public/v1/markets"

Example response, values illustrative · GET /public/v1/markets

{
  "markets": [
    {
      "id": "nyc",
      "name": "New York City",
      "venues": 27,
      "latestWeek": {
        "id": "2026-W45",
        "from": "2026-11-02",
        "to": "2026-11-08"
      }
    },
    {
      "id": "orange-county",
      "name": "Orange County, CA",
      "venues": 11,
      "latestWeek": {
        "id": "2026-W45",
        "from": "2026-11-02",
        "to": "2026-11-08"
      }
    }
  ]
}

GET `/public/v1/markets/nyc/insights`

The data of the insights pages: one completed week of market utilization, weekdays, weekday × daypart cells, peaks, borough bands (New York City only) and a trend of up to 13 weeks. No venue names or money; under 3 contributing venues is null. ref identifies the request. CC BY 4.0, credit “HeatCheck (heatcheck.tech)”.

Parameters

market path, required Market id from /public/v1/markets (nyc, orange-county, los-angeles, …); others are 404 market_not_found.
week query ISO week YYYY-Www, one of the last 13 completed, never earlier than 2026-W44. Defaults to the latest; others are 404 week_not_public.

Request · GET /public/v1/markets/nyc/insights

curl "https://api.heatcheck.tech/public/v1/markets/nyc/insights?week=2026-W45"

Example response, values illustrative · GET /public/v1/markets/nyc/insights

{
  "market": {
    "id": "nyc",
    "name": "New York City"
  },
  "week": {
    "id": "2026-W45",
    "from": "2026-11-02",
    "to": "2026-11-08"
  },
  "computedAt": "2026-11-09T09:00:00.000Z",
  "methodVersion": "public-insights/v1",
  "venues": 27,
  "observedVenues": 19,
  "utilization": 0.64,
  "changePoints": 3,
  "weekdays": [
    {
      "weekday": "MON",
      "utilization": 0.52
    },
    {
      "weekday": "SAT",
      "utilization": 0.78
    }
  ],
  "dayparts": {
    "rows": [
      "MON",
      "SAT"
    ],
    "cols": [
      "early",
      "morning",
      "midday",
      "afternoon",
      "evening",
      "late"
    ],
    "cells": [
      [
        null,
        0.41,
        0.47,
        0.5,
        0.68,
        0.55
      ],
      [
        0.36,
        0.7,
        0.79,
        0.76,
        0.81,
        0.63
      ]
    ]
  },
  "peaks": {
    "busiest": [
      {
        "weekday": "SAT",
        "daypart": "evening",
        "utilization": 0.81
      }
    ],
    "quietest": [
      {
        "weekday": "MON",
        "daypart": "morning",
        "utilization": 0.41
      }
    ]
  },
  "boroughs": [
    {
      "borough": "Manhattan",
      "venues": 11,
      "utilization": {
        "low": 0.6,
        "high": 0.7
      }
    },
    {
      "borough": "Staten Island",
      "venues": 1,
      "utilization": null
    }
  ],
  "trend": [
    {
      "week": "2026-W44",
      "from": "2026-10-26",
      "utilization": 0.61
    },
    {
      "week": "2026-W45",
      "from": "2026-11-02",
      "utilization": 0.64
    }
  ],
  "license": "CC BY 4.0",
  "attribution": "HeatCheck (heatcheck.tech)",
  "links": {
    "self": "https://api.heatcheck.tech/public/v1/markets/nyc/insights?week=2026-W45",
    "html": "https://heatcheck.tech/insights/nyc/2026-w45",
    "methodology": "https://heatcheck.tech/methodology",
    "pricing": "https://heatcheck.tech/pricing",
    "previous": "https://api.heatcheck.tech/public/v1/markets/nyc/insights?week=2026-W44",
    "next": null
  },
  "ref": "r_3f9c2a7b"
}

GET `/public/heatmap`

One market’s last completed week: seven weekdays × half-hour starts (00:00–23:30), each cell the unit-hour-weighted utilization of completed slots. Fewer than 3 contributing venues is null; offered tells unknown from not offered.

Parameters

market query Market id from /public/v1/markets; default nyc. Others are 404 market_not_found.

Request · GET /public/heatmap

curl "https://api.heatcheck.tech/public/heatmap?market=nyc"

Example response, values illustrative · GET /public/heatmap

{
  "period": {
    "grain": "day",
    "from": "2026-10-26",
    "to": "2026-11-01"
  },
  "computedAt": "2026-11-02T09:00:00.000Z",
  "venues": 27,
  "methodVersion": "public-heatmap/v1",
  "heatmap": {
    "rows": [
      "Mon",
      "Tue"
    ],
    "cols": [
      "18:00",
      "18:30"
    ],
    "cells": [
      [
        0.71,
        null
      ],
      [
        0.66,
        0.58
      ]
    ],
    "offered": [
      [
        true,
        true
      ],
      [
        true,
        true
      ]
    ]
  }
}

GET `/public/pulse`

Live counts across every public market, yesterday’s utilization and one anonymous heat point per venue (heat: null without supply).

Request · GET /public/pulse

curl "https://api.heatcheck.tech/public/pulse"

Example response, values illustrative · GET /public/pulse

{
  "venues": 127,
  "slotsTracked": 1840,
  "pollsPerDay": 5904,
  "yesterday": {
    "date": "2026-11-01",
    "utilization": 0.6412,
    "soldUnits": 1312
  },
  "points": [
    {
      "lat": 40.7411,
      "lng": -73.9897,
      "heat": 0.7
    },
    {
      "lat": 40.6782,
      "lng": -73.9442,
      "heat": null
    }
  ]
}

GET `/health`

200 with the version while the service and database are up; 503 with status: "error" otherwise.

Request · GET /health

curl "https://api.heatcheck.tech/health"

Example response, values illustrative · GET /health

{
  "status": "ok",
  "version": "0.1.0"
}

Investor API · Bearer key

GET `/v1/venues`

Every public venue with its figures for the period and spark, its daily utilization.

Parameters

grain, from, to query The period (see Overview).

Request · GET /v1/venues

curl -H "Authorization: Bearer $HEATCHECK_API_KEY" "https://api.heatcheck.tech/v1/venues?from=2026-10-26&to=2026-11-01"

Example response, values illustrative · GET /v1/venues

{
  "period": {
    "grain": "day",
    "from": "2026-10-26",
    "to": "2026-11-01"
  },
  "access": {
    "plan": "investor",
    "resolution": "exact",
    "window": null,
    "locked": []
  },
  "venues": [
    {
      "venue": {
        "id": "example-bathhouse",
        "name": "Example Bathhouse",
        "brand": "Example",
        "neighborhood": "Flatiron",
        "borough": "Manhattan",
        "lat": 40.7411,
        "lng": -73.9897,
        "unitLabel": "admission",
        "unitsLabel": "admissions",
        "platform": "trybe",
        "studied": [
          "Bathhouse day pass"
        ],
        "listPrice": {
          "minor": 6500,
          "per": "admission",
          "source": "pricing-page"
        }
      },
      "figures": {
        "venueId": "example-bathhouse",
        "period": {
          "grain": "day",
          "from": "2026-11-01",
          "to": "2026-11-01",
          "label": "2026-11-01"
        },
        "status": "complete",
        "slots": {
          "offered": 30,
          "completed": 30,
          "stale": 0,
          "open": 0
        },
        "supply": {
          "units": 600,
          "unitHours": 1200
        },
        "sold": {
          "low": 402,
          "mid": 418,
          "high": 431,
          "ci": 0.8,
          "grade": "A",
          "drivers": [
            {
              "factor": "stale-final-states",
              "share": 1
            }
          ]
        },
        "utilization": {
          "low": 0.67,
          "mid": 0.697,
          "high": 0.718,
          "ci": 0.8,
          "grade": "A",
          "drivers": [
            {
              "factor": "stale-final-states",
              "share": 1
            }
          ]
        },
        "coverage": 0.98,
        "leftCensoredUnits": 12,
        "revenue": {
          "low": 2540000,
          "mid": 2790000,
          "high": 3080000,
          "ci": 0.8,
          "grade": "B",
          "drivers": [
            {
              "factor": "mix-price",
              "share": 0.58
            },
            {
              "factor": "sold-share",
              "share": 0.42
            }
          ]
        },
        "revPAUH": {
          "low": 181000,
          "mid": 199000,
          "high": 220000,
          "ci": 0.8,
          "grade": "B",
          "drivers": [
            {
              "factor": "mix-price",
              "share": 0.58
            },
            {
              "factor": "sold-share",
              "share": 0.42
            }
          ]
        },
        "guests": null,
        "price": {
          "minMinor": 5500,
          "medianMinor": 6500,
          "maxMinor": 9500
        },
        "modelVersions": {
          "utilization": "utilization/v1",
          "revenue": "revenue/v3"
        },
        "model": {
          "utilization": "v2",
          "revenue": "v3"
        }
      },
      "spark": [
        0.66,
        0.71,
        0.697
      ]
    }
  ]
}

GET `/v1/venues/{id}`

Profile, figures, a series row per day or month, the start-time heatmap (with sold and capacity) and the next-day forecast.

Parameters

id path, required Venue id from /v1/venues.
grain, from, to query The period (see Overview).

Request · GET /v1/venues/{id}

curl -H "Authorization: Bearer $HEATCHECK_API_KEY" "https://api.heatcheck.tech/v1/venues/example-bathhouse?from=2026-11-01&to=2026-11-01"

Example response, values illustrative · GET /v1/venues/{id}

{
  "period": {
    "grain": "day",
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "access": {
    "plan": "investor",
    "resolution": "exact",
    "window": null,
    "locked": []
  },
  "venue": {
    "id": "example-bathhouse",
    "name": "Example Bathhouse",
    "brand": "Example",
    "neighborhood": "Flatiron",
    "borough": "Manhattan",
    "lat": 40.7411,
    "lng": -73.9897,
    "unitLabel": "admission",
    "unitsLabel": "admissions",
    "platform": "trybe",
    "studied": [
      "Bathhouse day pass"
    ],
    "listPrice": {
      "minor": 6500,
      "per": "admission",
      "source": "pricing-page"
    },
    "description": "Thermal circuit with saunas, steam rooms and cold plunges",
    "address": {
      "line1": "1 Example Street",
      "city": "New York",
      "region": "NY",
      "postalCode": "10010"
    },
    "website": "https://example.com",
    "bookingUrl": "https://example.com/book",
    "services": [
      {
        "id": "day-pass",
        "name": "Bathhouse day pass",
        "category": "thermal-circuit",
        "prices": [
          {
            "amountMinor": 6500,
            "currency": "USD",
            "per": "person",
            "durationMinutes": 120,
            "source": "pricing-page",
            "observedAt": "2026-10-24"
          }
        ],
        "studied": true,
        "source": "pricing-page"
      }
    ],
    "scope": {
      "unit": "admission",
      "window": "30-minute arrival window",
      "notes": [
        "Day passes only"
      ],
      "excluded": [
        {
          "what": "Spa treatments",
          "why": "Booked by appointment, not by arrival window"
        }
      ]
    },
    "pools": [
      {
        "id": "admission",
        "label": "Day pass entry",
        "kind": "entry-window"
      }
    ],
    "streams": [
      {
        "id": "near",
        "cadenceMinutes": 5,
        "dayOffsets": [
          0,
          2
        ]
      }
    ]
  },
  "figures": {
    "venueId": "example-bathhouse",
    "period": {
      "grain": "day",
      "from": "2026-11-01",
      "to": "2026-11-01",
      "label": "2026-11-01"
    },
    "status": "complete",
    "slots": {
      "offered": 30,
      "completed": 30,
      "stale": 0,
      "open": 0
    },
    "supply": {
      "units": 600,
      "unitHours": 1200
    },
    "sold": {
      "low": 402,
      "mid": 418,
      "high": 431,
      "ci": 0.8,
      "grade": "A",
      "drivers": [
        {
          "factor": "stale-final-states",
          "share": 1
        }
      ]
    },
    "utilization": {
      "low": 0.67,
      "mid": 0.697,
      "high": 0.718,
      "ci": 0.8,
      "grade": "A",
      "drivers": [
        {
          "factor": "stale-final-states",
          "share": 1
        }
      ]
    },
    "coverage": 0.98,
    "leftCensoredUnits": 12,
    "revenue": {
      "low": 2540000,
      "mid": 2790000,
      "high": 3080000,
      "ci": 0.8,
      "grade": "B",
      "drivers": [
        {
          "factor": "mix-price",
          "share": 0.58
        },
        {
          "factor": "sold-share",
          "share": 0.42
        }
      ]
    },
    "revPAUH": {
      "low": 181000,
      "mid": 199000,
      "high": 220000,
      "ci": 0.8,
      "grade": "B",
      "drivers": [
        {
          "factor": "mix-price",
          "share": 0.58
        },
        {
          "factor": "sold-share",
          "share": 0.42
        }
      ]
    },
    "guests": null,
    "price": {
      "minMinor": 5500,
      "medianMinor": 6500,
      "maxMinor": 9500
    },
    "modelVersions": {
      "utilization": "utilization/v1",
      "revenue": "revenue/v3"
    },
    "model": {
      "utilization": "v2",
      "revenue": "v3"
    }
  },
  "series": [
    {
      "venueId": "example-bathhouse",
      "period": {
        "grain": "day",
        "from": "2026-11-01",
        "to": "2026-11-01",
        "label": "2026-11-01"
      },
      "status": "complete",
      "slots": {
        "offered": 30,
        "completed": 30,
        "stale": 0,
        "open": 0
      },
      "supply": {
        "units": 600,
        "unitHours": 1200
      },
      "sold": {
        "low": 402,
        "mid": 418,
        "high": 431,
        "ci": 0.8,
        "grade": "A",
        "drivers": [
          {
            "factor": "stale-final-states",
            "share": 1
          }
        ]
      },
      "utilization": {
        "low": 0.67,
        "mid": 0.697,
        "high": 0.718,
        "ci": 0.8,
        "grade": "A",
        "drivers": [
          {
            "factor": "stale-final-states",
            "share": 1
          }
        ]
      },
      "coverage": 0.98,
      "leftCensoredUnits": 12,
      "revenue": {
        "low": 2540000,
        "mid": 2790000,
        "high": 3080000,
        "ci": 0.8,
        "grade": "B",
        "drivers": [
          {
            "factor": "mix-price",
            "share": 0.58
          },
          {
            "factor": "sold-share",
            "share": 0.42
          }
        ]
      },
      "revPAUH": {
        "low": 181000,
        "mid": 199000,
        "high": 220000,
        "ci": 0.8,
        "grade": "B",
        "drivers": [
          {
            "factor": "mix-price",
            "share": 0.58
          },
          {
            "factor": "sold-share",
            "share": 0.42
          }
        ]
      },
      "guests": null,
      "price": {
        "minMinor": 5500,
        "medianMinor": 6500,
        "maxMinor": 9500
      },
      "modelVersions": {
        "utilization": "utilization/v1",
        "revenue": "revenue/v3"
      },
      "model": {
        "utilization": "v2",
        "revenue": "v3"
      }
    }
  ],
  "heatmap": {
    "rows": [
      "2026-11-01"
    ],
    "cols": [
      "18:00",
      "18:30"
    ],
    "cells": [
      [
        0.93,
        null
      ]
    ],
    "offered": [
      [
        true,
        true
      ]
    ],
    "sold": [
      [
        28,
        null
      ]
    ],
    "capacity": [
      [
        30,
        null
      ]
    ]
  },
  "forecast": {
    "venueId": "example-bathhouse",
    "date": "2026-11-02",
    "asOf": "2026-11-01T22:00:00.000Z",
    "status": "provisional",
    "method": "additive-pickup-v1",
    "bookedSoFar": {
      "units": 212,
      "share": 0.35
    },
    "sold": {
      "low": 371,
      "mid": 405,
      "high": 438,
      "ci": 0.8,
      "grade": "B",
      "drivers": []
    },
    "revenue": {
      "low": 2330000,
      "mid": 2640000,
      "high": 2990000,
      "ci": 0.8,
      "grade": "B",
      "drivers": []
    },
    "utilization": {
      "low": 0.62,
      "mid": 0.675,
      "high": 0.73,
      "ci": 0.8,
      "grade": "B",
      "drivers": []
    },
    "reason": null
  }
}

GET `/v1/venues/{id}/timeline`

How each slot of one service date sold down, poll by poll, and the booking pace curve. leftCensored counts units already gone at the first observation.

Parameters

id path, required Venue id.
date query Service date YYYY-MM-DD; defaults to yesterday on Pro, today on Investor (New York). On Pro, today or later is 403 plan_required (intraday).

Request · GET /v1/venues/{id}/timeline

curl -H "Authorization: Bearer $HEATCHECK_API_KEY" "https://api.heatcheck.tech/v1/venues/example-bathhouse/timeline?date=2026-11-01"

Example response, values illustrative · GET /v1/venues/{id}/timeline

{
  "date": "2026-11-01",
  "slots": [
    {
      "time": "18:00",
      "poolId": "admission",
      "capacity": 30,
      "leftCensored": 6,
      "points": [
        {
          "at": "2026-10-30T22:00:00.000Z",
          "unavailable": 6
        },
        {
          "at": "2026-11-01T22:55:00.000Z",
          "unavailable": 28
        }
      ],
      "finalStatus": "completed"
    }
  ],
  "curve": [
    {
      "leadHours": 48,
      "share": 0.21
    },
    {
      "leadHours": 0,
      "share": 0.83
    }
  ],
  "access": {
    "plan": "investor",
    "resolution": "exact",
    "window": null,
    "locked": []
  }
}

GET `/v1/compare`

Figures and series of 2–6 venues on one period and scale. An unknown id is 404 venue_not_found.

Parameters

ids query, required Comma-separated venue ids, 2 to 6.
grain, from, to query The period (see Overview).

Request · GET /v1/compare

curl -H "Authorization: Bearer $HEATCHECK_API_KEY" "https://api.heatcheck.tech/v1/compare?ids=example-bathhouse,another-venue&from=2026-11-01&to=2026-11-01"

Example response, values illustrative · GET /v1/compare

{
  "period": {
    "grain": "day",
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "access": {
    "plan": "investor",
    "resolution": "exact",
    "window": null,
    "locked": []
  },
  "venues": [
    {
      "venue": {
        "id": "example-bathhouse",
        "name": "Example Bathhouse",
        "brand": "Example",
        "neighborhood": "Flatiron",
        "borough": "Manhattan",
        "lat": 40.7411,
        "lng": -73.9897,
        "unitLabel": "admission",
        "unitsLabel": "admissions",
        "platform": "trybe",
        "studied": [
          "Bathhouse day pass"
        ],
        "listPrice": {
          "minor": 6500,
          "per": "admission",
          "source": "pricing-page"
        }
      },
      "figures": {
        "venueId": "example-bathhouse",
        "period": {
          "grain": "day",
          "from": "2026-11-01",
          "to": "2026-11-01",
          "label": "2026-11-01"
        },
        "status": "complete",
        "slots": {
          "offered": 30,
          "completed": 30,
          "stale": 0,
          "open": 0
        },
        "supply": {
          "units": 600,
          "unitHours": 1200
        },
        "sold": {
          "low": 402,
          "mid": 418,
          "high": 431,
          "ci": 0.8,
          "grade": "A",
          "drivers": [
            {
              "factor": "stale-final-states",
              "share": 1
            }
          ]
        },
        "utilization": {
          "low": 0.67,
          "mid": 0.697,
          "high": 0.718,
          "ci": 0.8,
          "grade": "A",
          "drivers": [
            {
              "factor": "stale-final-states",
              "share": 1
            }
          ]
        },
        "coverage": 0.98,
        "leftCensoredUnits": 12,
        "revenue": {
          "low": 2540000,
          "mid": 2790000,
          "high": 3080000,
          "ci": 0.8,
          "grade": "B",
          "drivers": [
            {
              "factor": "mix-price",
              "share": 0.58
            },
            {
              "factor": "sold-share",
              "share": 0.42
            }
          ]
        },
        "revPAUH": {
          "low": 181000,
          "mid": 199000,
          "high": 220000,
          "ci": 0.8,
          "grade": "B",
          "drivers": [
            {
              "factor": "mix-price",
              "share": 0.58
            },
            {
              "factor": "sold-share",
              "share": 0.42
            }
          ]
        },
        "guests": null,
        "price": {
          "minMinor": 5500,
          "medianMinor": 6500,
          "maxMinor": 9500
        },
        "modelVersions": {
          "utilization": "utilization/v1",
          "revenue": "revenue/v3"
        },
        "model": {
          "utilization": "v2",
          "revenue": "v3"
        }
      },
      "series": [
        {
          "venueId": "example-bathhouse",
          "period": {
            "grain": "day",
            "from": "2026-11-01",
            "to": "2026-11-01",
            "label": "2026-11-01"
          },
          "status": "complete",
          "slots": {
            "offered": 30,
            "completed": 30,
            "stale": 0,
            "open": 0
          },
          "supply": {
            "units": 600,
            "unitHours": 1200
          },
          "sold": {
            "low": 402,
            "mid": 418,
            "high": 431,
            "ci": 0.8,
            "grade": "A",
            "drivers": [
              {
                "factor": "stale-final-states",
                "share": 1
              }
            ]
          },
          "utilization": {
            "low": 0.67,
            "mid": 0.697,
            "high": 0.718,
            "ci": 0.8,
            "grade": "A",
            "drivers": [
              {
                "factor": "stale-final-states",
                "share": 1
              }
            ]
          },
          "coverage": 0.98,
          "leftCensoredUnits": 12,
          "revenue": {
            "low": 2540000,
            "mid": 2790000,
            "high": 3080000,
            "ci": 0.8,
            "grade": "B",
            "drivers": [
              {
                "factor": "mix-price",
                "share": 0.58
              },
              {
                "factor": "sold-share",
                "share": 0.42
              }
            ]
          },
          "revPAUH": {
            "low": 181000,
            "mid": 199000,
            "high": 220000,
            "ci": 0.8,
            "grade": "B",
            "drivers": [
              {
                "factor": "mix-price",
                "share": 0.58
              },
              {
                "factor": "sold-share",
                "share": 0.42
              }
            ]
          },
          "guests": null,
          "price": {
            "minMinor": 5500,
            "medianMinor": 6500,
            "maxMinor": 9500
          },
          "modelVersions": {
            "utilization": "utilization/v1",
            "revenue": "revenue/v3"
          },
          "model": {
            "utilization": "v2",
            "revenue": "v3"
          }
        }
      ]
    }
  ]
}

GET `/v1/market`

Market and borough revenue (the sum of venue estimates), unit-hour-weighted utilization and coverage. An estimate with nothing behind it is null, never zero.

Parameters

grain, from, to query The period (see Overview).

Request · GET /v1/market

curl -H "Authorization: Bearer $HEATCHECK_API_KEY" "https://api.heatcheck.tech/v1/market?from=2026-10-26&to=2026-11-01"

Example response, values illustrative · GET /v1/market

{
  "period": {
    "grain": "day",
    "from": "2026-10-26",
    "to": "2026-11-01"
  },
  "access": {
    "plan": "investor",
    "resolution": "exact",
    "window": null,
    "locked": []
  },
  "figures": {
    "revenue": {
      "low": 41200000,
      "mid": 48900000,
      "high": 58100000,
      "ci": 0.8,
      "grade": "B",
      "drivers": []
    },
    "utilization": {
      "low": 0.61,
      "mid": 0.64,
      "high": 0.67,
      "ci": 0.8,
      "grade": "A",
      "drivers": []
    },
    "coverage": {
      "venues": 27,
      "observed": 19
    }
  },
  "byBorough": [
    {
      "borough": "Manhattan",
      "revenue": {
        "low": 25800000,
        "mid": 31400000,
        "high": 38000000,
        "ci": 0.8,
        "grade": "B",
        "drivers": []
      },
      "utilization": {
        "low": 0.63,
        "mid": 0.66,
        "high": 0.69,
        "ci": 0.8,
        "grade": "A",
        "drivers": []
      },
      "coverage": {
        "venues": 11,
        "observed": 11
      }
    }
  ]
}

POST `/v1/reports`

Builds a CSV: venue, compare (2–12 venues) or market, by default the 30 days to yesterday. Up to 20 a day per user; the same request on the same day returns the existing report (200, reused: true), for 15 minutes only if it reaches today. Kept 7 days.

Parameters

kind body, required venue, compare or market.
venueIds body One for venue, 2–12 for compare, none for market.
grain, from, to body The period, never clamped: a day range over 92 days is 400 period_too_long.

Request · POST /v1/reports

curl -X POST -H "Authorization: Bearer $HEATCHECK_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"market","grain":"day","from":"2026-10-24","to":"2026-11-01"}' \
  "https://api.heatcheck.tech/v1/reports"

Example response (201), values illustrative · POST /v1/reports

{
  "report": {
    "id": "rpt_8d1f0c",
    "kind": "market",
    "label": "Market",
    "grain": "day",
    "from": "2026-10-24",
    "to": "2026-11-01",
    "venueIds": [],
    "status": "ready",
    "bytes": 18342,
    "createdAt": "2026-11-02T14:03:11.000Z",
    "expiresAt": "2026-11-09T14:03:11.000Z"
  }
}

GET `/v1/reports`

Your accounts’ reports, newest first (up to 100), and today’s quota.

Request · GET /v1/reports

curl -H "Authorization: Bearer $HEATCHECK_API_KEY" "https://api.heatcheck.tech/v1/reports"

Example response, values illustrative · GET /v1/reports

{
  "reports": [
    {
      "id": "rpt_8d1f0c",
      "kind": "market",
      "label": "Market",
      "grain": "day",
      "from": "2026-10-24",
      "to": "2026-11-01",
      "venueIds": [],
      "status": "ready",
      "bytes": 18342,
      "createdAt": "2026-11-02T14:03:11.000Z",
      "expiresAt": "2026-11-09T14:03:11.000Z"
    }
  ],
  "quota": {
    "used": 1,
    "limit": 20
  }
}

GET `/v1/reports/{id}/download`

The report as text/csv (UTF-8 with BOM, CRLF), named heatcheck-<kind>-<from>-<to>.csv. Money in USD with cents; unknown values empty, never 0. Expired: 410 report_expired.

Parameters

id path, required Report id from /v1/reports.

Request · GET /v1/reports/{id}/download

curl -H "Authorization: Bearer $HEATCHECK_API_KEY" -OJ "https://api.heatcheck.tech/v1/reports/rpt_8d1f0c/download"

Example response, values illustrative · GET /v1/reports/{id}/download

venue_id,name,period_from,period_to,status,supply_units,sold_low,sold_mid,sold_high,utilization_low,utilization_mid,utilization_high,revenue_low,revenue_mid,revenue_high,revpauh_mid,price_min,price_median,price_max,coverage,grade

Rate limits

Rate limits
Caller	Counted	Per day	Per minute
Anonymous, public routes	per IP (an IPv6 /48 counts as one)	1,000	60
Free, signed in	per user	300	—
Pro, signed in	per user	3,000	—
Investor, signed in	per user	10,000	—
Investor API key	per account a day, per key a minute	10,000	60
Investor CSV reports	new reports per user	20	—

Days are New York days. /v1 responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for the daily quota. Over a limit: 429 with Retry-After (seconds).

Plans and access

Every /v1 data response carries access: the plan, the resolution (exact or band), the readable date window (null = all) and the locked features. A route outside the plan is 403 plan_required, with feature and requiredPlan.

Access by plan
Route	Free	Pro	Investor
`GET /v1/venues`, `/v1/venues/{id}`, `/v1/market`	Band shapes, last completed week	Full shapes, every day since 2026-10-24	Same as Pro
`GET /v1/venues/{id}/timeline`	`plan_required`	✓	✓
`GET /v1/compare`	`plan_required`	✓ (2–6 venues)	✓ (2–6 venues)
`POST /v1/reports`, `GET /v1/reports`, download	`plan_required`	`plan_required`	✓ (20 a day, up to 12 venues)
API keys on `/v1/*`	—	—	✓ (5 keys)

Free (signed in, no key): Always the last completed Monday–Sunday week. /v1/venues returns {period, access, venues: [{venue, band}]} by rank, each band a 10-point utilization band ({low: 0.6, high: 0.7}), rank and price range; /v1/venues/{id} adds dayparts; /v1/market returns bands and a revenue range rounded to two significant figures. No exact figure, series, revenue or half-hour cell.

Free shapes, values illustrative, trimmed

{
  "access": {
    "plan": "free",
    "resolution": "band",
    "window": {
      "from": "2026-10-26",
      "to": "2026-11-01"
    },
    "locked": [
      "exact",
      "history",
      "revenue",
      "series",
      "forecast",
      "timeline",
      "halfHour",
      "intraday"
    ]
  },
  "band": {
    "venueId": "example-bathhouse",
    "period": {
      "grain": "day",
      "from": "2026-10-26",
      "to": "2026-11-01"
    },
    "status": "complete",
    "utilization": {
      "low": 0.6,
      "high": 0.7
    },
    "rank": 4,
    "ranked": 19,
    "price": {
      "minMinor": 5500,
      "medianMinor": 6500,
      "maxMinor": 9500
    }
  },
  "dayparts": {
    "rows": [
      "MON",
      "TUE"
    ],
    "cols": [
      "early",
      "morning",
      "midday",
      "afternoon",
      "evening",
      "late"
    ],
    "cells": [
      [
        null,
        {
          "low": 0.3,
          "high": 0.4
        },
        {
          "low": 0.4,
          "high": 0.5
        },
        {
          "low": 0.5,
          "high": 0.6
        },
        {
          "low": 0.8,
          "high": 0.9
        },
        {
          "low": 0.6,
          "high": 0.7
        }
      ],
      [
        null,
        {
          "low": 0.3,
          "high": 0.4
        },
        {
          "low": 0.4,
          "high": 0.5
        },
        null,
        {
          "low": 0.7,
          "high": 0.8
        },
        {
          "low": 0.6,
          "high": 0.7
        }
      ]
    ],
    "offered": [
      [
        false,
        true,
        true,
        true,
        true,
        true
      ],
      [
        false,
        true,
        true,
        true,
        true,
        true
      ]
    ]
  }
}

Errors

One envelope, with a matching HTTP status. Branch on error.code; message is for people.

Error envelope

{
  "error": {
    "code": "plan_required",
    "message": "Compare needs the Pro plan",
    "feature": "compare",
    "requiredPlan": "pro"
  }
}

Error codes
Status	Codes
400	`invalid_request`, `invalid_json`, `invalid_period`, `period_too_long`, `too_many_venues`, `invalid_week`
401	`invalid_api_key`, `unauthenticated`
403	`plan_required` (with `feature` and `requiredPlan`), `forbidden`, `no_account`
404	`not_found`, `venue_not_found`, `report_not_found`, `market_not_found`, `week_not_public`
410	`report_expired`
415	`unsupported_media_type`: a `POST` or `DELETE` without `Content-Type: application/json`
429	`quota_exceeded`, `rate_limited`, `report_quota_exceeded`
503	`busy` (retry shortly)

Licence

Public insights (the pages and /public/v1) are CC BY 4.0: reuse them, commercially too, crediting “HeatCheck (heatcheck.tech)”.

App, /v1 and CSV data are for the subscribing account’s internal use; redistribution needs a separate agreement (talk to us).

Get an API key

Investor, from $12,000 a year. Write to [email protected] with your company and the data you need.

OpenAPI 3.1 description · llms.txt · Pricing · Methodology · Talk to us about Investor