How it works
What a route is really like, before you run it
A line on a map says how far. It doesn't say whether the trees along it will be shading the road at six in the evening, whether there is a sidewalk or only a verge, how much of it climbs, or whether the wind will be in your face on the way home. RunMapApp works those out for every stretch you draw. These pages explain how, in plain English and in detail: which data, which maths, and exactly where each one runs out.
Nothing here is a simplified version of what the app does. The numbers are the ones the app uses, most of them read straight from its code as this page is drawn, and the interactive diagrams run the same functions that colour your route line. If the app changes, these pages change with it.
Four questions a route has to answer
Where the trees are, how tall they are, where buildings stand, and where the sun will be at the hour you run. Chapters 2–4.
Sidewalks, confirmed missing sidewalks, paths, greenways and crossings, from OpenStreetMap and from cities' own surveys. Chapter 5.
The height of the bare ground, from laser surveys where they exist, so rooftops and treetops are not counted as hills. Chapter 6.
The forecast for when you run, where it will be in your face, where trees and buildings shelter you from it, and the pace your effort turns into. Chapter 7.
And for when there is no route yet, a fifth: can it suggest one? The loop generator builds loops of your target length in six directions, measures each one against all of the above, and shows you the best three that are really different from each other, with the numbers that decided them, ranked for what you said matters most. Try again for more. It never picks for you.
What happens when you draw a line
Every click sets off the same short chain of events. Most of the work is looking things up once; the maths that depends on the time you choose runs in your browser, which is why dragging the time slider recolours the route instantly without asking anything new of anyone.
- You click.
Each point is joined to the one before by a walking route from Mapbox, so the line follows roads, sidewalks, footpaths and greenways instead of cutting across a block. More in chapter 1.
- The line is sampled.
Evenly spaced points are picked along it: up to 360 for shade, 100 for the elevation profile, and one every 25 metres for wind. Every stretch between two of your points gets its fair share, so a long, straight leg is measured as carefully as a short, twisty one.
- Our server looks things up.
For each shade point: how much of the ground beside it is under trees, how tall those trees are, and which buildings nearby could cast a shadow on it. For the profile, the height of the ground. For wind, the forecast for the few areas the route crosses, and the trees and buildings upwind of every point. Almost all of it is cached, so a street somebody has run before answers straight away.
- Your browser does the maths.
Where the sun is at the time you picked; which trees and buildings stand between each point and the sun; how much wind gets past what stands upwind, how it meets each stretch, and what that does to your pace. Change the time and only this step runs again.
- You decide.
The line is coloured, the profile and strips fill in, and each stretch can tell you what it measured. The route itself never moves: the app informs you, and never re-routes you somewhere you did not draw.
Three habits that run through all of it
Every source was checked against the real world before it was trusted, and the checks are written up in each chapter: a canopy reading that said 0% on a tree-lined street, an elevation service that put 53 m of climb on a flat street that really climbs 15, building heights compared with 80 independently measured buildings in Sheffield.
A tree of unknown height is assumed to be 12 m, towards the short end for a mature street tree. A building of unknown height is assumed to be one storey. A sidewalk is only drawn as missing where a survey says it is missing. Each of those errs towards promising less shade, and less certainty, than may really be there.
Data has edges: cities that have surveyed their sidewalks and cities that haven't, places with building data and places without, forecasts that turn six-hourly after a couple of days. The map names the source for whatever you are looking at, and chapter 9 lists every edge in one place.
The chapters
- 1 Drawing a route From a click to a line that follows real paths, and how that line is measured.
- 2 Tree cover Where the trees are, from city surveys, a US national survey and a global satellite map.
- 3 The sun and the shadows How tall the trees are, where the sun is, and where their shadows actually fall.
- 4 Buildings Footprints, heights measured by laser, and the shade a building throws.
- 5 Crossings, sidewalks and paths Somewhere to run that is not the road, and somewhere safe to cross it.
- 6 Hills Why the profile reads the bare ground, not rooftops and treetops.
- 7 Wind The forecast, the physics of a headwind, and which way round to run.
- 8 The loop generator How candidate loops are built, measured and ranked, and why it never chooses for you.
- 9 What it doesn't know The honest edges of every estimate on these pages.
- 10 Every source Each dataset, service and piece of research, with its licence and a link.
What leaves your device, and who sees it
Looking things up means asking other people's servers. Here is exactly who is asked what. Everything except Mapbox is asked by our server, not by your browser, so none of those services learns your address or your device.
| Who | What they receive | Why |
|---|---|---|
| Mapbox from your browser | The points you click, whatever you type into search, and which map tiles you look at | The walking route between points, place search, and the base map |
| RunMapApp | The route's sample points, and the area of map on screen | To look up everything below on your behalf |
| Tree cover services NLCD, ESA WorldCover, city surveys | A rectangle of map around the route, or a map tile | Tree cover beside each point |
| Canopy height Meta and WRI, on Amazon Web Services | Requests for small blocks of a large image file | How tall the trees are |
| OpenStreetMap and city GIS services | Square map areas about 2 km across | Crossings, sidewalks and paths |
| Environment Agency (England) · Copernicus (elsewhere) | Squares of about 1 km, or whole 1-degree tiles | Ground height for the profile |
| USGS (US) | The profile's 100 sample points | Ground height for the profile; the one place a route's points leave our server |
| MET Norway | The centre of each ~5 km forecast area, rounded, never the route | The wind forecast |
| NOAA (US) · DWD (Europe) | Nothing about you: our own job downloads their public model files, a few times a day, whoever is using the app | Sharper wind and gusts in the forecast areas |
The privacy page covers what is stored and for how long.