API & MCP

Everything a person can do on Cartograph GPS Art Route Designer (shape → roads → GPX), a program or AI agent can do with the same inputs and get the identical result.

HTTP API

POST https://cartographrouteart.usefulweb.app/api/v1/calculate – run Cartograph GPS Art Route Designer (shape → roads → GPX)
GET https://cartographrouteart.usefulweb.app/api/v1/tool – inputs, output schema, examples
OpenAPI 3.1: /openapi.json · /openapi.yaml
Errors: application/problem+json; 422 includes per-field errors.

Cartograph GPS Art Route Designer (shape → roads → GPX)

Places a shape (heart, star, circle, square, triangle, arrow or zigzag) at a point, size and rotation, samples it into waypoints, snaps them to the walkable or rideable roads of your own OpenStreetMap extract and joins them with shortest paths that stay close to the shape. Returns the route as GPX with its length and how closely it follows the drawing. Routing runs on the extract itself — no routing service is used. It is the GPS-art engine of the Cartograph app.

Inputs of Cartograph GPS Art Route Designer (shape → roads → GPX)
Field	Type	Default	Description
`file`	file	—	OpenStreetMap extract (.osm, .osm.pbf or GeoJSON). Up to 25 MB. Leave empty to use the built-in Vaduz sample. Download extracts from your own OpenStreetMap export, Geofabrik or BBBike; Cartograph never fetches map data itself.
`shape`	select (heart, star, circle, square, triangle, arrow, zigzag)	"heart"	Shape
`center`	text	—	Shape centre. Empty: the middle of the extract.
`widthM`	number	1000	Shape width
`rotationDeg`	number	0	Rotation (clockwise)
`profile`	select (foot, bike)	"foot"	Travel mode
`spacingM`	number	0	Waypoint spacing. 0 = automatic (shape length ÷ 60, at least 30 m).
`guidance`	number	2	Stay-on-shape weight. 0 = plain shortest paths between waypoints; higher values prefer streets close to the drawn line.

Example request

Heart run in Vaduz (built-in sample)

curl -X POST https://cartographrouteart.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{"shape":"heart","center":"47.145, 9.517","widthM":1000,"profile":"foot"}'

Every result contains

inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.

MCP (Model Context Protocol)

Streamable HTTP endpoint: https://cartographrouteart.usefulweb.app/mcp – protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake).
Tools: cartograph_route_art
Local stdio connector: node src/mcp-stdio.ts --tool=cartograph-route-art

{
  "mcpServers": {
    "cartograph-route-art": { "type": "http", "url": "https://cartographrouteart.usefulweb.app/mcp" }
  }
}