TrailSplits API for outdoor maps and routes

A useful first result

Get modelled elevation for two public points in the Dolomites. Coordinates here are latitude, longitude; heights are metres. No account, key or third-party geocoder is needed.

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/tiles/v1/elevation/current/sample?points=46.5369,12.1352%7C46.5193,12.0106&z=12&encoding=mapbox"

Verified on 1 October 2026: two finite samples, approximately 1182.8 m and 2101.2 m at z12. This is a dated check of a terrain model, not surveyed ground truth. Values may change with a new release.

Run the existing live elevation example, inspect map assets or request a short route. Requests below have time and transfer bounds.

Display an outdoor map

Use the served MapLibre style with the PMTiles basemap, then add terrain or trail overlays. The global OSM-derived map is useful across borders; mapped features and detail vary by place. See it in the Planner.

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/styles/current/trailsplits_openmaptiles_style.json" -o style.json

The style needs a MapLibre client and the PMTiles protocol. Read the artifact manifest to pin the basemap, style and glyphs for a session. A versioned style can still refer to mutable current dependencies; the site's existing release helpers resolve and rewrite those addresses.

Run the map and terrain example to inspect the pinned assets and download its client.

import maplibregl from 'maplibre-gl';
import { Protocol } from 'pmtiles';
maplibregl.addProtocol('pmtiles', new Protocol().tile);
new maplibregl.Map({
  container: 'map',
  style: 'https://api.trailsplits.com/styles/current/topo.json',
  center: [7.75, 46.02], zoom: 13,
  // Compact on phones: the credit stays one tap away instead of covering the map.
  attributionControl: { compact: true },
});

const tj = await (await fetch('https://api.trailsplits.com/tiles/v1/imagery/tilejson')).json();
map.addSource('imagery', { type: 'raster', tiles: tj.tiles, tileSize: 256, minzoom: tj.minzoom, maxzoom: tj.maxzoom, attribution: tj.attribution });
map.addLayer({ id: 'imagery', type: 'raster', source: 'imagery' }, firstLabelLayerId);

pmtiles://https://api.trailsplits.com/pmtiles/current/tiles/openmaptiles_planet.pmtiles

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS --range 0-1023 -D - -o /dev/null "https://api.trailsplits.com/pmtiles/current/tiles/openmaptiles_planet.pmtiles"

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS -X POST "https://api.trailsplits.com/static-map/render" \
  -H 'Content-Type: application/json' \
  --data-raw '{"width":256,"height":256,"bbox":[12.13,46.53,12.14,46.54]}' -o map.png

Calculate an outdoor route

Walking, running and cycling use the TrailSplits outdoor router over OpenStreetMap. Choose explicit points and a difficulty cap; inspect defaults and warnings in the result. Car routing (auto) is unavailable and returns 400.

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS -X POST "https://api.trailsplits.com/route/v1" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "locations": [
    {
      "lat": 46.5369,
      "lon": 12.1352
    },
    {
      "lat": 46.536,
      "lon": 12.133
    }
  ],
  "costing": "pedestrian",
  "costing_options": {
    "pedestrian": {
      "max_hiking_difficulty": 3
    }
  }
}'

Run the outdoor routing example to inspect explicit settings, geometry and a documented refusal.

This short public Dolomites input returned a 395 m route in the 1 October check. Routes include an engine/tile stamp and defaulted settings; that provenance is not a request parameter to pin future calculations.

Analyse a route, get a loop, or the weather on the way

Three calls built on the same router as the Planner. All three answer with facts placed on the mapped network and say what is not known; none invents a line it did not find.

Analyse a route you already have

POST https://api.trailsplits.com/v1/route-analysis with a GPX document (gpx) or a GeoJSON line (geometry) and a profile (hike, run or bike). The answer says where the line runs on the mapped network (match, with unmatched stretches listed), on what surface, which OpenStreetMap difficulty grades are tagged, how much it climbs and by which method, how long a hike takes with the model's scope (time.outside_calibration), and every unknown in unknowns.

curl --fail-with-body 'https://api.trailsplits.com/v1/route-analysis' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[12.1352,46.5369],[12.133,46.536]]},"profile":"hike"}'

