Use cases

Building a hiking trail difficulty rating from elevation data

Distance alone is a poor way to rate how hard a hike actually is. A flat six-mile trail along a riverbank and a six-mile trail that climbs a mountain both showed up under the same "moderate, six miles" label in a trail guide app's directory, a categorization that had generated a steady stream of complaints from hikers who trusted the moderate rating and found themselves on a much harder climb than they had prepared for.

The app already stored each trail as a sequence of coordinates tracing its path, gathered from GPS recordings submitted by contributors. What it was missing was elevation along that path, the piece of data that actually distinguishes a flat walk from a serious climb at the same distance. /v1/elevation took the full list of coordinates for a trail, since a bulk request accepts a list of points and returns elevation for each one, and the app got back an elevation value for every point along the recorded path, still in the same order they were submitted.

From that list, computing total elevation gain, the sum of every upward change along the route, was straightforward arithmetic the app's own backend handled. Total gain, combined with distance, produced a genuinely more useful difficulty signal than distance alone: a trail with high gain over a short distance rated as steep and difficult regardless of how short it looked on paper, while a long, flat trail rated easier despite its length, matching what hikers actually experience on the ground far more closely than the old distance-only system had.

The app rebuilt its difficulty rating around this combined figure and retroactively recalculated every trail already in its directory, a one-time batch job across the full trail library. That batch was the single largest request the app ever sent, and because a bulk elevation request counts each point as one billed item rather than each trail, the exact size of the job scaled with how many coordinate points existed across the whole library rather than with the number of trails, something the team accounted for when estimating cost ahead of time rather than being surprised by it afterward.

Beyond the headline difficulty rating, the same elevation data let the app show a climbing profile chart on every trail page, similar to what a cycling app might show, letting a hiker see exactly where the steep sections fell along the route rather than only knowing an aggregate difficulty label. Hikers who wanted to prepare for a specific tough stretch, rather than just knowing a trail was hard overall, found the chart more useful than the label by itself.

Ongoing elevation lookups after the initial batch were driven by new trail submissions, a much smaller and steadier volume than the one-time recalculation project, comfortably inside the free daily allowance for the app's typical rate of new contributor submissions.

A rating system is only as good as the data underneath it, and elevation turned out to be the missing input the app's difficulty rating needed all along. Documentation for the endpoint, including limits on points per request, is at /docs/elevation-lookup/.