Claude Skill

maptiler

Expert coding skill for the full MapTiler platform — Cloud REST APIs, MapTiler SDK JS (built on MapLibre GL JS), native mobile SDKs, on-premise infrastructure, and vector tile schemas. USE WHEN the user wants to add a map to a web or mobile app, show locations or routes, display

LLM Mart · 0 points · 3 views 52 listing impressions 0 install-command copies
Download maptiler-maptiler-skills-skills-3c37eba.zip · 1188 KB

Install

skills CLI npx skills add https://github.com/maptiler/maptiler-skills/tree/main/skills
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install maptiler-maptiler-skills@llmmart
Git git clone https://github.com/maptiler/maptiler-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole maptiler/maptiler-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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:

Target Platform File Name Prefix
Web (Core JS SDK) sdk-js-*, examples-sdk-js-*
Web Frameworks (React, Svelte, Vue, Angular) web-libraries-*, examples-react-*, examples-svelte-*, examples-vuejs-*, examples-angular-*
Web Mapping Engines (Leaflet, OpenLayers, Cesium, deck.gl) examples-leaflet-*, examples-openlayers-*, examples-cesium-*, web-libraries-deck-gl*
Android (Kotlin/Java) mobile-sdks-android-*, examples-android-*
iOS (Swift) mobile-sdks-ios-*, examples-ios-*
Cross-Platform Mobile (Flutter, React Native) mobile-sdks-flutter-*, mobile-sdks-react-native-*
Cloud REST APIs cloud-api-*, cloud-admin-api-*
On-Premise Infrastructure on-prem-*
Vector Tile Schemas map-resources-schemas-*
MapLibre Style Spec map-resources-specifications-*

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.

Legacy Modern Replacement SDK Constant
basic-v2 / streets-v2-light base-v4 MapStyle.BASE
basic-v2-dark base-v4-dark MapStyle.BASE.DARK
streets-v2 streets-v4 MapStyle.STREETS
outdoor-v2 outdoor-v4 MapStyle.OUTDOOR
satellite / satellite-v2 satellite-v4 MapStyle.SATELLITE
hybrid hybrid-v4 MapStyle.HYBRID
dataviz-dark dataviz-v4-dark MapStyle.DATAVIZ.DARK
topo-v2 topo-v4 MapStyle.TOPO

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.

Source Convention When you encounter it
MapTiler SDK JS / MapLibre / Mapbox [lng, lat] array All web SDK code (center, marker, source coordinates, expressions)
GeoJSON spec [lng, lat] (or [lng, lat, ele]) Every geometry.coordinates value
MapTiler REST URLs {lng},{lat} in the path /geocoding/{lng},{lat}.json, /elevation/dataset/{lng},{lat}.json, static maps /static/{lng},{lat},{zoom}/…
Leaflet (lat, lng) — reversed L.map().setView([lat, lng], z), L.marker([lat, lng]), L.latLng(lat, lng)
iOS CLLocationCoordinate2D (latitude:, longitude:) — reversed at the struct level Apple CoreLocation. When building a MapTiler URL: c.longitude, c.latitude
Android LatLng / LngLat MapTiler Android SDK uses LngLat(lng, lat); system Location exposes latitude/longitude as flat properties Match the SDK type, not the system type
MapTiler Geolocation API response Flat fields latitude / longitude (not a pair) Construct [loc.longitude, loc.latitude] before passing to any SDK call

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:

Tool Env var
Vite VITE_MAPTILER_API_KEY
Next.js NEXT_PUBLIC_MAPTILER_API_KEY
CRA REACT_APP_MAPTILER_API_KEY
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)

Style Purpose Variants
MapStyle.STREETS Comprehensive street map .DARK, .PASTEL
MapStyle.SATELLITE Beautiful satellite map .DARK
MapStyle.HYBRID Beautiful satellite map with context .DARK
MapStyle.OUTDOOR Map for hiking and sports .DARK
MapStyle.WINTER Map for winter activities .DARK
MapStyle.TOPO General-purpose topographic map .DARK, .PASTEL, .TOPOGRAPHIQUE
MapStyle.DATAVIZ Simple data visualization map .DARK, .LIGHT
MapStyle.BASE Clear general-purpose map .DARK, .LIGHT
MapStyle.BRIGHT Shiny map for context or navigation .DARK, .LIGHT, .PASTEL
MapStyle.BACKDROP Monochrome context map .DARK, .LIGHT
MapStyle.AQUARELLE Artistic watercolor map .DARK, .VIVID
MapStyle.LANDSCAPE Light hillshade map .DARK, .VIVID
MapStyle.OCEAN Seabed and bathymetry map .DARK
MapStyle.OPENSTREETMAP Rich, familiar OSM community style .DARK
MapStyle.TONER Contrasted monochrome map .LITE

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.

Helper Key options
addPolyline lineColor, lineWidth, outline
addPolygon fillColor, fillOpacity, outlineColor
addPoint pointColor, pointRadius, cluster, showLabel
addHeatmap colorRamp (ColorRamp.*), property, radius, opacity
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:

OMT (old) Planet v4 (current)
transportation (class: motorway/primary/.../residential) road (class: motorway/trunk/primary/secondary/tertiary/minor/service/...); no residential class — use minor or service
transportation_name road_label
(none — bundled) railway, aviation, ferry, aerialway as separate layers
place country_label, city_label, island_label, continent_label (hierarchy split)

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

Schema Reference
Planet v4 (latest) map-resources-schemas-planet-v4.md
OpenMapTiles Planet map-resources-schemas-omt-planet.md
Planet Lite map-resources-schemas-planet-lite.md
Buildings map-resources-schemas-buildings.md
Contours / Outdoor / Ocean contours, outdoor, ocean
Landcover / Landform / Cadastre landcover, landform, cadastre
Style spec (layers / sources / expressions / root) layers, sources, expressions, root

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.

Concern Standard (maptiler_planet_v4) Specialized (buildings)
Height fields render_height, render_min_height height, height_min
Colors — facade_color, roof_color
Shape — roof_shape
Labels — building_label (names, ISO 639 translations)
Entrances — building_entrance
Unique IDs False True (z14+) — usable with setFeatureState
// 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.

Module Purpose Key Methods / Reference
geocoding Place search, reverse forward(), reverse(), batch() — cloud-api-geocoding.md
geolocation IP visitor location info() — cloud-api-geolocation.md
elevation Altitude lookup at(), batch(), fromLineString() — cloud-api-elevation.md
staticMaps Static map images centered(), bounded(), automatic() — cloud-api-static-maps.md
coordinates CRS / EPSG transform search(), transform() — cloud-api-coordinates.md
data MapTiler datasets get(uuid) — cloud-api-data.md
weather Wind, temp, pressure, radar cloud-api-weather.md
maps (Vector/Raster) Tilesets, styles cloud-api-maps.md
tiles Raw tile endpoints cloud-api-tiles.md
fonts / images / ogc Misc fonts, images, ogc
Admin (tilesets, uploads, keys, analytics) Account management cloud-admin-api-tilesets.md, api-keys, analytics
Auth Key-vs-token, referrer rules cloud-api-authentication.md
// 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

Platform Overview API Reference
iOS (Swift) mobile-sdks-ios.md mobile-sdks-ios-api-classes.md
Android (Kotlin) mobile-sdks-android.md mobile-sdks-android-api-com-maptiler-maptilersdk-map.md
Flutter mobile-sdks-flutter.md search mobile-sdks-flutter-*.md
React Native mobile-sdks-react-native.md search mobile-sdks-react-native-*.md

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:

Topic Reference
MapTiler Server — Getting Started on-prem-server-getting-started.md
Hosting Data on-prem-server-hosting-data.md
Virtual Tilesets on-prem-server-virtual-tilesets.md
Map Styling on Server on-prem-server-map-styling.md
On-Premise Geocoding on-prem-server-geocoding.md
Engine CLI — Getting Started on-prem-engine-getting-started-cli.md
Engine — Input / Output Options input, output

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


11. Critical Gotchas (cross-platform)