• Limits: body 1 MB, 5,000 points, 300 km along the line. Larger files are refused (413 or 422), never cut.
• The line you send is the authority: it is never simplified, reordered or joined across a gap. Positions are metres along your line.
• Untagged paths are unknown, not easy. A surface the map does not state is reported as a class default (source: class_default).
• Only hike has a time estimate (trailsplits-hike/2, moving time). Run and bike answer time: null.
• No geometry is kept after the answer, and logs carry no coordinates.

Round trips from a start point

POST https://api.trailsplits.com/v1/roundtrips with start ([lon, lat]), distance_km, profile and up to three alternatives. Each loop reports its length against the target (target_error_pct), how much is walked twice (repeated_share), climb, the hike time and its surfaces, with the loop as polyline6 in shape.

curl --fail-with-body 'https://api.trailsplits.com/v1/roundtrips' \
  -H 'Content-Type: application/json' \
  --data '{"start":[7.7491,46.0207],"distance_km":12,"profile":"hike"}'

• status: complete means within 10 % of the target with at most 20 % walked twice; rough is answered with a reason. When no good loop exists the answer is 422 no_loop, not a forced loop.
• Limits: 0.5–40 km on foot, 0.5–60 km by bike (422 too_long). Hike and run keep to marked trails where they go and never use a tagged grade above max_sac (default T3).

Route through waypoints

POST https://api.trailsplits.com/v1/route with 2 to 100 waypoints as [lon, lat] and a profile: a walking, running or cycling route on signed trails by default, as a GeoJSON line with its legs, climb, hike time, surfaces, SAC grades, hazards and turn-by-turn steps. It is the same router as the Valhalla-compatible POST /route/v1, in the /v1 style. Reference and Try it.

Exits along a route

POST https://api.trailsplits.com/v1/route-exits with one day's line: every kilometre, the nearest mapped public road, stop, village and hut with walking minutes, and the longest stretch with no way out within an hour. A mapped way out, never a safe one. Reference and Try it · Recipe.

Day outings near a point

POST https://api.trailsplits.com/v1/outings with a lat, lon and your rules (hours, SAC grade, a stop at the start, water): an ordered list of curated outings (Switzerland and its borders so far) and round trips from your point, each with its facts and why it is listed; with a date, its go window. A rule leaves out what it cannot judge, never passes it as easy. Reference and Try it · Recipe.

Your own walking pace

POST https://api.trailsplits.com/v1/time-model/fit with 1 to 30 of a person's own timed walks: their pace against the TrailSplits hike time model on the flat, uphill and downhill, with its uncertainty, as pace_profile. Send it to route analysis, the route brief, route weather or go windows for their own time beside the model's. Nothing is kept. Reference · Recipe.

Route card to print

POST https://api.trailsplits.com/v1/route-card with a line, a name and your waypoints: one self-contained HTML page or a PDF on A4 or Letter, with the map, profile, legs, water and huts, the weather when you give a departure, and a QR code to your trailsplits.com link. Nothing is stored or published. Reference.

Downloads

GET https://api.trailsplits.com/v1/downloads/catalog lists prebuilt regional packages (offline map extracts in PMTiles, outdoor places packs); POST https://api.trailsplits.com/v1/downloads returns signed links valid 24 hours, charged once. Packages appear as they are built. Reference · Console.

Go windows: which day and start time

POST https://api.trailsplits.com/v1/route-windows with one day's line, days and your prefer order (no_thunder, dry, daylight, calm, warm, cool): every day × start time with its forecast facts at the hour you reach each point, ordered by your preferences, each saying why. An ordering of facts, never a safety score. Reference and Try it · Recipe.

Bulk jobs: many lines in one call

POST https://api.trailsplits.com/v1/jobs with up to 100 { op, body } items (route analysis, elevation profile, GPX clean or simplify, places along a route, pace plan; each body exactly as its own endpoint takes it), then poll GET /v1/jobs/{id} and read each answer at /items/{n}. The same answers, later: the worker gives way to interactive traffic, so a job may wait. Each item is charged as its own call when it runs; results are kept 72 hours. Secret keys only. Reference.

Watches: tell me when it changes

POST https://api.trailsplits.com/v1/watches with a line, a few dates and your webhook_url: TrailSplits checks it every few hours and calls your webhook, signed with your project's secret, when the best window or a thunderstorm signal changes. The route is kept only while the watch exists. Manage watches, the signing secret and the delivery log in the console. Reference.

