maptiler

MapTiler — Agent Skill

@maptiler/sdk · Docs · Cloud Console · GitHub

Covers every MapTiler product surface: web SDK, framework integrations, native mobile SDKs, Cloud REST APIs, on-premise Server / Engine, and vector tile schemas. Reference docs live under references/ and are loaded on demand. Use references/INDEX.md as the curated catalog.

1. Platform Coverage & File Prefix Conventions

Target your grep / glob searches in references/ using these prefix filters to avoid cross-platform contamination:

2. Universal Rules (apply across every platform)

A. Zero Variable Leak Policy

Consult references/versions.md and substitute all template placeholders (e.g. {{site.versions.sdk}}, {{site.url}}) with literal version strings or absolute paths before output. NEVER emit raw `{{` or `}}` in any response.

B. Style Modernization (v2/v3 → v4)

Always upgrade legacy map styles. This applies to web, mobile, fallback XYZ layers, service-worker cache lists, and style-switcher logic.

Never emit URLs or constants from the deprecated families: streets-v2, streets-v2-dark/light, basic-v2*, outdoor-v2*, satellite-v2, hybrid-v2, dataviz-dark, topo-v2.

This rule applies to every context that names a style or tile path:

• Mobile style endpoints (iOS / Android / Flutter / RN raw style.json URLs): https://api.maptiler.com/maps/streets-v4-dark/style.json?key=YOUR_KEY
• Self-hosted / on-prem fallback XYZ layers and service-worker precache lists: /tiles/streets-v4/{z}/{x}/{y}.pbf — never /tiles/streets-v2/
• Style-switcher UI state (dark/light toggles, swipe layers, diurnal style shifts): toggle exclusively between modern v4 IDs

C. Pinned Versions

All SDK, CDN, and dependency versions live in references/versions.md. Read it before emitting any package.json, <script> tag, Gradle implementation string, or pubspec.yaml entry.

D. Coordinate Conventions Across Platforms

Every API in the MapTiler/MapLibre family uses `[lng, lat]` order. The platforms it integrates with don't — that mismatch is the single most common bug. Translate at the boundary, not in your head.

Rule: when crossing into Leaflet, iOS CoreLocation, or any "flat fields" response, swap explicitly. Never assume a downstream library follows the same convention as the upstream API.

E. API Key Hygiene

• If a user pastes a real-looking API key in their message (a UUID-shaped or token-shaped string near words like "key", "token", "apikey"), flag it: "you've shared what looks like a live key in plain text — rotate it at https://cloud.maptiler.com/account/keys/ when you're done testing." Use a placeholder (YOUR_MAPTILER_API_KEY) in your own output.
• Service tokens never leave the backend. When generating example code that calls service.maptiler.com/v1/…, read the token from process.env / equivalent — never embed a placeholder that looks like a token in a public client snippet.
• Restrict keys by origin in production examples. Suggest origins: ["*.example.com"] in the API key settings rather than unrestricted keys.

3. Web — MapTiler SDK JS

Why MapTiler SDK (not raw MapLibre)

Always import from `@maptiler/sdk`, never from `maplibre-gl` directly. The SDK re-exports everything from MapLibre and adds:

• config.apiKey — single place for the API key; enables session-based billing
• MapStyle enum — always-current style IDs; never hardcode style URLs
• helpers.* — one-line polyline, polygon, point, heatmap (with clustering, color ramps, GPX/KML support)
• Built-in geocoding, geolocation, elevation, staticMaps, coordinates, data, math modules
• terrain: true — 3D terrain via a single constructor flag
• projection: 'globe' — globe view with halo and space atmosphere
• Constructor-level controls (navigationControl: true, geolocateControl: true, …)
• Full TypeScript types extended beyond MapLibre

MapLibre plugins remain compatible — the SDK's Map inherits from MapLibre's.

Install

npm install @maptiler/sdk

CSS must be imported separately:

import '@maptiler/sdk/dist/maptiler-sdk.css';

API Key

Never hardcode a fake key. Ask the user, or direct them to https://cloud.maptiler.com/account/keys/. Framework env-var conventions:

