Documentation menu
Copy it, run it
34 worked examples covering the platform end to end, each one with the code for the way you actually work: the Web SDK, a plain curl against the hosted gateway, and the MCP tool call an agent sends. Every sample is checked against the contract it claims, so what you paste is what the API takes.
What you need to run these
Nothing you have to buy. The MCP examples need no key at all: point a client at https://mcp.mapmap.ai/mcp and call the tools under fair use. The static map endpoint takes no key either. Everything else runs on a free key you mint in one call, with no card, no console and no wait:
curl -fsS -X POST "https://api.mapmap.ai/v1/keys" \
-H "Content-Type: application/json" \
-d '{"email": "you@example.co.uk", "accept_tos": true}'The key works immediately for 1,000 calls. Clicking the emailed verification link lifts it to 50,000 calls a month, free, commercial use allowed. Full detail on the quickstart.
Add a map
A branded vector map in five lines: MapMap tiles, the MapLibre renderer and the pmtiles protocol already wired up. The container needs a real height or MapLibre draws into a zero-pixel canvas.
Custom markers
Your own pins on the map: 21 built-in glyphs, three size presets, any colour, optional labels, or a data URI image of your own. The same schema Studio's markers panel writes and the gateway validates.
3D terrain
One flag drapes the map over real elevation and shades the relief. The default DEM is the same dataset the gateway samples for POST /elevation, so a rendered mountain and a queried one agree.
Globe projection
The map on a sphere rather than a plane, for the zoomed-out view. Globe is a MapLibre projection, so it is set on the underlying map; the navigation chase camera is mercator only and says so.
Static map image
A rendered PNG of a view, a route or a GeoJSON overlay, from one URL and no API key. Built for agents, which can look at a map but cannot run a renderer.
GeoJSON lines and polygons
Your own zones and paths from one GeoJSON source: a fill and an outline for the polygons, a line for the paths, split by geometry type. The layers sit beneath the labels, so street names stay readable over your shapes.
Clustered points with totals
Thousands of points collapse into clusters that carry a running total of a property, not just a count. DataLayer's cluster mode sums each drop's parcels into its cluster, so the cluster under the pointer reads 1,240 parcels rather than 38 points.
Heatmap
Density from your own points, weighted by a property, that hands over to individual circles as you zoom in. The weight, the radius and the fade are all expressions, so the same data reads at city scale and at street scale.
Choropleth
Polygons coloured by a number on each one, with a graduated ramp you can read at a glance and white outlines that keep neighbouring areas apart. The same pattern fits wards, postcode districts, sales territories or delivery zones.
Extrude your own polygons
Raise your polygons into 3D by a height property, in metres, with fill-extrusion. Tilt the camera and a value becomes a block you can compare across the city. The same layer draws planned buildings, stock levels or any number per area.
Hover highlight with feature-state
Highlight the polygon under the pointer without touching the data. DataLayer flips a feature-state flag on one feature and its paint expressions read it, so hover costs no setData and no re-tiling, even on large sources.
Click a feature for a popup
Click one of your points and get a popup built from its properties, with a pointer cursor on hover so people know it is clickable. The popup content is an element filled with textContent, so a property holding markup is shown as text, never run.
Live updates with updateData
Move a fleet of vans every two seconds by sending only what changed. DataLayer.updateData patches features by id, so a position feed of hundreds of vehicles never re-sends the whole collection the way setData does.
Animate a point along a line
A marker that travels a path at a steady speed, frame by frame, from a small GeoJSON source you update with requestAnimationFrame. It stops dead for people who ask their system for reduced motion.
Line gradient
Colour a line along its own length, start to finish, with line-gradient over line-progress. Good for showing direction, progress along a trip or a value that changes along a path, with one line and no splitting.
Image overlay
Pin a picture to four corners on the map: a site plan, a scanned survey or a rendered surface. This one is MapMap's own hillshade of Kynance Cove, made from Environment Agency LiDAR, with the sea left transparent so the basemap shows through.
Video overlay
Play a video on the map, pinned to four corners like an image. This loop is MapMap's own render of the light moving round Kynance Cove over Environment Agency LiDAR, and the controls are plain pause and play calls on the source.
Your own XYZ raster tiles
Draw raster tiles from your own tile server over the MapMap basemap: aerial imagery, a flood model, a scanned historic map. One raster source with a {z}/{x}/{y} template, your credit on it, and the roads and labels kept on top.
Vector tiles you host as PMTiles
Put a large dataset on the map as vector tiles from one PMTiles file on your own bucket: no tile server, no upload to us. The browser reads only the byte ranges it needs, so a file of gigabytes draws as fast as a small one.
Data on the globe
Your own lines and points on the globe projection, from offices to the routes between them. Lines are bent into great circles before they are added, because a straight two-point line is not the shortest path on a sphere.
Click and hover on basemap features
React to clicks and hovers on the basemap's own POIs, place names and buildings with addInteraction and a named featureset, shaped like Mapbox's. Handlers resolve against the live style, so they keep working after a theme swap.
Live bus positions
England's local buses moving on your map from the Bus Open Data Service, polled for the area on screen and drawn one poll behind so they glide between fixes. Display only: positions as the feed reports them, never an arrival prediction.
Bus stops, lines and departures
England's bus stops and lines from NaPTAN and the BODS timetables, kept apart from the basemap, with a click on a stop fetching its timetabled departures. The times are the timetable's; MapMap does not plan journeys or predict arrivals.
Truck route with dimensions and ADR
A 44 tonne artic, 4.0 m high, carrying dangerous goods under ADR tunnel restriction code C/E. The dimensions and the tunnel code go into costing, so the route comes back already refusing what the vehicle cannot legally take.
Turn instructions anchored to landmarks
"Turn right just after the Shell garage", beside the engine's own street-name instruction rather than instead of it. Nothing is named unless it is recognisable from the road, within 40 m of the junction and not tagged as closed, so many routes come back with none.
Why this route
Ask a route to explain itself. The gateway re-routes with each declared constraint relaxed and reports the ones that provably changed the geometry, with the place the routes part ways. Derived by the engine, not written by a language model.
Optimise a mixed fleet
Two lorries, two drops, one of them dangerous goods, and only one vehicle is ADR licensed. The ADR profile constrains the roads; skills constrain the assignment, so the hazmat job can only land on the licensed lorry.
Reachable area (isochrones)
How far a vehicle gets from a point inside a time budget, as GeoJSON you can drop straight onto a map. Pass a truck profile and the contour respects the dimensions the vehicle actually has.
Distance and duration matrix
Many-to-many travel times and distances: the workhorse behind "which of my drivers is genuinely closest, by road, in a lorry". Unreachable pairs come back as honest nulls, never a sentinel cost.
Cheapest fuel along a route
Forecourts on the way, ranked cheapest first, each priced with its real engine-computed detour. A station 3p cheaper is not cheaper if reaching it costs eight minutes, which is why the detour is measured rather than assumed.
Geocode with a location bias
Free text to coordinates, with a bias point that reorders candidates and a bounding box that excludes anything outside it outright. Reverse lookups add a distance and, on POI hits, a details object straight from OpenStreetMap.
Search along a route, with real detour costs
"Coffee, adds 4 min." Every candidate is costed leave-route, stop, rejoin against staying on the route, under your own costing, so a truck's detour is a truck's detour. Note the two surfaces search different data.
Nearby places, described from where you are standing
Give the search a compass heading and every result is phrased from the user's point of view: "ahead and slightly to your right, about 80 metres". That is what a voice or wearable client reads out, instead of coordinates.
Call the route tool over MCP
Point any MCP client at the hosted endpoint and routing becomes a tool the model can call. No key is needed to connect for evaluation; present your own snk_ key and the metered calls bill to you instead of us.
Want to run a request without writing any code first? The playground makes the same calls from your browser, and the video library shows several of these being built.