Slope at the path (experimental)

POST https://api.trailsplits.com/v1/route-slopes with one line: the stretches where the terrain model at the path is 30° or steeper, in three classes, with the way each faces and links to the official avalanche bulletins for the areas the line touches. It is the slope at the path on a model of about 26 m: not the path's gradient, not the slopes above or beside it, not avalanche terrain and not a risk. Reference and Try it.

Route brief

POST https://api.trailsplits.com/v1/route-brief with one day's line and include: route analysis, weather at arrival time (with a departure), sun and shade, places along the route and snow evidence in one call, each the same answer as its own endpoint, plus notices: fact codes placed along the line, such as a ford, a stretch tagged T4 or a long stretch without mapped water. Notices are facts, never advice or a safety score. Reference and Try it.

Places along a route

POST https://api.trailsplits.com/v1/route-places with one line: mapped drinking water, springs, huts, shelters and transport stops within within_m of it, in order along it, with their OSM tags as tagged, and the longest stretch without confirmed drinking water. It says where water is mapped, never that it runs. Reference and Try it.

Pace plan for a course

POST https://api.trailsplits.com/v1/pace-plan with one line and a target_time (or flat_pace_s_per_km): splits every kilometre or mile, slower where the course climbs or descends steeply, each named by its terrain. The engine of the Pace & Split Calculator. Reference and Try it.

Elevation profile of a line

POST https://api.trailsplits.com/v1/elevation-profile with a GPX or GeoJSON line: the series a chart draws (distance, height, grade and position at each point) and the climb read from it. Reference and Try it.

Clean and simplify GPX files

POST https://api.trailsplits.com/v1/gpx/clean removes repeated and broken points, and on request times and sensor data; the file comes back as the file, everything else byte for byte. POST https://api.trailsplits.com/v1/gpx/simplify keeps the shape within a tolerance in metres (or a point budget), protects the climb and keeps stops; it answers like the GPX Simplifier. Files up to 5 MB. Clean · Simplify.

Weather along the route, at the hour you get there

POST https://api.trailsplits.com/v1/route-weather with one line (gpx or geometry), a departure with its time-zone offset and a profile. Samples every 2 km, plus the start, the end and the marked highs and lows, each get the forecast for the hour you reach them, at their own terrain height. Each hour names its model; sections give ranges between the marked points.

curl --fail-with-body 'https://api.trailsplits.com/v1/route-weather' \
  -H 'Content-Type: application/json' \
  --data '{"geometry":{"type":"LineString","coordinates":[[12.1352,46.5369],[12.133,46.536]]},"departure":"2026-10-03T08:00:00+02:00","profile":"hike"}'
# Set departure inside the next 16 days.

• Hike times come from the calibrated trailsplits-hike/2 model (add pace_factor and stops); run and bike need your own min_per_km or kmh.
• An hour the forecast does not hold is weather: null with missing; a missing value is null, never 0. There is no combined safety score.
• Limits: one part, 5,000 points, 120 km, 1 MB; a departure from six hours ago to 16 days ahead. Show forecast.provider.attribution with the values.

Hazards on the line. Route analysis and every round trip list hazards[]: each ford, aided passage (ladders, fixed ropes) and via ferrata from OpenStreetMap, placed in metres along the line.

Errors from all three are {"error": {"code", "message"}}. Full references: route analysis, round trips and route weather, each with Try it on a map. The downloadable examples include analysis.mjs, roundtrip.mjs and routeweather.mjs.

Inspect terrain and elevation

Run the elevation profile example to inspect modelled heights and missing-data gaps.

Terrain, hillshade and contours use the Copernicus GLO-30 surface model. The served TerrainRGB layer reaches z12, with processing improvements in selected patches. Source resolution, delivered pixel size and measured accuracy are different things: overzoom does not recover detail absent from the source.

Elevation sampling

GET /tiles/v1/elevation/<release>/sample for supplied points in lat,lon|lat,lon order. Results are modelled metres; elevation_m:null means missing data. The sampler reads a terrain pixel at each point. It does not choose spacing along a line, smooth a profile or guarantee surveyed ascent.