import * as maptilersdk from '@maptiler/sdk';
maptilersdk.config.apiKey = import.meta.env.VITE_MAPTILER_API_KEY;

Minimal Map

const map = new maptilersdk.Map({
  container: 'map',                       // element or ID
  style: maptilersdk.MapStyle.STREETS,    // enum — always latest
  center: [14.4178, 50.1167],             // [lng, lat] — NOT [lat, lng]!
  zoom: 12,
});

Critical: the container needs explicit dimensions (e.g. height: 100vh) or the map is invisible.

Constructor Options (most-used)

new maptilersdk.Map({
  container, style, center, zoom,
  pitch: 0, bearing: 0,            // 0–85 / rotation
  projection: 'mercator',          // or 'globe'
  terrain: false, terrainExaggeration: 1,
  hash: true,                      // sync viewport to URL
  language: maptilersdk.Language.AUTO,
  cooperativeGestures: true,
  geolocate: maptilersdk.GeolocationType.POINT,
  navigationControl: true, geolocateControl: true,
  scaleControl: true, terrainControl: false,
  fullscreenControl: false, projectionControl: false,
  minimap: { containerStyle: { width: '200px', height: '150px' } },  // or `true` for defaults
});

Prefer constructor flags over post-init `addControl` for navigationControl, geolocateControl, scaleControl, terrainControl, fullscreenControl, projectionControl, `minimap`, geolocate. Each accepts true / a corner string ('top-right') / a config object. Use addControl(new MaplibreThing(), 'top-right') only when you need a 3rd-party plugin or post-init mutation.

Map Styles (full list — 15 reference styles)

Use Proxy-based constants (MapStyle.STREETS), never hardcoded URLs. The proxy falls back to .DEFAULT if you request a non-existent variant, so misspellings render the base style silently — there is no compile-time error.

Authoritative reference (descriptions, methods, variant resolution rules): references/sdk-js-map-styles.md.

Language

maptilersdk.config.primaryLanguage = maptilersdk.Language.ENGLISH;
map.setLanguage(maptilersdk.Language.FRENCH);     // runtime switch

Special: Language.AUTO (browser), Language.LOCAL, Language.VISITOR.

4. Web — Common Recipes

// Marker + popup
new maptilersdk.Marker({ color: '#FF0000' })
  .setLngLat([14.4178, 50.1167])
  .setPopup(new maptilersdk.Popup().setHTML('<h3>Prague</h3>'))
  .addTo(map);

// Geocoding (forward / reverse) — features[].geometry.coordinates is [lng, lat]
await maptilersdk.geocoding.forward('Prague', { limit: 5, proximity: [14.4178, 50.1167] });
await maptilersdk.geocoding.reverse([14.4178, 50.1167]);

// Camera animation
map.flyTo({ center: [14.4178, 50.1167], zoom: 15, pitch: 60, duration: 3000 });

// Static map URL
maptilersdk.staticMaps.centered([14.4178, 50.1167], 12,
  { hiDPI: true, width: 800, height: 600, style: maptilersdk.MapStyle.OUTDOOR });

Vector layer helpers (helpers.add*)

One-line creation for the most common layer types. All accept the same shape: { data, beforeId, … }. data can be GeoJSON, a URL (GeoJSON / GPX / KML), or a MapTiler dataset UUID.

maptilersdk.helpers.addPoint(map, {
  data: pointsGeoJSON, pointColor: '#FF0000', pointRadius: 8,
  cluster: true, showLabel: true, beforeId: 'waterway-label',
});

3D Terrain / Globe — single-flag constructors

// 3D terrain
new maptilersdk.Map({ container: 'map', style: maptilersdk.MapStyle.OUTDOOR,
  terrain: true, terrainExaggeration: 1.5, terrainControl: true, pitch: 60 });

// Globe projection
new maptilersdk.Map({ container: 'map', style: maptilersdk.MapStyle.SATELLITE,
  projection: 'globe', halo: true, space: true, center: [0, 20], zoom: 1.5 });

