Metadata-Version: 2.4
Name: uk-elevation-grid
Version: 1.0.0
Summary: Terrain heights for Great Britain on a 100 m grid, from OS Terrain 50. No API key, no quota.
Author: bikers.co.uk
License: MIT
Project-URL: Homepage, https://bikers.co.uk/ride-planner
Project-URL: Source, https://github.com/copious-git/uk-elevation-grid
Project-URL: Documentation, https://uk-road-data-handbook.readthedocs.io/
Keywords: elevation,terrain,dem,great-britain,ordnance-survey,os-terrain-50,cycling,motorcycling,route-planning,open-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# uk-elevation-grid

Terrain heights for **Great Britain** on a 100 m grid, read straight from a CDN
with no API key, no quota and no rate limit.

```python
from uk_elevation_grid import elevation_at, route_profile, total_ascent

elevation_at(53.5300, -1.8500)      # Holme Moss, Peak District -> 505.5
elevation_at(54.5973, -5.9301)      # Belfast -> None, outside coverage

heights = route_profile([(50.9200, -0.1146), (50.9008, -0.1064)])
total_ascent(heights)
```

Only the Ordnance Survey 10 km squares your points fall in are fetched, about
17 KB each, and they are cached in memory. A fifty-mile route pulls around ten.

## Why this exists

Every free elevation API is either metered, rate-limited or restricted to
non-commercial use. This is neither: the underlying grid is derived from
**OS Terrain 50**, Ordnance Survey open data under the Open Government Licence,
and republished as small binary tiles.

It was built for the
[bikers.co.uk Ride Planner](https://bikers.co.uk/ride-planner), which uses it to
show riders and cyclists the climbing on a route before they set off, alongside
the [exposure-adjusted casualty rate for every numbered British road](https://bikers.co.uk/data/dangerous-roads/rates)
and [when riders actually crash, by month, day and hour](https://bikers.co.uk/data/when-riders-crash).
The method, and the mistakes made along the way, are written up in the
[British road casualty data handbook](https://uk-road-data-handbook.readthedocs.io/).

## Three things that will catch you out

**Great Britain only.** OS Terrain 50 does not cover Northern Ireland or the
Republic of Ireland. Points outside coverage return `None`, never `0`. If you
coerce that to zero, a Belfast route reads as pancake flat.

**Sea is not a no-data value.** The source fills the sea with a real-looking
constant near −2.2 m. Do not strip values near zero to "clean" it: genuine land
below sea level exists in the Fens and you would delete it.

**Total ascent is easy to get wrong.** Summing every positive step of any
elevation model inflates the figure badly, because contour-derived data is noisy
at the metre scale. `total_ascent()` smooths over a window and ignores rises
under 2 m. A closed loop is the best check available — ascent and descent must
agree, and on a 56-mile Peak District loop this returns 1,375 m against 1,373 m
of descent.

## Accuracy

Validated against EU-DEM 25 m at identical points along four British climbs,
531 samples: **mean difference −0.75 m, RMS 1.9–4.1 m**. Route high points
reproduce known figures — Snake Pass 512 m, Holme Moss 524 m — and the steepest
500 m of the A39 reads 19.1%, which is Porlock Hill, famously 1-in-4.

Heights are bilinearly interpolated from a 100 m grid, down-sampled by 2×2
averaging from the native 50 m source. Coordinates go through a Helmert
transform to OSGB36 without the OSTN15 shift, which is accurate to about 5 m —
a twentieth of one grid cell.

## Data and licence

Grid data: [copious-git/uk-elevation-grid](https://github.com/copious-git/uk-elevation-grid),
also deposited at [figshare](https://doi.org/10.6084/m9.figshare.33439279) and
[DataHub](https://datahub.io/uk-elevation-grid/uk-elevation-grid).

Code MIT. Data under the Open Government Licence v3.0:

> Contains OS data © Crown copyright and database right 2026.