Submit the form to make a live request.

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/tiles/v1/terrainrgb/current/9/271/186.png" -o terrain.png

{
  "version": 8,
  "sources": {
    "dem": {
      "type": "raster-dem",
      "tiles": [
        "https://api.trailsplits.com/tiles/v1/terrainrgb/current/{z}/{x}/{y}.png"
      ],
      "tileSize": 256,
      "encoding": "mapbox",
      "maxzoom": 12,
      "attribution": "Terrain and contours in Switzerland © swisstopo (swissALTI3D). Terrain and contours produced using Copernicus WorldDEM-30 © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved"
    }
  },
  "terrain": {
    "source": "dem",
    "exaggeration": 1.2
  },
  "layers": [
    {
      "id": "hillshade",
      "type": "hillshade",
      "source": "dem"
    }
  ]
}

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/tiles/v1/contours/current/12/2186/1448.pbf" -o contours.pbf

Discover trails and places

Search OSM-derived named places, retrieve outdoor POIs, or inspect hiking/cycling relations. These are source records with uneven completeness. A raw relation can contain disconnected or unordered members; it is not automatically a usable itinerary.

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/search/v1/forward?q=Zermatt&limit=2"

Search results give center: [lon,lat]. Empty results do not establish that a place, water source or trail is absent on the ground.

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/search/v1/reverse?lat=46.0207&lon=7.7491&limit=2"

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/tiles/v1/hiking-network/current/12/2186/1448.pbf" -o network.pbf

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/tiles/v1/outdoor-pois/current/14/8744/5793.pbf" -o pois.pbf

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/pois/v1/bbox?min_lat=46.5&max_lat=46.55&min_lon=12.0&max_lon=12.05&kind=water,hut&limit=3"

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/trails/v1/search?q=Tour+du+Mont+Blanc&limit=1"

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/trails/v1/relation/9678362" -o relation.json

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/trails/v1/bbox?min_lat=46.0&min_lng=7.74&max_lat=46.03&max_lng=7.77&type=hiking&limit=2"

Access available datasets and source evidence

Use the manifest to discover served artifacts, and each product's metadata to understand its bounds and sources. Production liveness, build time, source date and freshness verdict are separate facts. A recent promotion does not make an old observation new.

Artifact manifest

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/pmtiles/current/manifest.json"

GET /pmtiles/current/manifest.json returns per-artifact versions, versioned/current addresses, sources and attribution. Use each artifact's version; the top-level release is not a shared release for every dataset.

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/healthz"

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/tiles/v1/catalog"

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://api.trailsplits.com/tiles/v1/snow/route-forecast?points=46.5369,12.1352%7C46.5360,12.1330&evidence=1&revision=dx-public-example"

Weather forecasts

GET https://trailsplits.com/api/weather/forecast with p=lat,lon[,elevation];… (1 to 12 points), d=1–16 days (default 7), optional fl=1 for the hourly freezing level and optional h=1 for hourly values per point (temperature, precipitation, rain probability, wind, gusts, wind direction, weather code, each hour with its model; about 130 bytes per hour and point, so ask only for the days you need). The answer is weather-forecast/1: daily weather code, maximum and minimum temperature, precipitation, fresh snow (snowfall_cm) and rain (rain_mm), rain probability, wind and gusts, per point and local date. The snow/rain split follows the model's own terrain height: on global-model days in high mountains, read it with the freezing level (fl=1).

curl --fail-with-body --max-time 12 --max-filesize 1048576 -sS "https://trailsplits.com/api/weather/forecast?p=45.9763,7.6586,4478;46.0207,7.7491,1608&d=7"

• Each day comes from the best model that covers it whole: MeteoSwiss ICON-CH2 in the Alps (about 2 km, 5 days), DWD ICON-D2 in Central Europe (2 km, 2 days), then ECMWF IFS 0.25° (15 days); days[].model names it, and probability_model says when the rain probability comes from another model. models=ecmwf asks for ECMWF alone.
• issued_at is the oldest model run used (each run is listed in provider.runs); fetched_at is when it was asked and fresh_until how long to show it as current. Do not present the fetch time as the forecast's age.
• Pass the height of each point. Without one, TrailSplits' terrain model supplies it (elevation_source: terrain); only if that fails is the forecast for a model cell's mean height (provider_grid), which in the mountains can be a thousand metres off.
• A missing value is null, never 0; a point with fewer days or fields than asked is state: partial with reasons. The last forecast day is often partial.
• When the forecast copy is down, the last good answer is served for up to 12 hours (its fresh_until has passed), then 503 forecast_unavailable. Answers may be cached for ten minutes.
• Attribution: “Weather data by Open-Meteo.com (CC BY 4.0)”, returned in provider.attribution. Full weather reference.