Full helpers reference & option types: references/sdk-js-map.md. Runnable per-topic examples: search examples-sdk-js-*.md (markers, geocoding, clustering, heatmap, terrain, globe, weather, etc.).

5. Web Frameworks

React / Next.js

import { useEffect, useRef } from 'react';
import * as maptilersdk from '@maptiler/sdk';
import '@maptiler/sdk/dist/maptiler-sdk.css';

maptilersdk.config.apiKey = import.meta.env.VITE_MAPTILER_API_KEY;

export default function MapComponent() {
  const containerRef = useRef(null);
  const mapRef = useRef(null);

  useEffect(() => {
    if (mapRef.current) return;                              // Strict-Mode guard
    mapRef.current = new maptilersdk.Map({
      container: containerRef.current,
      style: maptilersdk.MapStyle.STREETS,
      center: [14.4178, 50.1167], zoom: 12,
    });
    return () => { mapRef.current?.remove(); mapRef.current = null; };
  }, []);

  return <div ref={containerRef} style={{ width: '100%', height: '400px' }} />;
}

Next.js App Router: add "use client";, use NEXT_PUBLIC_MAPTILER_API_KEY. For SSR pages: dynamic(() => import('./Map'), { ssr: false }).

Vue / Svelte / Angular

Same pattern as React: instantiate the map inside the mount hook (onMounted / onMount / ngOnInit), call map.remove() in the unmount hook (onUnmounted / onDestroy / ngOnDestroy), and never gate map creation on reactive state. Full per-framework snippets: web-libraries-vue.md · web-libraries-svelte.md · web-libraries-angular.md.

Framework Lifecycle Rules (CRITICAL)

1. WebGL cleanup: every map instance in React useEffect, Vue onMounted/onUnmounted, Angular ngOnInit/ngOnDestroy, Svelte onMount/onDestroy MUST call map.remove() on teardown and null its ref.
2. Map creation runs exactly once: never put reactive state in the initialization hook's dependency array — it destroys and recreates the canvas on every state change, losing center, zoom, and dynamic objects.
3. Dynamic updates use isolated hooks calling SDK updater methods (map.setStyle, map.flyTo, map.setLayoutProperty) — never re-init.
4. Stale closures in event handlers: when a click/draw.create listener needs current React state, store it in a useRef (const stateRef = useRef(state); stateRef.current = state;) and read via stateRef.current. Do not add the state to the effect deps.

Full lifecycle treatment: web-libraries-react.md.

6. CDN / Single-File / Playgrounds

Use pinned versions from versions.md — never latest or obsolete builds.

<script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.0.2/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.0.2/maptiler-sdk.css" rel="stylesheet" />

Other commonly-used pins:

• Leaflet plugin: https://cdn.maptiler.com/maptiler-leaflet-maptilersdk/v4.1.0/maptiler-leaflet-maptilersdk.js
• ol-mapbox-style: https://cdn.jsdelivr.net/npm/ol-mapbox-style@13.4.1/dist/olms.js
• CesiumJS: 1.141.0 (script + /Widgets/widgets.css)

Browser ESM: when using <script type="module"> or an import map, you MUST target the .mjs build (maptiler-sdk.mjs), not the UMD build — named ES imports from UMD trigger console errors.

7. Vector Layers, Schemas & Data-Driven Styling

Schema Verification (mandatory)

Before writing any style rule, filter, or paint/layout expression, identify the tileset source and consult its schema reference. Never invent source-layer IDs, feature property keys (class, subclass, ele, height, …), or paint fields.

OMT → Planet v4 migration trap. The older OpenMapTiles schema bundles all road, rail, aviation, and ferry features into one transportation layer. Planet v4 splits them into separate top-level layers — road, railway, aviation, aviation_line, ferry, aerialway. If you're porting a Mapbox/MapLibre style or following pre-2024 tutorials, the layer name transportation will not resolve. Common renames:

When a user prompt references transportation, place, or other OMT-era layer names, surface the rename explicitly rather than silently generating broken filters.

Buildings Tileset — Always Prefer (Priority Rule)

