HEAT API technical reference
Start with an assessment exported from the web tool. The exported input list and the selected API model must correspond to the same assessment structure. Keep a record of the endpoint and data assumptions.
Endpoint and methods
Send POST requests to https://api.heatwalkingcycling.org/apiv1/heat_5_0/METHOD?output_format=rds. Replace METHOD with one of the methods below. The model identifier is the service route; it should not be inferred from the website’s version number.
| Method | Purpose | Request objects |
|---|---|---|
results | Prepare the required background data and calculate results in one call. | webapp_input |
prepare_gdr | Prepare relevant generic/background data. | webapp_input |
calc_results | Calculate using supplied inputs and relevant generic data. | webapp_input and generic_data_relevant |
Minimal R example
This example uses the same JSON multipart request style as the downloadable tutorial and requests a serialized R response. Set your own HEAT_API_USER_COOKIE in your private environment before running it.
library(httr)
library(jsonlite)
cookie <- Sys.getenv("HEAT_API_USER_COOKIE")
if (!nzchar(cookie)) stop("Set your own API cookie privately first")
webapp_input <- readRDS("webapp_inputs.rds")
response <- httr::POST(
"https://api.heatwalkingcycling.org/apiv1/heat_5_0/results?output_format=rds",
httr::set_cookies(user = cookie),
body = jsonlite::toJSON(list(webapp_input = webapp_input)),
encode = "multipart",
httr::timeout(90)
)
httr::stop_for_status(response)
assessment <- unserialize(httr::content(response, as = "raw"))
assessment$results
The API also documents JSON and serialized-JSON formats. For complex R objects and empty/NA columns, use the serialization guidance in the original technical documentation; the request and response formats are separate choices.
Understand the returned objects
results contains the presentation-level result table; results_raw contains the model’s unformatted results. Other objects can contain intermediate calculations. Keep the complete response for reproducibility. Mode, pathway and overall totals can overlap: do not add different aggregation levels together.
Prepare valid variations
Use the input codebook to match export names. Keep the ucc_ choices and structural fields from your template unless you are deliberately rebuilding the assessment structure. Numeric changes must still respect the tool’s input restrictions. The API does not replace all validation performed in the web interface.
For a new location, check population, age ranges, mortality, pollution, crash rates and economic valuation. Replacing IDs alone can leave old location-specific values in an exported template. prepare_gdr prepares generic data; it is not a substitute for checking explicit values in your exported input list.
Run and check a batch
Keep within the service limit of five requests per minute per IP address, shared across endpoints and other users on that address. The tutorial spaces requests by 13 seconds; its loop is intended to run sequentially. Stop or reduce requests after service errors, retain successful responses, and check a sample against the web interface. No API calls run when you view these pages or download the example.
Codebooks are versioned reference snapshots. Their values are not a guarantee that a different API deployment or development data bundle uses the same defaults.