Skip to content
Back to search

sms

simple mbtiles server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/markuman--sms/badge.svg)](/listings/markuman--sms)

HTML

<a href="/listings/markuman--sms"><img src="/api/listings/markuman--sms/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

mkdir osm
wget --continue -O osm/planet.mbtiles https://osm.osuv.de/planet.mbtiles
wget --continue -O osm/contours.mbtiles https://osm.osuv.de/contours.mbtiles
podman run -ti --rm -p 9000:9000 --name sms -v "$(pwd)/osm/:/data/" registry.gitlab.com/markuman/sms:latest
firefox http://localhost:9000

requirements: * `podman` (_or `docker`_) * 101 GB storage is required (_1 core and 512MB memory are sufficient_) * optional 290 GB storage is required for contour lines

notes: * "_~30 minutes_" depends on your bandwidth ...and the hidrive performance of ionos.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 949 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🗺️ OSM - self host the entire planet 🌎 in ~30 minutes 🚀
  2. **s**imple **m**btiles **s**erver
  3. > **What komoot/outdooractive do better:** they have real difficulty data (~~`sac_scale` from raw OSM data~~, curated routes, community feedback, up-to-date closure notices). ~~Our router sends you over the Stopselzieher without a word — they don't.~~ ~~When it comes to pure routing, they're clearly ahead of us.~~
  4. >
  5. > **What we have and they don't:**
  6. >
  7. > - **Agent-native.** "Plan me a 3-day tour with hut stays, check the opening hours" is an afternoon of clicking on komoot — here it's one sentence. They have no MCP interface and won't build one anytime soon; their business model is keeping you inside their app.
  8. > - **Composability.** geocode → poi → route → gpx → nextcloud are building blocks the agent chains freely and enriches with web research. Over there it's a monolith.
  9. > - **Self-hosted, offline, no paywall.** The komoot world pack costs money, so does outdooractive pro, and both phone home.
  10. > - **Transparency.** When our router screws up, I can measure why. Their black box you can only doubt.
  11. >
  12. > We didn't build the better router — we built the better **interface for LLM agents**. A dumb-but-honest router + an agent that fills the gaps via web search + GPX export: that's the real lever.
  13. >
  14. > — *Fable 5.1, Sept 2026*
  15. >
  16. > <sub>Fact check: `sac_scale` was in the OSM data all along — planetiler just filtered it out. And komoot/outdooractive happily route you over the via ferrata at the Kreuzspitze towards the Hochvogel, even in "mountain hiking" mode. Ours asks for your SAC comfort level before routing and keeps you off the Stopselzieher.</sub>
  17. #### SETUP - TL;DR
  18. ```
  19. mkdir osm
  20. wget --continue -O osm/planet.mbtiles https://osm.osuv.de/planet.mbtiles
  21. wget --continue -O osm/contours.mbtiles https://osm.osuv.de/contours.mbtiles
  22. podman run -ti --rm -p 9000:9000 --name sms -v "$(pwd)/osm/:/data/" registry.gitlab.com/markuman/sms:latest
  23. firefox http://localhost:9000
  24. ```
  25. requirements:
  26. * `podman` (_or `docker`_)
  27. * 101 GB storage is required (_1 core and 512MB memory are sufficient_)
  28. * optional 290 GB storage is required for contour lines
  29. notes:
  30. * "_~30 minutes_" depends on your bandwidth ...and the hidrive performance of ionos.
  31. # credits
  32. * https://github.com/onthegomap/planetiler is used to generate the planet.mbtiles file
  33. * https://github.com/uktrade/mbtiles-s3-server is the origin code-base of my `sms` project
  34. # Usage
  35. ## nextcloud GpxPod
  36. 1. Deploy the container/service behind a webproxy (_caddy, nginx, traefik,...you name it._) to get a valid SSL certificate.
  37. 2. Goto GpxPod Settings -> Tile Servers
  38. * Type: Vector
  39. * Server address: `https://<YOUR_SMS_SERVICE_DEPLOYMENT>/v1/styles/osm-bright-gl-style@1.0.0/style.json?fonts=fonts-gl@1.0.0&tiles=mytiles@1.0.0`
  40. ## URL Parameter
  41. You can add coordinates and Zoomlevel.
  42. `https://maps.osuv.de/?lat=48.1374&lng=11.5752&zoom=9`
  43. ## Reverse Geolocation / Photon Integration
  44. * sms supports [photon](https://github.com/rtuszik/photon-docker) reverse geocoding server.
  45. Just set `-e PHOTONSERVER="https://photon.osuv.de"` for your sms Container.
  46. This also enables the `geocode` and `reverse_geocode` MCP tools; without it
  47. they are not registered at all.
  48. ### Two consumers, possibly two URLs
  49. `PHOTONSERVER` is substituted into `index.html` at startup, so **the browser**
  50. talks to Photon directly with that URL — it has to be publicly reachable.
  51. The MCP tools, on the other hand, call Photon **from inside the container**.
  52. If both run in podman/docker, the public hostname often resolves to a LAN
  53. address the container network cannot route to (split-horizon DNS), and you get
  54. `Connection refused`. Changing `PHOTONSERVER` is not the fix: that would break
  55. the frontend.
  56. Use `PHOTONSERVER_INTERNAL` for the server-side path instead:
  57. ```bash
  58. podman network create osm
  59. podman run -d --rm --network osm --name photon \
  60. -e UPDATE_STRATEGY=DISABLED \
  61. -p 8888:2322 \
  62. -v /home/m/osm/photon/:/photon/data \
  63. docker.io/rtuszik/photon-docker:2.1.1
  64. podman run -ti --rm --network osm --name sms \
  65. -p 9000:9000 \
  66. -e PHOTONSERVER="https://photon.osuv.de" \
  67. -e PHOTONSERVER_INTERNAL="http://photon:2322" \
  68. -v /home/m/osm/sms/:/data/ \
  69. localhost/sms:dev
  70. ```
  71. If `PHOTONSERVER_INTERNAL` is unset, server-side calls fall back to
  72. `PHOTONSERVER`, which is the right thing when both are reachable from
  73. everywhere (single host, no container network in between).
  74. ## Configuration
  75. Tilesets are configured through numbered environment variable groups
  76. (`MBTILES__1__*`, `MBTILES__2__*`, …):
  77. | Variable | Required | Description |
  78. |---|---|---|
  79. | `PORT` | yes | Listen port |
  80. | `MBTILES__n__URL` | yes | Path to the `.mbtiles` file |
  81. | `MBTILES__n__IDENTIFIER` | yes | Tileset name used in URLs |
  82. | `MBTILES__n__VERSION` | yes | Tileset version used in URLs |
  83. | `MBTILES__n__MIN_ZOOM` | yes | Minimum zoom level |
  84. | `MBTILES__n__MAX_ZOOM` | yes | Maximum zoom level |
  85. | `HTTP_ACCESS_CONTROL_ALLOW_ORIGIN` | no | CORS header value |
  86. | `PHOTONSERVER` | no | Public Photon base URL; enables geocoding and is embedded into the map UI |
  87. | `PHOTONSERVER_INTERNAL` | no | Photon URL used for server-side calls (MCP tools) when the public one is not reachable from inside the container |
  88. | `TILE_CACHE_SIZE` | no | Decoded road tiles kept in memory (default 2000; contour and POI caches get a quarter of that each) |
  89. | `ROUTE_MAX_TILES` | no | Corridor tile limit per segment (default 1200) |
  90. | `ROUTE_MAX_CROW_KM` | no | Straight-line limit per segment in km (default 50) |
  91. | `GPX_DIR` | no | Where generated GPX files are stored (default `$TMPDIR/sms-gpx`) |
  92. | `GPX_MAX_FILES` | no | Keep at most this many GPX files (default 200) |
  93. | `GPX_TTL_SECONDS` | no | Delete GPX files older than this (default 86400) |
  94. | `GPX_MAX_UPLOAD_BYTES` | no | Size limit for `POST /v1/gpx` uploads (default 10 MiB) |
  95. ## HELP WANTED
  96. * Improve Style
  97. * special for Nextcloud GxpPod
  98. * provide more style? remove some?
  99. ## planet.mbtiles
  100. My provided planet.mbtiles is generated by using
  101. https://github.com/markuman/planetiler — a fork of
  102. [planetiler](https://github.com/onthegomap/planetiler) following its
  103. [PLANET.md](https://github.com/onthegomap/planetiler/blob/main/PLANET.md)
  104. tutorial, with one difference: the OpenMapTiles profile is extended to emit
  105. outdoor attributes at z14 that the upstream schema drops.
  106. **transportation:** `sac_scale`, `trail_visibility`, `via_ferrata_scale`,
  107. `ladder`, `incline`, `smoothness`, `width`, `tracktype`, `segregated`,
  108. `mtb_scale_uphill`, `osm_id`
  109. **poi:** cave entrances, springs, wells, water taps, bivouac huts, saddles,
  110. summits, emergency phones, mountain rescue
  111. Without those, sms still works — it simply has no difficulty data to route on
  112. or warn about, and the `drinking_water`/`cave`/`viewpoint`/`emergency` POI
  113. categories stay empty. `/v1/capabilities` reports which attributes the loaded
  114. tiles actually carry under `difficulty_data`.
  115. ## contours.mbtiles
  116. Contours will be displayed if a file called `contours.mbtiles` is places next to `planet.mbtiles`.
  117. There are two different contours files provided. 90m resolution in Zoom Level 11 to 14 and 90m resolution in Zoom Level 11 to 13 with 30m resolution in Zoom Level 14.
  118. > GLO-30: "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"
  119. > GLO-90: "produced using Copernicus WorldDEM-90 © 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"
  120. ## Core API
  121. ### `GET /`
  122. Serves the map UI frontend (index.html) with optional URL parameters for coordinates and zoom level.
  123. **URL Parameters:**
  124. - `lat` — Latitude coordinate
  125. - `lng` — Longitude coordinate
  126. - `zoom` — Zoom level
  127. **Example:** `https://maps.osuv.de/?lat=48.1374&lng=11.5752&zoom=9`
  128. ### `GET /v1/capabilities`
  129. Returns JSON capabilities indicating available optional features.
  130. **Response:**
  131. ```json
  132. {
  133. "contours": true,
  134. "routing": true,
  135. "mcp": true,
  136. "gpx": true,
  137. "geocoding": false,
  138. "mcp_tools": ["search_poi", "plan_route", "export_gpx"],
  139. "difficulty_data": {
  140. "sac_scale": true, "via_ferrata_scale": true,
  141. "trail_visibility": true, "smoothness": true
  142. },
  143. "routing_limits": { "max_tiles": 1200, "max_crow_km": 50.0, "zoom": 14 },
  144. "tile_cache": {
  145. "roads": { "entries": 812, "max_entries": 2000, "hits": 4210, "misses": 812 },
  146. "contours": { "entries": 240, "max_entries": 500, "hits": 190, "misses": 240 },
  147. "poi": { "entries": 0, "max_entries": 500, "hits": 0, "misses": 0 }
  148. }
  149. }
  150. ```
  151. - `contours` — whether `contours.mbtiles` was detected and loaded
  152. - `routing` — always `true`; indicates the `/v1/route/` endpoint is available
  153. - `mcp` — the MCP endpoint at `POST /mcp` is available
  154. - `gpx` — GPX export is available
  155. - `geocoding` — whether `PHOTONSERVER` is configured (enables the `geocode`
  156. and `reverse_geocode` MCP tools)
  157. - `mcp_tools` — names of the registered MCP tools
  158. - `difficulty_data` — which hiking attributes the loaded tiles actually carry.
  159. All `false` on stock OpenMapTiles tiles (see *Hiking attributes* below), and
  160. in that case a missing warning means missing data, not easy terrain. The
  161. flags flip to `true` as soon as a tile containing them has been decoded.
  162. - `sac_scale_values` — accepted values for `max_sac_scale`, easiest first
  163. - `tile_cache` — live hit/miss counters of the decoded-tile caches
  164. ### `GET /v1/poi/{identifier}@{version}?lat={lat}&lon={lon}&category={category}&radius={radius}`
  165. Search for Points of Interest (POI) within a radius and return GeoJSON features.
  166. **Path Parameters:**
  167. - `identifier` — Tileset identifier
  168. - `version` — Tileset version
  169. **Query Parameters:**
  170. - `lat` — Latitude coordinate (required)
  171. - `lon` — Longitude coordinate (required)
  172. - `category` — POI category (required): `supermarket`, `pharmacy`, `hospital`,
  173. `fuel`, `charging_station`, `alpine_hut`, `camp_site`, `shelter`,
  174. `drinking_water`, `cave`, `viewpoint`, or `emergency`
  175. `drinking_water`, `cave`, `viewpoint` and `emergency` need tiles built with
  176. the extended profile linked above — stock OpenMapTiles does not put springs,
  177. wells or cave entrances into the `poi` layer at all. Note that
  178. `drinking_water` includes springs and cattle troughs: that is a location, not
  179. a potability guarantee.
  180. Note that `alpine_hut` covers only real mountain huts
  181. (`alpine_hut`, `wilderness_hut`, `basic_hut`). OpenMapTiles files bus stop
  182. shelters and public air-raid shelters under `subclass=shelter`, which around
  183. Garmisch is 113 of 122 hits and mostly unnamed — those live in the separate
  184. `shelter` category so they cannot bury the actual huts.
  185. - `radius` — Search radius in km, default 15, max 50 (optional)
  186. **Response:** GeoJSON FeatureCollection of POIs, each with a
  187. `properties.distance_km`. Sorted by distance, but named POIs come first
  188. within the same ~500 m band — an unnamed hut slightly closer is less useful
  189. than a named one you can look up.
  190. ### `GET /v1/tiles/{identifier}@{version}/{z}/{x}/{y}.mvt`
  191. Fetch a tile in Mapbox Vector Tile (MVT) format.
  192. **Path Parameters:**
  193. - `identifier` — Tileset identifier (e.g., from `MBTILES__1__IDENTIFIER`)
  194. - `version` — Tileset version (e.g., from `MBTILES__1__VERSION`)
  195. - `z` — Zoom level
  196. - `x` — Tile column coordinate
  197. - `y` — Tile row coordinate (converts from Web Mercator to TMS)
  198. **Special:** `contours@1.0.0` is auto-loaded if `contours.mbtiles` exists.
  199. **Gzip Negotiation:** Returns gzip-compressed tiles if client sends `Accept-Encoding: gzip`.
  200. **Caching:** `max-age=604800` plus an ETag that changes when the `.mbtiles`
  201. file is rebuilt — see [Caching](#caching). Send `If-None-Match` to get a
  202. cheap `304`.
  203. **Response:** `application/vnd.mapbox-vector-tile` (MVT format)
  204. ### `GET /v1/styles/{identifier}@{version}/style.json`
  205. Returns a MapLibre GL style JSON with injected tile, font, and sprite URLs.
  206. **Path Parameters:**
  207. - `identifier` — Style identifier (e.g., `osm-bright-gl-style`)
  208. - `version` — Style version (e.g., `1.0.0`)
  209. **Query Parameters:**
  210. - `tiles` — Tile source in format `{tile_id}@{tile_version}` (required)
  211. - `fonts` — Font source in format `{font_id}@{font_version}` (required)
  212. **Available Styles:**
  213. - `dark-matter-gl-style@1.0.0`
  214. - `fiord-color-gl-style@1.0.0`
  215. - `maptiler-3d-gl-style@1.0.0`
  216. - `maptiler-terrain-gl-style@1.0.0`
  217. - `maptiler-basic-gl-style@1.0.0`
  218. - `maptiler-toner-gl-style@1.0.0`
  219. - `osm-bright-gl-style@1.0.0`
  220. - `positron-gl-style@1.0.0`
  221. - `osuv-style@1.0.0`
  222. **Response:** `application/json` with complete style JSON including:
  223. - Tile source URL: `/v1/tiles/{tiles}@{version}/{z}/{x}/{y}.mvt`
  224. - Glyph URL: `/v1/fonts/{fonts}@{version}/{fontstack}/{range}.pbf`
  225. - Sprite URL: `/v1/styles/{identifier}@{version}/sprite`
  226. - Contour layers (if contours.mbtiles detected): `contour-line` and `contour-label` (visible when toggled in frontend)
  227. ### `GET /v1/styles/{identifier}@{version}/sprite.json`
  228. Returns the sprite JSON index file.
  229. **Path Parameters:**
  230. - `identifier` — Style identifier
  231. - `version` — Style version
  232. **Response:** `application/json` with sprite image references and bounds
  233. ### `GET /v1/styles/{identifier}@{version}/sprite@2x.json`
  234. Returns the high-resolution (2x) sprite JSON index file.
  235. **Path Parameters:**
  236. - `identifier` — Style identifier
  237. - `version` — Style version
  238. **Response:** `application/json` with high-res sprite references
  239. ### `GET /v1/styles/{identifier}@{version}/sprite.png`
  240. Returns the sprite image (1x resolution).
  241. **Path Parameters:**
  242. - `identifier` — Style identifier
  243. - `version` — Style version
  244. **Response:** `image/png`
  245. ### `GET /v1/styles/{identifier}@{version}/sprite@2x.png`
  246. Returns the sprite image (2x resolution for retina displays).
  247. **Path Parameters:**
  248. - `identifier` — Style identifier
  249. - `version` — Style version
  250. **Response:** `image/png`
  251. ### `GET /v1/fonts/{identifier}@{version}/{stack}/{range}.pbf`
  252. Returns merged glyph data in Protocol Buffer format for font rendering.
  253. **Path Parameters:**
  254. - `identifier` — Font identifier (`fonts-gl`)
  255. - `version` — Font version (`1.0.0`)
  256. - `stack` — Comma-separated font stack (max 4 fonts, e.g., `Noto Sans Regular,Noto Sans Bold`)
  257. - `range` — Glyph range (e.g., `0-255`)
  258. **Response:** `application/vnd.google.protobuf`
  259. - Gzip-compressed if client sends `Accept-Encoding: gzip`
  260. - Merges glyphs from all fonts in stack, deduplicating by glyph ID
  261. ### `GET /v1/route/{identifier}@{version}?from={lat},{lon}&to={lat},{lon}&profile={profile}`
  262. Compute a walking or cycling route between two coordinates using the vector tile road network.
  263. No external routing engine required — routing is performed entirely server-side from the MBTiles data.
  264. **Path Parameters:**
  265. - `identifier` — Tileset identifier (same as used for `/v1/tiles/`)
  266. - `version` — Tileset version
  267. **Query Parameters:**
  268. - `from` — Start point as `lat,lon` (required)
  269. - `to` — End point as `lat,lon` (required)
  270. - `profile` — Routing profile: `foot` (default) or `bike`
  271. - `buffer_km` — Corridor half-width around the straight line (optional).
  272. Defaults to 10 % of the segment length, at least ~3.3 km. Raise it when a
  273. detour around a lake or a closed area is needed.
  274. - `elevation` — `true` to add `ascent_m`/`descent_m` from `contours.mbtiles`
  275. and switch the duration estimate to DIN 33466 (optional)
  276. - `max_sac_scale` — hardest SAC grade allowed: `hiking` (T1),
  277. `mountain_hiking` (T2), `demanding_mountain_hiking` (T3), `alpine_hiking`
  278. (T4), `demanding_alpine_hiking` (T5), `difficult_alpine_hiking` (T6).
  279. Ways tagged *above* the limit are excluded from routing. Requires tiles with
  280. hiking attributes (optional)
  281. - `allow_via_ferrata` — `false` excludes ways tagged as via ferrata or with
  282. fixed ladders (optional, default `true`)
  283. - `prefer_routes` — `true` prefers ways carrying a marked hiking route
  284. (`iwn`/`nwn`/`rwn`/`lwn`), or a cycle route for `profile=bike` (optional)
  285. - `follow_route` — follow one named route, e.g. `Malerweg` or the ref `E3`
  286. (optional)
  287. Note these are **independent axes**: a way can be T6 scrambling without any
  288. ferrata tag, and a cabled route can be tagged T2. On a real Zugspitze test,
  289. excluding ferratas alone still produced a T6 route — for a safe tour set
  290. both. The response says so via `terrain_warnings` when only one is used.
  291. **Example:**
  292. ```
  293. GET /v1/route/mytiles@1.0.0?from=48.137,11.575&to=48.155,11.602&profile=foot
  294. ```
  295. **Response:** GeoJSON Feature with LineString geometry
  296. ```json
  297. {
  298. "type": "Feature",
  299. "geometry": {
  300. "type": "LineString",
  301. "coordinates": [[11.575, 48.137], ...]
  302. },
  303. "properties": {
  304. "distance_km": 3.241,
  305. "duration_min": 43.2,
  306. "profile": "foot",
  307. "tiles_loaded": 36,
  308. "buffer_tiles": 2.0,
  309. "nodes": 12847,
  310. "cache_hits": 30,
  311. "cache_misses": 6,
  312. "snap_start_m": 12.4,
  313. "snap_end_m": 31.9
  314. }
  315. }
  316. ```
  317. With hiking attributes in the tiles, `properties` additionally carries:
  318. ```json
  319. {
  320. "max_sac_scale": "T3",
  321. "sac_scale": { "T1": "hiking", "T2": "mountain_hiking",
  322. "T3": "demanding_mountain_hiking" },
  323. "surface_segments": { "unpaved": 788, "paved": 16 },
  324. "via_ferrata_sections": 36,
  325. "routes": [
  326. { "network": "rwn", "network_label": "regional",
  327. "name": "Malerweg", "segments": 68, "share_percent": 28 }
  328. ],
  329. "terrain_warnings": [
  330. "hardest section on this route is T3 = demanding_mountain_hiking near ...",
  331. "trail_visibility=horrible near 47.08226,9.61025 -- the path may be hard ..."
  332. ]
  333. }
  334. ```
  335. `sac_scale_data` appears instead of `sac_scale` when nothing along the route
  336. is tagged — that is a reminder that the difficulty is unknown, not that it is
  337. easy.
  338. **Profile weights** (OpenMapTiles `transportation` layer `class` attribute):
  339. | Road class | `foot` | `bike` |
  340. |---|---|---|
  341. | `footway`, `path`, `pedestrian` | preferred (1.0) | not passable |
  342. | `cycleway` | allowed (1.3) | preferred (1.0) |
  343. | `track` | 1.1 | 1.2 |
  344. | `residential`, `living_street` | 1.2–1.3 | 1.1 |
  345. | `tertiary` | 1.8 | 1.4 |
  346. | `secondary` | 2.5 | 1.6 |
  347. | `primary` | not passable | 2.5 |
  348. | `motorway`, `trunk` | not passable | not passable |
  349. | `steps` | 1.2 | not passable |
  350. **Duration estimate:** 4.5 km/h for `foot`, 15 km/h for `bike`. With
  351. `elevation=true` and `contours.mbtiles` present, `foot` switches to a
  352. DIN 33466 / SAC estimate instead (300 m ascent or 500 m descent per hour,
  353. combined as `max(horizontal, vertical) + min(horizontal, vertical) / 2`).
  354. ### Hiking attributes: sac_scale, via ferratas, surface
  355. OpenMapTiles is a **rendering** schema. Its transportation layer whitelists the
  356. attributes it keeps, and `sac_scale`, `trail_visibility` and
  357. `via_ferrata_scale` are not on that list — they exist in the OSM source data
  358. but are dropped during tile generation. The practical consequence is severe: a
  359. router cannot tell a T1 stroll from a T5 scramble, and **via ferratas appear as
  360. ordinary paths**. A route from the Zugspitze to the Alpspitze happily runs over
  361. "Stopselzieher" and "Höllentalsteig", both cabled climbing routes with ladders
  362. and a glacier crossing.
  363. sms therefore evaluates these attributes when they are present:
  364. | Attribute | Used for |
  365. |---|---|
  366. | `sac_scale` | `max_sac_scale` filter, `terrain_warnings`, extra time for T3+ on foot |
  367. | `via_ferrata_scale`, `ladder` | `allow_via_ferrata=false` filter, warnings |
  368. | `trail_visibility` | warning at `bad`/`horrible`/`no` |
  369. | `smoothness`, `tracktype` | weighting for `bike` — decides riding vs. pushing |
  370. | `mtb_scale` | warning at 4+ |
  371. | `surface` | statistics, minor weighting |
  372. | `osm_id` | warnings link to the way on openstreetmap.org, and group repeated sections |
  373. Where a way carries a real grade, the name-based fallback heuristic ("...steig",
  374. "Ferrata", "Grat") is suppressed — the "Höllentalsteig" near Garmisch is tagged
  375. T2, so warning about its name would contradict the data. The heuristic stays
  376. active on untagged ways.
  377. To get them, the tiles must be built with a planetiler whose OpenMapTiles
  378. profile emits those fields — see
  379. [markuman/planetiler](https://github.com/markuman/planetiler), which adds them
  380. at z14. `/v1/capabilities` reports under `difficulty_data` whether the loaded
  381. tiles carry them.
  382. **Without such tiles everything still works**, just without difficulty data:
  383. untagged ways are never excluded and never penalised, so routing behaves
  384. exactly as before. That is deliberate — most of the world has no `sac_scale`,
  385. and excluding untagged ways would produce empty results while pretending to be
  386. safe. An untagged path can be anything.
  387. ### Marked hiking routes
  388. OpenMapTiles flattens route relations into `route_1_*` … `route_4_*` on the
  389. `transportation_name` layer, so the tiles know which ways carry the E3, the
  390. Malerweg, a Via Alpina stage or a local marked trail. A way on a marked route
  391. is signposted, maintained and usually the scenic line, so `prefer_routes=true`
  392. gives those a weight discount, ordered by network importance:
  393. | Network | Meaning | Factor |
  394. |---|---|---|
  395. | `iwn` / `icn` | international | 0.70 |
  396. | `nwn` / `ncn` | national | 0.72 |
  397. | `rwn` / `rcn` | regional | 0.78 |
  398. | `lwn` / `lcn` | local | 0.85 |
  399. Road route relations (`DE:national`, `cz:regional`, `e-road`) are *not*
  400. weighted — those are road numbers, not trails.
  401. `follow_route=Forststeig` pulls much harder (factor 0.25) towards one specific
  402. route. This exists because plain waypoint routing cuts the loops a marked
  403. trail makes: on the Forststeig Elbsandstein the rock-group detours
  404. (Müllerstein, Rotstein, Spanghorn) are skipped unless every one of them is a
  405. waypoint. Measured on that trail:
  406. | | Distance | Routes followed |
  407. |---|---|---|
  408. | plain | 13.11 km | — |
  409. | `prefer_routes` | 13.11 km | Gelber Balken 49 %, Roter Punkt 32 % |
  410. | `follow_route=Forststeig` | 14.83 km | **Forststeig Elbsandstein 28 %** |
  411. Both are **weightings, not filters**: unmarked ways stay available, so a
  412. region without marked routes still routes normally. `follow_route` returns a
  413. `404` if no such route exists in the corridor, and a `terrain_warnings` entry
  414. if the route exists but does not connect the two points.
  415. The response lists the routes actually used under `properties.routes` with the
  416. share of the track:
  417. ```json
  418. "routes": [
  419. { "network": "rwn", "network_label": "regional",
  420. "name": "Forststeig Elbsandstein", "segments": 68, "share_percent": 28 }
  421. ]
  422. ```
  423. Route geometry lives in its own generalised layer, so routes are matched to
  424. graph edges by proximity (~200 m grid on the segment midpoints).
  425. ### Tile selection: corridor instead of bounding box
  426. Tiles are loaded as a **corridor along the straight line** between the two
  427. points, not as a bounding box. At 48° N a zoom-14 tile is about 1.64 km wide,
  428. so a bounding box for a diagonal 50 km route covers ~1260 tiles of which most
  429. are nowhere near the route. The corridor keeps only tiles within
  430. `buffer_km` of the line:
  431. | Route | Corridor | Old bounding box | Saving |
  432. |---|---|---|---|
  433. | 30 km diagonal | 112 tiles | 484 tiles | 4.3x |
  434. | 50 km diagonal | 276 tiles | 1260 tiles | 4.6x |
  435. | 50 km at 15° | 239 tiles | 598 tiles | 2.5x |
  436. | 50 km axis-parallel | 99 tiles | 100 tiles | 1.0x |
  437. For an almost axis-parallel route the bounding box is naturally narrow
  438. already, so the default buffer is capped at the box's short side and the
  439. corridor never ends up loading materially more than a bbox would.
  440. **Limits:**
  441. - `max_tiles`: 1200 tiles at zoom 14 (OOM guard, configurable via
  442. `ROUTE_MAX_TILES`)
  443. - `max_crow_km`: 50 km straight-line distance per segment (configurable via
  444. `ROUTE_MAX_CROW_KM`). Longer tours are possible via the `plan_route` MCP
  445. tool, which chains segments.
  446. - Start and end points must be within 500 m of a routable road. Both ends are
  447. snapped onto the *same* connected part of the network — vector tiles are
  448. clipped at tile borders, so the decoded graph contains many short
  449. disconnected stubs that would otherwise swallow the start point.
  450. - No turn restrictions and no access tags (OSM relations and `access=private`
  451. are not stored in vector tiles)
  452. - Routing always uses zoom 14. There is deliberately **no zoom-13 fallback**:
  453. `path` and `footway` have minzoom 14 in OpenMapTiles, so on z13 exactly the
  454. ways that matter for hiking disappear.
  455. - Decoded tiles are cached (see `TILE_CACHE_SIZE`), so repeated queries in the
  456. same region are much faster than the first one. Expect ~0.2–2 s cold and
  457. well under 0.5 s warm for a 50 km segment. Memory stays within the
  458. documented 512 MB.
  459. **Error responses:**
  460. - `400` — invalid parameters, straight-line distance over the limit, or
  461. corridor over `max_tiles`
  462. - `404` — no road network in area, no way passable for the profile, start or
  463. end further than 500 m from a road, or no route found
  464. ### `POST /v1/elevation/{identifier}@{version}`
  465. Estimate ascent and descent of a track by intersecting it with the contour
  466. lines from `contours.mbtiles`. Only available when that file is present.
  467. **Body:**
  468. ```json
  469. { "coordinates": [[11.575, 48.137], [11.602, 48.155]] }
  470. ```
  471. Coordinates are `[lon, lat]` pairs (GeoJSON order).
  472. **Response:**
  473. ```json
  474. { "ascent_m": 640, "descent_m": 210 }
  475. ```
  476. Accuracy is limited by the contour interval (about ±half an interval), so
  477. treat these as estimates, not survey data.
  478. **Error responses:**
  479. - `400` — invalid body or area too large
  480. - `404` — no `contours.mbtiles` loaded
  481. ### `GET /v1/gpx/{id}.gpx`
  482. Download a GPX file previously generated by the `plan_route` or `export_gpx`
  483. MCP tool. The id is the `gpx_id` from the tool result.
  484. **Response:** `application/gpx+xml` (GPX 1.1, with `<wpt>` waypoints and
  485. `<ele>` values when contours were available)
  486. Generated files are cleaned up automatically: anything older than
  487. `GPX_TTL_SECONDS` is removed, and at most `GPX_MAX_FILES` are kept.
  488. **Error responses:**
  489. - `404` — unknown or expired id
  490. ### `POST /v1/gpx`
  491. Upload a GPX file and get a `gpx_id` back — the input side of the
  492. `analyze_gpx` MCP tool. The body is either the raw document
  493. (`application/gpx+xml`, `text/xml`, anything) or a multipart form with a
  494. `file` field. GPX 1.0 and 1.1 are accepted, `<trk>` segments are
  495. concatenated, `<rte>` is used when there is no track. Files with a `DOCTYPE`
  496. or entity declarations are rejected (no `defusedxml` dependency, so no
  497. entity expansion at all).
  498. ```bash
  499. curl -s -X POST --data-binary @tour.gpx localhost:9000/v1/gpx
  500. ```
  501. ```json
  502. {
  503. "gpx_id": "5c925fc1584040a4",
  504. "gpx_url": "http://localhost:9000/v1/gpx/5c925fc1584040a4.gpx",
  505. "name": "Karwendel-Durchquerung",
  506. "points": 4812,
  507. "waypoints": 3,
  508. "has_elevation": true
  509. }
  510. ```
  511. The file is stored verbatim (download is byte-identical) and subject to the
  512. same TTL / max-files housekeeping as generated tracks.
  513. **Error responses:**
  514. - `400` — not a usable GPX (malformed, fewer than two points, `DOCTYPE`)
  515. - `413` — larger than `GPX_MAX_UPLOAD_BYTES`
  516. ### `GET /v1/gpx/{id}/analysis`
  517. REST twin of the `analyze_gpx` MCP tool (see below). Query parameters:
  518. `profile`, `poi_categories` (comma separated), `poi_max_off_km`,
  519. `elevation_source`, `tileset`.
  520. ### Map UI routing options
  521. The map UI exposes the same knobs: a transport dropdown (hiking / bike), a
  522. difficulty dropdown (T1–T6, default "egal"/any) and an "ohne Klettersteig"
  523. checkbox which is **on by default** — a hiking UI should not silently route
  524. over a via ferrata — plus a "markierte Wege" checkbox (also on by default)
  525. for `prefer_routes`. The names of the marked trails the route follows are
  526. shown below the toolbar. Changing any of them recalculates all segments, and
  527. `terrain_warnings` are shown below the toolbar with the OSM way linked.
  528. ## Caching
  529. Tiles are the hot path — a single pan fetches dozens of them — so everything
  530. that can be cached is cached, and everything dynamic explicitly is not:
  531. | Endpoint | `Cache-Control` | Why |
  532. |---|---|---|
  533. | `/v1/tiles/…` | `public, max-age=604800, stale-while-revalidate=86400` | immutable per dataset, ETag catches rebuilds |
  534. | `/v1/tiles/…` (404) | `public, max-age=3600` | ocean and out-of-extract tiles 404 on every pan |
  535. | `/v1/static/…`, `/v1/fonts/…`, sprites | `public, max-age=31536000, immutable` | version is part of the URL |
  536. | `/v1/styles/…/style.json` | `public, max-age=3600` | embeds request-derived URLs |
  537. | `/v1/gpx/<id>.gpx` | `private, max-age=86400` | stable per id, but user generated |
  538. | `/` | `no-cache` | rewritten by `startup.sh`, revalidates via ETag |
  539. | `/v1/route`, `/v1/poi`, `/v1/gpx/<id>/analysis`, `/v1/capabilities`, `/mcp` | `no-store` | a stale route is worse than a recomputed one |
  540. **Tile ETags are `<dataset>-<z>-<x>-<y>`**, where `dataset` is a fingerprint of
  541. the `.mbtiles` file (mtime and size). Rebuilding the dataset therefore
  542. invalidates every cached tile automatically — no version to bump, no cache to
  543. purge. A revalidation costs one conditional request and returns `304` with an
  544. empty body; measured over 20 tiles: 250 kB and 763 ms down to 0 kB and 9 ms,
  545. and within `max-age` the browser does not even ask.
  546. The ETag is checked *before* touching SQLite, so a revalidation is answered
  547. without a database read.
  548. ## MCP API (route planning for LLM agents)
  549. sms exposes a [Model Context Protocol](https://modelcontextprotocol.io)
  550. endpoint so that an LLM agent can plan hiking and trekking tours and export
  551. them as GPX — without an external routing engine and without any additional
  552. data source.
  553. ### `POST /mcp`
  554. Stateless JSON-RPC 2.0 (streamable HTTP without SSE). Implemented methods:
  555. `initialize`, `notifications/*`, `ping`, `tools/list`, `tools/call`.
  556. `GET /mcp` returns `405` — there is no event stream.
  557. Register it with an MCP client, for example in `opencode.json`:
  558. ```json
  559. {
  560. "mcp": {
  561. "sms": {
  562. "type": "remote",
  563. "url": "https://maps.example.org/mcp",
  564. "enabled": true
  565. }
  566. }
  567. }
  568. ```
  569. Or check it manually:
  570. ```bash
  571. curl -s localhost:9000/mcp -H 'content-type: application/json' \
  572. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
  573. ```
  574. ### Tools
  575. | Tool | Purpose | Requires |
  576. |---|---|---|
  577. | `geocode` | place name / address → coordinates | `PHOTONSERVER` |
  578. | `reverse_geocode` | coordinates → nearest address | `PHOTONSERVER` |
  579. | `search_poi` | huts, water, resupply around a point | — |
  580. | `plan_route` | multi-waypoint tour + GPX export | — |
  581. | `export_gpx` | write arbitrary coordinates as GPX | — |
  582. | `analyze_gpx` | assess an uploaded GPX track: ways, difficulty, elevation, POIs along it | — |
  583. `plan_route` takes `waypoints: [[lat, lon], ...]` and routes each consecutive
  584. pair separately. Each single segment must stay under `max_crow_km`, but the
  585. total tour is unlimited — three 45 km segments give a 135 km track. If a
  586. segment fails, the remaining segments are still returned and the failure is
  587. reported per segment (`"segment 2 (48.15,11.57 -> ...): no routable way
  588. within 500 m ..."`), so the agent can fix that one waypoint instead of
  589. guessing blindly.
  590. Besides `waypoints`, `profile` and `buffer_km`, `plan_route` accepts the same
  591. knobs as the REST endpoint:
  592. | Argument | Purpose |
  593. |---|---|
  594. | `max_sac_scale` | exclude terrain above a SAC grade |
  595. | `allow_via_ferrata` | `false` keeps cabled climbing routes out |
  596. | `prefer_routes` | prefer signposted trails |
  597. | `follow_route` | follow one named trail, e.g. `"Malerweg"` or `"E3"` |
  598. | `elevation` | ascent/descent from `contours.mbtiles` |
  599. | `export_gpx` | write the GPX file (default `true`) |
  600. | `name` | track name stored in the GPX file |
  601. | `tileset` | pick a tileset as `identifier@version` when several are configured |
  602. The track geometry is deliberately **not** part of the tool result — a few
  603. thousand track points as text would flood the model's context window. The
  604. tool returns metadata plus a URL:
  605. ```json
  606. {
  607. "name": "Karwendel-Durchquerung",
  608. "distance_km": 42.1,
  609. "duration_min": 561,
  610. "ascent_m": 1840,
  611. "descent_m": 1620,
  612. "points": 3000,
  613. "max_sac_scale": "T3",
  614. "routes": [
  615. { "network": "iwn", "network_label": "international",
  616. "ref": "E4", "name": "European long distance path E4",
  617. "segments": 412, "share_percent": 41 }
  618. ],
  619. "terrain_warnings": [
  620. "hardest section on this route is T3 = demanding_mountain_hiking near 47.42107,11.06653; ..."
  621. ],
  622. "gpx_url": "https://maps.example.org/v1/gpx/5c925fc1584040a4.gpx"
  623. }
  624. ```
  625. ### `analyze_gpx` — assessing an existing track
  626. The reverse direction: the user already has a GPX (from a tour portal, a
  627. friend, last year's recording) and wants to know what they are getting into.
  628. Upload it with `POST /v1/gpx`, then call `analyze_gpx` with the `gpx_id`. The
  629. ids returned by `plan_route` and `export_gpx` work as well, so an agent can
  630. plan a tour and immediately check it for water and huts along the way.
  631. The track is **map-matched** onto the tile network: it is resampled every
  632. 20 m and each sample is snapped to the nearest transportation segment within
  633. 30 m. From the matched segments the tool reports way classes, surfaces,
  634. tagged difficulty and marked routes — everything `plan_route` reports, plus
  635. the km position on the track (`"VIA FERRATA at km 12.0 (…)"`). Samples with
  636. no way within 30 m count as **off-network**: pathless terrain (alpine
  637. crossings, glaciers, fords) *or* ways missing in the tiles — either way the
  638. agent cannot say anything about those sections and is told so.
  639. POIs are collected along the corridor with their position on the track and
  640. distance off it. `poi_summary` gives, per category, the count and the
  641. **longest gap** — "16 km without drinking water" is the number that decides
  642. how much to carry.
  643. ```json
  644. {
  645. "name": "Forststeig Etappe 3",
  646. "distance_km": 18.4,
  647. "duration_min": 372,
  648. "elevation_source": "gpx",
  649. "ascent_m": 640, "descent_m": 710, "min_ele_m": 312, "max_ele_m": 561,
  650. "matched_percent": 94,
  651. "off_network_km": 1.1,
  652. "off_network_sections": [{ "from_km": 7.2, "to_km": 8.1, "length_km": 0.9 }],
  653. "road_classes_km": { "path": 12.3, "track": 4.9, "minor": 1.2 },
  654. "surface_km": { "ground": 6.1, "gravel": 3.2 },
  655. "max_sac_scale": "T2",
  656. "routes": [{ "network": "rwn", "network_label": "regional", "name": "Forststeig", "share_percent": 71 }],
  657. "terrain_warnings": ["hardest section on this route is T2 = mountain_hiking at km 9.6 (…)"],
  658. "poi_summary": {
  659. "drinking_water": { "count": 2, "max_gap_km": 11.3 },
  660. "shelter": { "count": 5, "max_gap_km": 6.0 },
  661. "alpine_hut": { "count": 0, "max_gap_km": 18.4 }
  662. },
  663. "pois": [
  664. { "name": "Taubenteich", "category": "drinking_water", "at_km": 3.1, "off_track_m": 40, "lat": 50.8794, "lon": 14.1201 }
  665. ]
  666. }
  667. ```
  668. | Argument | Purpose |
  669. |---|---|
  670. | `gpx_id` | from `POST /v1/gpx`, `plan_route` or `export_gpx` (required) |
  671. | `profile` | `foot` / `bike`, for the duration estimate |
  672. | `poi_categories` | default `alpine_hut, shelter, camp_site, drinking_water, supermarket, emergency` |
  673. | `poi_max_off_km` | corridor half-width for POIs (default 1, max 5) |
  674. | `elevation_source` | `auto` (track `<ele>` when ≥ 90 % of points have it, else contours), `gpx`, `contours` |
  675. | `tileset` | `identifier@version` |
  676. Elevation from the track's own `<ele>` is smoothed with a 10 m hysteresis;
  677. barometric recordings are good, plain GPS elevation still tends to overstate.
  678. Pass `elevation_source: "contours"` to cross-check.
  679. ### What the agent can and cannot know
  680. With tiles built from the [extended profile](#hiking-attributes-sac_scale-via-ferratas-surface),
  681. difficulty **is** available where OSM contributors tagged it: `plan_route`
  682. accepts `max_sac_scale` and `allow_via_ferrata`, and returns
  683. `terrain_warnings`, `max_sac_scale` and the marked trails under `routes`.
  684. Agents are told to pass those on verbatim.
  685. What still cannot be known, and what the tool descriptions say explicitly:
  686. - **Untagged ways are unknown, not easy.** They are never excluded and never
  687. penalised (see above for why), so a route may still contain a T5 scramble
  688. that nobody tagged. A missing warning means missing data.
  689. - **Via ferratas are ordinary paths in the data.** Where no
  690. `via_ferrata_scale` exists, only a name heuristic ("…steig", "Ferrata",
  691. "Grat") is left — it produces false positives and misses unnamed ways.
  692. - **`max_sac_scale` and `allow_via_ferrata` are independent axes.** A way can
  693. be T6 scrambling without a ferrata tag, and a cabled route can be tagged
  694. T2. Set both.
  695. - **Not in the tiles at all:** seasonal closures, wildlife sanctuaries with
  696. right-of-way restrictions, `access=private`, turn restrictions, hut opening
  697. hours, prices and whether a hut is staffed.
  698. - **On stock OpenMapTiles tiles none of the difficulty data exists.**
  699. `/v1/capabilities` reports this under `difficulty_data`; when those flags
  700. are `false`, the agent is flying blind and should say so.
  701. Never treat a generated track as a safety assessment — cross-check it against
  702. a topographic map before walking it.
  703. ### `GET /v1/static/{identifier}@{version}/{file}`
  704. Serves vendored MapLibre GL JS/CSS static assets.
  705. **Path Parameters:**
  706. - `identifier` — Asset identifier (`maplibre-gl`)
  707. - `version` — Asset version (`5.19.0`)
  708. - `file` — File name: `maplibre-gl.css` or `maplibre-gl.js`
  709. **Response:** CSS or JavaScript file
  710. ## For the curious, advanced, or developers of this server itself
  711. Hosting your own vector map tiles to show them in a browser requires quite a few components:
  712. 1. **JavaScript and CSS**
  713. A Javascript and CSS library, such as [MapLibre GL](https://github.com/maplibre/maplibre-gl-js), and your own code to run this library, pointing it to a style file
  714. 2. **Style file**
  715. A JSON file that defines how the library should visually style the map data, and where it should find the map tiles, glyphs (fonts), and the sprite. This server transforms the built-in Style files on the fly to be able to refer to any map data.
  716. 3. **Glyphs** (fonts)
  717. Different fonts can be used for different labels and zoom levels, as defined in the Style file. The fonts must Signed Distance Field (SDF) fonts wrapped in a particular Protocol Buffer format. The Style file can refer to "stacks" of fonts; but unlike CSS, the server combines the fonts on the fly in an API where the resulting "font" has at most one glyph from each source font.
  718. 4. **Sprite**
  719. A sprite is actually 4 URLs: a JSON index file and a single PNG file, and a "@2x" JSON index file and PNG files for higher pixel ratio devices (e.g. Retina). The JSON files contains the offsets and sizes of images within corresponding PNG file. The style file refers the common "base" of these. For example, if the style file has `"sprite":"https://my.test/sprite"` then the 4 files must be at `https://my.test/sprite.json`, `https://my.test/sprite.png`, `https://my.test/sprite@2x.json` and `https://my.test/sprite@2x.png`.
  720. 5. **Vector map tiles**
  721. A set of often millions of tiles each covering a different location and different zoom level. These can be distributed as a single mbtiles file, but this is not the format that the Javascript library accepts. This on-the-fly conversion from the mbtiles file to tiles is the main feature of this server.
  722. The mbtiles file is a SQLite file, containing gzipped Mapbox Vector Tile tiles. This server leaves the un-gzipping to the browser, by sending tiles with a `content-encoding: gzip` header, which results in browser un-gzipping the tile data before it hits the Javascript.
  723. ## Licenses
  724. The code of the server itself is released under the MIT license. However, several components included in [mbtiles_s3_server/vendor/](./mbtiles_s3_server/vendor/) are released under different licenses.
  725. # support
  726. * My Project: https://github.com/markuman/sms
  727. * For the large planet.mbtiles generation and hosting, donations are welcome 🙂
  728. * paypal.me/MarkusBergholz
  729. * bc1qz33cf70vq82gxf8kps06j7lv7m2903hsnjak6k

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.