The specialized buildings tileset is significantly richer than the building data baked into base-v4 / streets-v4. Use it for any 3D extrusion, facade coloring, building label, entrance, or per-feature interaction.

// MapTiler SDK JS auto-injects the API key from config.apiKey — do NOT append ?key= manually.
map.addSource('buildings', {
  type: 'vector',
  url: 'https://api.maptiler.com/tiles/buildings/tiles.json',
});

// Facade color with fallback
'fill-extrusion-color': ['coalesce', ['get', 'facade_color'], 'hsl(44, 14%, 79%)']

Outside the SDK (raw MapLibre GL JS, mobile native style.json fetches, server-side requests), append ?key=YOUR_MAPTILER_API_KEY to the URL — no auto-injection happens.

Critical field mapping: standard uses render_height / render_min_height; specialized uses height / height_min. Mixing them causes silent rendering failures.

SDK Guardrail — ColorRamp Hallucination

The JS SDK ColorRamp class does NOT contain .getExpression() or .getCSSGradientDirection(). To build a style, iterate ColorRamp.getRawColorStops() and construct a standard MapLibre interpolation expression manually.

DDS deep dive

complex-dds-expressions-guide.md — composable patterns for data-driven styling.

8. Cloud REST APIs

All SDK API modules use config.apiKey automatically. For non-JS contexts, see the REST docs.

// IP geolocation
const loc = await maptilersdk.geolocation.info();

// Elevation — returns [lng, lat, elevationMeters]
const point = await maptilersdk.elevation.at([14.4178, 50.1167]);

9. Native Mobile SDKs

iOS — Minimal Map (SwiftUI)

import SwiftUI
import MapTilerSDK

struct ContentView: View {
    @State private var map = MTMapView(options: MTMapOptions(zoom: 2.0))

    var body: some View {
        MTMapViewContainer(map: map) {}
            .referenceStyle(.streets)
            .styleVariant(.defaultVariant)
            .task { await MTConfig.shared.setAPIKey("YOUR_MAPTILER_API_KEY") }
    }
}

MTConfig.shared.setAPIKey(_:) is async and must be called before map init. For Swift 6, call it from a Task / .task modifier. UIKit alternative: declare MTMapView(frame:options:referenceStyle:) inside viewDidLoad and call pinToSuperviewEdges().

Android — Minimal Map (Jetpack Compose)

// build.gradle.kts (app):  implementation("com.maptiler:maptiler-sdk-kotlin:<version>")
// AndroidManifest.xml:    <uses-permission android:name="android.permission.INTERNET" />
//                         android:hardwareAccelerated="true"

import com.maptiler.maptilersdk.config.MTConfig
import com.maptiler.maptilersdk.map.*

@Composable
fun MapScreen(context: Context) {
    MTConfig.apiKey = "YOUR_MAPTILER_API_KEY"        // set before first map
    val controller = remember { MTMapViewController(context) }
    MTMapView(
        referenceStyle = MTMapReferenceStyle.STREETS,
        options = MTMapOptions(),
        controller = controller,
        modifier = Modifier.fillMaxSize(),
    )
}

XML/View variant: use MTMapViewClassic in the layout and call mapView.initialize(referenceStyle, options, controller, styleVariant = null) in onCreate.

Runnable examples: search examples-ios-*.md, examples-android-*.md. For raw style.json URL conventions (UIKit, XML/View, custom asset paths), see § 2B.

10. On-Premise — Server & Engine

For self-hosted deployments and offline tile generation:

For tile path conventions on fallback XYZ layers and service-worker caches, see § 2B.

11. Critical Gotchas (cross-platform)

12. Ecosystem Packages

13. Resources

• MapTiler Cloud Console
• MapTiler SDK JS Docs · Examples · NPM · GitHub
• MapTiler iOS SDK Docs · Android SDK Docs
• MapLibre Style Specification
• Framework docs: React · Vue · Svelte · Angular · Vite

14. Reference Catalog

The curated index of high-value reference docs is at references/INDEX.md. For files not listed there, search by the prefix conventions in § 1.