Build on your own map server.

Mapwright exposes a clean, versioned /v1 surface plus Mapbox / MapTiler-compatible aliases. Same API whether you self-host or use the cloud — only the base URL changes.

01 / Quickstart

Your first request.

Pick a base URL — your self-hosted host, or https://api.mapwright.io — mint a key in the console, and call any endpoint.

# 1. base URL
#   self-host → https://your-host
#   cloud     → https://api.mapwright.io

# 2. a geocode, key in the query
curl "https://api.mapwright.io/v1/geocode/boston?key=mpw_pk_..."

// a MapLibre map pointed at your styles
new maplibregl.Map({
  container: "map",
  style: "https://api.mapwright.io/v1/styles/streets.json",
  transformRequest: (url) => ({
    url: url + (url.includes("?") ? "&" : "?") + "key=mpw_pk_...",
  }),
})

02 / Authentication

Keys, three ways.

Every key is prefixed mpw_pk_. Send it whichever way suits the client — query param for map URLs, headers for server-side calls.

?key=mpw_pk_...                       # query param
Authorization: Bearer mpw_pk_...      # header
X-Api-Key: mpw_pk_...                 # header

Keys carry scopes and an optional origin allowlist. A request only succeeds if the key holds the scope its path needs.

tiles tiles, geocoding, elevation, coordinates, OGC, images, data

styles styles, static maps

fonts glyphs + sprites

routing directions, matrix, isochrone, matching, optimization

admin control plane (/admin) — keep this off public keys

03 / API surface

Everything under /v1.

Resource-grouped native routes, plus Mapbox / MapTiler-compatible aliases (/maps/{id}/style.json, /geocoding/…) so existing clients work unchanged.

Tiles /v1/tiles/{id}/{z}/{x}/{y}.mvt tiles

Styles /v1/styles/{id}.json styles

Fonts / sprites /fonts/{stack}/{range}.pbf fonts

Geocoding /v1/geocode/{query} tiles

Routing /v1/route/{profile}/{coords} routing

Matrix / isochrone /v1/route/matrix · /v1/route/isochrone routing

Static maps /v1/static/{id}/{lon},{lat},{z}/{w}x{h}.png styles

Elevation /v1/elevation/{lng},{lat} tiles

Coordinates /v1/coordinates/transform/{coords} tiles

OGC /wmts/{id}/… · /wms?… · /collections tiles

Images / data /images/{id}/… · /data/{id}/features.json tiles

Geolocation /geolocation/ip.json tiles

04 / Drop-in migration

Keep your MapLibre code.

Repoint at your host and swap the token for a key. The @mapwright/compat helper rewrites Mapbox / MapTiler requests for you.

// npm i @mapwright/compat
import { mapwrightTransformRequest } from "@mapwright/compat"

map.transformRequest = mapwrightTransformRequest({
  host: "https://api.mapwright.io",
  key: "mpw_pk_...",
})

05 / MCP server

Mapwright for AI assistants.

@mapwright/mcp is a Model Context Protocol server — it lets Claude and other MCP clients migrate Mapbox / MapTiler code, browse the API reference, and call live endpoints. Three tool groups:

Migration

offline

map_endpoint · transform_request · migrate_style · scan_code

Convert Mapbox / MapTiler URLs, tokens, styles and code to Mapwright.

Reference

offline

list_apis · describe_api

Browse Mapwright's API — endpoints, params, examples — with no instance.

Live API

needs key

geocode · tilequery · directions · isochrone · elevation · static_map

Call a running Mapwright when MAPWRIGHT_URL + MAPWRIGHT_KEY are set.

Add it to your MCP client. Drop the env block to run only the offline migration + reference tools.

// claude_desktop_config.json
{
  "mcpServers": {
    "mapwright": {
      "command": "npx",
      "args": ["-y", "@mapwright/mcp"],
      "env": {
        "MAPWRIGHT_URL": "https://api.mapwright.io",
        "MAPWRIGHT_KEY": "mpw_pk_..."
      }
    }
  }
}

06 / Full reference

Every endpoint, with examples.

The complete API reference — every endpoint, parameter, auth scope, drop-in alias and a live curl example.

Open the reference →