Migration from Mapbox-style APIs
Move MapLibre and Mapbox-style clients to the implemented Planisfy routes and authentication model.
Migration from Mapbox-style APIs
Planisfy intentionally uses familiar style, tile, and coordinate shapes, but it is not a complete Mapbox API clone. Treat route compatibility as a practical migration layer, not a promise that every Mapbox endpoint or query parameter exists.
URL changes
| Need | Planisfy route |
|---|---|
| Style JSON | /styles/v1/{owner}/{style} |
| Versioned style JSON | /styles/v1/{owner}/{style}@{version} |
| TileJSON | /tiles/v1/{owner}.{tileset}.json or /tiles/v1/{owner}/{tileset}.json |
| Versioned TileJSON | /tiles/v1/{owner}.{tileset}@{version}.json or /tiles/v1/{owner}/{tileset}/versions/{version}.json |
| Vector tile | /tiles/v1/{owner}.{tileset}/{z}/{x}/{y} or /tiles/v1/{owner}/{tileset}/{z}/{x}/{y} |
| Tilequery | /v4/{owner}.{tileset}/tilequery/{lon},{lat}.json |
| Style sprite | /styles/v1/{owner}/{style}/sprite.json, .png, @2x.json, or @2x.png |
| Glyph PBF | /fonts/v1/{fontstack}/{range}.pbf |
| Directions | /directions/v1/{profile}/{lon,lat;lon,lat} |
| Static map | /static/v1/{owner}/{style}/{lon},{lat},{zoom}/{width}x{height}.png |
Authentication changes
Use X-API-Key: pk_... for service APIs. The API middleware validates API keys and authenticated Console sessions. Do not pass Mapbox-style access_token as the primary auth mechanism.
Public published styles, tiles, and glyphs can load anonymously when the resource is public. Private-owner reads and metered service APIs need an API key or session. See authentication and API key management.
Compatibility limits
Tilequery is implemented for PMTiles-backed vector tilesets. Raster tilequery is not supported.
Sprite routes are published only when the style references sprite assets. Styles without sprite assets return 404 Sprite not configured.
Routing profiles are mapped to Valhalla costing. Review directions, isochrone, matrix, and optimized trips before migrating route-heavy clients.
Suggested migration order
- Move style URLs to
/styles/v1/{owner}/{style}. - Confirm glyph and sprite URLs resolve from the published style JSON.
- Move TileJSON and vector tile URLs to
/tiles/v1/*. - Replace
access_tokenusage withX-API-Key. - Migrate geocoding, routing, elevation, and static map calls one service at a time.
- Use error handling and rate limits to update client retries and monitoring.