maptiler

# 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]