Record schema

Each trail has one record: <id>/trail.toml. The file is TOML. Field names are stable: tools read them, so fields are added, not renamed. Optional fields are marked "where present".

Example (shortened):

id = "long-trail"
name = "Long Trail (Vermont)"
short_name = "LT"
country = "US"
regions = ["VT"]
length_km = 438
length_note = "272 mi published"
tier = "regional"
designation = "Green Mountain Club; oldest long-distance trail in the US"
wave = 1

[source]
status = "osm-only"
publisher = "Green Mountain Club (publishes the trail)"
url = "https://www.openstreetmap.org/relation/391736"
licence = "ODbL-1.0"
attribution = "OpenStreetMap contributors (ODbL)"
osm_only = true
line_file = "line.geojson"

Top level

[source]: where the track comes from

The field and file names keep the word "line" (line.geojson, line_file, line_policy, line_source); they refer to the trail's track.

[osm]: the OpenStreetMap relation

[shield]: the logo

[verification]: what was checked

[hike]: what a hiker asks first

Optional: a record without [hike] is valid. The table holds the facts a hiker wants before anything else: where the trail goes, what the country is like, how long it takes, when to go, where its own site is. Every fact is read on a page of the trail's holder (the agency, the association, or for a route its author) or on a government page, and named in [[hike.source]]. A fact that was not found on such a page is left out, never guessed. Where sources disagree, the managing body's figure is used. Wording is ours: nothing is copied from a source.

[[hike.source]]: where the [hike] facts were read

An array of tables, and at least one when [hike] is present. Every fact field in [hike] (every field except checked) must be named in the facts of at least one source. summary and terrain are our own wording and judgement, but each still names the page or pages it was drawn from.

[route]: the author and the track policy

Present only when kind = "route". A route is a high route, a traverse or a loop of linked trails that a hiker or a small group worked out and published.

[[guide]]: where the route is got from

An array of tables, one per guide, and at least one for every route. A guide is the book, map set or page that gives the route.

Files beside the record

elevation.json: elevation facts and profile

Computed by python3 tools/elevation.py from the trail's track (line.geojson) and the Terrain Tiles open elevation data. It is not read from any trail page. The file is one line of compact JSON. The same track gives the same file.

Method

1. Pieces of the track whose ends are within 100 m are joined into parts. Parts are never joined to each other. No climb is counted across a gap.
2. Each part is walked from its start and a point is taken every 30 m along it, and at its end.
3. The elevation at each point is read from the elevation tiles by interpolating between the four nearest grid cells. The tiles used are Terrain Tiles "terrarium" tiles at zoom 12, about 29 m per cell at 40 degrees north. Cells that are far out of line with their neighbours are tile-making errors and are replaced, and values below sea level are set to 0.
4. highest and lowest are the largest and smallest of these values.
5. For ascent_m and descent_m the profile is first smoothed with a moving average over 90 m (three points). Then a climb or a descent counts only after the profile has moved more than 5 m against the last high or low point. Without that, noise in the model adds a great deal of climbing that is not there.
6. The smoothing and the 5 m threshold were chosen once, to match published figures for ten well-known trails, and then left fixed for every trail. They are in tools/elevation.py.

Limits

• These are computed values, not measurements. Where a published figure exists, it may differ. For ten well-known trails the computed climbing is within about 15% of the published figure, and the published figures themselves differ by about as much from one source to another.
• The elevation model is a grid. A narrow summit can be missed by up to 15 m of position and so read a little low. Highest and lowest are the model's values at the samples, not surveyed benchmarks. Values below sea level are set to 0, because beside a coast the model carries the depth of the sea and none of these trails goes below sea level.
• The model's own accuracy varies. In the United States it is built from 10 m surveys; in Canada it is coarser (20 m to 400 m, depending on the place), so a Canadian trail's ascent is likely to be low.
• Ascent and descent depend on the method's settings. They are comparable between trails in this dataset, which all use the same settings. They are not the figure a GPS watch or another site would show.
• The profile follows the track as it is stored. Where the track is partial, joined in the wrong order, or includes side trails or alternates, the facts follow it. Check coverage and parts first.
• The direction is a convention, chosen to make the output repeatable. It is not the trail's usual direction.