Base URL, releases and caching

The documented asset/calculation paths above use https://api.trailsplits.com. The linked capabilities document uses the main site. current is mutable; versioned asset content is immutable while retained. Retired tile releases can return 410 with successor information; indefinite hosting is not promised.

Pin related map assets together. Dynamic routes and current search do not share the tile-release pinning contract. Follow each response's Cache-Control: versioned basemap/style assets advertise immutable caching, while current aliases and computations differ. Some current tile responses include no-store. Cache expiry is not a source date.

Authentication, CORS and limits

The API-host examples were verified anonymously with permissive CORS on 1 October 2026. No key or sign-up is needed for these examples. The site's capabilities URL is a separate origin and lacks external browser CORS; read it from the same origin or your server.

Projects and keys. Signed in with your TrailSplits account, the API console creates a project, issues a server key (shown once) and shows what your calls use. Send it as Authorization: Bearer <key>. Without a key you get 500 credits a day per address; a key gives your project its plan's monthly credits and burst rate. Map tiles and styles need no key.

Limits. Calculated answers (routes, elevation samples, search, route analysis, round trips) are rate-limited. Without a key, each address may make 5 requests per second, in bursts of up to 60, and use 500 credits a UTC day. With a key, calls count against your project: its burst rate and monthly credits are shown in the console, where you also see usage per operation. Keyed answers carry X-TrailSplits-Credits-Remaining, and GET https://api.trailsplits.com/v1/usage with your key returns the same figures as the console. Map tiles, styles and the manifest are not counted. Cache where response headers allow it, keep inputs small and avoid repeated requests while typing. No SLA or paid service commitment is offered here.

Gateway errors are JSON: {"error", "status", "message", "limit", "retry_after"}, where message is safe to show and limit and retry_after appear when they apply.

Attribution is part of integration: TrailSplits and © OpenStreetMap contributors for OSM-derived products, OpenMapTiles where applicable, the full DEM notice for terrain/contours, and source-specific notices for imagery/weather. Read the manifest and returned forecast metadata.

Plans and terms

The Free plan includes commercial use with attribution: 30,000 API credits a month, with the credit cost of each call published. Larger plans are planned and not yet available. Use follows the API terms: show the source credits, keep keys on your server, and do not resell the data as a dataset or tile service.

Need more than the Free plan, redistribution or a data delivery? Write to support@trailsplits.com with your use case, the capabilities and area you need, and your expected volume.

Questions before integrating

Is the TrailSplits API free to use?

Yes. The Free plan includes commercial use with attribution: 30,000 API credits a month at 5 requests per second, and map tiles are not counted at present. When the credits are used up, calls stop until the next month; nothing is charged. Larger plans are planned. See the plans page and the API terms.

Do I need an API key or authentication?

No, to try it: without a key you get 500 credits a day per address at 5 requests per second. A free key from the API console, sent as Authorization: Bearer, gives you 30,000 credits a month, a usage view and higher limits. Map tiles and styles need no key. The api.trailsplits.com examples allow cross-origin browser calls; the separate trailsplits.com routing-capabilities URL does not.

Where does the API work?

The basemap, terrain and OSM-derived search, trails and places are globally scoped, with uneven source coverage. Terrain uses the Copernicus GLO-30 surface model and selected processing patches. Snow observations have regional coverage; available weather forecasts do not establish observed snow coverage.

How are datasets versioned?

The manifest names each served artifact and its version. current is a mutable alias; versioned assets keep the same content while retained, but may later be retired. Pin map dependencies as well as the style document. Search and dynamic routes do not have the same release-pinning contract.

Are responses cached?

Read Cache-Control on the specific response. Versioned basemap and style assets advertise immutable caching; current aliases and computed responses differ. Some current tile responses include no-store. A cache lifetime is not a source observation date or retention promise.