Running bulk applications using the HEAT API
Advanced users can now run bulk HEAT assessments via code, using the API (Application Programming Interface) feature.
The API connects your code to the HEAT calculation model. It is useful for repeating an assessment across locations, years or scenarios and collecting the results in one workflow.
Run many assessments using code
- Set up one assessment in the HEAT web tool. Choose the modes, pathways, cases and units you need; complete the assessment and export the input RDS file. See How HEAT works.
- Prepare your variations. Use a table with one row per run and field names matching the export. The tutorial includes a small example.
- Run a small test. Compare the returned results with the web tool before expanding the batch.
- Collect and interpret the results. Keep the inputs, model version and assumptions with the results.
Access and preparation
You need experience with R or a similar programming language. Request an API access cookie from heatwalkingcycling@who.int. Supply your own cookie privately; do not share it in scripts, repositories or results.
The exported template determines the assessment structure. Changing location requires country-specific population, mortality, pollution, crash and valuation inputs as well as location IDs. The codebooks explain the fields; the tutorial does not automatically refresh every background input.
Help, codebooks and downloads
- Technical reference: requests, input objects, returned results and a minimal R example.
- Input-variable codebook: find the field names and questions used by the web interface.
- Background-parameter codebook: definitions, units and default-value references.
- Download the tutorial R-script and example files (ZIP). The archive contains
HEAT_API_tutorial.R, a sample scenario table and instructions. It contains no access cookie. View the R-script as text. - Download the HEAT API poster (PDF): a visual introduction to the workflow.
Multi-country case studies
See how repeated assessments were used to explore higher activity across the WHO European Region:
- What could Europe gain from more cycling?
- What could Europe gain from more walking?
- What could Europe gain from doubling cycling?
Original HEAT API technical instructions and documentation. Consult if this website guidance should not resolve all your questions, or contact us (see below).