Problem Fix
Map invisible (web) Container needs explicit height (100vh or position: absolute; inset: 0)
Markers / map center on the wrong continent Coordinates are [lng, lat], not [lat, lng] (e.g. Prague is [14.4178, 50.1167], not [50.1167, 14.4178])
Layers vanish after setStyle() Re-add inside map.once('styledata', …)
Data covers labels Use beforeId: 'waterway-label'
Slow with many points Enable cluster: true (helpers or source)
SPA memory leak Always call map.remove() on unmount; null the ref
Importing maplibre-gl separately Use @maptiler/sdk — it includes and extends MapLibre
Map re-creates on every state change (React) Empty useEffect deps; mutate via setX methods, not re-init
Stale closures in handlers Use a useRef mirror of state, read .current
Browser ESM script error Use .mjs build, not UMD, with <script type="module">
Mobile rendering 3D buildings looks flat You loaded the standard style — add the specialized buildings source
Style 404s on mobile Update endpoint from streets-v2 family to streets-v4 family
Geocoding key 403 Verify referrer/whitelist in the key settings (cloud-api-authentication.md)
{{ }} leaking into output Resolve via versions.md before emitting
MapTiler Engine refuses to start The -o output_dir (or -o file.mbtiles) target must not already exist. Delete it, or pick a new path. No -f / --force flag
iOS app produces 403s on every tile MTConfig.shared.setAPIKey(_:) is async and was called without await — set it inside a Task { … } or SwiftUI .task modifier before the first map view appears
mapbox-gl-draw cursors / hit-test broken Plugin CSS targets .mapboxgl-canvas; MapTiler/MapLibre uses .maplibregl-canvas. Add fallback rules: .maplibregl-canvas.mouse-add { cursor: crosshair } and .maplibregl-canvas.mouse-drag { cursor: grabbing }
User pastes a live API key in chat Flag it (rotate at the Cloud Console) and use a YOUR_MAPTILER_API_KEY placeholder in your own output — never echo a real key back
Inventing addControl(new XControl()) patterns Many MapTiler controls live as constructor flags: minimap, navigationControl, geolocateControl, scaleControl, terrainControl, fullscreenControl, projectionControl. Use the flag first; only reach for addControl for 3rd-party plugins or post-init changes
Hallucinated SDK class names (MinimapControl, GeocodingBar, …) Cross-reference references/sdk-js-controls.md and sdk-js-map.md before emitting a class name. The canonical minimap class is MaptilerMinimapControl (Maptiler prefix), and the constructor option is the preferred path anyway
GeoSplats rendering fails / blank model GeoSplats SDK requires WebGPU support. Always verify browser compatibility (navigator.gpu) and provide a clear UI fallback error overlay

12. Ecosystem Packages

Package Purpose
@maptiler/geosplats High-performance 3D Gaussian Splatting (WebGPU-powered)
@maptiler/geocoding-control Address-search bar UI
@maptiler/weather Wind, temperature, pressure, radar layers (60 fps)
@maptiler/3d glTF / GLB 3D model placement
@maptiler/elevation-profile Elevation chart for routes
@maptiler/marker-layout Non-colliding DOM marker overlay
@maptiler/ar Augmented-reality 3D terrain
@maptiler/client Headless API client (Node.js / browser, no map)

13. Resources


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.

