# TrailSplits API

> HTTP API for outdoor apps: walking, running and cycling routes on signed trails, round trips from a start point, route analysis for any GPX or GeoJSON line, weather along a route at the hour you reach each part, elevation, GPX clean and simplify, place and trail search, outdoor places (huts, springs, shelters), static maps, map matching, snow, and MapLibre map styles with PMTiles and terrain. Keys are optional; registry 1.7.0.

- Hosts: `https://api.trailsplits.com` for everything except weather (`https://trailsplits.com/api/weather/forecast`). Both answer browsers (CORS). One server in one region (Helsinki, Finland); no SLA.
- Keys: optional. Without a key: 500 credits a day per address, 5 requests/s. With a free key from https://trailsplits.com/api/console: `Authorization: Bearer <key>`, 30,000 credits a month, commercial use with attribution. Secret keys stay on servers; a web page uses a browser key (`ts_pub_…`) limited to its origins.
- Coordinates: WGS84. Request bodies and JSON results use [lon, lat] (GeoJSON order). Older query strings use lat,lon (elevation `points`, weather `p`, snow `points`, reverse `lat`/`lon`). Lines in route answers are polyline6 (lat,lon pairs at 1e-6) unless the field is GeoJSON.
- Units: metres, seconds (or named `minutes`), °C, mm, km/h, %. Unknown values are null, never 0.
- Errors are JSON with a stable code: gateway `{error, status, message, retry_after?}`; /v1 calls `{error: {code, message}}`; legacy /route/v1 `{error, status_code, trailsplits: {code, message}}`. 429 carries Retry-After. A refused call costs no credits.
- Attribution: show "© TrailSplits" and the data credits (© OpenStreetMap contributors; the named terrain, imagery or weather source) wherever results are shown. ODbL applies to map data: https://trailsplits.com/api/attribution

## Start
- [Quickstart](https://trailsplits.com/api/quickstart): an 8 km hiking loop on a map in five minutes, one HTML file, no key.
- [Full reference for agents](https://trailsplits.com/api/llms-full.txt): every operation with fields, a working request and errors, in one file.
- [MCP server](https://trailsplits.com/api/agents): `https://trailsplits.com/api/mcp` (Streamable HTTP), one tool per operation, with your key.
- [OpenAPI 3](https://trailsplits.com/api/reference/openapi.json) · [TypeScript client](https://trailsplits.com/api/reference/trailsplits-client.ts) · [Postman collection](https://trailsplits.com/api/reference/trailsplits-api.postman.json)
- [Conventions](https://trailsplits.com/api/conventions) · [Changelog](https://trailsplits.com/api/changelog) ([Atom](https://trailsplits.com/api/changelog.xml)) · [Status](https://trailsplits.com/api/status) · [Plans and limits](https://trailsplits.com/api/pricing) · [Terms](https://trailsplits.com/api/terms)

## Operations
- [Tile gateway health](https://trailsplits.com/api/reference/health): `GET https://api.trailsplits.com/healthz`
- [Published artifact identities](https://trailsplits.com/api/reference/manifest): `GET https://api.trailsplits.com/pmtiles/current/manifest.json`
- [Artifact status verdict](https://trailsplits.com/api/reference/status): `GET https://api.trailsplits.com/tiles/v1/status`
- [Terrain pixel sampling](https://trailsplits.com/api/reference/elevation): `GET https://api.trailsplits.com/tiles/v1/elevation/{release}/sample`
- [Point and batch weather forecast](https://trailsplits.com/api/reference/weather): `GET https://trailsplits.com/api/weather/forecast`
- [Analyse a route you already have](https://trailsplits.com/api/reference/route-analysis): `POST https://api.trailsplits.com/v1/route-analysis`
- [Round trips from a start point](https://trailsplits.com/api/reference/roundtrips): `POST https://api.trailsplits.com/v1/roundtrips`
- [Weather along a route at arrival time](https://trailsplits.com/api/reference/route-weather): `POST https://api.trailsplits.com/v1/route-weather`
- [Elevation profile of a line](https://trailsplits.com/api/reference/elevation-profile): `POST https://api.trailsplits.com/v1/elevation-profile`
- [Route through waypoints](https://trailsplits.com/api/reference/waypoint-route): `POST https://api.trailsplits.com/v1/route`
- [Pace plan for a course](https://trailsplits.com/api/reference/pace-plan): `POST https://api.trailsplits.com/v1/pace-plan`
- [Clean a GPX file](https://trailsplits.com/api/reference/gpx-clean): `POST https://api.trailsplits.com/v1/gpx/clean`
- [Simplify a GPX file or line](https://trailsplits.com/api/reference/gpx-simplify): `POST https://api.trailsplits.com/v1/gpx/simplify`
- [Place search](https://trailsplits.com/api/reference/search): `GET https://api.trailsplits.com/search/v1/forward`
- [Places near a point](https://trailsplits.com/api/reference/reverse): `GET https://api.trailsplits.com/search/v1/reverse`
- [Trail search](https://trailsplits.com/api/reference/trails): `GET https://api.trailsplits.com/trails/v1/search`
- [Outdoor places in an area](https://trailsplits.com/api/reference/pois): `GET https://api.trailsplits.com/pois/v1/bbox`
- [Static map image](https://trailsplits.com/api/reference/static-map): `POST https://api.trailsplits.com/static-map/render`
- [Map matching and trace attributes](https://trailsplits.com/api/reference/trace-attributes): `POST https://api.trailsplits.com/valhalla/trace_attributes`
- [Snow along a route](https://trailsplits.com/api/reference/snow): `GET https://api.trailsplits.com/tiles/v1/snow/route-forecast`
- [Outdoor point-to-point route](https://trailsplits.com/api/reference/route): `POST https://api.trailsplits.com/route/v1`

## Recipes
- [An elevation profile for a GPX file](https://trailsplits.com/api/recipes#elevation-profile): Reads a GPX file, asks for its elevation profile, prints climb and descent, and writes distance, height and grade as CSV for any chart library.
- [Clean and simplify a GPX file](https://trailsplits.com/api/recipes#clean-simplify): Removes repeated and broken points, then keeps the shape within 10 m with fewer points. Names, waypoints and the climb stay. Writes the new file next to the old one.
- [A loop generator in 30 lines](https://trailsplits.com/api/recipes#loop-generator): Takes a start, a distance and a profile, asks for the best loop and three alternatives on signed trails, prints them as a table, and saves them as GeoJSON for any map.
- [Race splits for a course](https://trailsplits.com/api/recipes#pace-splits): For a GPX course and a target time, prints a split for every kilometre, slower on the climbs and steep descents, with the terrain of each. Paste it on your wrist or into your watch.
- [Weather along a hike](https://trailsplits.com/api/recipes#weather-along): For a GPX file and a departure time, prints the forecast at each point at the hour you reach it, at that point's own height. Missing hours stay missing.
- [A map with 3D terrain](https://trailsplits.com/api/recipes#terrain-map): One HTML file: the TrailSplits outdoor map with hillshading and 3D terrain from the TrailSplits elevation tiles. Drag with the right mouse button (or two fingers) to tilt.