Files (maptiler-skills)
  • references
    • cloud-admin-api-analytics.md 2.6 KB
      Loading…
    • cloud-admin-api-api-keys.md 2.4 KB
      Loading…
    • cloud-admin-api-index.md 1.2 KB
      Loading…
    • cloud-admin-api-tilesets.md 3 KB
      Loading…
    • cloud-api-authentication.md 2 KB
      Loading…
    • cloud-api-coordinates.md 3.7 KB
      Loading…
    • cloud-api-data.md 976 B
      Loading…
    • cloud-api-elevation.md 1.4 KB
      Loading…
    • cloud-api-fonts.md 1.1 KB
      Loading…
    • cloud-api-geocoding.md 14.7 KB
      Loading…
    • cloud-api-geolocation.md 2.4 KB
      Loading…
    • cloud-api-images.md 2.2 KB
      Loading…
    • cloud-api-index.md 3.9 KB
      Loading…
    • cloud-api-maps.md 3.5 KB
      Loading…
    • cloud-api-ogc.md 2 KB
      Loading…
    • cloud-api-static-maps.md 9.1 KB
      Loading…
    • cloud-api-tiles.md 2.5 KB
      Loading…
    • cloud-api-weather.md 3.4 KB
      Loading…
    • complex-dds-expressions-guide.md 3 KB
      Loading…
    • examples-android-3d-terrain.md 2.3 KB
      Loading…
    • examples-android-add-data.md 5 KB
      Loading…
    • examples-android-cluster.md 6.6 KB
      Loading…
    • examples-android-controls.md 2.7 KB
      Loading…
    • examples-android-custom-annotations.md 4.9 KB
      Loading…
    • examples-android-fly-to.md 6.9 KB
      Loading…
    • examples-android-get-started.md 5.1 KB
      Loading…
    • examples-android-globe.md 2.5 KB
      Loading…
    • examples-android-heatmap-helper.md 3 KB
      Loading…
    • examples-android-point-helper-cluster.md 3.2 KB
      Loading…
    • examples-android-point-helper.md 3.2 KB
      Loading…
    • examples-android-polygon-helper.md 1.9 KB
      Loading…
    • examples-android-polyline-helper.md 2.3 KB
      Loading…
    • examples-android-satellite.md 2.3 KB
      Loading…
    • examples-android-switch-from-mapbox.md 6.9 KB
      Loading…
    • examples-android-switch-from-maplibre.md 7.4 KB
      Loading…
    • examples-angular-maplibre-get-started.md 2 KB
      Loading…
    • examples-angular-sdk-get-started.md 16.2 KB
      Loading…
    • examples-cesium-how-to-use-cesium.md 14 KB
      Loading…
    • examples-ios-3d-terrain.md 1.6 KB
      Loading…
    • examples-ios-add-data.md 3.6 KB
      Loading…
    • examples-ios-build-mac-app.md 4.4 KB
      Loading…
    • examples-ios-cluster.md 4.4 KB
      Loading…
    • examples-ios-controls.md 2 KB
      Loading…
    • examples-ios-custom-annotations.md 6.7 KB
      Loading…
    • examples-ios-custom-style.md 2.3 KB
      Loading…
    • examples-ios-fly-to.md 5 KB
      Loading…
    • examples-ios-get-started.md 5.8 KB
      Loading…
    • examples-ios-globe.md 1.5 KB
      Loading…
    • examples-ios-heatmap-helper.md 2.1 KB
      Loading…
    • examples-ios-point-helper-cluster.md 2.2 KB
      Loading…
    • examples-ios-point-helper.md 2.2 KB
      Loading…
    • examples-ios-polygon-helper.md 1.4 KB
      Loading…
    • examples-ios-polyline-helper.md 1.7 KB
      Loading…
    • examples-ios-satellite.md 1.6 KB
      Loading…
    • examples-ios-sources-layers.md 9.2 KB
      Loading…
    • examples-ios-switch-from-mapbox.md 8.5 KB
      Loading…
    • examples-ios-switch-from-maplibre.md 9 KB
      Loading…
    • examples-leaflet-choropleth-geojson.md 12.8 KB
      Loading…
    • examples-leaflet-cluster.md 3.4 KB
      Loading…
    • examples-leaflet-custom-map.md 2.8 KB
      Loading…
    • examples-leaflet-custom-marker.md 2.9 KB
      Loading…
    • examples-leaflet-default-marker.md 2.3 KB
      Loading…
    • examples-leaflet-detect-retina.md 2.4 KB
      Loading…
    • examples-leaflet-geocoding-control.md 3.5 KB
      Loading…
    • examples-leaflet-geojson-polygon.md 5.7 KB
      Loading…
    • examples-leaflet-geolocate-user.md 1.9 KB
      Loading…
    • examples-leaflet-get-started.md 449 B
      Loading…
    • examples-leaflet-helpers-heatmap.md 2.3 KB
      Loading…
    • examples-leaflet-helpers-point.md 3 KB
      Loading…
    • examples-leaflet-helpers-polygon.md 4.1 KB
      Loading…
    • examples-leaflet-helpers-polyline.md 3.5 KB
      Loading…
    • examples-leaflet-how-to-use-leaflet.md 4 KB
      Loading…
    • examples-leaflet-map-events.md 7.1 KB
      Loading…
    • examples-leaflet-map-language.md 2.3 KB
      Loading…
    • examples-leaflet-map-style.md 3.2 KB
      Loading…
    • examples-leaflet-map-with-pins.md 2.9 KB
      Loading…
    • examples-leaflet-nextjs.md 8.6 KB
      Loading…
    • examples-leaflet-npm-get-started.md 3.8 KB
      Loading…
    • examples-leaflet-raster-layer.md 2.8 KB
      Loading…
    • examples-leaflet-raster-tiles-in-leaflet-js.md 2.8 KB
      Loading…
    • examples-leaflet-react.md 8.4 KB
      Loading…
    • examples-leaflet-ts-get-started.md 2.6 KB
      Loading…
    • examples-leaflet-vector-tiles-in-leaflet-js.md 5.3 KB
      Loading…
    • examples-leaflet-vite-vanilla-js-default.md 3.7 KB
      Loading…
    • examples-leaflet-vite-vanilla-js-named.md 3.9 KB
      Loading…
    • examples-openlayers-choropleth-geojson.md 20.4 KB
      Loading…
    • examples-openlayers-custom-map.md 3 KB
      Loading…
    • examples-openlayers-default-marker.md 4.8 KB
      Loading…
    • examples-openlayers-geocoding-control.md 4.1 KB
      Loading…
    • examples-openlayers-geojson-multigeometry.md 14.7 KB
      Loading…
    • examples-openlayers-geojson-points.md 5.7 KB
      Loading…
    • examples-openlayers-geojson-polygon.md 5.4 KB
      Loading…
    • examples-openlayers-get-started.md 473 B
      Loading…
    • examples-openlayers-how-to-use-openlayers.md 9 KB
      Loading…
    • examples-openlayers-raster-layer.md 4.2 KB
      Loading…
    • examples-openlayers-raster-tiles-in-openlayers.md 8.5 KB
      Loading…
    • examples-openlayers-vector-tiles-in-openlayers.md 2 KB
      Loading…
    • examples-openlayers-vector-tiles-with-polygon-from-geojson.md 3 KB
      Loading…
    • examples-openlayers-wmts.md 6.9 KB
      Loading…
    • examples-react-maplibre-geocoding.md 4.3 KB
      Loading…
    • examples-react-maplibre-get-started.md 2.1 KB
      Loading…
    • examples-react-sdk-3d-map.md 7.2 KB
      Loading…
    • examples-react-sdk-geocoding-component.md 4 KB
      Loading…
    • examples-react-sdk-geocoding-control.md 5.9 KB
      Loading…
    • examples-react-sdk-geojson-points.md 9.6 KB
      Loading…
    • examples-react-sdk-get-started.md 12.8 KB
      Loading…
    • examples-react-sdk-heatmap.md 9.5 KB
      Loading…
    • examples-react-sdk-material-ui.md 14.7 KB
      Loading…
    • examples-react-sdk-popup-sidebar.md 30.6 KB
      Loading…
    • examples-sdk-js-3d-buildings.md 5.1 KB
      Loading…
    • examples-sdk-js-3d-extrusion-floorplan.md 4 KB
      Loading…
    • examples-sdk-js-3d-js-animated-flight.md 12.4 KB
      Loading…
    • examples-sdk-js-3d-js-animated.md 4.5 KB
      Loading…
    • examples-sdk-js-3d-js-cinematic-path.md 25.6 KB
      Loading…
    • examples-sdk-js-3d-js-events.md 11.7 KB
      Loading…
    • examples-sdk-js-3d-js-flight.md 5.8 KB
      Loading…
    • examples-sdk-js-3d-js-get-started.md 6.3 KB
      Loading…
    • examples-sdk-js-3d-js-intersections.md 10.8 KB
      Loading…
    • examples-sdk-js-3d-js-model-interaction.md 14 KB
      Loading…
    • examples-sdk-js-3d-js-multi.md 9.7 KB
      Loading…
    • examples-sdk-js-3d-js-pitch.md 5.7 KB
      Loading…
    • examples-sdk-js-3d-js-plane.md 7.1 KB
      Loading…
    • examples-sdk-js-3d-js-point-cad.md 7.2 KB
      Loading…
    • examples-sdk-js-3d-js-point-cloud-dundee.md 5 KB
      Loading…
    • examples-sdk-js-3d-js-point-cloud-lidar.md 5 KB
      Loading…
    • examples-sdk-js-3d-js-point-cloud-nmh.md 5.3 KB
      Loading…
    • examples-sdk-js-3d-js-position-relative.md 10.5 KB
      Loading…
    • examples-sdk-js-3d-js-roll-pitch.md 10.1 KB
      Loading…
    • examples-sdk-js-3d-js-roll.md 5.7 KB
      Loading…
    • examples-sdk-js-3d-map.md 2.8 KB
      Loading…
    • examples-sdk-js-add-3d-model-babylon.md 8.6 KB
      Loading…
    • examples-sdk-js-add-3d-model-terrain.md 13.1 KB
      Loading…
    • examples-sdk-js-add-3d-model.md 8.6 KB
      Loading…
    • examples-sdk-js-add-image-animated.md 8 KB
      Loading…
    • examples-sdk-js-add-image-generated.md 4.2 KB
      Loading…
    • examples-sdk-js-add-image-missing-generated.md 6.9 KB
      Loading…
    • examples-sdk-js-add-image-stretchable.md 11.3 KB
      Loading…
    • examples-sdk-js-add-image.md 3 KB
      Loading…
    • examples-sdk-js-add-map.md 1.8 KB
      Loading…
    • examples-sdk-js-animate-a-line.md 7.9 KB
      Loading…
    • examples-sdk-js-animate-camera-around-point.md 5.3 KB
      Loading…
    • examples-sdk-js-animate-images.md 3.3 KB
      Loading…
    • examples-sdk-js-animate-marker.md 2.7 KB
      Loading…
    • examples-sdk-js-animate-point-along-line.md 3.7 KB
      Loading…
    • examples-sdk-js-animate-point-along-route.md 11.3 KB
      Loading…
    • examples-sdk-js-animated-route.md 27.1 KB
      Loading…
    • examples-sdk-js-ar-control-custom.md 3.6 KB
      Loading…
    • examples-sdk-js-ar-control-geojson-line.md 4.4 KB
      Loading…
    • examples-sdk-js-ar-control-no-button.md 3.7 KB
      Loading…
    • examples-sdk-js-ar-control-qr.md 3.5 KB
      Loading…
    • examples-sdk-js-ar-control.md 3.2 KB
      Loading…
    • examples-sdk-js-attribution-position.md 1.4 KB
      Loading…
    • examples-sdk-js-built-in-styles.md 5.4 KB
      Loading…
    • examples-sdk-js-cadastre.md 7.8 KB
      Loading…
    • examples-sdk-js-camera-animation.md 6.5 KB
      Loading…
    • examples-sdk-js-canvas-source.md 2.6 KB
      Loading…
    • examples-sdk-js-center-on-symbol.md 7 KB
      Loading…
    • examples-sdk-js-change-building-color-based-on-zoom-level.md 2.6 KB
      Loading…
    • examples-sdk-js-change-case-of-labels.md 3.5 KB
      Loading…
    • examples-sdk-js-change-map-styles.md 5.1 KB
      Loading…
    • examples-sdk-js-choropleth-geojson.md 10.8 KB
      Loading…
    • examples-sdk-js-cluster-html.md 17.2 KB
      Loading…
    • examples-sdk-js-cluster.md 10.5 KB
      Loading…
    • examples-sdk-js-color-ramp-custom.md 2.9 KB
      Loading…
    • examples-sdk-js-color-ramp-resample.md 4.8 KB
      Loading…
    • examples-sdk-js-color-switcher.md 2.6 KB
      Loading…
    • examples-sdk-js-contour-lines.md 7.5 KB
      Loading…
    • examples-sdk-js-contour-meter-feet.md 3.8 KB
      Loading…
    • examples-sdk-js-control-legend-choropleth.md 33.4 KB
      Loading…
    • examples-sdk-js-control-legend.md 5 KB
      Loading…
    • examples-sdk-js-control-minimap.md 1.8 KB
      Loading…
    • examples-sdk-js-control-scale.md 3.8 KB
      Loading…
    • examples-sdk-js-control-style-switcher.md 11.9 KB
      Loading…
    • examples-sdk-js-cooperative-gestures.md 1.5 KB
      Loading…
    • examples-sdk-js-countries-filter.md 9.6 KB
      Loading…
    • examples-sdk-js-countries-with-own-data.md 19.8 KB
      Loading…
    • examples-sdk-js-custom-control-compass-rose.md 1.5 KB
      Loading…
    • examples-sdk-js-custom-control.md 3.8 KB
      Loading…
    • examples-sdk-js-custom-controls-declarative.md 2.8 KB
      Loading…
    • examples-sdk-js-custom-controls-programmatic.md 8.7 KB
      Loading…
    • examples-sdk-js-custom-map.md 2.7 KB
      Loading…
    • examples-sdk-js-custom-marker-icons.md 2.9 KB
      Loading…
    • examples-sdk-js-custom-points-icon-png.md 3.1 KB
      Loading…
    • examples-sdk-js-custom-points-icon-svg.md 4.9 KB
      Loading…
    • examples-sdk-js-custom-style-layer.md 8.5 KB
      Loading…
    • examples-sdk-js-data-driven-lines.md 9.4 KB
      Loading…
    • examples-sdk-js-default-marker.md 2.8 KB
      Loading…
    • examples-sdk-js-disable-rotation.md 1.6 KB
      Loading…
    • examples-sdk-js-disable-scroll-zoom.md 1.4 KB
      Loading…
    • examples-sdk-js-display-and-style-rich-text-labels.md 2.4 KB
      Loading…
    • examples-sdk-js-drag-a-marker.md 2.1 KB
      Loading…
    • examples-sdk-js-drag-a-point.md 6.5 KB
      Loading…
    • examples-sdk-js-dynamic-hillshade.md 2 KB
      Loading…
    • examples-sdk-js-election-map-usa.md 45.8 KB
      Loading…
    • examples-sdk-js-elevation-at.md 2.6 KB
      Loading…
    • examples-sdk-js-elevation-profile-control-customized.md 8.9 KB
      Loading…
    • examples-sdk-js-elevation-profile-control-gpx.md 12.4 KB
      Loading…
    • examples-sdk-js-elevation-profile-control-marker.md 7.3 KB
      Loading…
    • examples-sdk-js-elevation-profile-control-simple.md 6.6 KB
      Loading…
    • examples-sdk-js-elevation-profile-control-zoomed-section.md 8.1 KB
      Loading…
    • examples-sdk-js-event-ready.md 2.2 KB
      Loading…
    • examples-sdk-js-fallback-image.md 6 KB
      Loading…
    • examples-sdk-js-fill-extrusion.md 4.5 KB
      Loading…
    • examples-sdk-js-fill-pattern.md 4.1 KB
      Loading…
    • examples-sdk-js-filter-markers-by-input.md 5 KB
      Loading…
    • examples-sdk-js-filter-markers.md 4.6 KB
      Loading…
    • examples-sdk-js-filter-within-layer.md 5.8 KB
      Loading…
    • examples-sdk-js-fitbounds.md 1.7 KB
      Loading…
    • examples-sdk-js-flyto-options.md 3.6 KB
      Loading…
    • examples-sdk-js-flyto.md 2.2 KB
      Loading…
    • examples-sdk-js-fullscreen.md 1.2 KB
      Loading…
    • examples-sdk-js-game-controls.md 4.3 KB
      Loading…
    • examples-sdk-js-geocoder-component.md 4.1 KB
      Loading…
    • examples-sdk-js-geocoding-adjusturl.md 3 KB
      Loading…
    • examples-sdk-js-geocoding-filter-bbox.md 2.2 KB
      Loading…
    • examples-sdk-js-geocoding-filter-country.md 2.3 KB
      Loading…
    • examples-sdk-js-geocoding-filter-draw-bbox.md 4.9 KB
      Loading…
    • examples-sdk-js-geocoding-filter-proximity.md 2.8 KB
      Loading…
    • examples-sdk-js-geocoding-filter-types.md 3 KB
      Loading…
    • examples-sdk-js-geocoding-language.md 3.8 KB
      Loading…
    • examples-sdk-js-geocoding-reverse-json.md 5.5 KB
      Loading…
    • examples-sdk-js-geocoding-reverse.md 2.4 KB
      Loading…
    • examples-sdk-js-geocoding-vanilla-js.md 5.6 KB
      Loading…
    • examples-sdk-js-geocoding.md 5.8 KB
      Loading…
    • examples-sdk-js-geojson-layer-in-stack.md 4.4 KB
      Loading…
    • examples-sdk-js-geojson-line.md 4.5 KB
      Loading…
    • examples-sdk-js-geojson-markers.md 13.9 KB
      Loading…
    • examples-sdk-js-geojson-multigeometry.md 9.3 KB
      Loading…
    • examples-sdk-js-geojson-point.md 5.3 KB
      Loading…
    • examples-sdk-js-geojson-polygon.md 4.7 KB
      Loading…
    • examples-sdk-js-geolocate-control.md 2.9 KB
      Loading…
    • examples-sdk-js-globe-3d-model-animated.md 6.9 KB
      Loading…
    • examples-sdk-js-globe-3d-model.md 5.3 KB
      Loading…
    • examples-sdk-js-globe-bathymetry.md 2.8 KB
      Loading…
    • examples-sdk-js-globe-control.md 2.6 KB
      Loading…
    • examples-sdk-js-globe-marker-layout-weather.md 20.2 KB
      Loading…
    • examples-sdk-js-globe-marker-layout.md 10.8 KB
      Loading…
    • examples-sdk-js-globe-projection-switch.md 2.7 KB
      Loading…
    • examples-sdk-js-globe-projection.md 2.1 KB
      Loading…
    • examples-sdk-js-globe-terrain.md 2.4 KB
      Loading…
    • examples-sdk-js-halo-custom.md 2.3 KB
      Loading…
    • examples-sdk-js-halo-simple.md 1.8 KB
      Loading…
    • examples-sdk-js-halo-space-night.md 6.3 KB
      Loading…
    • examples-sdk-js-hash.md 2.7 KB
      Loading…
    • examples-sdk-js-heatmap-animated.md 11.8 KB
      Loading…
    • examples-sdk-js-heatmap-layer.md 9.8 KB
      Loading…
    • examples-sdk-js-helper-heatmap-color-ramp.md 2 KB
      Loading…
    • examples-sdk-js-helper-heatmap-intensity.md 2 KB
      Loading…
    • examples-sdk-js-helper-heatmap-min-max-zoom.md 2.1 KB
      Loading…
    • examples-sdk-js-helper-heatmap-minimal.md 2.3 KB
      Loading…
    • examples-sdk-js-helper-heatmap-no-zoom-compensation.md 2.5 KB
      Loading…
    • examples-sdk-js-helper-heatmap-opacity.md 2.4 KB
      Loading…
    • examples-sdk-js-helper-heatmap-radius-weight-property.md 2.7 KB
      Loading…
    • examples-sdk-js-helper-heatmap-ramped-radius-property.md 2.2 KB
      Loading…
    • examples-sdk-js-helper-heatmap-ramped-radius.md 2.3 KB
      Loading…
    • examples-sdk-js-helper-heatmap-weight.md 2.4 KB
      Loading…
    • examples-sdk-js-helper-point-cluster.md 2.6 KB
      Loading…
    • examples-sdk-js-helper-point-label.md 2.2 KB
      Loading…
    • examples-sdk-js-helper-point-min-max-radius.md 2.4 KB
      Loading…
    • examples-sdk-js-helper-point-minimal.md 1.8 KB
      Loading…
    • examples-sdk-js-helper-point-no-zoom-compensation.md 2.5 KB
      Loading…
    • examples-sdk-js-helper-point-outline.md 3.2 KB
      Loading…
    • examples-sdk-js-helper-point-property-style.md 2.2 KB
      Loading…
    • examples-sdk-js-helper-point-ramped-property.md 2.6 KB
      Loading…
    • examples-sdk-js-helper-point-ramped-radius.md 2.2 KB
      Loading…
    • examples-sdk-js-helper-polygon-minimal.md 1.9 KB
      Loading…
    • examples-sdk-js-helper-polygon-pattern.md 2.3 KB
      Loading…
    • examples-sdk-js-helper-polygon-ramped-style.md 4 KB
      Loading…
    • examples-sdk-js-helper-polyline-blur.md 2.8 KB
      Loading…
    • examples-sdk-js-helper-polyline-dash-array.md 2.2 KB
      Loading…
    • examples-sdk-js-helper-polyline-gpx.md 1.8 KB
      Loading…
    • examples-sdk-js-helper-polyline-kml.md 1.9 KB
      Loading…
    • examples-sdk-js-helper-polyline-minimal.md 2 KB
      Loading…
    • examples-sdk-js-helper-polyline-ramped-style.md 3.8 KB
      Loading…
    • examples-sdk-js-helper-polyline-simple.md 2.3 KB
      Loading…
    • examples-sdk-js-helper-screenshot-download.md 2.1 KB
      Loading…
    • examples-sdk-js-helper-screenshot-feedback.md 10.9 KB
      Loading…
    • examples-sdk-js-helper-screenshot-usersnap.md 8.1 KB
      Loading…
    • examples-sdk-js-helper-screenshot-ybug.md 7.7 KB
      Loading…
    • examples-sdk-js-helper-screenshot.md 2.9 KB
      Loading…
    • examples-sdk-js-hillshade.md 2.2 KB
      Loading…
    • examples-sdk-js-hover-styles.md 6.2 KB
      Loading…
    • examples-sdk-js-how-to-use.md 5.4 KB
      Loading…
    • examples-sdk-js-image-viewer-marker.md 2.7 KB
      Loading…
    • examples-sdk-js-image-viewer.md 2.4 KB
      Loading…
    • examples-sdk-js-interactive-choropleth.md 8.3 KB
      Loading…
    • examples-sdk-js-interactive-false.md 2.1 KB
      Loading…
    • examples-sdk-js-ip-center-map.md 3 KB
      Loading…
    • examples-sdk-js-ip-cookie-bar.md 6.3 KB
      Loading…
    • examples-sdk-js-ip-country-map.md 3.4 KB
      Loading…
    • examples-sdk-js-ip-disputed-borders.md 6.6 KB
      Loading…
    • examples-sdk-js-ip-map-language.md 4 KB
      Loading…
    • examples-sdk-js-jump-to.md 1.8 KB
      Loading…
    • examples-sdk-js-landmarks-interactions.md 5.5 KB
      Loading…
    • examples-sdk-js-language-map.md 4.5 KB
      Loading…
    • examples-sdk-js-language-switch.md 1.9 KB
      Loading…
    • examples-sdk-js-line-across-180th-meridian.md 7 KB
      Loading…
    • examples-sdk-js-line-gradient.md 6.7 KB
      Loading…
    • examples-sdk-js-list-of-places.md 27.8 KB
      Loading…
    • examples-sdk-js-live-geojson.md 5.1 KB
      Loading…
    • examples-sdk-js-live-update-feature.md 5.4 KB
      Loading…
    • examples-sdk-js-local-geojson-experimental.md 5.7 KB
      Loading…
    • examples-sdk-js-local-geojson.md 4.1 KB
      Loading…
    • examples-sdk-js-local-ideographs.md 2.1 KB
      Loading…
    • examples-sdk-js-map-terrain.md 5.1 KB
      Loading…
    • examples-sdk-js-map-tiles.md 1.5 KB
      Loading…
    • examples-sdk-js-mapbox-gl-draw.md 4.1 KB
      Loading…
    • examples-sdk-js-maptiler-animation.md 9.5 KB
      Loading…
    • examples-sdk-js-marker-layout-basic.md 9.9 KB
      Loading…
    • examples-sdk-js-marker-layout-many.md 11.2 KB
      Loading…
    • examples-sdk-js-marker-layout-weather.md 18.8 KB
      Loading…
    • examples-sdk-js-measure.md 8.4 KB
      Loading…
    • examples-sdk-js-mobile-pwa.md 2.1 KB
      Loading…
    • examples-sdk-js-mouse-position.md 2.1 KB
      Loading…
    • examples-sdk-js-move-marker.md 2.3 KB
      Loading…
    • examples-sdk-js-navigation.md 2.7 KB
      Loading…
    • examples-sdk-js-ocean-bathymetry.md 2 KB
      Loading…
    • examples-sdk-js-offset-vanishing-point-with-padding.md 3.8 KB
      Loading…
    • examples-sdk-js-point-filtering.md 9.4 KB
      Loading…
    • examples-sdk-js-pois-info.md 15.9 KB
      Loading…
    • examples-sdk-js-polygon-popup-on-click.md 4.4 KB
      Loading…
    • examples-sdk-js-popup-on-click.md 20.3 KB
      Loading…
    • examples-sdk-js-popup-on-hover.md 17.3 KB
      Loading…
    • examples-sdk-js-popup.md 1.5 KB
      Loading…
    • examples-sdk-js-queryrenderedfeatures.md 3 KB
      Loading…
    • examples-sdk-js-raster-layer.md 4.5 KB
      Loading…
    • examples-sdk-js-render-world-copies.md 2.2 KB
      Loading…
    • examples-sdk-js-restrict-bounds.md 1.3 KB
      Loading…
    • examples-sdk-js-reverse-geocoding.md 7.9 KB
      Loading…
    • examples-sdk-js-rich-text-format.md 5.2 KB
      Loading…
    • examples-sdk-js-satellite-map.md 1.7 KB
      Loading…
    • examples-sdk-js-scroll-fly-to.md 6 KB
      Loading…
    • examples-sdk-js-set-perspective.md 1.3 KB
      Loading…
    • examples-sdk-js-set-popup.md 2.2 KB
      Loading…
    • examples-sdk-js-sky-fog-terrain.md 5.5 KB
      Loading…
    • examples-sdk-js-space-milkyway-halo.md 3 KB
      Loading…
    • examples-sdk-js-space-milkyway.md 2.2 KB
      Loading…
    • examples-sdk-js-space-simple-color.md 1.8 KB
      Loading…
    • examples-sdk-js-space-simple.md 1.8 KB
      Loading…
    • examples-sdk-js-style-by-daytime.md 2.7 KB
      Loading…
    • examples-sdk-js-style-by-settings.md 2.3 KB
      Loading…
    • examples-sdk-js-style-by-tunnel.md 13.7 KB
      Loading…
    • examples-sdk-js-switch-from-mapbox.md 13.1 KB
      Loading…
    • examples-sdk-js-switch-from-maplibre.md 10.9 KB
      Loading…
    • examples-sdk-js-third-party.md 3.7 KB
      Loading…
    • examples-sdk-js-timeline-animation.md 8.5 KB
      Loading…
    • examples-sdk-js-toggle-interaction-handlers.md 1.9 KB
      Loading…
    • examples-sdk-js-ts-get-started.md 5.9 KB
      Loading…
    • examples-sdk-js-variable-label-placement.md 2.9 KB
      Loading…
    • examples-sdk-js-vector-source.md 2.9 KB
      Loading…
    • examples-sdk-js-video-on-a-map.md 1.7 KB
      Loading…
    • examples-sdk-js-visualize-population-density.md 4.9 KB
      Loading…
    • examples-sdk-js-weather-custom-dataset-population-density.md 34.5 KB
      Loading…
    • examples-sdk-js-weather-custom-popup.md 20.8 KB
      Loading…
    • examples-sdk-js-weather-layer-switcher.md 18.5 KB
      Loading…
    • examples-sdk-js-weather-plus-pressure-isolines-animated.md 10.6 KB
      Loading…
    • examples-sdk-js-weather-plus-pressure-isolines-labels.md 3.8 KB
      Loading…
    • examples-sdk-js-weather-plus-pressure-isolines.md 2.6 KB
      Loading…
    • examples-sdk-js-weather-plus-wind-arrow-animated.md 8.4 KB
      Loading…
    • examples-sdk-js-weather-plus-wind-arrow.md 2.5 KB
      Loading…
    • examples-sdk-js-weather-precipitation.md 5.2 KB
      Loading…
    • examples-sdk-js-weather-pressure.md 5.4 KB
      Loading…
    • examples-sdk-js-weather-radar-cloud.md 8.5 KB
      Loading…
    • examples-sdk-js-weather-radar.md 5.3 KB
      Loading…
    • examples-sdk-js-weather-temperature-color-ramp.md 10.1 KB
      Loading…
    • examples-sdk-js-weather-temperature.md 5.5 KB
      Loading…
    • examples-sdk-js-weather-wind-direction.md 6.6 KB
      Loading…
    • examples-sdk-js-weather-wind-temperature.md 8.2 KB
      Loading…
    • examples-sdk-js-weather-wind.md 8.1 KB
      Loading…
    • examples-sdk-js-wms.md 3.1 KB
      Loading…
    • examples-sdk-js-zoomto-linestring.md 4.2 KB
      Loading…
    • examples-svelte-maplibre-geocoding.md 4.4 KB
      Loading…
    • examples-svelte-maplibre-get-started.md 1.9 KB
      Loading…
    • examples-svelte-sdk-geocoding.md 4.1 KB
      Loading…
    • examples-svelte-sdk-get-started.md 11.5 KB
      Loading…
    • examples-vuejs-maplibre-get-started.md 1.9 KB
      Loading…
    • examples-vuejs-sdk-get-started.md 11.7 KB
      Loading…
    • INDEX.md 4.7 KB
      Loading…
    • map-resources-how-maps-work-coordinate-systems.md 5 KB
      Loading…
    • map-resources-how-maps-work-map-data.md 2.9 KB
      Loading…
    • map-resources-how-maps-work-raster-vs-vector.md 5.8 KB
      Loading…
    • map-resources-how-maps-work-resolution.md 4.9 KB
      Loading…
    • map-resources-how-maps-work-vector-features.md 2.7 KB
      Loading…
    • map-resources-how-maps-work-zoomable-maps.md 5.3 KB
      Loading…
    • map-resources-schemas-buildings.md 7.4 KB
      Loading…
    • map-resources-schemas-cadastre.md 8.8 KB
      Loading…
    • map-resources-schemas-ch-swisstopo-lbm.md 15.5 KB
      Loading…
    • map-resources-schemas-contours.md 3 KB
      Loading…
    • map-resources-schemas-countries.md 5.9 KB
      Loading…
    • map-resources-schemas-fr-cadastre.md 1.6 KB
      Loading…
    • map-resources-schemas-grid.md 9.4 KB
      Loading…
    • map-resources-schemas-jp-gsi-building.md 582 B
      Loading…
    • map-resources-schemas-jp-gsi.md 12.3 KB
      Loading…
    • map-resources-schemas-land.md 408 B
      Loading…
    • map-resources-schemas-landcover.md 669 B
      Loading…
    • map-resources-schemas-landform.md 4.4 KB
      Loading…
    • map-resources-schemas-nl-cartiqo.md 9.3 KB
      Loading…
    • map-resources-schemas-ocean.md 2.3 KB
      Loading…
    • map-resources-schemas-omt-planet.md 26.5 KB
      Loading…
    • map-resources-schemas-outdoor.md 7.1 KB
      Loading…
    • map-resources-schemas-planet-lite.md 6.8 KB
      Loading…
    • map-resources-schemas-planet-v4.md 88 KB
      Loading…
    • map-resources-schemas-uk-openzoomstack.md 5.2 KB
      Loading…
    • map-resources-specifications-expressions.md 50.4 KB
      Loading…
    • map-resources-specifications-layers.md 82.1 KB
      Loading…
    • map-resources-specifications-overview.md 1.5 KB
      Loading…
    • map-resources-specifications-root.md 4.8 KB
      Loading…
    • map-resources-specifications-sources.md 15.1 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-annotations.md 115.9 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-bridge.md 15.1 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-colorramp.md 94.1 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-events.md 52.5 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-helpers.md 153.3 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-location.md 9.3 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-logging.md 19.4 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-gestures.md 27.4 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-options.md 75.7 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-dsl.md 39.2 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-image.md 3.8 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-background.md 10.1 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-circle.md 33.7 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-fill.md 20.3 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-fillextrusion.md 25.6 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-heatmap.md 18.6 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-hillshade.md 17.7 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-line.md 33.9 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-raster.md 19.3 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer-symbol.md 33.2 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-layer.md 20.1 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style-source.md 77.2 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-style.md 95.8 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-types.md 95.6 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-workers-navigable.md 36.9 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-workers-stylable.md 4.1 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map-workers-zoomable.md 7.3 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk-map.md 181.9 KB
      Loading…
    • mobile-sdks-android-api-com-maptiler-maptilersdk.md 139.9 KB
      Loading…
    • mobile-sdks-android-api-root.md 10.8 KB
      Loading…
    • mobile-sdks-android.md 12.1 KB
      Loading…
    • mobile-sdks-flutter.md 3.2 KB
      Loading…
    • mobile-sdks-ios-api-actors.md 3.8 KB
      Loading…
    • mobile-sdks-ios-api-classes.md 233.9 KB
      Loading…
    • mobile-sdks-ios-api-enums.md 76.4 KB
      Loading…
    • mobile-sdks-ios-api-extensions.md 1.3 KB
      Loading…
    • mobile-sdks-ios-api-protocols.md 29.9 KB
      Loading…
    • mobile-sdks-ios-api-root.md 57.6 KB
      Loading…
    • mobile-sdks-ios-api-structs.md 72.3 KB
      Loading…
    • mobile-sdks-ios.md 10.4 KB
      Loading…
    • mobile-sdks-react-native.md 3.2 KB
      Loading…
    • on-prem-engine-getting-started-cli.md 2.2 KB
      Loading…
    • on-prem-engine-getting-started-desktop.md 8.1 KB
      Loading…
    • on-prem-engine-input-options.md 8 KB
      Loading…
    • on-prem-engine-installation.md 2.6 KB
      Loading…
    • on-prem-engine-license-activation.md 4.7 KB
      Loading…
    • on-prem-engine-merging-mbtiles.md 2.4 KB
      Loading…
    • on-prem-engine-output-formats.md 3.4 KB
      Loading…
    • on-prem-engine-output-options.md 16.3 KB
      Loading…
    • on-prem-server-geocoding.md 7.5 KB
      Loading…
    • on-prem-server-getting-started.md 8.8 KB
      Loading…
    • on-prem-server-hosting-data.md 4.6 KB
      Loading…
    • on-prem-server-map-styling.md 4 KB
      Loading…
    • on-prem-server-virtual-tilesets.md 4.3 KB
      Loading…
    • sdk-js-animation.md 782 B
      Loading…
    • sdk-js-api-client.md 1.1 KB
      Loading…
    • sdk-js-color-ramp.md 14.7 KB
      Loading…
    • sdk-js-config.md 2.6 KB
      Loading…
    • sdk-js-controls.md 43.1 KB
      Loading…
    • sdk-js-coordinates.md 34.6 KB
      Loading…
    • sdk-js-events.md 9.9 KB
      Loading…
    • sdk-js-geosplats.md 6.2 KB
      Loading…
    • sdk-js-handlers.md 24.8 KB
      Loading…
    • sdk-js-helpers.md 49.6 KB
      Loading…
    • sdk-js-image-viewer.md 13.7 KB
      Loading…
    • sdk-js-index.md 5.3 KB
      Loading…
    • sdk-js-languages.md 2.6 KB
      Loading…
    • sdk-js-layers.md 568 B
      Loading…
    • sdk-js-map-styles.md 12.2 KB
      Loading…
    • sdk-js-map.md 186.9 KB
      Loading…
    • sdk-js-markers-popups.md 40.3 KB
      Loading…
    • sdk-js-module-3d.md 1.6 KB
      Loading…
    • sdk-js-module-geocoding-migration.md 11 KB
      Loading…
    • sdk-js-module-geocoding.md 4.1 KB
      Loading…
    • sdk-js-properties.md 31.7 KB
      Loading…
    • sdk-js-sources.md 25.1 KB
      Loading…
    • sdk-js-types.md 6.7 KB
      Loading…
    • versions.md 8.3 KB
      Loading…
    • web-libraries-angular.md 16.2 KB
      Loading…
    • web-libraries-cesium.md 1.3 KB
      Loading…
    • web-libraries-deck-gl.md 4.2 KB
      Loading…
    • web-libraries-leaflet.md 3.3 KB
      Loading…
    • web-libraries-openlayers.md 2.4 KB
      Loading…
    • web-libraries-react.md 13.8 KB
      Loading…
    • web-libraries-svelte.md 10.1 KB
      Loading…
    • web-libraries-vue.md 10.2 KB
      Loading…
  • SKILL.md 31.2 KB
    ---
    name: maptiler
    description: >-
      Expert coding skill for the full MapTiler platform — Cloud REST APIs, MapTiler
      SDK JS (built on MapLibre GL JS), native mobile SDKs, on-premise infrastructure,
      and vector tile schemas. USE WHEN the user wants to add a map to a web or mobile
      app, show locations or routes, display geographic data, build a store locator,
      create data visualizations on maps, add geocoding or address search, do reverse
      geocoding, look up elevation, do IP geolocation, fetch weather data, transform
      coordinates between CRS/EPSG, embed static map images, work with vector tilesets
      (Planet v4, Buildings, Contours, Outdoor, Ocean, Landcover, Cadastre), write
      MapLibre style expressions or data-driven styling, render 3D terrain, globe view,
      or 3D buildings extrusion, use satellite imagery, add markers, popups, heatmaps,
      or clustering, integrate maps in React, Vue, Svelte, Angular, Next.js, Leaflet,
      OpenLayers, Cesium, or deck.gl, build native maps on iOS (Swift), Android (Kotlin),
      Flutter, or React Native, self-host with MapTiler Server or generate tiles with
      MapTiler Engine CLI, or upload/manage tilesets via the Admin API. Also USE WHEN
      the user mentions MapLibre GL JS — the SDK extends MapLibre with built-in cloud
      services, helpers, and session billing.
    ---
    
    # MapTiler — Agent Skill
    
    > [@maptiler/sdk](https://www.npmjs.com/package/@maptiler/sdk) · [Docs](https://docs.maptiler.com/) · [Cloud Console](https://cloud.maptiler.com/) · [GitHub](https://github.com/maptiler)
    
    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](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:
    
    | Target Platform | File Name Prefix |
    | :--- | :--- |
    | **Web** (Core JS SDK) | `sdk-js-*`, `examples-sdk-js-*` |
    | **Web Frameworks** (React, Svelte, Vue, Angular) | `web-libraries-*`, `examples-react-*`, `examples-svelte-*`, `examples-vuejs-*`, `examples-angular-*` |
    | **Web Mapping Engines** (Leaflet, OpenLayers, Cesium, deck.gl) | `examples-leaflet-*`, `examples-openlayers-*`, `examples-cesium-*`, `web-libraries-deck-gl*` |
    | **Android** (Kotlin/Java) | `mobile-sdks-android-*`, `examples-android-*` |
    | **iOS** (Swift) | `mobile-sdks-ios-*`, `examples-ios-*` |
    | **Cross-Platform Mobile** (Flutter, React Native) | `mobile-sdks-flutter-*`, `mobile-sdks-react-native-*` |
    | **Cloud REST APIs** | `cloud-api-*`, `cloud-admin-api-*` |
    | **On-Premise Infrastructure** | `on-prem-*` |
    | **Vector Tile Schemas** | `map-resources-schemas-*` |
    | **MapLibre Style Spec** | `map-resources-specifications-*` |
    
    ---
    
    ## 2. Universal Rules (apply across every platform)
    
    ### A. Zero Variable Leak Policy
    Consult [references/versions.md](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.
    
    | Legacy | Modern Replacement | SDK Constant |
    | :--- | :--- | :--- |
    | `basic-v2` / `streets-v2-light` | `base-v4` | `MapStyle.BASE` |
    | `basic-v2-dark` | `base-v4-dark` | `MapStyle.BASE.DARK` |
    | `streets-v2` | `streets-v4` | `MapStyle.STREETS` |
    | `outdoor-v2` | `outdoor-v4` | `MapStyle.OUTDOOR` |
    | `satellite` / `satellite-v2` | `satellite-v4` | `MapStyle.SATELLITE` |
    | `hybrid` | `hybrid-v4` | `MapStyle.HYBRID` |
    | `dataviz-dark` | `dataviz-v4-dark` | `MapStyle.DATAVIZ.DARK` |
    | `topo-v2` | `topo-v4` | `MapStyle.TOPO` |
    
    **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](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.
    
    | Source | Convention | When you encounter it |
    | :--- | :--- | :--- |
    | **MapTiler SDK JS / MapLibre / Mapbox** | `[lng, lat]` array | All web SDK code (center, marker, source coordinates, expressions) |
    | **GeoJSON spec** | `[lng, lat]` (or `[lng, lat, ele]`) | Every `geometry.coordinates` value |
    | **MapTiler REST URLs** | `{lng},{lat}` in the path | `/geocoding/{lng},{lat}.json`, `/elevation/dataset/{lng},{lat}.json`, static maps `/static/{lng},{lat},{zoom}/…` |
    | **Leaflet** | `(lat, lng)` — **reversed** | `L.map().setView([lat, lng], z)`, `L.marker([lat, lng])`, `L.latLng(lat, lng)` |
    | **iOS `CLLocationCoordinate2D`** | `(latitude:, longitude:)` — **reversed at the struct level** | Apple CoreLocation. When building a MapTiler URL: `c.longitude, c.latitude` |
    | **Android `LatLng` / `LngLat`** | MapTiler Android SDK uses `LngLat(lng, lat)`; system `Location` exposes `latitude`/`longitude` as flat properties | Match the SDK type, not the system type |
    | **MapTiler Geolocation API response** | Flat fields `latitude` / `longitude` (not a pair) | Construct `[loc.longitude, loc.latitude]` before passing to any SDK call |
    
    **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
    
    ```bash
    npm install @maptiler/sdk
    ```
    
    CSS must be imported separately:
    ```js
    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:
    
    | Tool | Env var |
    | :--- | :--- |
    | Vite | `VITE_MAPTILER_API_KEY` |
    | Next.js | `NEXT_PUBLIC_MAPTILER_API_KEY` |
    | CRA | `REACT_APP_MAPTILER_API_KEY` |
    
    ```js
    import * as maptilersdk from '@maptiler/sdk';
    maptilersdk.config.apiKey = import.meta.env.VITE_MAPTILER_API_KEY;
    ```
    
    ### Minimal Map
    
    ```js
    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)
    
    ```js
    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)
    
    | Style | Purpose | Variants |
    | :--- | :--- | :--- |
    | `MapStyle.STREETS` | Comprehensive street map | `.DARK`, `.PASTEL` |
    | `MapStyle.SATELLITE` | Beautiful satellite map | `.DARK` |
    | `MapStyle.HYBRID` | Beautiful satellite map with context | `.DARK` |
    | `MapStyle.OUTDOOR` | Map for hiking and sports | `.DARK` |
    | `MapStyle.WINTER` | Map for winter activities | `.DARK` |
    | `MapStyle.TOPO` | General-purpose topographic map | `.DARK`, `.PASTEL`, `.TOPOGRAPHIQUE` |
    | `MapStyle.DATAVIZ` | Simple data visualization map | `.DARK`, `.LIGHT` |
    | `MapStyle.BASE` | Clear general-purpose map | `.DARK`, `.LIGHT` |
    | `MapStyle.BRIGHT` | Shiny map for context or navigation | `.DARK`, `.LIGHT`, `.PASTEL` |
    | `MapStyle.BACKDROP` | Monochrome context map | `.DARK`, `.LIGHT` |
    | `MapStyle.AQUARELLE` | Artistic watercolor map | `.DARK`, `.VIVID` |
    | `MapStyle.LANDSCAPE` | Light hillshade map | `.DARK`, `.VIVID` |
    | `MapStyle.OCEAN` | Seabed and bathymetry map | `.DARK` |
    | `MapStyle.OPENSTREETMAP` | Rich, familiar OSM community style | `.DARK` |
    | `MapStyle.TONER` | Contrasted monochrome map | `.LITE` |
    
    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](references/sdk-js-map-styles.md).
    
    ### Language
    
    ```js
    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
    
    ```js
    // 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.
    
    | Helper | Key options |
    | :--- | :--- |
    | `addPolyline` | `lineColor`, `lineWidth`, `outline` |
    | `addPolygon` | `fillColor`, `fillOpacity`, `outlineColor` |
    | `addPoint` | `pointColor`, `pointRadius`, `cluster`, `showLabel` |
    | `addHeatmap` | `colorRamp` (`ColorRamp.*`), `property`, `radius`, `opacity` |
    
    ```js
    maptilersdk.helpers.addPoint(map, {
      data: pointsGeoJSON, pointColor: '#FF0000', pointRadius: 8,
      cluster: true, showLabel: true, beforeId: 'waterway-label',
    });
    ```
    
    ### 3D Terrain / Globe — single-flag constructors
    
    ```js
    // 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](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
    
    ```jsx
    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](references/web-libraries-vue.md) · [web-libraries-svelte.md](references/web-libraries-svelte.md) · [web-libraries-angular.md](references/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](references/web-libraries-react.md).
    
    ---
    
    ## 6. CDN / Single-File / Playgrounds
    
    Use pinned versions from `versions.md` — never `latest` or obsolete builds.
    
    ```html
    <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:
    
    | OMT (old) | Planet v4 (current) |
    | :--- | :--- |
    | `transportation` (`class: motorway/primary/.../residential`) | `road` (`class: motorway/trunk/primary/secondary/tertiary/minor/service/...`); no `residential` class — use `minor` or `service` |
    | `transportation_name` | `road_label` |
    | (none — bundled) | `railway`, `aviation`, `ferry`, `aerialway` as separate layers |
    | `place` | `country_label`, `city_label`, `island_label`, `continent_label` (hierarchy split) |
    
    When a user prompt references `transportation`, `place`, or other OMT-era layer names, surface the rename explicitly rather than silently generating broken filters.
    
    | Schema | Reference |
    | :--- | :--- |
    | Planet v4 (latest) | [map-resources-schemas-planet-v4.md](references/map-resources-schemas-planet-v4.md) |
    | OpenMapTiles Planet | [map-resources-schemas-omt-planet.md](references/map-resources-schemas-omt-planet.md) |
    | Planet Lite | [map-resources-schemas-planet-lite.md](references/map-resources-schemas-planet-lite.md) |
    | Buildings | [map-resources-schemas-buildings.md](references/map-resources-schemas-buildings.md) |
    | Contours / Outdoor / Ocean | [contours](references/map-resources-schemas-contours.md), [outdoor](references/map-resources-schemas-outdoor.md), [ocean](references/map-resources-schemas-ocean.md) |
    | Landcover / Landform / Cadastre | [landcover](references/map-resources-schemas-landcover.md), [landform](references/map-resources-schemas-landform.md), [cadastre](references/map-resources-schemas-cadastre.md) |
    | Style spec (layers / sources / expressions / root) | [layers](references/map-resources-specifications-layers.md), [sources](references/map-resources-specifications-sources.md), [expressions](references/map-resources-specifications-expressions.md), [root](references/map-resources-specifications-root.md) |
    
    ### 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.
    
    | Concern | Standard (`maptiler_planet_v4`) | Specialized (`buildings`) |
    | :--- | :--- | :--- |
    | Height fields | `render_height`, `render_min_height` | `height`, `height_min` |
    | Colors | — | `facade_color`, `roof_color` |
    | Shape | — | `roof_shape` |
    | Labels | — | `building_label` (names, ISO 639 translations) |
    | Entrances | — | `building_entrance` |
    | Unique IDs | False | **True** (z14+) — usable with `setFeatureState` |
    
    ```js
    // 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](references/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.
    
    | Module | Purpose | Key Methods / Reference |
    | :--- | :--- | :--- |
    | `geocoding` | Place search, reverse | `forward()`, `reverse()`, `batch()` — [cloud-api-geocoding.md](references/cloud-api-geocoding.md) |
    | `geolocation` | IP visitor location | `info()` — [cloud-api-geolocation.md](references/cloud-api-geolocation.md) |
    | `elevation` | Altitude lookup | `at()`, `batch()`, `fromLineString()` — [cloud-api-elevation.md](references/cloud-api-elevation.md) |
    | `staticMaps` | Static map images | `centered()`, `bounded()`, `automatic()` — [cloud-api-static-maps.md](references/cloud-api-static-maps.md) |
    | `coordinates` | CRS / EPSG transform | `search()`, `transform()` — [cloud-api-coordinates.md](references/cloud-api-coordinates.md) |
    | `data` | MapTiler datasets | `get(uuid)` — [cloud-api-data.md](references/cloud-api-data.md) |
    | `weather` | Wind, temp, pressure, radar | [cloud-api-weather.md](references/cloud-api-weather.md) |
    | `maps` (Vector/Raster) | Tilesets, styles | [cloud-api-maps.md](references/cloud-api-maps.md) |
    | `tiles` | Raw tile endpoints | [cloud-api-tiles.md](references/cloud-api-tiles.md) |
    | `fonts` / `images` / `ogc` | Misc | [fonts](references/cloud-api-fonts.md), [images](references/cloud-api-images.md), [ogc](references/cloud-api-ogc.md) |
    | **Admin** (tilesets, uploads, keys, analytics) | Account management | [cloud-admin-api-tilesets.md](references/cloud-admin-api-tilesets.md), [api-keys](references/cloud-admin-api-api-keys.md), [analytics](references/cloud-admin-api-analytics.md) |
    | Auth | Key-vs-token, referrer rules | [cloud-api-authentication.md](references/cloud-api-authentication.md) |
    
    ```js
    // 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
    
    | Platform | Overview | API Reference |
    | :--- | :--- | :--- |
    | **iOS (Swift)** | [mobile-sdks-ios.md](references/mobile-sdks-ios.md) | [mobile-sdks-ios-api-classes.md](references/mobile-sdks-ios-api-classes.md) |
    | **Android (Kotlin)** | [mobile-sdks-android.md](references/mobile-sdks-android.md) | [mobile-sdks-android-api-com-maptiler-maptilersdk-map.md](references/mobile-sdks-android-api-com-maptiler-maptilersdk-map.md) |
    | **Flutter** | [mobile-sdks-flutter.md](references/mobile-sdks-flutter.md) | search `mobile-sdks-flutter-*.md` |
    | **React Native** | [mobile-sdks-react-native.md](references/mobile-sdks-react-native.md) | search `mobile-sdks-react-native-*.md` |
    
    ### iOS — Minimal Map (SwiftUI)
    
    ```swift
    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)
    
    ```kotlin
    // 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:
    
    | Topic | Reference |
    | :--- | :--- |
    | MapTiler Server — Getting Started | [on-prem-server-getting-started.md](references/on-prem-server-getting-started.md) |
    | Hosting Data | [on-prem-server-hosting-data.md](references/on-prem-server-hosting-data.md) |
    | Virtual Tilesets | [on-prem-server-virtual-tilesets.md](references/on-prem-server-virtual-tilesets.md) |
    | Map Styling on Server | [on-prem-server-map-styling.md](references/on-prem-server-map-styling.md) |
    | On-Premise Geocoding | [on-prem-server-geocoding.md](references/on-prem-server-geocoding.md) |
    | Engine CLI — Getting Started | [on-prem-engine-getting-started-cli.md](references/on-prem-engine-getting-started-cli.md) |
    | Engine — Input / Output Options | [input](references/on-prem-engine-input-options.md), [output](references/on-prem-engine-output-options.md) |
    
    For tile path conventions on fallback XYZ layers and service-worker caches, see § 2B.
    
    ---
    
    ## 11. Critical Gotchas (cross-platform)
    
    | Problem | Fix |
    | :--- | :--- |
    | Map invisible (web) | Container needs explicit height (`100vh` or `position: absolute; inset: 0`) |
    | Markers / map center on the wrong continent | Coordinates are `[lng, lat]`, not `[lat, lng]` (e.g. Prague is `[14.4178, 50.1167]`, not `[50.1167, 14.4178]`) |
    | Layers vanish after `setStyle()` | Re-add inside `map.once('styledata', …)` |
    | Data covers labels | Use `beforeId: 'waterway-label'` |
    | Slow with many points | Enable `cluster: true` (helpers or source) |
    | SPA memory leak | Always call `map.remove()` on unmount; null the ref |
    | Importing `maplibre-gl` separately | Use `@maptiler/sdk` — it includes and extends MapLibre |
    | Map re-creates on every state change (React) | Empty `useEffect` deps; mutate via `setX` methods, not re-init |
    | Stale closures in handlers | Use a `useRef` mirror of state, read `.current` |
    | Browser ESM script error | Use `.mjs` build, not UMD, with `<script type="module">` |
    | Mobile rendering 3D buildings looks flat | You loaded the standard style — add the specialized `buildings` source |
    | Style 404s on mobile | Update endpoint from `streets-v2` family to `streets-v4` family |
    | Geocoding key 403 | Verify referrer/whitelist in the key settings ([cloud-api-authentication.md](references/cloud-api-authentication.md)) |
    | `{{ }}` leaking into output | Resolve via [versions.md](references/versions.md) before emitting |
    | MapTiler Engine refuses to start | The `-o output_dir` (or `-o file.mbtiles`) target **must not already exist**. Delete it, or pick a new path. No `-f` / `--force` flag |
    | iOS app produces 403s on every tile | `MTConfig.shared.setAPIKey(_:)` is `async` and was called without `await` — set it inside a `Task { … }` or SwiftUI `.task` modifier *before* the first map view appears |
    | mapbox-gl-draw cursors / hit-test broken | Plugin CSS targets `.mapboxgl-canvas`; MapTiler/MapLibre uses `.maplibregl-canvas`. Add fallback rules: `.maplibregl-canvas.mouse-add { cursor: crosshair }` and `.maplibregl-canvas.mouse-drag { cursor: grabbing }` |
    | User pastes a live API key in chat | Flag it (rotate at the Cloud Console) and use a `YOUR_MAPTILER_API_KEY` placeholder in your own output — never echo a real key back |
    | Inventing `addControl(new XControl())` patterns | Many MapTiler controls live as **constructor flags**: `minimap`, `navigationControl`, `geolocateControl`, `scaleControl`, `terrainControl`, `fullscreenControl`, `projectionControl`. Use the flag first; only reach for `addControl` for 3rd-party plugins or post-init changes |
    | Hallucinated SDK class names (`MinimapControl`, `GeocodingBar`, …) | Cross-reference `references/sdk-js-controls.md` and `sdk-js-map.md` before emitting a class name. The canonical minimap class is `MaptilerMinimapControl` (`Maptiler` prefix), and the constructor option is the preferred path anyway |
    | GeoSplats rendering fails / blank model | GeoSplats SDK **requires WebGPU support**. Always verify browser compatibility (`navigator.gpu`) and provide a clear UI fallback error overlay |
    
    
    ---
    
    ## 12. Ecosystem Packages
    
    | Package | Purpose |
    | :--- | :--- |
    | `@maptiler/geosplats` | High-performance 3D Gaussian Splatting (WebGPU-powered) |
    | `@maptiler/geocoding-control` | Address-search bar UI |
    | `@maptiler/weather` | Wind, temperature, pressure, radar layers (60 fps) |
    | `@maptiler/3d` | glTF / GLB 3D model placement |
    | `@maptiler/elevation-profile` | Elevation chart for routes |
    | `@maptiler/marker-layout` | Non-colliding DOM marker overlay |
    | `@maptiler/ar` | Augmented-reality 3D terrain |
    | `@maptiler/client` | Headless API client (Node.js / browser, no map) |
    
    ---
    
    ## 13. Resources
    
    - [MapTiler Cloud Console](https://cloud.maptiler.com/)
    - [MapTiler SDK JS Docs](https://docs.maptiler.com/sdk-js/) · [Examples](https://docs.maptiler.com/sdk-js/examples/) · [NPM](https://www.npmjs.com/package/@maptiler/sdk) · [GitHub](https://github.com/maptiler/maptiler-sdk-js)
    - [MapTiler iOS SDK Docs](https://docs.maptiler.com/mobile-sdk/ios/) · [Android SDK Docs](https://docs.maptiler.com/mobile-sdk/android/)
    - [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/)
    - Framework docs: [React](https://docs.maptiler.com/react/) · [Vue](https://docs.maptiler.com/vuejs/) · [Svelte](https://docs.maptiler.com/svelte/) · [Angular](https://docs.maptiler.com/angular/) · [Vite](https://docs.maptiler.com/vite/)
    
    ---
    
    ## 14. Reference Catalog
    
    The curated index of high-value reference docs is at [references/INDEX.md](references/INDEX.md). For files not listed there, search by the prefix conventions in § 1.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.