# MapTiler documentation Source: https://docs.maptiler.com/ Home Updates MapTiler Planet Guides Get started Use a ready-made map Use static map image Define map area Add markers Add lines or polygons Use link to map Embed map in iFrame Use prepared code examples Use map in desktop GIS Use map in Tableau Design your map Get started with Map Designer Interface Global settings Quick editing Working with layers Styling map layers Styling by zoom range Adding new layer Layer filters Publishing Icons & patterns Icons Patterns Watermarks Feature highlighting Style individual buildings Highlight boundaries Highlight countries Enhance coastlines Add drop shadow Use masking Terrain styling Hillshading Hand-drawn hillshading Color relief Localization Map language Meters vs feet Disputed borders Automatic disputed borders Map attribution Add attribution Remove attribution Data visualization Work with data sources Replace data sources Replace name labels Edit style JSON Select visualization type Prepare data for visualization Tutorials Retro map Pop art map Image-styled map Oktoberfest map Ocean map Custom 3D globe Bring your data Upload your files Formats and limits for upload Add image (overlay) to map Add vector features to map Add 3D objects to map Build 3D map with LiDAR 🛠️ Vector Data Editor Upload existing data Add features Modify features Edit properties Show your data on map Export to GeoJSON 🛠️ Georeferencer Georeference your image Use location services Use place search Basic parameters Batch geocoding Locate IP addresses Use elevation Transform coordinates Search Transform Transform in batch Manage your account Sessions vs requests Usage analytics Team account Developer resources Overview APIs Maps API Static maps API Tiles API Data API Images API Geocoding API Geolocation API Coordinates API Elevation API Weather API Other API clients JS/TS client library Reference Upload JS library Reference Upload CLI tool Service APIs Upload API Tileset API API keys API Analytics API Using Service API Authentication What's an API key Protecting your API key Service token SDK JS Code examples Reference Map Map styles Markers and popups Sources Layers Helpers Controls Coordinates Events User interaction handlers Languages Color ramp Config ImageViewer MaptilerAnimation API client Properties and options Types Modules 3D objects Reference Examples AR control Reference Examples Elevation control Reference Examples Geocoding control Reference Examples Migration v2 to v3 Marker layout Reference Examples Weather JS How to make weather maps Methods Events Layers Precipitation Pressure Radar Temperature Wind Pressure isolines (PLUS) Wind arrow (PLUS) Color ramp Types & interfaces Advanced Tile layer intensity Coloring fragment Particle animation Arrow layer (PLUS) Isolines layer (PLUS) Mobile SDKs How to build mobile apps Mobile PWA app Android SDK Reference Examples iOS SDK Reference Examples React Native Flutter Agent Skills beta JavaScript frameworks Angular Examples React Examples Svelte Examples Vite Vue.js Examples 3rd party libraries Leaflet Examples MapLibre GL JS Examples OpenLayers Examples Deck.gl Examples Cesium Game engines Unreal Unity Map resources How maps work Zoomable maps Resolution and zoom Coordinate systems Map data Vector features Raster vs vector tiles Generalization in maps MapTiler schemas & data MapTiler Planet v4 (vector) Buildings (vector) Cadastre (vector) How to use Contours (vector) How to use Countries (vector) How to use Grid (vector) Hillshading (raster) Hand drawn hillshading (raster) Land (vector) Landcover (vector) How to use Landform (vector) Land gradient (raster) Ocean (vector) Ocean RGB (raster-DEM) About Outdoor (vector) Satellite (raster) About satellite maps Satellite Medium Res Satellite night (raster) Terrain RGB (raster-DEM) About Terrain 3D (mesh) OpenMapTiles Planet (vector) About MapTiler Planet Lite v3 (vector) MapTiler Planet v3 (vector) Data origin Weather data National tilesets UK OS Open Zoomstack NL Cartiqo CH Swisstopo LeichteBasiskarte JP GSI France Cadastre Map specifications GL style specification Root Light Sources Sprite Glyphs Transition Layers Projection Sky Types Expressions Tilestats How to generate tilestats On-prem MapTiler Server Installation Windows macOS Linux Raspberry Pi Kubernetes Docker Getting started Hosting map data On-prem map styling On-prem geocoding (map search) Virtual tilesets Technical specification APIs Geocoding API Maps API Static maps API Tiles API Other Admin APIs Authentication Maps API Tiles API Tile ingest API MapTiler Engine Getting started Managing tasks Settings Input formats Output formats Technical specification CLI manual Installation Getting started Input options Output options Map hosting Advanced options Merging MBTiles License activation Bug reporting Georeferencing tool MapTiler documentation Tutorials, examples, and API reference for building map applications. Getting started Learn the basics and take your first steps with MapTiler. Perfect for mapping beginners. Get started   Developer resources Find all you need to build map apps in one place: SDKs, API reference, and tutorials for devs. See resources   Code examples Get inspired and speed up your work with our collection of 200+ customizable code examples. Browse examples   # Platform updates Source: https://docs.maptiler.com/updates/ - [General news and blogposts](https://www.maptiler.com/news/) - [MapTiler **SDK JS** changelog](https://github.com/maptiler/maptiler-sdk-js/releases/) - [MapTiler **Engine** changelog](https://www.maptiler.com/engine/changelog/) - [MapTiler **Server** changelog](https://www.maptiler.com/server/changelog/) - [**MapTiler Planet** – main dataset changelog](/updates/data/planet-v4-latest/) --- This page lists major updates to our products with focus on technical specs and practical implications. Find out exactly what's changing, what it means for your projects, and if there are any actions to take. ### 2026-05 #### MapTiler Server 4.8 This new version of MapTiler Server introduces: - A visual [Virtual Tileset Editor](/guides/on-prem/server/virtual-tileset/) to easily **combine and color-tone** multiple raster datasets, or to combine vector data from various sets into one. - New [macOS installation](/guides/on-prem/server/installation/macos/) using a DMG package to install easily via **drag-and-drop**. ### 2026-04 #### Geocoding control module v3 We've released a new version of the Geocoding control module for the MapTiler SDK JS. The module implements a search box in a map. If you've used the previous module version and want to upgrade, *please note that there are some breaking changes.* 👉 [Learn how to migrate from v2 to v3](https://docs.maptiler.com/sdk-js/modules/geocoding/api/migration/) #### Icon sets management (BETA) We're introducing advanced options to add, style, and replace map icons. You can now add custom icon sets, combine them with our catalog sets, and manage them all in one place. Also, you now have the option to style vector icons together with their label. 👉 [Learn about the new icon sets management](/guides/map-design/icons/) ### 2026-02: Georeferencing in cloud We've added the ability to georeference images directly in your browser. Previously, files without location metadata required pre-processing with [MapTiler Engine](/guides/map-tiling-hosting/data-processing/). Now you can manually assign coordinates to any supported raster file and process it into map tiles within your MapTiler account. 👉 [Learn how to georeference your images in cloud](/guides/georeferencer/get-started/) ### 2026-01: [Style individual buildings](https://www.maptiler.com/news/2026/01/style-individual-buildings-with-our-new-tileset/) We're introducing an easier option to style and highlight individual buildings in your maps. Previously, this required manual style JSON editing; now you can use the visual interface. The functionality is powered by the new [Buildings](/schema/buildings/) tileset which includes unique building IDs and metadata, making it possible to filter out specific structures for styling. 👉 [Learn the new method to style buildings](/guides/map-design/how-to-style-individual-buildings/) ### 2025-11: [New generation of MapTiler maps](https://www.maptiler.com/news/2025/10/new-generation-of-maptiler-maps) We're releasing [MapTiler Planet v4](/schema/planet-v4/) as the new data backbone for our maps, officially replacing [MapTiler Planet v3](/schema/planet/). Related to that, we're introducing new versions of our [maps](https://www.maptiler.com/maps/), built and optimized specifically for Planet v4. - **Changes in your account:** Within your [MapTiler account](https://cloud.maptiler.com/maps/), updated maps and tilesets are now labeled as `new` and the older ones as `deprecated`. Some older tilesets or map styles may no longer be listed at all. - **Functionality of deprecated maps:** All older (deprecated) map styles remain fully functional, so any maps you've already implemented are safe. However, please note that there won't be no further maintenance except critical bug fixes. - **Updates of deprecated data:** Older maps (v2, v3) and their data sources continue to get standard bi-weekly data updates. Any change in long-term support of previous generations of maps and data will be announced well ahead. - **Backward compatibility:** Due to different internal data structure, the new Planet v4 dataset is not compatible with older map styles, and Planet v3 is not compatible with new map styles. This means that simple upgrading of older maps to Planet v4 isn't possible. - **New map implementations:** For all new projects, we strongly recommend using the latest datasets and map styles. They'll be now getting the most love, careful maintenance, improvements, and features unavailable in previous versions. ### 2025-10: MapTiler Server 4.7.1 Since this minor version, MapTiler Server fully supports **rasterization on macOS**. ### 2025-07: MapTiler Server 4.7 The new version of MapTiler Server introduces [on-prem geocoding](/guides/on-prem/server/geocoding/). This feature makes it possible to set up a local Geocoding API and implement **offline place search** in your self-hosted maps. # MapTiler Planet – release 2026-05-12 Source: https://docs.maptiler.com/updates/data/planet-v4-latest/ This automatically generated report provides a snapshot of our main dataset, [MapTiler Planet](https://docs.maptiler.com/schema/planet-v4/). We update its data bi-weekly to enable new map functions and integrate the latest OpenStreetMap updates. Our proprietary processing and QA remove any vandalism and ensure data integrity. Use these metrics to monitor what's newly available and to track layer-specific changes that might affect your map implementations. ## Special note There are more waterways (rivers, streams, canals, etc.) in our data now across all zoom levels. If you want to reduce the number in your maps, move the minzoom of River, Waterway or Stream layers up based on your preference. ## Key statistics | Metric | Current count | Δ vs. previous | | :--- | :---: | :---: | | **Total objects** | 15,236,883,078 | 8,419,125 | | Nodes | 10,619,729,289 | 41,175,068 | | Ways | 1,189,171,829 | 6,380,296 | | Relations | 14,346,301 | 48,147 | | POI count | 54,516,860 | 126,026 | | Avg. tile size | 15kB | 26B | ## Download and access - [Online data in MapTiler account](https://cloud.maptiler.com/tiles/v4) - [On-prem data for self-hosting](https://www.maptiler.com/on-prem-datasets/planet/) - [Regional extracts](https://data.maptiler.com/extracts/) ## Support For questions or bug reports, please contact us at . Alternatively, use the feedback form in [Map Designer](https://cloud.maptiler.com/maps/editor), menu **Help**. ## Update history You can find the history of all updates on the [MapTiler data updates](/updates/data/) page. --- © 2026 MapTiler © OpenStreetMap Contributors # Get started with MapTiler Source: https://docs.maptiler.com/guides/getting-started/ First time here? Perfect. Let's walk you through the mapping basics and show you where to go next, depending on your needs. ### Step 1: Create a MapTiler account Workflows described in this documentation generally require you to be logged in to a MapTiler account. Creating one is fast, free, and with no obligations. 👉 [Create account](https://cloud.maptiler.com/) ### Step 2: Get an API key You need an API key to make any of our maps and services work, so create yours now to have it handy. 👉 **[Get your key here](https://cloud.maptiler.com/account/keys/)** and [learn how to protect it](https://docs.maptiler.com/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). ### Step 3: Learn the basics (optional) If you're completely new to digital maps, we recommend getting familiar with the basic concepts. It's not necessary, but it does make things easier. 👉 [How maps work](/guides/getting-started/how-maps-work/) ### Step 4: Build your map Now for the exciting part. You've got data you want to visualize – like locations, routes, 3D models, live updates, historical maps, drone imagery – and you want to put it on a map. Here's how: 1. **Pick and use a ready-made map.** 2. **Customize the map design.** (Optional) 3. **Add your data.** These steps are universal enough for anyone, but **developers** might want to do them mostly programmatically. We have tools to make the job easier and plenty of examples for a quick start, including materials for open-source map libraries and popular frontend frameworks. See 👉 [Developer resources](/guides/getting-started/developer/) ### Other options and services - [**Search & location services**](/guides/location-services/) – add place search to your app, get elevation at any point, or locate your users to customize their experience. With or without a map. - **On-prem/offline setup** – maintain complete control and secure access to your maps and data by using your own infrastructure, even completely offline: - Self-host your maps with MapTiler Server - Process your data on-prem with MapTiler Engine ### More help Got stuck and self-study resources don't get you anywhere? [Contact our support](https://docs.maptiler.com/support/requests/) for real human-to-human help. Happy mapping! # Use a ready-made map Source: https://docs.maptiler.com/guides/getting-started/use-map/ The fastest way to show a map on your website is to [select one of our maps](https://cloud.maptiler.com/maps/) and add it in one of the ways described below. > [!KEY] > You'll need a **MapTiler API key** to use our maps, otherwise they won't work. If you're not familiar with API keys, learn [what's an API key and how to get one](/cloud/api/authentication-key/). Each use case below explains where to put it. You can also explore prepared [ready-to-use code examples](/guides/maps-apis/maps-platform/use-maps-interactively-with-javascript/) that are available in your MapTiler account and customized for each map. ## Link to map A simple link to your map like this allows you to specify the initial map location and zoom, bearing (map orientation), and pitch (visual tilt). 👉 [How to configure a link to map](/guides/getting-started/use-map/link/) ## Embed map as iFrame For the easiest way to embed a map on your website, you need to wrap the link to your map in an iFrame. The possibilities are the same as for a link (described above). 👉 [How to embed map with iFrame code](/guides/getting-started/use-map/iframe/) ## Use a static map image A static map loads as a simple cut-out image, so it's not interactive or zoomable. However, it uses the latest map data whenever it loads, so it doesn't get outdated like a screenshot would. In addition to custom initial position and view, a static map allows you to add one or more colored **markers** (pins), **lines** (paths), or **polygons** (areas). 👉 [How to use a static map image](/guides/maps-apis/static-maps/static-maps-for-your-web/) ## Add map with our SDK To create map experiences with _rich interactivity_ and _advanced visual effects_, you'll need developer tools. Using [MapTiler SDK JS](/sdk-js/) gives you many options: You can add markers or trails to your map, highlight certain areas, add controls for users to adjust the map view to their needs, add 3D effects, animations, and much more. - See the collection of MapTiler SDK JS [code examples and tutorials](/sdk-js/examples/) - Start with your favorite JS framework: [React](/react/) • [Angular](/angular/) • [Svelte](/svelte/) • [Vue.js](/vuejs/) • [Vite](/vite/) If you prefer another mapping library or need a mobile SDK or game engine instructions, you'll find it all under [Developer resources](/guides/getting-started/developer/). ## Other options Of course, you can use our maps in more ways than just showing them on a website. For example: - You can use your map [with a desktop GIS application](/guides/maps-apis/maps-platform/how-to-load-maps-to-desktop-gis/). - You can use your map [with Tableau](/guides/maps-apis/maps-platform/how-to-add-maps-to-tableau/). - You can print your map. ## What's next? With a basemap selected and working, you'll probably want to [add some custom data to it](/guides/getting-started/add-data/) so that it shows whatever you want to share with the world. Optionally, you can also [adjust the map design](/guides/getting-started/map-design/) to use your brand colors, custom icons, fonts and so on. All our maps are fully customizable! # Use a static map image Source: https://docs.maptiler.com/guides/maps-apis/static-maps/static-maps-for-your-web/ This page explains how to insert a map into a webpage as a static non-zoomable map image, like this: ![Example of a static map](https://api.maptiler.com/maps//static/8.57,47.35,8.8/825x350.png?key=) A map image shows any area you specify on a map of your choice. Optionally, you can also [add markers, lines or polygons](#add-markers) to the map image. Then you can use the map on your website just like a regular image. A static map renders a fresh, up-to-date map image whenever it loads.
Static maps don't work with a free plan. Get them with any paid plan, including our most affordable tier.
## Quick start The URL of a static map image is actually an API request to the [**Static maps API**](/cloud/api/static-maps/), containing all the necessary parameters to render the map image. The easiest way to generate the image's API URL is to use our visual generator: Open static maps generator With the URL generated, insert the map image into your website just like a regular image, for example using HTML tag ``. The API URL contains a placeholder for an API key. Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! ## Modify the map URL If you want to manually tweak the API URL of your static map, create it from scratch, or just understand how it is constructed, see 👉 [How to define the static map area](/guides/maps-apis/static-maps/static-map-area/). ## Add markers or lines {#add-markers}

To learn how to add markers (pins), see 👉 Static map with markers.

To add paths or highlight areas, see 👉 Static map with lines or polygons.

## Switch map to static If you have an existing interactive web map, you can switch it to static with a single parameter. This is also handy if you need to add more complex features than markers and lines. See the code example 👉 [Create a non-interactive map](/sdk-js/examples/interactive-false/) for MapTiler SDK JS. ## API reference - [Static maps API – reference](/cloud/api/static-maps/) - [Static maps API – Client JS](/client-js/#%EF%B8%8F-static-maps) # Define area of static map image Source: https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-area/ This page explains in detail how the API URL for a [static map](/guides/maps-apis/static-maps/static-maps-for-your-web/) is constructed. Using this knowledge, you can manually modify the output from our visual [static map generator](https://www.maptiler.com/cloud/static-maps/generator/), or you can create the URL from scratch. ## By center To define your map image by its center, use this URL format: `https://api.maptiler.com/maps/{mapId}/static/{longitude},{latitude},{zoom}/{width}x{height}.{format}?key=YOUR_MAPTILER_API_KEY_HERE` #### Parameters - **mapId** – The map ID identifies the map (style) that should be used. You can pick any ready-made MapTiler map or your own custom map: [Go to your MapTiler account](https://cloud.maptiler.com/maps/), click on any map, and copy its map ID from the address bar. For example, in the address `https://cloud.maptiler.com/maps//` the map ID is "streets-v4". Your custom maps will have IDs consisting of random letters and numbers. - **lng, lat** – Any location on Earth can be uniquely described by its coordinates: longitude and latitude. [Get your coordinates here.](https://www.maptiler.com/tools/coordinates) - **zoom** – Zoom level can range from 0 (whole world) to 22 (most detailed view). - **width, height** – The image dimensions in pixels. - **format** – The image format, for example `PNG`. See the [API reference](/cloud/api/static-maps/#center-based-image-path-format) for all supported formats. - **key** – Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! _Bearing and pitch aren't supported at the moment._ #### Example [https://api.maptiler.com/maps//static/8.581627,47.137726,16/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE](https://api.maptiler.com/maps//static/8.581627,47.137726,16/825x350.png?key=) ![Define a static map by center point](../img/center-based.png) ### Get HiDPI resolution For Retina and other high resolution displays, add `@2x` before the file extension to increase scale. This renders the map image in double resolution. #### Example [https://api.maptiler.com/maps//static/8.581627,47.137726,16/825x350@2x.png?key=YOUR_MAPTILER_API_KEY_HERE](https://api.maptiler.com/maps//static/8.581627,47.137726,16/825x350@2x.png?key=) ## By bounds To define your map area by a bounding box, use this format: `https://api.maptiler.com/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}?key=YOUR_MAPTILER_API_KEY_HERE` Parameters are the same as in a center-based URL, except: - **minx, miny** – Coordinates of the _lower left_ corner of the bounding box. - **maxx, maxy** – Coordinates of the _upper right_ corner of the bounding box. The most convenient way to get the bounding box coordinates is to use the [visual generator](https://www.maptiler.com/cloud/static-maps/generator/). #### Example [https://api.maptiler.com/maps//static/-70.3,-46.5,70.3,46.5/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE](https://api.maptiler.com/maps//static/-70.3,-46.5,70.3,46.5/825x350.png?key=) ![Define a static map by bounding box](../img/bounding-box.png) ## Auto-fit If you add at least one marker, line, or polygon to your static map, you can use `auto` instead of center or bounds. This will calculate the image area automatically so that all markers and paths in your query are visible. To learn more, see 👉 [Static map with markers](/guides/maps-apis/static-maps/static-map-with-markers/) and [Static map with lines or polygons](/guides/maps-apis/static-maps/static-map-with-lines/). # Static map with markers Source: https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-markers/ To add markers to your [static map](/guides/maps-apis/static-maps/static-maps-for-your-web/), use the `markers` parameter in the URL. Each marker is a `lng,lat` pair of coordinates, with multiple markers separated by pipe symbols `|`. To get the coordinates of a place, use our [Coordinates finder](https://www.maptiler.com/tools/coordinates) tool. ## Basic markers [https://api.maptiler.com/maps/base-v4/static/auto/825x350\.png?key=YOUR_MAPTILER_API_KEY_HERE\&markers\=14\.4,50\.1\|8\.6,47\.4\|2\.4,48\.9](https://api.maptiler.com/maps/base-v4/static/auto/825x350.png?key=&markers=14.4,50.1%7C8.6,47.4%7C2.4,48.9) Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! ![Add multiple basic markers](../img/basic-markers.png) ## Colored markers To style your markers in various colors, add color as a third parameter. You can define color in several ways: - Color names: `red`, `blue` - RGBA: `rgba(255,255,255,0.5)` - Hexadecimal: `#0000ff` (use `%23` instead of `#` in URLs!) https://api.maptiler.com/maps/base-v4/static/auto/825x350\.png?key=YOUR_MAPTILER_API_KEY_HERE&markers\=14\.4,50\.1,red\|8\.6,47\.4,rgba(118,31,232,1\)\|2\.4,48\.9,%23ffaa00 ![Add multiple colored markers](../img/colored-markers.png) ## Custom marker icons To use a custom image as marker, add the necessary parameters in this format: `&markers=icon:{url}|anchor:{position]}|{scale}|{lng,lat}` - **icon** – Specify URL to a remote image. - Max size of the icon image is 4096 pixels (64 × 64) - SVG icons must have explicit width and height attributes - URLs generated by shortener services are allowed - Any specified colors are ignored - **anchor** – Specify the position (anchor point) of the icon relative to its coordinates. - Accepted values: `top`, `left`, `bottom`, `right`, `center`, `topleft`, `bottomleft`, `topright`, `bottomright` - Default is `bottom` - **scale** – Scale of the image icon. Default is `1`, for HiDPI/Retina displays use `2`. - **lng, lat** – Add the [coordinates](https://www.maptiler.com/tools/coordinates) of where to place the marker icon. You can specify multiple places separated by pipe symbols `|`. #### Single custom marker https://api.maptiler.com/maps//static/8\.579446,47\.127792,16/825x350\.png?key=YOUR_MAPTILER_API_KEY_HERE&markers\=icon:https://tinyurl.com/yakrjl3t\|anchor:center\|8\.57916,47\.127899 ![Add a custom marker](../img/custom-marker.png) #### Multiple custom markers _Note that you can only use one custom icon for multiple markers._ https://api.maptiler.com/maps/base-v4/static/auto/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE&markers=icon:https://tinyurl.com/yakrjl3t|anchor:center|14.4,50.1|8.6,47.4|2.4,48.9 ![Add multiple custom markers](../img/custom-markers.png) ## Use case: Office locations Display office or store locations with static map images that link to interactive maps:

Headquarters

Zugerstrasse 22

6314 Unterägeri

Switzerland

Dev center

Tišnovská 137

614 00 Brno

Czech Republic

This example uses our **Static maps API** and **Maps API**. Copy the code snippet here: ```html ``` # Static map with lines or polygons Source: https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-lines/ To add lines or polygons to your [static map](/guides/maps-apis/static-maps/static-maps-for-your-web/), specify coordinates of the individual path vertices as comma\-separated lng, lat pairs. To get the coordinates, use our [Coordinates finder](https://www.maptiler.com/tools/coordinates) tool. You can add multiple lines by using the path parameter several times. Separate the vertices by a pipe symbol `|`. Specify styling before the path coordinates using `key:value` format: - **fill** – Fill color: `red`, `rgba(255,255,255,0.5)`, `#0000ff` (default: `rgba(255, 255, 255, 0.5)`). To draw lines without fill, set the fill property to `none` or `false`. - **stroke** – Stroke color (default: `blue`) - **width** – Stroke width in pixels (default: `1`) - **shortest** – Draw the shortest paths, crossing the dateline if needed. - **enc** – Path encoded with [Google Encoded Polyline Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) (optional): - Example: `_p~iF~ps|U_ulLnnqC_mqNvxq@` - If used, the rest of the path parameter is considered to be part of the encoded polyline string – do not specify the coordinate pairs. You can also use `fill`, `stroke`, `width` and `shortest` as separate query parameters to specify default styling for all the paths. ### Examples Use a line to indicate how to get from a parking lot to a restaurant: https://api.maptiler.com/maps//static/auto/825x350\.png?key=YOUR_MAPTILER_API_KEY_HERE\&path\=fill:none\|width:3\|stroke:red\|2\.1699929237365723,41\.40282721444188\|2\.1697568893432617,41\.40266626487097\|2\.1708834171295166,41\.401801154097434\|2\.172026038169861,41\.40266224112659\|2\.173168659210205,41\.40181724928674\|2\.1750354766845703,41\.403217515495896 ![make map with a line to get from a parking lot to a restaurant](../img/4491445112337_00666f5efb.png) Add multiple colored lines: https://api.maptiler.com/maps//static/auto/825x350\.png?key=YOUR_MAPTILER_API_KEY_HERE\&path\=fill:none\|width:3\|stroke:red\|2\.1751588582992554,41\.40390556628419\|2\.1745795011520386,41\.404336097282346\|2\.17429518699646,41\.40427171899671\|2\.174190580844879,41\.40433408546189\|2\.1740511059761047,41\.4042314825358\&path\=fill:none\|width:3\|stroke:blue\|2\.1751856803894043,41\.403909589951574\|2\.1755397319793697,41\.40361586157709\|2\.17429518699646,41\.402710526042696 ![create-map-with-multiple-lines.png](../img/7922420387985_2a4f48d1b7.png) Use a polygon to highlight a real estate property: https://api.maptiler.com/maps//static/\-80\.40494,26\.11650,16/825x350\.png?key=YOUR_MAPTILER_API_KEY_HERE\&path\=width:3\|stroke:rgba(255,170,1,1\)\|\-80\.40516972541809,26\.11666628740777\|\-80\.40514826774597,26\.116630162087464\|\-80\.40510803461075,26\.116547073808373\|\-80\.40506646037102,26\.116436289344406\|\-80\.40499940514565,26\.116255662275762\|\-80\.40496319532393,26\.116255662275762\|\-80\.40483713150024,26\.116313462968083\|\-80\.40466278791428,26\.116457964573883\|\-80\.40470570325851,26\.11651456098744\|\-80\.40483176708221,26\.116654245635566\|\-80\.40503025054932,26\.116740946367674\|\-80\.40506646037102,26\.116704821070446\|\-80\.40516972541809,26\.11666628740777 ![make a map image with a polygon to highlight a real state property](../img/4491481414033_c21ed4f29e.png) # Use a configurable link to map Source: https://docs.maptiler.com/guides/getting-started/use-map/link/ This page explains how to prepare a simple link to a map, so that it displays the desired map view when users click on the link. All necessary info to show the map is contained directly in the link URL. Here's the general format: `Link text` The link URL is in fact a request to our [Maps API](https://docs.maptiler.com/cloud/api/maps/). Let's see what parameters it contains and how you can customize it. ## Map ID The map ID identifies the map (style) that should be used. You can pick any ready-made MapTiler map or your own custom map: [Go to your MapTiler account](https://cloud.maptiler.com/maps/), click on any map, and copy its map ID from the address bar. For example, in the address `https://cloud.maptiler.com/maps//` the map ID is "streets-v4". Your custom maps will have IDs consisting of random letters and numbers. ## API key The key is necessary to identify you and legitimate users of your maps. If it's missing, the map won't work. Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! ## Location and zoom Any location on Earth can be uniquely described by its coordinates: longitude and latitude. [Get your coordinates here.](https://www.maptiler.com/tools/coordinates) Zoom level can range from 0 (whole world) to 22 (most detailed view). #### Example A map centered on Spain: [https://api.maptiler.com/maps//?key=\#6/40\.018/\-3\.779](https://api.maptiler.com/maps//?key=#6/40.018/-3.779) The position hash is composed of zoom level, map center latitude, and map center longitude. In the example above: - Zoom level \= 6 - Map center latitude \= 40\.018 - Map center longitude \= \-3\.779 ## Bearing and pitch Bearing (map orientation) and pitch (visual tilt) are **optional**. If you don't specify them in the URL, you'll get the default map view: North up and no tilt. #### Examples By adding the bearing and pitch to a map centered on Barcelona, we get a map where the coastline is aligned with the screen: [https://api.maptiler.com/maps//?key=\#12\.83/41\.39474/2\.16377/\-45/60](https://api.maptiler.com/maps//?key=#12.83/41.39474/2.16377/-45/60) - Zoom level \= 12\.83 - Map center latitude \= 41\.39474 - Map center longitude \= 2\.16377 - Bearing \= \-45 - Pitch \= 60 ![Map centered on Barcelona: without bearing and pitch (left), and with bearing and pitch (right).](./tilt.png) _Map centered on Barcelona without bearing and pitch (left), and with bearing and pitch (right)._ If you'd like to show your map view on a webpage directly instead of linking to it, you can [embed it with an iFrame](/guides/getting-started/use-map/iframe/). # Insert map with iFrame Source: https://docs.maptiler.com/guides/getting-started/use-map/iframe/ This page explains how to embed a map in your website with an iFrame, like this: To add a map to your website or blog, you need the HTML code of the iFrame. There's ready-to-use code for each map (including custom maps) in your MapTiler account, so you just need to copy and paste. ## Get your iFrame code 1. Go to [page **Maps**](https://cloud.maptiler.com/maps/) in your MapTiler account. 2. Click on the map you want to use. It can be a standard or custom map. 3. In section **Embeddable viewer**, switch on the **iframe** slider and copy the code. ![Where to get the iFrame code](./iframe-map-code.png) ## Protect the API key The iFrame code looks like this: ```html ``` Note the part `YOUR_DEFAULT_MAPTILER_API_KEY`. In this place, the code contains your actual **default** [API key](/cloud/api/authentication-key/). > [!WARNING] > The default API key in the iFrame code is **not protected**. Use it for testing only! Before publishing the iFrame code, [create a protected key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) that only allows usage on your website. Then replace the default key with the new, protected one. ## Use the iFrame code Once your iFrame code contains a protected API key, you can publish it on your webpage. Insert the code between `` and `` HTML tags where you want to show the map. If you are using a blogging platform, search for a button to switch to HTML code and insert the code in a suitable space between paragraphs. ## Modify the iFrame {#modify-and-move-the-map} The code adds a simple embedded map viewer with basic controls to zoom and navigate the map. You can modify the default look as follows: #### Map size Change the size of the map by modifying `width` and `height`. Alternatively, you can use CSS styling for the element. #### Map style (design) The part `streets-v4` of the sample URL is the map ID. To use another map, replace this ID with your preferred map's ID. #### Location and zoom The part `#2.5/49.34892/15.26930` of the URL gives **#zoom/latitude/longitude** respectively. Move the map preview to update the pre-generated iFrame code automatically to the new place and zoom level. #### Bearing and pitch To adjust bearing (map orientation), and pitch (visual tilt), add these values at the end of the map URL. For example, the sample code adjusted for bearing `-45` and pitch `60` will look like this: `` ![Tilted map view of Manhattan](./manhattan.png) _Example of a tilted map view of Manhattan_ If you want to configure the map controls or create more complex web applications, check out [our JavaScript SDK](/sdk-js/). # Get custom map code examples Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/use-maps-interactively-with-javascript/ The fastest way to integrate a map is by using the pre-configured code examples available in your MapTiler account. You can get these snippets for any map including custom. ## Find your code examples 1. Log in to your [MapTiler account](https://cloud.maptiler.com/maps/). 2. Click on your desired map style. 3. Scroll down for code snippets for various libraries and frameworks. 4. Copy the source code directly into your project. > [!WARNING] > The example code uses your **default API key**, which is only intended for testing. In production environments, you need to [protect your API key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/)! ## Choose implementation method ### Vector style Vector tiles are rendered on the client side using WebGL. They're a fast, lightweight modern technology that delivers smooth zooming and panning experience to end users. To display a map with vector tiles, the API calls the **style JSON** of the map. The style JSON conforms to the schema described in the [GL style specification](/gl-style-specification/). See an [example of a style JSON](https://api.maptiler.com/maps/basic-v2/style.json?key=). We've prepared ready-made code examples to use vector tiles with multiple JavaScript libraries, frameworks, and mobile SDKs. We recommend implementing a vector style map with [**MapTiler SDK JS**](/sdk-js/) which is optimized for MapTiler and services. It supports 3D terrain, globe projection, and automatically handles HiDPI (Retina) displays. ### Raster tiles Raster tiles are pre-rendered images (256x256 or 512x512 pixels). This older technology is typically used in legacy software or in environments with limited hardware resources where WebGL is unavailable. In MapTiler, raster tiles are generally available on [paid plans](https://www.maptiler.com/cloud/pricing/). For HiDPI/Retina displays, use the `(@2x)` suffix. Example: [https://api.maptiler.com/maps/streets-v4/256/3/4/2@2x.png?key=](https://api.maptiler.com/maps/basic-v2/256/3/4/2@2x.png?key=) ### Other options If a JavaScript library is not required, use these standard integration methods: - [Embeddable viewer (iFrame)](/guides/getting-started/use-map/iframe/): For simple map displays without custom coding. - [Web Map Tile Service (WMTS)](/guides/maps-apis/maps-platform/wmts/) and [OGC Tiles API](/guides/maps-apis/maps-platform/ogc-api-tiles/): For integration with GIS software or standardized mapping clients. - [Static maps](/guides/maps-apis/static-maps/static-maps-for-your-web/): To show non-interactive map images. - [Tableau](/guides/maps-apis/maps-platform/how-to-add-maps-to-tableau/): To add MapTiler layers as background maps in Tableau. # How to load maps to desktop GIS Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/how-to-load-maps-to-desktop-gis/ Loading a map in desktop GIS software is simple. If you go in the administration menu on Maps and click one of the maps, you will see on the new page a map and few generated links. Use the link in the Web map service section. If you have the Free or Vector plan, you need to use a different method to load the map (read below). ![1.png](./27865611259793_52fe06a8a3.png) ArcGIS ------ A Web Map Tile Service (WMTS) delivers pre\-generated georeferenced map images. A WMTS service may contain one or more styles, dimensions, or tiling schemes to specify how the WMTS layer is to be displayed. 1. On the **Insert** tab, in the **Project** group, click **Connections \> Server \> New WMTS Server.** The **Add WMTS Server Connection** dialog box appears. 2. Type the URL of the WMTS server site you want to connect to in the **Server URL** text box.  The URL varies depending on the site configuration. 3. Specify the **version** number of the server, if applicable. 4. If the WMTS server you are connecting to has additional capabilities, expand the **Custom request parameters** section and type the custom request parameters specific to this WMTS server as a parameter list. ArcGIS Pro cannot validate these additional parameters. 5. Type your user name and password, if appropriate. To save the user name and password information to Wind Credential Manager or as a connection file, check the **Save Username/Password** check box. 6. Click **OK**. A WMTS connection file (`.wmts`) is created and saved in the project's home folder. An item referencing this connection file is added to the project, and the connection appears in the **Catalog** pane and the catalog view. Right\-click the WMTS service in the **Catalog** pane to add the service to the current map or a new map. Expand the WMTS connection in the **Catalog** pane to access its layers. You can right\-click a layer to add it to the current map or a new map. You can also add the layer by dragging it to the map view or the **Contents** pane. QGIS ---- ### WMS/WMTS In QGIS, click on **Add WMS/WMTS Layer…** in the left menu (shortcut *Ctrl \+ Shift \+ W*) or from the context menu select **Layer** \-\> **Add Layer** \-\> **Add WMS/WMTS Layer…**. In the new window, click **New**, write any **Name,** and paste the generated link into the **URL** bar. Now click on **Connect**, you will get to the list of available layers. Select one and click on **Add**. If you want to change the layer, open the **Add WMS/WMTS Layer…** window again, select your layer from the drop\-down menu a click on **Connect**. **ProTip**: To improve the look of any WMS/WMTS in QGIS, just right\-click on the layer in the **Layers panel**, select **Properties,** and in **Styles** set the **Resampling** method for **out** to **Average**. ### XYZ Tiles Connecting XYZ Tiles to QGIS is similar to the process of connecting a WMTS layer. Just follow these steps: 1. Right\-click the **XYZ tiles** in the left menu. 2. Select **New Connection**... 3. Fill in the **name** and **URL** of **your** **new** **XYZ** tile connection. Set up the **min** and **max** **zoom** **levels** for the visibility of your tiles. **Hit** **OK** to save. 4. **Connect** to your **new** **XYZ** tile layer in the left menu and use the XYZ tile layer in the main window. ### MapTiler QGIS plugin MapTiler QGIS plugin is probably the easiest way of using MapTiler maps with QGIS. Simply install the plugin according to [this guide](https://www.maptiler.com/qgis-plugin/). After that, you can also [browse additional content](/guides/general/maptiler-qgis-plugin) related to MapTiler QGIS plugin or try out the workflow for [maps printing](/guides/maps-apis/maps-platform/how-to-print-and-show-vector-tiles-in-qgis-via-maptiler-plugin). Other GIS software ------------------ There is a similar process for MapInfo, gvSIG, GRASS GIS, uDig, and other GIS software. If you are interested in how\-to open maps in any of these, search for How\-to open WMTS in my\-favourite\-GIS. # How to add maps to Tableau Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/how-to-add-maps-to-tableau/ This article shows how to add any map from MapTiler into Tableau: Get a Tableau TMS file from MapTiler ------------------------------------------ First login to your MapTiler account and go to the [maps page](https://cloud.maptiler.com/maps/). ![StandardMaps.png](./StandardMaps_f205e43546.png) Click on the map style that you want to add to Tableau, it could be one of our standard maps or one of your own creations. Scroll down to the bottom of the options for the map style to find the Download TMS button.  ![CloudTMS.png](./CloudTMS_90b50ce0dd.png) The TMS file contains instructions for Tableau to access your MapTiler Account with your API Key. **Keep your TMS files secure and don't share them as they contain your API Key.**They will be saved in the same location as your regular browser downloads. Import your map into Tableau ---------------------------- To import maps from MapTiler to Tableau we recommend using one of the [**Tableau templates**](https://help.tableau.com/current/pro/desktop/en-us/buildexamples_maps.htm) with **imported maps**, for example, the Regional project template. ![tableau_screen_templates.png](./14246430458001_eafac9bfae.png) Tableau has a feature that prevents users from making charts without the correct type of data. Therefore your data **needs to have a** **geographical element** to be able to add a map. If your data has a **zip code** or **X and Y coordinate columns** you can designate these as geographical and then add a map. However, it is easier to use an existing project though as it is not always that easy to get coordinates work! When you have opened Tableau and chosen your project template, click on the window with the original map and you can import the TMS file here:  *Map* \-\> *Background Maps* \-\> *Manage Maps...* ![](./file_e54d30070e.png) Click on the *Import...* button ![](./file_ba36bf5ead.png) Import your TMS file and enjoy the beautiful map from your MapTiler account! ![](./file_ba26b3602a.png) Want to add maps from MapTiler Server? Read this: [On\-premise Tableau maps](/guides/self-hosting/map-server/on-premise-tableau-maps) Useful links ------------ [On\-premise Tableau maps](/guides/self-hosting/map-server/on-premise-tableau-maps) [How to upload map style to MapTiler](/guides/map-design/how-to-upload-map-style-to-maptiler-cloud) # Map design Source: https://docs.maptiler.com/guides/map-design/ Need a map with custom look? No problem, our no-code [**Map Designer**](https://cloud.maptiler.com/maps/editor) tool makes that possible. You can define every single aspect of a map's visual style to get exactly the result you need. 👉 [Get started with Map Designer](/guides/map-design/maps-and-styles-basics/) > [!INFO] > Note that map design is about styling elements on the map, such as lines or icons, which is only possible on maps that use [vector tiles](/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/). Customizability of maps that only consist of raster tiles (standard images) is very limited. Likewise, if you need to create a map using your own imagery, you won't be "designing" the map but rather [adding your images](/guides/getting-started/add-data/#add-images) on top of an existing map as an overlay. ## Tutorials Many tasks in map design can be achieved in two ways: programmatically using our [SDK JS](/sdk-js/), or in our visual [map design editor](https://cloud.maptiler.com/maps/editor). We have tutorials for both: - [Developer tutorials](/sdk-js/examples/) and code examples for the SDK JS - [No code tutorials](/guides/getting-started/map-design-tutorials/) for the visual editor ### Use dark mode We have distinctive [light](https://www.maptiler.com/maps/light/) and [dark](https://www.maptiler.com/maps/dark/) map modes, so you can simply use them via presets in our [SDK JS](/sdk-js/) without having to design them first. 👉 [How to use the dark mode](/sdk-js/examples/?q=dark+mode) ## Advanced resources Our online resources include all our maps, additional data that you can enhance the maps with, and detailed specifications of both to help you out with advanced design tasks. ### Map styles A map consists of two things: raw map data and a **map style** document (JSON), which defines the design of the map and visual styling of the data in it. - [Available map styles](https://cloud.maptiler.com/maps/) for instant use or customization - [GL style specification](/gl-style-specification/) for advanced style config and creating map styles by hand ### Datasets Raw map data come in **datasets** of several types. Most MapTiler data is packaged in **tilesets** containing [map tiles](/google-maps-coordinates-tile-bounds-projection/) ready for building zoomable maps. - [Available datasets](https://cloud.maptiler.com/tiles/) with global, up-to-date data to add to your maps - [Dataset documentation](/guides/getting-started/datasets/) to learn what datasets we offer and how to use them - [Schemas](/schema/) with detailed description of our vector tilesets # Editor interface Source: https://docs.maptiler.com/guides/map-design/maps-and-styles-basics/ This page explains the basic concepts and controls of our no-code map design editor [Map Designer](/guides/getting-started/map-design/) to help you get around its interface. ## Navigating the editor There are four panels on the left, each specific to map styling:  - **Quick edits** (Alt + Q) to easily adjustment map color palette and fonts. See [Quick map editing](/guides/map-design/quick-map-editing/). - **Layers** (Alt + L) for complex styling of individual or multiple layers, filtering data or writing JSON. - **Settings** (Alt + S) for setting global map options such as language, borders, or initial position. - **Data sources** (Alt + D) for adding, removing, or replacing map data sources or checking data details. ![Map Designer main panel](./map-designer-panel.png) ## What's what **Map Style =** a unique map, either one of MapTiler's default styles or your own style. **MapLibre style/style.json** = a JSON document that defines the visual appearance of a map: colors, layer order, data sources, etc. (every map style is a `style.json` file). This is what you get when you download a map style. **Layer =** an entity in a map containing specific map features that are styled together (Road network); takes the data from a data source layer, optionally filters features, and defines how those features are styled. **Block** = a group of layers. **Verticality** \= order of the layers in the map; the first one is rendered on top. **Style/Data =** style panel serves for map design/data panel handles filters, geometry, or type of visualization. **Filter** \= specifies conditions on source data; only features that match the filter are displayed in the map. * Filter Logic: **All** \= returns `true` if all the inputs are `true` * Filter Logic: **Any =** returns`true`if any of the inputs are`true` * Filter Logic: **None** \= returns `true` if none of the inputs are `true` **Attributes** \= information linked to the data that describes features and is used for filtering: class, admin\_level, rank, name etc. **Layout properties** \= define how data for a layer is passed to the GPU; icon or text size, font, offset, visibility, text-field etc. **Paint properties =** are applied later in the rendering process and happen synchronously: color, opacity, halo, width, etc. **Icon** \= properties for styling small images (icons) representing point data. **Text** \= properties for styling text labels such as font, size, or justification. **Fill** \= properties for styling fill of polygons such as color, opacity, or pattern. **Outline =** properties for styling lines or borders of polygons: color, opacity, width, or style (dash array). **Layout =** influences the placement of features: anchor, padding, overlap, etc. **Effects** \= includes blur of lines. **Default View** \= defines the initial position of the map with the zoom level, map center (latitude, longitude), tilt, and rotation angle. **Font Fallback** = a font to which your default font switches in case of unsupported characters (Arabic, Cyrillic etc.). **Data source =** source of map features (tiles or other data formats). Every layer needs to have one. **Data layer** \= an entity in a data source containing specific map features. **Geometry** \= encoding of geographic data, related to data representation: Polygon, LineString, Point etc. **Visualization** \= specifies the styling options; Polygon, Line, Point, Symbol, Heatmap etc. **Save** = saves a map or your changes in the MapTiler interface. **Publish** = publishes your changes into production across all your apps where the map is embedded. # Global map settings Source: https://docs.maptiler.com/guides/map-design/global-map-settings/ This page explains **Global map settings** in MapTiler Map Designer. You can find this panel as a **third icon** on the left side menu or use the **Alt\+S** shortcut. ## Worldview The worldview section of the Settings allows changing map **language**, **translation**, **units,** and **borders**. ![global-settings.png](./21513603860113_b40fd72b12.png) ### Language The language menu contains many **different world languages** or a **local** option. Local is the native language of the country where the map feature is located. All MapTiler styles have the **"Defined by style"** option selected by default. This means there is a combination of languages selected by our cartographers. ![global-language.png](./21513590475921_965f4c4901.png) If the data have different languages tagged in the `name` attributes, it will change with this setting. You can check this after clicking on a specific layer and switching to the Data tab. ![settings-data.png](./17594195616017_6ea3a3c004.png) ### Translation To enable translation, you need to **select a language** for your map. You can then add labels in any other language **under** your initial language choice. ![global-translation.png](./21513590484753_dde452a36f.png) ### Units Units allow switching between **meters and feet** globally. You will see this setting only if there are layers with units in your map. By default, [Outdoor](https://cloud.maptiler.com/maps//), [Winter](https://cloud.maptiler.com/maps//), [Topo](https://cloud.maptiler.com/maps//) and [Ocean](https://cloud.maptiler.com/maps//) map styles include it. This setting is visible in mountain peaks' elevation or contours. MapTiler styles have the **"Mixed"** option selected by default. This means there are Feet used for the US, whereas the rest of the world uses Meters. ![global-units.png](./21513590495505_b9bdf71cf2.png) ### Borders In the Borders settings, users can choose their **preferred disputed borders** view. More details can be found in this [article](/guides/map-design/disputed-borders-on-your-maps). ![settings-borders.png](./17594180144785_aecb376069.png) ## Default view The default view defines the **initial rendering position** of the map with the zoom level, latitude, longitude, tilt, and rotation. The default position of MapTiler maps is zoom level 1 with all other properties on zero. ![settings-default-view.png](./17594180148753_f0d880694b.png) If you want to have a map's specific position as the default view, use the icon next to it (**Set current view**). ![default-view-current.png](./17594195643153_2f6d2c1c5a.png) ### Zoom level Zoom level defines the level of detail that can vary from value **0 to 22**. Zoom level can be changed by scrolling in the map or typing it in the **upper right corner**. You can also use a **set current zoom level** button. ![default-view-zoom.png](./17594180157713_811c0df01c.png) ### Latitude, longitude Lat and lon coordinates define the **center of the map**. Both are measured in **degrees**. If you are not sure about the coordinates of a place, get them easily in our Coordinate Finder. ![default-view-lat-lon.png](./17595061687441_db977f0950.png) ### Tilt and rotation You can tilt or rotate the map with your **right mouse button** or with the **clock symbol** in the upper right corner of the map. ![default-view-tilt.png](./17595076368785_06c01893b7.png) ## Font fallback In global maps, it is important to think about the font’s ability to **draw different scripts**. Your default font will switch to the fallback font in case of **unsupported characters**. We include **Noto Sans** and **Serif** in the drop\-down menu as it supports Arabic, Cyrillic, Greek, Chinese, or Japanese scripts as well as Latin. ![settings-fallback.png](./17595076370449_5135e8969f.png) ## Conclusion Settings (Alt\+S) in MapTiler Map Designer allow users to adjust **languages**, **units,** or **borders** in their maps or **change the initial map position** based on zoom level, latitude, longitude, or tilt and rotation. ## Next steps Continue to [Disputed borders on your maps](/guides/map-design/disputed-borders-on-your-maps/) to learn how to display the borders according to the selected country’s policy. ## Useful links [Change language in a map](/guides/map-design/change-language-in-a-map) [Disputed borders on your maps](/guides/map-design/disputed-borders-on-your-maps) [Contours and mountain peaks in feet](/guides/map-design/contours-and-mountain-peaks-in-feet) [Languages \| MapTiler Planet schema](https://docs.maptiler.com/schema/planet/#languages) # Quick map editing Source: https://docs.maptiler.com/guides/map-design/quick-map-editing/ This page explains how to use the **Quick edit** panel in our no-code map design editor [Map Designer](/guides/getting-started/map-design/) to do basic design tweaks. ## Change colors In the first section of the panel, it is possible to adjust map colors in two ways. 1\. Change the map appearance in a color picker. ![quick-edits-colors.png](./17654865485841_8a0384c382.png) 2\. Shift hue, saturation, or lightness. ![quick-edits-hsl.png](./17654865490065_91b6cf9bea.png) ## Change fonts Text fonts can be changed in the bottom section called Map Typography. Click on a used font and select a different font family and style. ![quick-edits-fonts.png](./17654909812497_c7969a2beb.png) ## Other settings Other settings, such as map language, units, borders, or position, can be changed in the Settings panel (Alt\+S). More information about this is in the [Global map settings](/guides/map-design/global-map-settings) article. ## Next steps Once happy with your edits, [save and publish your map](/guides/map-design/how-to-publish-a-map/). # Layer styling Source: https://docs.maptiler.com/guides/map-design/layer-styling/ This page describes how to **style map layers** in MapTiler Map Designer. This way, you can adjust colors in any MapTiler map to your brand design. You can also style multiple layers at once and use advanced paint properties. ## How to style a layer Go to the **Layers panel** (Alt\+L) and click on a preferred layer. By clicking on paint properties such as **Fill** or **Outline**, you will get to a **color picker**. You can also adjust the color **opacity**. ![layer-styling.png](./17414968501009_f677981e01.png) ### Polygon styling Layers visualized as polygons have two main paint properties \- **Fill** and **Outline**. If a map has loaded [sprite](/gl-style-specification/sprite/), you can also pick a **pattern**. ![polygon-styling.png](./17414968505873_bef4fa1a4b.png) MapTiler maps with sprites included by default: - [Bright](https://cloud.maptiler.com/maps//) - [OpenStreetMap](https://cloud.maptiler.com/maps/openstreetmap/) - [Outdoor](https://cloud.maptiler.com/maps//) - [Streets](https://cloud.maptiler.com/maps//) - [Toner](https://cloud.maptiler.com/maps//) - [Topo](https://cloud.maptiler.com/maps//) - [Winter](https://cloud.maptiler.com/maps//) ### Line styling Layers visualized as lines don't have the option to adjust the Fill color (because of the [GL Style Specification](/gl-style-specification/layers/#line) that doesn't support line\-fill property). You can adjust **Outline** color, **opacity,** and **width** or specify **a blur** under the **Effects.** **![line-styling.png](./17414968508433_c0690060af.png)** A specific paint property for lines is a **dash array** under **Advanced outline properties**. The format is: `number, number` (**lengths** of the alternating dashes, **gaps** that form the dash pattern). Dashed lines are commonly used for borders, roads under construction, intermittent rivers, or paths. ![dasharray.png](./17414985484817_b31ad1d145.png) ### Symbol styling Layers visualized as symbols have **Fill** and **Outline** paint properties. You can also add **icons** that will differentiate between Icon and Text paint properties. ![symbol-styling.png](./17414985487249_03d9145449.png) To adjust the position of labels, go to the **Layout** properties (scroll down in the Style tab). ![layout-properties.png](./17414968518801_78ba44a681.png) ### Raster styling Rasters have specific paint properties depending on the data. For example, in [MapTiler Satellite](https://cloud.maptiler.com/maps//) map, you can adjust contrast, hue, saturation, or brightness. ![raster-styling.png](./17414968520849_9b0ebe6808.png) ### Hillshade styling Many of our maps contain hillshading that adds perspective to mountainous terrain and ocean depths. To learn about hillshading layers and how to customize them, see section [Terrain styling](/guides/map-design/terrain/hillshading/). ## Styling of multiple layers MapTiler Map Designer allows the styling of multiple layers at once: **hold Shift while selecting**. To change the styling, click on the paint properties with multiple values, **reset** them to default, and then style. Layers need to be of the **same visualization [type](/gl-style-specification/layers/#type)**! ![multiple-layers.png](./17415917529105_feef8a5185.png) ![multiple-layers-reset.png](./17415933644433_dc1013280e.png) ## Next steps Continue to [Style by the zoom range](/guides/map-design/style-by-the-zoom-range/) to learn how to style your maps based on the zoom level in MapTiler Map Designer. ## Useful links [Style by the zoom range](/guides/map-design/style-by-the-zoom-range) [Add a new style layer](/guides/map-design/add-a-new-style-layer) [Using sprites](/guides/map-design/using-sprites) [GL Style Specification](/gl-style-specification/) # Style by the zoom range Source: https://docs.maptiler.com/guides/map-design/style-by-the-zoom-range/ This page describes how to **style your maps** based on the **zoom level** in MapTiler Map Designer. You can assign different colors, text sizes, or line widths on different zoom level ranges. ## Zoom range styling panel You can find the panel after clicking on a layer in the **Layers tab** (Alt\+L) \> hover on any **styling property** \> click on **three dots**. ![zoom-styling-panel.png](./17583042987665_f3561d4a31.png) In the [Dataviz map](https://cloud.maptiler.com/maps//), we are using zoom range styling for both the **outline color** and **width** of the Country border layer. ![zoom-styling-outline.png](./17582997139345_b0fd040bc6.png) ![zoom-styling-width.png](./17583042991377_0351e6e76d.png) ## How does it work In the panel, you can **remove** or **add** the zoom level range stops and **adjust their values**. In the case of colors, a color picker will appear. ![zoom-styling-colors.png](./17583042993937_e310ba6256.png) You can check the desired changes when adjusting the zoom level on the map. The zoom range will also be changing in the color UI. ![zoom-styling-check.png](./17583042995345_b73f8a77bb.png) Besides colors, you can use zoom range styling for a variety of properties: line width, pattern, offset, blur, opacity, text size, justify, anchor, etc. Some of the styling properties don't support the zoom range styling yet. You will get a notification for this. ![zoom-styling-not-supported.png](./17582997144081_b143e018f8.png) ## Function types There are 4 function types that you can use in zoom range styling: 1. **Linear interpolation** 2. **Exponential interpolation** 3. **Cubic Bezier interpolation** 4. **Steps** ![zoom-styling-functions.png](./17583424110737_e23574c9b6.png) **Interpolation** produces **continuous**, smooth results by interpolating between pairs of input values.  **Steps** produce **discrete** results (changes are visible between zoom levels). More details can be found in the [GL Style Specification](/gl-style-specification/expressions/#interpolate). ## Conclusion You can **style your maps based on zoom levels** in MapTiler Map Designer. Go to the **Styling tab** of a specific layer and click on the **three dots** to access the zoom range styling panel. **Remove** or **add** the zoom level range stops and **adjust their values**. There are 4 available function types: linear, exponential, and cubic bezier interpolation and steps. ## Next steps Continue to [Add a new style layer](/guides/map-design/add-a-new-style-layer/) to learn how to add a new style layer to a map in MapTiler Map Designer. ## Useful links [Layer styling](/guides/map-design/layer-styling) [Interpolate \| GL Style Specification](/gl-style-specification/expressions/#interpolate) [Step \| GL Style Specification](/gl-style-specification/expressions/#step) # Add a new style layer Source: https://docs.maptiler.com/guides/map-design/add-a-new-style-layer/ This page describes how to **add a new style layer to a map** in MapTiler Map Designer. Adding a new style layer ------------------------ Go to the **Layers panel** (Alt\+L) and click the **"plus"** button next to search. Select the **Layer** option. ![add-layer.png](./17472335038609_8e9a1b2039.png) **1\. First, select a source layer from data sources**. ![add-layer-1.png](./17491407635857_582bcd13b4.png) Data sources include **MapTiler data** such as MapTiler Planet, Contours, Terrain RGB etc. or **your own datasets**. (More details about data sources can be found [here](/guides/map-design/data-sources).) In this example, we chose a house number source layer from MapTiler Planet. ![choose-source-layer.png](./17475279805713_d12de17254.png) **2\. Specify the layer's data content**. Here you should choose the **geometry** of the layer, and if needed, you can **filter** out only specific values. Some layers can have multiple options of geometries. For example, the transportation layer can be both a LineString or Polygon. We choose Point for a house number (as this is the only option), and we won't be filtering any data. ![layer-content.png](./17476070633361_2e4bec05dd.png) **3\. Include the layer into your map.** In this step, you select a parent **block**, **visualization** type, and layer **name**. Visualization options depend on the geometry of the data layer.  For our house number layer, we used Symbol visualization. ![include-layer.png](./17476070641809_03639ceb0f.png) By clicking on Add layer, your new style layer will be added to your map with **default settings and colors**. ![added-layer.png](./17476070644113_93da64a737.png) You can easily adapt these. Layer styling is explained in this [article](/guides/map-design/layer-styling). You can also change the **order** of the layer in the **Verticality** tab. ![style-layer.png](./17476070647441_cc74c05b43.png) Geometry vs visualization ------------------------- Geometry and visualization menus appear when adding a new style layer or working with already added layers. **Geometry** is related to **data representation,** whereas **visualization** specifies the **styling** options. Let's illustrate this on a Bridge layer. Bridge geometry can be either a **Polygon** or **LineString**. If you select Polygon, you will get areas of bridges that you can style.  ![geometry-polygon.png](./17494040316817_9be0147a5c.png) Bridge visualization can be a **Polygon, Line, Extrusion or Symbol**. However, don't mix the Line visualization with LineString geometry. If you select Line visualization, you will still get bridge areas, only with a colored outline. ![visualization-line.png](./17494040319889_4d3186ab79.png) If you select LineString geometry, you get bridge lines. ![geometry-linestring.png](./17494040322193_6de9e420e4.png) You can visualize the LineString geometry as a **Line, Symbol, or Heatmap**. ![visualization-line-2.png](./17501792724369_ad6b20a760.png) The options available for visualization always depend on the geometry type. See the table below. | **Geometry** | **Visualization** | | --- | --- | | Point | Point, Symbol, Heatmap | | LineString | Line, Symbol, Heatmap | | Polygon | Polygon, Line, Extrusion, Symbol | | Mixed | Polygon, Line, Extrusion, Symbol, Heatmap | | Terrain/hillshade layers | Hillshade | | Raster/satellite layers | Raster | More information about the visualization options can be found in [GL Style Specification](/gl-style-specification/layers/#type). Geometry types encoded in MBTiles are based on the [MVT spec](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#434-geometry-types). Conclusion ---------- In MapTiler Map Designer, adding a new style layer consists of **3 simple steps** after clicking on the **"plus"** **button** in the **Layers panel** (Alt\+L): 1. select a source layer from data sources, 2. specify the layer's data content, 3. include the layer in your map. After adding, you can select a **geometry** and **visualization** type. Geometry comes from the nature of the original data processed to MBTiles. Visualization types depend on the geometry and allow different options for styling. ## Next steps Continue to [Layer filters](/guides/map-design/layer-filters/) to learn how layer filters in MapTiler Map Designer work. Useful links ------------ [Data sources](/guides/map-design/data-sources) [Layer styling](/guides/map-design/layer-styling) [Layer filters](/guides/map-design/layer-filters) [Layer type \| GL Style Specification](/gl-style-specification/layers/#type) [Geometry types \| MVT spec](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#434-geometry-types) # Layer filters Source: https://docs.maptiler.com/guides/map-design/layer-filters/ This page explains how layer filters in MapTiler Map Designer work. With layer filters, the user can select**data** in the map based on various **data attributes**. Thanks to MapTiler Map Designer, you do not need to have deep knowledge about the datasets as the tool shows all the data information on UI. Source selection, layer, geometry --------------------------------- To work with layer filters, click on a specific layer and go to the **Data tab**. By clicking on a "plus" button, you will see what **attributes** you can filter out in your map. ![filter-attributes.png](./17327051966225_9f2dbc0af6.png) Apart from filters, you can choose your preferred [Data source](/guides/map-design/data-sources), Data layer, or Geometry.  ![data-panel.png](./17327075908113_490abd791c.png) Inspect mode ------------ When switched to the Data tab, you can inspect the map on the right side, **click** on it and discover what **attributes** are stored in the data.  ![filter-inspect.png](./17327075915281_9adf1e5d88.png) This is similar to Inspect mode in the Maputnik editor. The attribute values can be **copied with a click** and then used in the filters.  You can also inspect your data in the **Data sources panel** (Alt\+D) and check what Layers you use a specific data source in. ![data-sources.png](./17327075918225_b1787c23d7.png) Attributes \- How to filter by class ------------------------------------ Every layer has a specific set of attributes. The most common for MapTiler data is a **class**(used for classification or hierarchy of map features). A list of classes is available after adding a new Filter \> **Filter by attribute: class**. ![filter-class-add.png](./17327051978257_f4e3ff5b77.png) For example, water can have various classes, such as lakes, oceans, or rivers. ![filter-class-water.png](./17327075923217_f8b000e5fe.png) The filter format can also be switched from Visual to Native, which is similar to the JSON code. ![filter-native.png](./17327051983633_ec8f9e2176.png) With filters UI, you can either select all values, multiple values, or one specific value. ![filter-select-one.png](./17328873889937_47731b1da6.png) Many other attributes apart from class can be filtered. It depends on what data and layer you are adjusting. The list of attributes is always visible once you click on the "plus" button to add a new filter. Some examples include subclass, name (mostly for labels), oneway, tunnel, toll or ramp for transport etc. Other values of attributes -------------------------- Attributes always have a **"No value" option**. This is to ensure that you can select data without any attribute value filled in. If you would like to omit this (recommended mostly for labels), unselect the No value option. ![filter-no-value.png](./17328841042065_fcebb07f76.png) Some filters can also have an **"All values" option**. This option appears for unique values which would not fit into a list (such as capital city names). ![filter-all-values.png](./17329182833169_c695bdcdff.png) Conclusion ---------- MapTiler Map Designer allows users to filter any data attributes. You get a list of possible values on UI or you can inspect the map and copy the values from there. ## Next steps Continue to [Working with Icons](/guides/map-design/working-with-icons/) to learn how use a set of icons for displaying points of interest, highway shields, peaks, etc. # Publish a custom map Source: https://docs.maptiler.com/guides/map-design/how-to-publish-a-map/ When you're finished customizing a map in Map Designer, you need to **save** and **publish** your edits. This page explains what "publishing" means and what to do next. ![Save and publish map edits](./map-save.png) ## Publishing a new map When you're publishing a custom map for the first time, you're making it accessible through our Maps API. This means that your new map is ready to be added to a public website or app, but it's **not actually visible to anyone**. You can safely ignore the warning that publishing will affect web apps that use this map, because the map is new and not used anywhere yet. To actually share your new map with the world, you need to take further steps: After publishing, the map is listed [in your MapTiler account](https://cloud.maptiler.com/maps/), section **My maps**. Now you can use it just like a ready-made MapTiler map – add it to a website, embed in a blogpost, use it in mobile app, via WMTS service, in a GIS app, and in many other ways. 👉 **[How to use your map](/guides/getting-started/use-map/)** ## Updating an existing map If you're publishing updates of an existing custom map, the changes will make their way to all the places, webs and apps, where the map is publicly used. > [!INFO] > Please note that the changes may take up to 1–2 hours to propagate everywhere due to caching, various browser types, or network issues. We recommend publishing changes to your map styles outside peak usage periods. # Customize map icons Source: https://docs.maptiler.com/guides/map-design/icons/ Maps use **icons** to display points of interest (POIs), landmarks, road shields, and other features. These icons come in **icon sets** where all icons are visually consistent. You can either use our professionally prepared catalog sets, or create your own custom sets and use them across multiple maps. This page explains how to customize and manage your map icons using our visual editor **[Map Designer](/guides/getting-started/map-design/)**. If you're looking for a programmatic way to work with icons, check out [icon code examples](https://docs.maptiler.com/sdk-js/examples/?q=icon) for MapTiler SDK JS. ![Standard catalog icons in our Winter map (left) vs custom icons](./icons-custom.png) *[Winter map](https://cloud.maptiler.com/maps/winter-v4/) with standard catalog icons (left) and with custom icons* ## Customize catalog icons **Catalog icons** are our default map icons. When you customize our maps, you can customize the icons too: 1. In your MapTiler account, [page **Maps**](https://cloud.maptiler.com/maps/), click on the map you want to use. It can be any map including custom. 2. Under the map preview, click **Customize**. This opens the map in [Map Designer](/guides/getting-started/map-design/). 3. Go to menu **Layers** and open the block and layer which contains the icon you want to customize. If you're not sure which layer it is, click on the icon in the map and you'll get a list of blocks and layers in that spot. The icon layer is typically at the top. ![Show the icon layer](./show-layers.png) 4. Adjust icon properties as needed: fill color, outline, opacity, size, and anchor (relative position of the icon and label). You can also swap the icon image with another one. ## Prepare custom icons For a fully custom map, you'll typically need a complete set of custom icons, which you need to prepare in a graphic design program. This section explains the technical requirements for best results. ### Size and count {#limits} To ensure map performance and compatibility with all devices, icon sets have the following constraints: * **Icon size**: Maximum 256×256 px. For better downscaling and sharper rendering, we recommend to prepare icons in even-pixel dimensions (e.g. 24×24 px). * **Icon count**: Maximum 500 icons per set. * **Total sprite size**: The generated sprite sheet is the "canvas" for all your icons. Its size is the hard limit which cannot exceed 4096×4096 px. > [!NOTE] > The icon size and count are "soft" limits that affect one another. You can upload up to 500 icons if they are smaller in dimension, but significantly fewer if they are near the maximum 256px resolution as they would exceed the total sprite sheet size. ### Icon format {#format} When preparing your icons, use **vector (SVG)** or **raster (PNG)** format: #### Vector (SVG to SDF) Vector icons are recommended for most map features. We save them in the **SDF (Signed Distance Field)** format, which is technically raster, but preserves the benefits of vector: the possibity to customize the icon's fill color, outline, and size while maintaining sharp edges. Vector icons must be monochrome. Color, outline and other properties are defined per map, which means that you can reuse a vector icon set across multiple maps and have it customized differently in each of them. Another benefit is that you can customize the icons along with their label. **Turn off customizability** You can choose to upload and use SVG icons but turn off the "customizable" (SDF) option. This makes the vector icon behave like a raster; it will preserve its original colors but cannot be recolored in the map editor. #### Raster (PNG) Raster icons are static images where the colors are already "baked" into the file. You cannot customize them in any way. Use the raster format for multicolored icons, photos, or complex patterns that need to stay exactly as they are. ### Resolution {#resolution} For high-res mobile or desktop screens, you can provide **2× or 3× resolution** versions to ensure your icons don't look blurry on modern devices. We also recommend to use this setting to preserve detailed, pixel-perfect design of large icons such as landmark images. ## Manage your icons To upload a new icon set or manage any of your custom sets, go to the icon set management. You can open it from any map: 1. In your MapTiler account, [page **Maps**](https://cloud.maptiler.com/maps/), click on the map you want to use. It can be any map including custom. 2. Under the map preview, click **Customize**. This opens the map in [Map Designer](/guides/getting-started/map-design/). 1. Open the "hamburger" menu → **Icon sets**. ![Open icon set management](./settings-icons.png) 2. To add a new set, click the **(+) plus button**. You can upload icons individually or in a ZIP file. > [!WARNING] > The icon management page is global and lists **all your custom icon sets** across all your maps. Editing a set here will affect every map where it is used, not just the one you're currently working on. # Working with Patterns Source: https://docs.maptiler.com/guides/map-design/working-with-patterns/ Every map can use its own **set of icons** for displaying points of interest, highway shields, peaks, etc. In special cases, maps can also include **patterns**, helping users distinguish between similar polygon features. A set of icons and patterns and a file defining which icon should be used for what purpose is called a **sprite**. ## Patterns in MapTiler maps The Pattern selection dialogue can be found in the **Fill properties** of your **polygon** layer. It is best practice to add the pattern to a duplicated layer positioned on top of the original one. This way, you also keep the underlying color of the area. ![fill-pattern.png](./28402462400017_28b882e29a.png) **Patterns currently don't support change of colors!** Patterns are saved as rasters, meaning their color is encoded within them and cannot be changed in the interface. Patterns prepared by our team can be found in the [Aquarelle](https://cloud.maptiler.com/maps//), [Toner](https://cloud.maptiler.com/maps//), and [OpenStreetMap](https://cloud.maptiler.com/maps/openstreetmap/) map styles. ![aquarelle.png](./28402471663121_e02757d5a6.png) ## How to create patterns Patterns can be created in graphic software such as Inkscape or using [HTML & JavaScript](https://snailbones.medium.com/halftone-bathymetry-in-maplibre-gl-js-b143651410c2). The pattern shape has to be **seamless**, as it will repeat across your map features. We recommend using an even amount of pixels for better downscaling. You can also use patterns from available libraries, such as [Hero Patterns](https://heropatterns.com/), provided you follow the licensing conditions. ## How to upload custom patterns We recommend working with raster patterns; vector icons are not suitable for repeating shapes and might distort your graphics. You can upload patterns with the **Raster icons (or mixed format)** option. This upload option allows for either **individual PNG files** or a **zipped** format.  ![patterns-upload.png](./28402462409361_2d0c8d3261.png) When you upload a new set of patterns, you automatically lose the previous one. **Map Designer currently doesn't support multiple icon sets.** If you need to combine your patterns with a MapTiler icon set or patterns from the maps, please contact [MapTiler Support](/support/requests/). ## Patterns in cartography Patterns are **repeating**, often geometric shapes used across maps to enhance the **readability** or category **distinction** of polygon areas. Patterns are **seamless** so that they can be used for various sizes of data and different zoom levels. They are particularly useful for **color\-blind\-friendly** maps, helping users to distinguish areas not only by color but also based on texture. Patterns can be **composed of shapes** such as lines, dots, circles, squares, crosses or even symbols like trees or flowers. **Hatchings** are a special category of patterns that are composed of lines only. ![preview.png](./28402462405649_137f833210.png) Patterns usually help to visualize landcover areas against the background. As there are many real\-world features with the same color scheme association (green for forests, grass, farmland, vineyards, etc.), users can experience a hard time telling them apart. Such an example is the garden pattern in the [OpenStreetMap](https://www.maptiler.com/maps/#style=openstreetmap&mode=2d&position=16.14/51.527072/-0.153332) style that helps to distinguish the garden areas from grass. ![osm-patterns.png](./28402471668497_45b99b130a.png) Patterns can also represent different values within a category, typically for a choropleth map. Different parameters can be used for visualizing the increasing intensity of your data values: - thickness (for lines) or size (for points) - density - direction - combination of the above ## Next steps Continue to [Using Sprites](/guides/map-design/using-sprites/) to learn what is a sprite and how to use it in your maps. ## Useful links [Maps & styles basics](/guides/map-design/maps-and-styles-basics) [Layer styling](/guides/map-design/layer-styling) [GL Style Specification | Sprite](/gl-style-specification/sprite/) [How to style a pop\-art map](/guides/map-design/how-to-style-a-pop-art-map) # Add custom watermark to your map Source: https://docs.maptiler.com/guides/map-design/add-custom-watermark-to-your-map/ Watermarks can help protect your map against misuse or serve as a means of brand promotion. It's easy to include a custom watermark on a MapTiler map with the **Map Designer** tool. ## Preparing watermark image Make sure your watermark image is in the supported format (PNG or SVG), with **transparent** **background**. For SVGs, make sure the **texts are converted to paths**. This can be done using for example [Inkscape](https://inkscape.org/) or other graphics software. ## Add watermark to your map Go to your map, click on Customize and then on the **Upload Icons** button. ![upload-icons.png](./27555038316945_853a500cf8.png) In the next dialogue window, choose the second option **Raster icons (or mixed format)**. Select your watermark image and click on Upload.  ![raster-icons.png](./27555054169233_1c540b4973.png) To display the watermark across the whole map, **duplicate the Background** layer and move it to the **top** using the Verticality tab. Then select your watermark image in the **Pattern** property. You can also adjust the Opacity to make the watermark more subtle. ![watermark2.gif](./27635796291985_74a1ad00df.gif) ## Keeping maps original icons When you upload a new set of icons (e.g. your watermark), you automatically lose the previous one. **Map Designer currently doesn't support multiple icon sets!** If you need to combine your icons with MapTiler icon set, please contact [MapTiler Support](/support/requests/) for the individual SVG files. This concerns the following map styles: - [Bright](https://cloud.maptiler.com/maps//) - [Landscape](https://cloud.maptiler.com/maps//) - [OpenStreetMap](https://cloud.maptiler.com/maps/openstreetmap/) - [Outdoor](https://cloud.maptiler.com/maps//) - [Topo](https://cloud.maptiler.com/maps//) - [Toner](https://cloud.maptiler.com/maps//) - [Streets](https://cloud.maptiler.com/maps//) - [Winter](https://cloud.maptiler.com/maps//) Learn more about: - [Icons](/guides/map-design/working-with-icons) - [Patterns](/guides/map-design/working-with-patterns) - [Sprites](/guides/map-design/using-sprites) ## Next steps Continue to [Change language in a map](/guides/map-design/change-language-in-a-map/) to learn how to change language in a map in the MapTiler Map Designer Settings panel. # How to style individual buildings Source: https://docs.maptiler.com/guides/map-design/how-to-style-individual-buildings/ Do you want to **highlight specific buildings** on your map? On this page you'll learn how to isolate selected buildings so you can style them in custom colors or apply 3D extrusion to make them literally stand out. ![Styled buildings](styled-buildings.png) ## Add a new building layer The layer that contains filterable building details isn't included in our maps by default, so the first step is to add it: 1. In your MapTiler account, [page **Maps**](https://cloud.maptiler.com/maps/), click on the map you want to use. It can be any map including custom. 2. Under the map preview, click **Customize**. This opens the map in [Map Designer](/guides/getting-started/map-design/). 3. Go to menu **Layers** and click the plus button to add a new **layer**. 4. Find the **Buildings** dataset and select the `building` layer in it. Add it to your map. ## Filter out your buildings Now you have a new layer in the **Built-up** block and you can proceed to filter out the buildings you want to style. 1. In the layer panel, switch view from **Style** to **Data**. Click on the desired building to show its details and click on the **id** to copy it. ![Copy the building ID](copy-id.png) 2. In the **Filter** section, click the plus button to open the **Filter by attribute** menu. Select **id**. ![Filter building by id](filter-by-id.png) 3. Paste the copied building ID to the input field and add it. Then hover over the building ID and **Select only this value** to hide all the other buildings. ![Add building IDs](add-ids.png) Repeat these steps to add any other buildings you want to style in the same way. > [!IDEA] > If your map contains multiple building layers, their styling can interfere and create unwanted "effects". You can use the little eye icon on any problematic layer to hide it, but the best practice is to have just one layer for regular buildings and another one for the styled buildings, where the regular layer has a filter to exclude the styled buildings. To do that, go to the regular buildings layer, switch view to **Data**, and replace the `MapTiler Planet` data source with `Buildings`. Now you can add a building ID filter as described above. ## Style the buildings With your buildings filtered out, switch view from **Data** back to **Style** and you're ready to do the magic! ### Adjust color In the layer panel, define the building's color, opacity, outline, or other properties. ![Style building in color](building-color.png) ### Use 3D extrusion To apply 3D shape, switch the visualization method to **Extrusion**. Tilt the map (right mouse button) to get a better view angle and adjust the color, opacity, and building height as needed. ![Extrude building](extrusion.png) ## Style multiple buildings What if you're working with multiple buildings and want to style each of them differently? Reuse your existing building layer to achieve that: 1. Right-click the building layer and select **Duplicate**. We recommend to **Rename** the duplicated layer, especially if you're going to create more copies. 2. Switch view to **Data**. In the **Filter** section, hover over a building ID and click **Select only this value**. 3. Switch view to **Style** and adjust the layer as preferred. Repeat for all buildings you want to style separately. ![Style multiple buildings differently](multiple-buildings.png) **Save** and **Publish** your map, and you're ready to [show it on your website](/guides/getting-started/use-map/). > [!IDEA] > By default, every map opens on a whole world view. If you'd like to show the location of your styled buildings instead, adjust the [default view](/guides/map-design/global-map-settings/#default-view) in the map settings. # How to highlight specific national boundary on your map Source: https://docs.maptiler.com/guides/map-design/how-to-highlight-specific-national-boundary-on-your-map/ This page will help you **highlight a specific country's national boundary**. Any map style that uses the MapTiler Planet tileset could use attributes included in the \`boundary\` layer. New attributes for highlighting national boundaries were announced in [OpenMapTiles v3\.12](https://www.maptiler.com/news/2021/01/openmaptiles-3-12-improved-city-centers/). In attributes (in step 6\) you can use the ISO A3 values of the country (e.g. CHE, FRA, CZE, ...). You can also find the required value in the Inspect mode (top right corner \- change from Map to Inspect). Highlight a national boundary step\-by\-step: --------------------------------------------- Click the button **Customize a copy.** ![swiss_1.png](./19484841076753_764466bc37.png) Duplicate the **Country border** layer, and rename it "Switzerland," move it below Country border layer. ![swiss_2.png](./19484854628497_1d378f3077.png) Switch to the **Data view** (bottom left) and add 2 new filters by clicking the **plus sign.** ![swiss_3.png](./19484854635665_59009547af.png) The 1st filter is "adm0\_l \=\= CHE"; the filter logic is set to "Any", only the "CHE" value applies. ![swiss_4.png](./19484854639249_b37d6d3be8.png) The 2nd filter is "adm0\_r \=\= CHE"; the filter logic is set to "Any", only the "CHE" value applies. ![swiss_5.png](./19484841093393_830afb890a.png) Set the zoom range styling settings accordingly: 1\-1px, 5\-3px, 10\-5px. ![swiss_6.png](./19484841095441_f06dfcbb1c.png) Publish your map by clicking the blue button **Publish** (top right). You will see the before/after screen. ![swiss_7.png](./19484854646033_575ebb87ec.png) Conclusion ---------- After publishing your map, you can use it in your application or on your web. The links for vector tiles, raster tiles, static maps, WMTS, or any of the major publishing libraries are listed below the map preview window. ![swiss_8.png](./19484841105425_9270bd858e.png) ## Next steps Continue to [How to highlight specific country on your map](/guides/map-design/how-to-highlight-specific-country-on-your-map/) to learn how to highlight a specific country in any map that you use in MapTiler. Useful links ------------ [How to highlight a specific country on your map](/guides/map-design/how-to-highlight-specific-country-on-your-map) [MapTiler map design section](/guides/map-design/) [MapTiler Planet Schema](https://docs.maptiler.com/schema/planet/) # How to highlight specific country on your map Source: https://docs.maptiler.com/guides/map-design/how-to-highlight-specific-country-on-your-map/ This page provides a detailed step\-by\-step tutorial on how to highlight a specific country in any map that you use in MapTiler. The tutorial works with the Dataviz style map and with the MapTiler Countries tileset. This process is also very useful when working with the GEOlayers 3 plugin for Adobe After Effects. Read more about Countries if you need [general information](https://www.maptiler.com/countries/) or see [schema documentation](https://docs.maptiler.com/schema/countries/). Highlight a specific country on your map ---------------------------------------- **1\. Create new map** * Go to MapTiler * Open the [Maps](https://cloud.maptiler.com/maps/) section * Click on NEW MAP * Keep in mind that there are also other ways how to edit a map, e.g. you can choose to upload your style or create a new one from scratch (under the drop arrow) ![Countries_1.png](./17594962096401_2c8dd2e1ed.png) **2\. Select the base map for the context** * Click on the Simple tab * Select Dataviz * Click on Customize ![Countries_2.png](./17594962098065_d3eefe97a9.png) **3\. Add a new data source to your map** * Click on Data Sources (Alt \+ D) button on the left panel * Click on \`\+\` sign (Alt \+ N) ![Countries_4.png](./17594976844305_14853766e6.png) **4\. Select the Countries tileset from the list** ![Countries_6.png](./17594976845329_134ef0708e.png) **5\. Add a new layer** * Click on the *Layers* (Alt \+ L) button on the left panel * Click on \`\+\` sign (Alt \+ N) * Select *Layer* ![Countries_8.png](./17594962105873_60b9768e9a.png) **6\. Select the administrative layer under Countries tileset** ![Countries_9.png](./17594976849809_9baa7c8df6.png) **7\. Filter Canada** * *iso\_a2 \= CA* + iso\_a2 attribute contains official [ISO 3166 Alpha\-2 codes](https://www.iso.org/obp/ui) of the countries * *level \= 0* + level attribute contains the hierarchical order of the administrative divisions (0 stands for country) * Filters could be changed in the future * See the [schema documentation](https://docs.maptiler.com/schema/countries/) ![Countries_13.png](./17594962113937_4145b0451e.png) **8\. Name your new layer** For example Canada ![Countries_14.png](./17594976856465_4dcc79d1a8.png) **9\. Change the color of layer Canada** * Find the *Canada* layer under the Administrative block * Change the color on \#A1FF00 ![Countries_15.png](./17594962117137_94c59f1bfd.png) **10\. Move the Canada layer e.g. under the Stadium layer** * Under the *Layer* (Alt \+ L) button at the left panel * Click on the *Verticality* tab at the bottom * Drag the Canada layer and drop it on desired place ![Countries_16.png](./17594976863377_8e5d39233f.png) **11\. Save the default view of the map** * Under *Settings* (Alt \+ S) button at the left panel * Click on Set current View button ![Countries_16b.png](./17594976866577_0ce78c4df7.png) **12\. Save the map to your account** Set the name on *Canada Dataviz* ![Countries_17.png](./17594962126865_d78b442a8f.png) **13\. Publish the map** ![Countries_18.png](./17594976930961_a98c5fc0dd.png) **14\. Confirm the publishing** ![Countries_19.png](./17594962132497_c87eabfd6d.png) **15\.  Close the Map Designer and use the link to share, or implement it into your websites** ![Countries_20.png](./17594962133905_79f230a2da.png) ## Next steps Continue to [Masking features in MapTiler](/guides/map-design/masking-features-in-maptiler-cloud/) to learn how to highlight a particular country by masking others using the MapTiler Map Designer and the Countries tileset. Useful links ------------ [MapTiler Countries Dataset](/guides/map-tiling-hosting/data-hosting/maptiler-countries-dataset) [MapTiler Countries Schema](https://docs.maptiler.com/schema/countries/) [Join MapTiler Countries with custom data](/guides/maps-apis/maps-platform/join-maptiler-countries-with-your-own-custom-data-and-make-a-choropleth-map) # Enhance coastlines with Land Gradient Source: https://docs.maptiler.com/guides/map-design/land-gradient/ Coastline enhancement is a classic cartographic technique used to visually define landmasses and make features stand out in the ocean. You can now easily replicate it with MapTiler and the [Land Gradient](https://cloud.maptiler.com/tiles/land-gradient/) tileset. ![Coastline enhancement](./coastline-enhancement.png) ## What is a gradient Let’s start by answering the question of how the effect is actually called. In cartography, we use the term **coastal vignette**, which means a gradual fade or glow around the coast and blending seamlessly into the background. Graphic designers would call this technique **feathering**. You can also find the terms **Gradient**, **Blur**, or **Shading** to be used. In MapTiler, we prepared the tilesets [Land Gradient](https://cloud.maptiler.com/tiles/land-gradient/) and [Land Gradient Dark](https://cloud.maptiler.com/tiles/land-gradient-dark/) to be used for this purpose. They use data from the [Land tileset](https://cloud.maptiler.com/tiles/land/), hence the naming. We also use the term gradient to emphasise not only the coastal vignette but also the fading as you approach the poles. ![Gradient at poles](./gradient-poles.png) ## Enhance your map Coastal vignettes serve multiple purposes in cartography: - **Visual separation**: Enhances the distinction between land and water. - **Depth perception**: Adds a sense of elevation and layering to the map. - **Historical aesthetics**: Mimics classic map styles from the Age of Exploration. The [Land Gradient](https://cloud.maptiler.com/tiles/land-gradient/) tileset replicates this effect by applying a soft outer glow around continents. It serves as a modern approach to traditional coastal vignettes, improving visual appeal while maintaining the speed of the MBTiles format. ![Outer glow](./map-enhancement.png) ## Using the Land Gradient dataset The Land Gradient tilesets are available in your Cloud [Tiles](https://cloud.maptiler.com/tiles/) section where you can preview them. - [Land Gradient](https://cloud.maptiler.com/tiles/land-gradient/) - [Land Gradient Dark](https://cloud.maptiler.com/tiles/land-gradient-dark/) We use the gradient effect in our [Landscape](https://cloud.maptiler.com/maps//) map style where it creates a plastic perception of the continents compared to the ocean. To achieve this effect, the gradient is overlaid with [Land](https://cloud.maptiler.com/tiles/land/), a vector polygon representation of global land areas. You can reuse this map style or customize it to your preference. We recommend using the following properties: - **Opacity**: helps to tune out or enhance the layer across the zoom levels - **Hue shift**: makes the gradient a different color - **Saturation shift**: turns the gradient monochromatic or more vivid ![Customize properties](./customize.png) There is also [Landscape Dark](https://cloud.maptiler.com/maps//) available for applications with dark modes, and [Landscape Vivid](https://cloud.maptiler.com/maps//) with a vibrant color scheme. To add the Land Gradient into one of your custom maps, click on the **plus button** in the left corner of your **Layers** panel in MapTiler Map Designer (and select Layer). ![Add new layer](/guides/map-design/add-a-new-style-layer/17472335038609_8e9a1b2039.png) Search for "Land Gradient" and then click **Continue**. In the last selection window, you can adjust the Parent Block or Layer name. Once in the map, we recommend moving the gradient down in your **Verticality** tab. The best position would be just above any water areas. For more info about how to add and style layers, see [Adding a new style layer](/guides/map-design/add-a-new-style-layer/). # How to create a land polygon with a drop shadow effect Source: https://docs.maptiler.com/guides/map-design/how-to-create-a-land-polygon-with-a-drop-shadow-effect/ A **land polygon** tileset is available in the Standard Tiles section of your MapTiler account. This article shows how to style land features with a drop\-shadow effect. The land polygon tileset can be accessed from [MapTiler Tiles](https://cloud.maptiler.com/tiles/land/). 1. Open any map style in the [MapTiler maps section](https://cloud.maptiler.com/maps/). 2. Hide all blocks except **Water** and **Background** (click the little eye icon). 3. Add a new layer (“plus” sign top-left). ![drop shadow 1](./1_shadow.png) 4. Add the data source called **Land** (geometry **polygon**, layer name **Land**). ![drop shadow 2](./2_shadow.png) 5. Change the color of the **Land** layer to HSL (49, 47, 91). ![drop shadow 3](./3_shadow.png) 6. Open the **Water** block and the **Water** layer. 7. Change the color of the **Water** layer to HSL (49, 47, 91). ![drop shadow 4](./4_shadow.png) 8. Duplicate the layer **Land**. ![drop shadow 5](./5_shadow.png) 9. Rename the new layer to **Land_polygon_shadow**. 10. Change the color of the **Land_polygon_shadow** layer to HSL (203, 65, 40). ![drop shadow 6](./6_shadow.png) 11. For **Land_polygon_shadow** adjust the layer opacity to 50% at ZL14. ![drop shadow 7](./7_shadow.png) 12. For **Land_polygon_shadow** adjust the **Fill** settings. Open **Advanced fill properties**, click **Layout**, click **Translate** and enable **Zoom range styling**. Use the following values: - ZL2 (1px, 1px) - ZL6 (1.5px, 1.5px) - ZL11 (2px, 2px) - ZL14 (2.2px, 2.2px) - ZL17 (1.6px, 1.6px) - ZL18 (1px, 1px). ![drop shadow 8](./8_shadow.png) 14. To achieve the final result, you have to re-arrange the order of layers. 15. Click **Verticality** (bottom-left). 16. Move the layer **Land_polygon_shadow** under the layer **Land**. ![drop shadow 9](./9_shadow.png) Congratulations, you have successfully created the drop shadow effect! **Bonus tip:** You can view the **JSON code** by clicking the **{}** icon at the bottom left. ![drop shadow 10](./10_shadow.png) 17. Save and publish your new map by clicking the top-right **Save** and **Publish** buttons. The final result will look like this (see above) in the detail of your map styles library [preview](https://cloud.maptiler.com/maps/). ## Useful links [MapTiler Land schema](https://docs.maptiler.com/schema/land/) # Masking features in MapTiler Source: https://docs.maptiler.com/guides/map-design/masking-features-in-maptiler-cloud/ Masking vector features on the map is a common cartography task. This page explains step by step how to highlight a particular country by masking others using the MapTiler Map Designer and the Countries tileset. ### Add the Satellite and Countries data sources Create a new empty map from your MapTiler account, and select the Satellite tileset in the data sources window. Add the Countries tileset data source the same way as Satellite. ![countries_mask_1.png](./17735307505937_1e251ef5ca.png) ### Add the layers Add the **satellite** (Satellite data source with layer *Satellite*) and **countries** (Countries data source with layer *administrative*) layers. ![countries_mask_3.png](./17735307506833_20644e6830.png) ![countries_mask_4.png](./17735307507729_462d327340.png) In the Style tab, it will appear as black by default, as shown below, and we are going to style it better in the next step. ![countries_mask_5.png](./17735307508369_9fe0a22d4a.png) ### Style countries with an expression In the **countries** layer, in the Data tab, set the filters *iso\_a2 !\= FR* and *level \= 0* ![countries_mask_6.png](./17735307508881_9040a0a615.png) Set the color of the **countries** layer (in the Style tab) to white (\#FFFFFF) and opacity to 65%. All countries except France will appear as semi\-transparent white. You can, of course, select another country of interest using a different country code (use the Data tab to find out) and adjust colors as desired. ![countries_mask_7.png](./17735261253009_7117e3bea2.png) ### Highlight the selected country It is possible to highlight France a bit further using the Countries tileset again. Right\-click on the **countries** layer and select Duplicate. Rename (right\-click on, for now, **countries copy**) the new layer to the **France border**. Adjust filter to *iso\_a2 \= FR*. ![countries_mask_8.png](./17735261254033_5e997fc5c1.png) In the Style tab, switch the Visualization value to Line. Set the Width to 2px and Blur to 3px. ![countries_mask_9.png](./17735307511441_a3153e9660.png) The country name label may also be overlayed using MapTiler Planet data source and *place* layer with filter *iso\_a2 \= FR*. ![countries_mask_11.png](./17735307511953_d760624619.png) Set up Visualization on Symbol, Fill Color on \#FFFFFF and Outline Color on \#000000\. ![](./17735292837137_00ffcf963d.png) ### Text label masking (experimental) It is possible to add more labels to the map, let’s say for every French city, and to mask them according to the shape of the country. From a new symbol layer, use a filter with an `within` expression including the GeoJSON description of the country polygon. The latter will render labels only for points being inside that polygon, so that would mask all labels outside France in our example. ``` json "filter": [ "all", ["==", ["geometry-type"], "Point"], ["==", ["get", "class"], "city"], [ "within", { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [[ [x,y], [x,y], [x,y], ..... ]] }, "properties": {} } ] ] ``` The more the GeoJSON describes a complex shape, the more the map performance decreases. ## Next steps Continue to [Contours and mountain peaks in feet](/guides/map-design/contours-and-mountain-peaks-in-feet/) to learn how to switch contour lines and mountain peaks from meters to feet in your MapTiler map. Useful links ------------ [MapTiler Tiles \- Satellite](https://cloud.maptiler.com/tiles/satellite/) [MapTiler Tiles \- Countries](https://cloud.maptiler.com/tiles/countries/) [MapTiler Tiles \- Planet](https://cloud.maptiler.com/tiles/v3/) [MapTiler Countries dataset](/guides/map-tiling-hosting/data-hosting/maptiler-countries-dataset) [MapTiler Countries](https://www.maptiler.com/countries/) [MapTiler Countries schema](https://docs.maptiler.com/schema/countries/) [Join MapTiler Countries with your own custom data and make a choropleth map](/guides/maps-apis/maps-platform/join-maptiler-countries-with-your-own-custom-data-and-make-a-choropleth-map) [How to highlight specific countries on your map](/guides/map-design/how-to-highlight-specific-country-on-your-map) [How to style a choropleth map in the Map Designer](/guides/map-design/how-to-style-a-choropleth-map-in-the-customize) # Style terrain with hillshading Source: https://docs.maptiler.com/guides/map-design/terrain/hillshading/ **Terrain shading (hillshading)** enhances natural features such as mountains and ocean floors, making maps more intuitive and visually striking. By simulating how sunlight interacts with terrain, you can create professional 3D effects for any map application purpose, from mountain sports to landscape planning. ![Map with and without hillshade](hillshade-compare.png) *Our [Topo](https://cloud.maptiler.com/maps/topo-v4/) map with hillshade (left) and without (right)* ## Quick start Many of our maps already contain the hillshading effect, so you can simply pick one of them and [use as-is](/guides/getting-started/use-map/): - [Backdrop](https://cloud.maptiler.com/maps/backdrop-v4/) - [Topo](https://cloud.maptiler.com/maps/topo-v4/) - [Outdoor](https://cloud.maptiler.com/maps/outdoor-v4/) - [Winter](https://cloud.maptiler.com/maps/winter-v4/) - [Landscape](https://cloud.maptiler.com/maps/landscape-v4/) – this map additionally contains the artistic [hand-drawn hillshade](/guides/map-design/terrain/hand-drawn-hillshading/) - [Ocean](https://cloud.maptiler.com/maps/ocean-v4/) – this map contains customizable shading of both land terrain and sea floor If the default hillshading in the map isn't exactly what you need, you can customize it. ## Customize the hillshade {#customize} The hillshading has adjustable light direction, color, and other properties. Here's how to customize it in our maps and how to add it to your custom maps: 1. In your MapTiler account, [page **Maps**](https://cloud.maptiler.com/maps/), click on the map you want to use. It can be any map including custom. 2. Under the map preview, click **Customize**. This opens the map in [Map Designer](/guides/getting-started/map-design/). 3. Go to menu **Layers** → block **Terrain** → layer **Hillshade**. ☝️ If the **Terrain** block is missing, click the plus button to add a new **layer**. Search for `Terrain RGB` and add it to your map. 4. In the **Hillshade** panel, adjust the light direction, color, opacity, and shading method. Hover over any setting control to display a mini help and learn what it does. ![Hillshade customization](hillshade-settings.png) ### Tips and best practices **Shadow color:** Match it to your map's palette. For example, use deep blues for shadows on dark map variants or soft ochres for a vintage feel. **Light altitude:** Controls how high the "sun" is in the sky. A lower altitude creates longer, more dramatic shadows. It also enables you to simulate sunlight at certain times during the day or season. *Note that this setting doesn't work with all hillshading methods.* For advanced users, **raw JSON editing** provides full control over the settings beyond UI toggles. Use the `{}` curly brackets button to open the JSON editor. > [!NOTE] > Please note that not all methods and styling options are available for **raster output**. If you need [rasters](/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/) rather than styling-friendly vectors, always check the preview and test your map on multiple zoom levels before deploying it. ## Use multicolored shading {#multicolor} ![Example of multidirectional hillshade](hillshading-color-example.png) *Example of multidirectional, multicolored hillshading* While standard hillshading uses a single light source, the **multidirectional** method adds light from multiple directions and in multiple colors simultaneously. ![Multidirectional hillshading method](hillshade-settings-multidirectional.png) This special shading method can expose hidden textures that the traditional single-source light might obscure. It's useful for high-precision geological mapping or high-end artistic cartography. > [!IDEA] > In the UI, you can only edit four light sources/directions. When you edit the raw JSON `{}` source file, you can specify as many as you need. ## Technical details ### Data source Hillshading is powered by our raster-DEM tileset [**Terrain RGB**](/guides/map-tiling-hosting/data-hosting/rgb-terrain-by-maptiler/). Raster-DEM format encodes elevation data into standard RGB (red-green-blue) values. If you [preview the raw Terrain RGB tileset](https://cloud.maptiler.com/tiles/terrain-rgb-v2/), you'll see elevated landforms such as mountains, hills, and volcanoes in different color shades. The hillshading settings described on this page allow you to change and customize those shades. ### Reference For full style specification, see the [Hillshade layer](/gl-style-specification/layers/#hillshade) reference. ## Other styling options You have styled the hillshade but it's still not "just it"? We have more options in store to help you enhance map terrain, so you can check them out and even combine them for best results. Here's the overview of all options: - **Hillshade** (this page): Custom color and precise light control, accurate on all zoom levels. - [**Hand-drawn hillshade**](/guides/map-design/terrain/hand-drawn-hillshading/): Artistic polished look, best for zoom up to 12. - [**Color relief**](/guides/map-design/terrain/color-relief/): Elevation visualized using a color range, no shadows. # Enhance terrain with hand-drawn hillshading Source: https://docs.maptiler.com/guides/map-design/terrain/hand-drawn-hillshading/ Do you want to achieve sophisticated terrain effect in your maps? The **hand-drawn hillshading** method gives mountainous regions in your map a polished look with subtle transitions, soft shadowing, and careful light positioning to maintain clarity and prevent over-exaggeration. ## What is hand-drawn hillshading Hand-drawn hillshading is a cartographic technique that enhances the visual representation of terrain using light, shadow, and artistic shading methods. One of the most influential figures in this field was **Eduard Imhof**, a Swiss cartographer known for his meticulous hand-drawn hillshades that created depth and realism in maps. His techniques emphasized natural landforms, improving readability and aesthetics. ![Hill-shading technique](Graubuenden-NW.png) *Image: [source](https://www.shadedreliefarchive.com/Graubuenden_NW.html)* In modern cartography, digital tools can replicate Imhof's shading style using specialized algorithms. MapTiler provides the [Hand-drawn hillshading](https://cloud.maptiler.com/tiles/hand-drawn-hillshade/) tileset, designed for Imhof-like visuals. This dataset allows map designers to integrate expressive and naturalistic relief shading into their maps effortlessly. ## Use hand-drawn hillshading The [Hand-drawn Hillshading](https://cloud.maptiler.com/tiles/hand-drawn-hillshade/) tileset is available in MapTiler in your [Tiles](https://cloud.maptiler.com/tiles/) section where you can preview it. It is generated for the medium resolutions until **zoom level 12**. ![Hand-drawn Hillshading tileset](tileset.png) We use this shaded relief in our [Landscape](https://cloud.maptiler.com/maps/landscape/) map style where it transitions seamlessly into the classic relief as you zoom past the 12th zoom level. Landcover colors such as forests, grass, or glaciers are positioned on top of the hillshade to give it a realistic feeling. ![Landscape map with hillshading](landscape-hillshade.png) You can reuse this map style or customize it to your preference. We recommend using the following properties: - **Opacity**: helps to tune out or enhance the layer - **Contrast shift**: makes the shading more prominent if turned up - Maximum/minimum brightness There is also [Landscape Dark](https://cloud.maptiler.com/maps//) available for applications with dark modes, and [Landscape Vivid](https://cloud.maptiler.com/maps//) with a vibrant color scheme. To add the hand-drawn hillshade into one of your custom maps: 1. Click on the **plus button** in the left corner of your **Layers** panel in MapTiler Map Designer (and select Layer). ![Add new layer](/guides/map-design/add-a-new-style-layer/17472335038609_8e9a1b2039.png) 2. Search for "Hand-drawn Hillshading" and add it to your map. 3. Once in the map, we recommend moving the hillshade down in your **Verticality** tab. The best position would be on top of any water areas, but below natural features. For more info about how to add and style layers, see [Adding a new style layer](/guides/map-design/add-a-new-style-layer/). # Style terrain with color relief Source: https://docs.maptiler.com/guides/map-design/terrain/color-relief/ **Color relief** is a visualization method that styles the map in diferent colors based on altitude. Unlike [hillshading](/guides/map-design/terrain/hillshading/), color relief focuses purely on elevation data without any simulated light or shadows. This allows you to show elevation using smooth color gradients, which is perfect for creating the "old-school geographical atlas" look or high-contrast environmental maps. ![Map with and without color relief](color-relief-compare.png) *Our [Topo](https://cloud.maptiler.com/maps/topo-v4/) map with color relief (left) vs hillshading (right)* ## Predefined color ramps Our cartographers have prepared a selection of beautiful predefined color ramps for any map look and type of terrain. Here's how to add the relief with a specific color ramp: 1. In your MapTiler account, [page **Maps**](https://cloud.maptiler.com/maps/), click on the map you want to use. It can be any map including custom. 2. Under the map preview, click **Customize**. This opens the map in [Map Designer](/guides/getting-started/map-design/). 3. Go to menu **Layers** → block **Terrain** → layer **Hillshade**. ☝️ If the **Terrain** block is missing, click the plus button to add a new **layer**. Search for `Terrain RGB` and add it to your map. 4. In the **Hillshade** panel, set **Visualization** to `Color relief`. 5. Choose a **Color ramp** from the presets. ![Color ramp settings](hillshade-settings-color-relief.png) > [!WARNING] > If you can't see your color ramp applied, check the `Visibility` and `Opacity` settings. The [**Landscape** map](https://cloud.maptiler.com/maps/landscape-v4/), for example, only makes the layer visible from zoom level 8 up. Adjust the settings manually if needed. ## Advanced techniques ### Custom color ramps You can create your own color ramp from scratch, or modify a preset to match a specific branding or map style. For power users, clicking the `{}` icon allows you to edit elevation values directly in the style JSON, giving you total control over the gradient interpolation. ![Custom color ramps](hillshade-settings-color-relief-custom.png) ### Adjusting breakpoints Default color ramps are calibrated globally, from sea level to Mount Everest. If your map is focused on a flatter region (like the Netherlands or Kansas), the color differences might be nearly invisible. To fix it, remove elevation breakpoints for values that aren't used in your map, and adjust the color of remaining breakpoints to increase the contrast. ![Color ramp breakpoints](hillshade-settings-color-relief-ramps.png) ### Styling combinations To combine a color relief with shading, use the [**Landscape** map](https://cloud.maptiler.com/maps/landscape-v4/) which additionally contains the [hand-drawn hillshading](/guides/map-design/terrain/hillshading/) layer, or add this layer to any map manually. For realistic 3D appearance with the selected tint, you can add a new [hillshading](/guides/map-design/terrain/hillshading/) layer. Place it on top of the color relief and adjust its opacity. This helps you achieve special effects like "plastic" or embossed. ![Terrain styling techniques combined](styling-combined.png) *Various terrain styling techniques combined (from left to right): color relief, color relief with hand-drawn hillshade, color relief with an extra hillshade layer* ## Technical details The color relief feature is powered by our [**Terrain RGB**](https://cloud.maptiler.com/tiles/terrain-rgb-v2/) tileset. When you select a color ramp, the elevation data from the tileset is translated into the colors defined in the ramp. The [**Ocean** map](https://cloud.maptiler.com/maps/ocean-v4/) uses an additional tileset [**Ocean RGB**](https://cloud.maptiler.com/tiles/ocean-rgb/). In this map, you can adjust separate color ramps for **Terrain** (land) and for **Ocean**. # Change language in a map Source: https://docs.maptiler.com/guides/map-design/change-language-in-a-map/ This page explains how to **change language** in a map. This is done in the MapTiler Map Designer **Settings panel** (Alt\+S). Change language --------------- In MapTiler Map Designer, go to **Settings (Alt\+S)** and see the **Worldview section**. ![language-settings.png](./20883093121041_1eaa89ed97.png) There are 3 main language options to choose from: **Defined by style**, **English**, and **Local**. ![language-options.png](./20883123960977_9c0e3a4150.png) 1\. **Defined by style\= default setting** for all MapTiler main styles. 2\. **English** \= uses English names to make the map understandable for the potential majority of users 3\. **Local \=** uses the **native language** of each country (attribute `name` instead of, for example, English naming `name:en`). The other options allow picking any preferred language. When selecting any other option than Defined by style, MapTiler Map Designer displays **Translation** –⁠ second naming where you can again choose any other language.  ![language-translation.png](./20883123971089_886a0ab3eb.png) MapTiler SDK ------------ You can control the map language from [MapTiler SDK](https://www.maptiler.com/sdk-javascript/). This way, you can implement **language changing based on the IP address** of users, among other things. See the documentation and examples below: * [Languages](https://docs.maptiler.com/sdk-js/api/languages/) * [How to change the default map labels language](https://docs.maptiler.com/sdk-js/examples/language-map/) * [Change a map's language](https://docs.maptiler.com/sdk-js/examples/language-switch/) * [How to change the map label language based on the visitor’s location](https://docs.maptiler.com/sdk-js/examples/ip-map-language/) Conclusion ---------- Language in a map can be easily changed in MapTiler Map Designer **Settings panel \> Worldview \> Language**. There are 3 main options: Defined by style, English, and Local. You can also control map language with **MapTiler SDK**. ## Next steps Continue to [Global map settings](/guides/map-design/global-map-settings/) to learn about Global map settings in MapTiler Map Designer. Useful links ------------ [Global map settings](/guides/map-design/global-map-settings) [Languages \| JavaScript maps SDK](https://docs.maptiler.com/sdk-js/api/languages/) # Contours and mountain peaks in feet Source: https://docs.maptiler.com/guides/map-design/contours-and-mountain-peaks-in-feet/ This page describes how to **switch contour lines and mountain peaks** from meters **to feet** in your MapTiler map, which might be useful to US users in particular. _To use the [Contours tileset](https://cloud.maptiler.com/tiles/contours/) in your maps on [MapTiler](https://www.maptiler.com/cloud/), you need to add it via the MapTiler Map Designer tool. A new layer can be added either through the "Plus" button in the Layers or Data sources tab. By default, contours and mountain peaks are included in the [Topo](https://cloud.maptiler.com/maps//), [Outdoor](https://cloud.maptiler.com/maps//), and [Winter](https://cloud.maptiler.com/maps//) map styles._ ## Switch to feet The default units in the MapTiler maps are **meters**. You need to use the **MapTiler Map Designer** tool to switch your contours and mountain peaks to feet. You can access it by clicking on the CUSTOMIZE A COPY button below your map. ![Customize.png](./17039926889617_b459a52c0c.png) The switch to feet is really easy. Go to the **Settings** panel and pick **Feet** from the drop\-down **Units** menu. This action will cause all contours and mountain peaks labels to switch to feet globally. ![Feet.png](./17039900908049_93a9732f30.png) For more detailed information about Contours attributes, please check the [Countours schema](https://docs.maptiler.com/schema/contours/). ## Conclusion With the switch of the **Units** in **MapTiler Map Designer**, you can easily change the contours and mountain peaks in your map from meters to **feet**. ## Next steps Continue to [Improve terrain visualization in glacial regions](/guides/map-design/improve-terrain-visualization-in-glacial-regions/) to learn how to style contour lines that intersect glaciers in your map on MapTiler. ## Useful links [Improve terrain visualization in glacial regions](/guides/map-design/improve-terrain-visualization-in-glacial-regions) [MapTiler Contours \| Schema](https://docs.maptiler.com/schema/contours/) [MapTiler Planet \| Schema \| Mountain peak](https://docs.maptiler.com/schema/planet/#mountain_peak) # Disputed borders on your maps Source: https://docs.maptiler.com/guides/map-design/disputed-borders-on-your-maps/ Border disputes often represent complex geopolitical disagreements as well as a challenge for cartographers. It is problematic to ensure that maps reflect the borders without any bias towards either side of the conflict. To ease this issue, [MapTiler](https://www.maptiler.com/cloud/) enables users to display the borders according to the selected country’s policy. In this article, we will show you the way how this is done. *To change disputed borders on your maps, you need to have a MapTiler account created. If you don’t have one yet, please register for free at [MapTiler](https://cloud.maptiler.com/) or directly purchase at [MapTiler \- Plans](https://www.maptiler.com/cloud/plans/).* Disputed borders ---------------- A boundary or territorial dispute is a **disagreement over an** **area of land claimed by two or more political entities**. Each involved party would publish its own maps where the area would be within their state territory. The conflicts can originate from historical background, different religious or ethnic perspectives, the possession of strategic natural resources or of a complex combination of a variety of these factors. What makes the mapping of border disputes even more difficult is the fact, that **every conflict is unique** and has its own geopolitical issues. Border disputes have significant meaning in **international law** as they disrupt its very basis – the state territory. There are a few terms widely used in relation: **border dispute**, **occupied territory** and **irredentism**. Occupied territory, however not accepted by the sovereign states, is usually in control of the occupied state by the military force. Irredentism has a deep basis in history. It is an ideological movement wanting to reclaim lost populations and territories that once declared the independence of their former state. The majority of current border disputes are already included in [MapTiler](https://maptiler.com/cloud) making it easy for you to adjust the boundaries as you wish. Tagging in OpenStreetMap ------------------------ Displaying the disputed borders according to your preference is enabled by the [OpenStreetMap](https://www.openstreetmap.org/) specialized tags such as `disputed_name` or `claimed_by`. These tags, however not officially approved, are widely used among users. There were several initiatives proposing the proper tagging of the border disputes, but none of them is active as of July 2021\. [MapTiler Planet](https://docs.maptiler.com/schema/planet/#boundary) and [OpenMapTiles schema](https://openmaptiles.org/schema/#boundary) used in MapTiler maps have similar tags that are in compliance with the OSM ones. `Disputed_name` tag contains the name of the disputed area without spaces and is valid for country boundaries only (`admin_level = 2`). `Claimed_by` tag consists of the ISO2 country code and specifies the country according to which’s policy the borders will be displayed. A list of the ISO2 country codes can be found for example [here](https://www.nationsonline.org/oneworld/country_code_list.htm). There is also the basic `disputed` tag which defines whether the border is (`value = 1`) or is not disputed (`value = 0`). Change disputed borders in one click ------------------------------------ MapTiler allows you to quickly create a map that would be in line with the selected country’s policy. 1. Log in to your Cloud account and select a map either from your maps or Standard maps section: [MapTiler \- Maps](https://cloud.maptiler.com/maps/), then click on **Customize a copy**. 2. Select Settings (Alt\+s) 3. From the Borders drop\-down list select **Preferred country borders**. You can **choose from the following countries'** points of view: Abkhazia, Armenia, Benin, Bhutan, Burkina Faso, China, Egypt, Ethiopia, France, Guyana, India, Israel, Italy, Kenya, Kosovo, Kyrgyzstan, Malawi, Nagorno Karabakh, Nepal, Pakistan, Palestine, Russia, South Ossetia, South Sudan, Spain, Sudan, Syria, Tanzania, Turkey, Ukraine and Western Sahara. Advanced changing of disputed borders ------------------------------------- If you want to dig a bit deeper into the disputed borders mapping, go to the **Layers** panel. Click on any borders layer and go to the **Data** tab. In the **Filter** properties, you can work with the disputed attribute tags: * `disputed` * `disputed_name` * `claimed_by` For highlighting just the borders that are disputed use **disputed Yes option** (or `disputed==1` filter in the JSON editor) and adjust the line styling (you can change color, width or use a dash array). You can also work with the `claimed_by` tag and [country codes](https://www.nationsonline.org/oneworld/country_code_list.htm). For example, if you want to see Kashmir from India's point of view, add the filter `claimed_by == IN`. With `disputed_name` filter, you can write specific values stored in the borders data. Click on the preferred border on the map \> click on disputed\_name \> copy the value \> add it to the filter with a "plus" button. ![disputed_borders_name.png](./17324652106257_370bdfb985.png) ### Removal of disputed borders Some claims (such as Moroccan over Western Sahara) require **hiding the disputed borders** between the two territories. You can filter out the border with `claimed_by` or  `disputed_name` tags and then use the **"eye" icon** next to the layer name to hide it. ### Styling The map design of the disputed borders is often being discussed by cartographers. A **dashed line** is the most commonly used style. This can be achieved in the Style tab under **Advanced outline properties** \> **Dasharray.** The format is **number, number** (**lengths** of the alternating dashes, **gaps** that form the dash pattern). Another way to add a bit of uncertainty is a **blur** (under Effects) or adjustment of **opacity**. If preferred, you can also edit the whole layer design in the **JSON editor** (Alt\+E). Conclusion ---------- Border disputes are difficult and complex situations requiring deeper thinking when creating a map. MapTiler allows every user to easily adjust the borders according to their preferred point of view using **MapTiler Map Designer**. MapTiler team carefully checks and maintains the disputed borders in MapTiler Planet. If you would like to add a new country point of view or adjust the existing ones, please don't hesitate to contact our [support team](/support/requests/). ## Next steps Continue to [How to automatically change disputed borders according to your map visitors' location](/guides/map-design/how-to-automatically-change-disputed-borders-according-to-your-map-visitors-location/) to learn how to change disputed borders on a MapTiler map based on the political view of the country where the visitor is from. Useful links ------------ [MapTiler Planet schema \- boundary](https://docs.maptiler.com/schema/planet/#boundary) # How to automatically change disputed borders according to your map visitors' location Source: https://docs.maptiler.com/guides/map-design/how-to-automatically-change-disputed-borders-according-to-your-map-visitors-location/ This page provides a process of how-to change disputed borders on a MapTiler map based on the political view of the country where the visitor is from. There is a JavaScript sample code for the setup, which uses the IP address of the visitor as one of the key components for the whole setup. ## Build a map with correct disputed borders Building a map can be quite sensitive, especially, if you live in a country that has a territorial dispute with another country. Or if you live somewhere else and you want your map to reflect these disputes and provide up-to-date information. [MapTiler](https://maptiler.com/cloud/) maps provide such tools with their disputed borders tag functionality and with other added features and code samples. If you are a developer, who wants to build an online map, based on MapTiler maps, that reflects globally known territorial disputes, and that serves correctly drawn disputed borders according to the policy of the country, where the map visitor is from, feel free to use the following sample code. ## Code Sample ```html freegeoip - Example
``` ## Conclusion Dealing with disputed borders is a sensitive topic that is ever-present. As countries and national states evolve, grow, shrink, fade away or wage wars against each other, their country borders change as well. MapTiler strives to develop comprehensive tools to empower its users and developers to provide up-to-date maps with advanced automated functionalities, such as the auto-adjustment of disputed borders based on visitors' location (IP based) and their country's national policy. ## Next steps Continue to [Creating a custom vector dataset (GeoJSON)](/guides/map-design/creating-a-custom-vector-dataset-geojson/) for a step-by-step guide on creating a custom dataset with specific information to be saved in GeoJSON format. ## Useful links [MapTiler Maps](https://maptiler.com/maps) [MapTiler API](https://docs.maptiler.com/cloud/admin-api/?_gl=1*1k4hqzq*_ga*NDI4MTAyMjA0LjE2NDk3Mzg3NjU.*_ga_K4SXYBF4HT*MTY0OTg0MDA0NS40LjEuMTY0OTg0MDQyMi42MA..&_ga=2.19086911.649711953.1649588462-428102204.1649738765) [Disputed borders on your maps](/guides/map-design/disputed-borders-on-your-maps) [List of disputed borders and their tags](/guides/maps-apis/maps-platform/list-of-disputed-border-names-and-tags) [How to display disputed borders according to the official national policy](/guides/map-design/disputed-borders-on-your-maps) [How to build a map for users in a specific country](/guides/map-design/change-language-in-a-map) [MapTiler Planet updates explained](/guides/map-tiling-hosting/data-hosting/maptiler-planet-updates) # Map attribution and how to add it Source: https://docs.maptiler.com/guides/map-design/attribution/add-attribution/ Map attribution is the copyright and licensing information that appears on a map, typically in the bottom corner. It gives credit to the map data providers and is required by their licenses. When you implement a MapTiler map using our SDKs or popular mapping libraries, it will usually have attribution added automatically. However, in some cases you may need to add it manually, and this page explains how. ## Attribution parts {#parts} MapTiler attribution consists of a text part (bottom right) and a logo (bottom left). ![MapTiler attribution example](./maptiler-attribution.png) #### Text attribution (required) The text attribution must appear on every map. It includes copyright notices with links for MapTiler and also for OpenStreetMap, which is the underlying data source: [© MapTiler](https://maptiler.com/copyright) [© OpenStreetMap contributors](https://openstreetmap.org/copyright) #### Logo attribution (free accounts only) If you're using a MapTiler Free account, you also need to display the [MapTiler logo](https://www.maptiler.com/press/#logo) linking to our website, [www.maptiler.com](https://www.maptiler.com/). ## Where to put attribution You need to include MapTiler attribution on: - Dynamic maps in websites or mobile apps – include both text and link - Static map images or printed maps – include text on or next to the image - Maps in videos, games, or animations – overlay in a corner or include in credits For complete details, see our [Terms and Conditions](https://www.maptiler.com/terms/#MapDataAttribution). If you need a map without attribution, learn how to remove it. ## How to add attribution Most JavaScript mapping libraries show attribution by default, based on the datasets that you use, so you usually won't need to add it manually. If the attribution is missing from your map, here's how to add it. ### MapTiler SDK JS Attribution is shown out-of-the-box. Configure the MapTiler logo and its position using these options: ```js // Logo display (setting to false only works with premium accounts) maptilerLogo: true // default: true // Logo position logoPosition: 'bottom-left' // options: 'top-left', 'top-right', 'bottom-left', 'bottom-right' ``` For extra configuration, see the [MapTiler SDK JS reference](/sdk-js/api/controls/#attributioncontrol). ### MapLibre GL JS Attribution is shown out-of-the-box. For more details, see the [MapLibre GL JS reference](https://maplibre.org/maplibre-gl-js/docs/API/classes/AttributionControl/). In case you are using the Free plan, you need to add the Logo as described in the [HTML section](#html). ### Leaflet Attribution is shown out-of-the-box. For more details, see the [Leaflet reference](https://leafletjs.com/reference.html#control-attribution). In case you are using the Free plan, you need to add the Logo as described in the [HTML section](#html). ### OpenLayers Attribution is associated with the map layer's source by default. In order to comply and show the attribution expanded, adjust the default behaviour to: ```js const attribution = new ol.control.Attribution({ collapsible: false, }); const map = new ol.Map({ controls: ol.control.defaults .defaults({ attribution: false }) .extend([attribution]), // other map settings... }) ``` For more details, see the [OpenLayers reference](https://openlayers.org/en/latest/apidoc/module-ol_control_Attribution-Attribution.html). In case you are using the Free plan, you need to add the Logo as described in the [HTML section](#html). ### Cesium For Cesium you need to specify the attribution directly: ```js const credit = new Cesium.Credit(`© MapTiler © OpenStreetMap contributors`, true) viewer.creditDisplay.addStaticCredit(credit); ``` For more details, see the [Cesium reference](https://cesium.com/learn/ion-sdk/ref-doc/CreditDisplay.html). In case you are using the Free plan, you need to add the Logo as described in the [HTML section](#html). ### HTML Add logo attribution (required only for the Free plan): ```html MapTiler logo ``` Add text attribution directly to your map container (only if you are not using some library which handles it already): ```html
© MapTiler © OpenStreetMap contributors
``` # Get a map without attribution Source: https://docs.maptiler.com/guides/map-design/attribution/remove-attribution/ The [map attribution](/guides/map-design/attribution/add-attribution/) must be present on every map, as outlined by our [Terms and Conditions](https://www.maptiler.com/terms/#MapDataAttribution). But what if you need a clean map, for example for use in videos? Removing the attribution is legally possible if you adhere to the rules explained on this page. ## Remove MapTiler attribution Our map attribution consists of [several parts](/guides/map-design/attribution/add-attribution/#parts). The MapTiler-branded parts are the **MapTiler logo** and the **© MapTiler** text with link. Here's how to remove them: - The **logo** is only mandatory for free users. So, to be eligible to remove it, simply upgrade to any of our [paid plans](https://www.maptiler.com/cloud/pricing/). Maps implemented with [MapTiler SDK JS](/sdk-js/) detect the license and the logo gets removed from your map automatically. - The **© MapTiler** link is mandatory for all users. To remove it, you need written permission. Please contact our Sales team to arrange it. ## Remove OSM attribution The **© OpenStreetMap** link is another mandatory part of our [map attribution](/guides/map-design/attribution/add-attribution/). You can only remove it if your map doesn't contain any data protected by the [OpenStreetMap (OSM) license](https://www.openstreetmap.org/copyright). The steps below help you update your map to use only non-OSM data. ### 1. Select a compatible map Removing the OSM attribution requires you to replace the main map data source, which is OSM-based, with an alternative one. We'll get to that part in the next step. However, some maps use more than one data source, and these additional datasets may contain OSM data too. They cannot be replaced, so you need to select a map without them. The following maps are safe to use: - [Base](https://cloud.maptiler.com/maps//) - [Bright](https://cloud.maptiler.com/maps//) - [Dataviz](https://cloud.maptiler.com/maps//) - [Satellite](https://cloud.maptiler.com/maps//) - [Streets](https://cloud.maptiler.com/maps//) - [Toner](https://cloud.maptiler.com/maps//) - [Topo](https://cloud.maptiler.com/maps//) You can also use a custom map derived from these map styles. Just make sure the map hasn't been enriched with any OSM-based content. ### 2. Replace map data source All our maps use the same main OSM-based dataset: [MapTiler Planet](https://www.maptiler.com/planet/). We provide another global dataset as an OSM-free alternative: [MapTiler Planet Lite](https://www.maptiler.com/attribution-free-map/). To remove the OSM attribution, you need to switch your map's main data source from `MapTiler Planet` to `MapTiler Planet Lite`. Note that MapTiler Planet Lite, as the name suggests, is "light", meaning it contains much less data. The maximum zoom level is 10 (for MapTiler Planet it's 15). This is fine for showing global context on the level of countries and larger administrative units, but not for detailed maps. #### How to switch to Planet Lite 1. In your MapTiler account, [page **Maps**](https://cloud.maptiler.com/maps/), select one of the compatible maps and click on **Customize**. 2. In the map editor, select **Data sources** in the left menu. 3. Right-click on the **MapTiler Planet** data source and select **Replace**. ![Replace MapTiler Planet data source](.\data-source-replace.png) 4. In the new window, search for `MapTiler Planet Lite` and select it. You'll get a comparison of the two data sources for your current map view. MapTiler Planet Lite contains less detail, which is visible on higher zoom levels, so you may need to zoom in to your area of interest to see any difference. The screenshot below shows an example on zoom level 11. ![Compare data sources](.\replace-planet-compare.png) 5. In most maps, you'll get a warning that the replacement will affect some style layers in your map, because the new data source doesn't contain data for them. This is expected, so confirm the replacement and then proceed to **Delete** these layers. ![Remove layers with missing data](.\replace-planet-layers.png) 6. **Save** and **Publish** the map under a name of your choice. Your map now contains no OSM data, and you're eligible to use it without the © **OpenStreetMap** attribution in videos, print, on the web, or in games. If you're using [MapTiler SDK JS](/sdk-js/) to implement the map, the SDK detects the source dataset and removes the OSM attribution automatically. # Data sources Source: https://docs.maptiler.com/guides/map-design/data-sources/ A data source is the backbone of each map. Data defines the **features** that are visible on the map and that you can style according to your needs. Each style layer in your map has a defined source. In **MapTiler Map Designer**, you can find the data source used for a specific layer in the **Data tab** under **Sources**. ![data-source.png](./17160106487825_90d07c42e2.png) You can add either MapTiler data sources or your own. Data sources can be of two types: **Tiles** or **Vector data file (GeoJSON)**. [Tiles](https://cloud.maptiler.com/tiles/) include a **Standard tiles** section with global data, **Country specific** tiles and if you add your own, you will get a **My Tiles** section. For upload of your own tileset, supported containers are [GeoPackage](https://www.geopackage.org/) or [MBTiles](https://github.com/mapbox/mbtiles-spec) with raster (PNG, JPG, or WebP) or vector tiles (MVT format). You can process your own data easily into tiles with [MapTiler Engine](https://www.maptiler.com/engine/) software. Vector MapTiler data sources that you can find in the Standard tiles section have their [detailed schemas](https://docs.maptiler.com/schema/). From the schema, you can discover everything from layer names or fields to maps in which the data source is included. ![tiles.png](./17160102173201_e549633e8e.png) [Vector data files](https://cloud.maptiler.com/data/) include your own data either **created from scratch** in our [Vector data editor](/guides/vector-data-editor/) or **uploaded** in geo formats (supported are GeoJSON, GPX, KML, and SHP). The maximum allowed file size is 10 MB with 10 000 features; hence this approach is suitable for small datasets. With bigger files, we recommend tiling your data to get the best performance. ![data.png](./17161963753105_11b928d0e1.png) ## Work with data sources programmatically As tiles are the raw data, to turn them into a map you also need information on how to style the data. Tiles are useful where you want to combine elements of different datasets into one map. MapTiler [Tiles API](/cloud/api/tiles/) offers several standard tilesets for everyone to use in their maps, such as MapTiler Planet, OpenMapTiles, Countries, Contours, Terrain, Satellite, etc. You can also [upload your own](/guides/map-data/upload-files/). Live example: MapTiler Planet tileset To add a tileset in a vector tile custom style, add a new data source in the sources section of the JSON style and write the URL of the tileset in the `url` property. Example: JSON style fragment with two tilesets ```json { .......... "sources": { "satellite": { "url": "https://api.maptiler.com/tiles/satellite-v2/tiles.json?key=", "tileSize": 512, "type": "raster" }, "openmaptiles": { "url": "https://api.maptiler.com/tiles/v3/tiles.json?key=", "type": "vector" } } ......... } ``` ## Work with data sources in Map Designer In MapTiler Map Designer, you can manipulate the data sources from the **Data sources panel** (puzzle icon or Alt\+D). You will find all data sources **used in your map** there, including the **data layers**. If a layer is not used in your map but is available, it will be greyed out. In the example below, we have a MapTiler Planet data source with layers such as "aerodrome\_label", "boundary", "landcover", etc. "Housenumber" or "mountain\_peak" layers are available but not used in our map. ![data-sources-panel.png](./17161924933393_0f2d18c2d2.png) After clicking on a specific data layer, MapTiler Map Designer will tell you what **map style layers** it is included in, what **attributes** it has, and what you have **filtered** in the map.  In our case, map style layers "Other border", "Disputed border" and "Country border" use data from the "boundary" layer. You can also see that in the map we don't use maritime boundaries (Maritime\=Yes is not selected in the filter). ![attributes.png](./17161963756433_9e0761a6d6.png) ### Add a new data source Adding a data source is easy; just use the **"plus" button next to the search**. In the dialogue window, you will see all available data sources with information (type, zoom, and date of creation) including your own uploaded data. When selecting your preferred data source, there is an overview map on the right which you can zoom in to explore the data thoroughly. ![add-data-source.png](./17161924937105_2b7e516077.png) Once you have the data source added, you can go to the Layers panel (Alt\+L) and include it in your style layers. It will appear as an option in a Source drop\-down menu in the Data panel. However, be aware that raster sources can be chosen only for raster layers and vectors for vector layers. ![add-to-map.png](./17161963760017_6edff99c49.png) ### Add a style layer A data source can also be added directly as a new style layer. Go to the Layers panel \> "plus" button \> Add a new layer to enrich your map. ![add-style-layer.png](./17161924939025_1b7bec30a6.png) In the case of **rasters**, you will choose your layer, geometry, and how it should be included in the map (Parent block, Visualization, Layer name) and you can style it right away. ![add-raster.png](./17161963763217_935cc52419.png) In this example, we are adding Terrain RGB into the Terrain block as a Hillshade. Below you can see how the map looks with the Terrain included. ![terrain.png](./17161963764625_816f62aebe.png) In the case of **vectors**, apart from choosing a geometry, you will be asked to look at **filters** before adding a layer to your map. This way, you can choose to include only **specific classes, names, or other values**. As an example, we are adding mountain peaks to our map.  ![add-vector.png](./17163093527057_c31698332b.png) ### Replace a data source Replacing data sources can be very useful in case of **updates**. Go to the Data source panel \> right\-click the Data source \> Replace data source... Data sources can be replaced only if they **cover the same style layers** as the initial source! ![replace.png](./17163093531281_bb6d0b293d.png) You can also **delete** a data source in the same manner. Map Designer will let you know if this action would cause any style layers to be removed from your map. ![remove.png](./17163088605457_c5dbd1cbbd.png) ## Links [Tiles \| MapTiler](https://cloud.maptiler.com/tiles/) [Data \| MapTiler](https://cloud.maptiler.com/data/) [MapTiler Schemas](https://docs.maptiler.com/schema/) # Replacing data sources Source: https://docs.maptiler.com/guides/map-design/replacing-data-sources/ This page describes the process of replacing data sources in a map. Working with different versions of data sources is very common, and replacing them is very useful during map updates.  *Data sources can be replaced only if they cover the same style layers as the initial source! Equally important is the fact that a raster data source can only be replaced by another raster data source. The same applies to vector data sources that can only be replaced by other vector data sources.* Replacing data sources can be very useful in case of **updates**. Go to the Data source panel \> right\-click the Data source \> Replace data source... Data sources can be replaced only if they **cover the same style layers** as the initial source! ![1.png](./17374853362705_7c8d518f86.png) After clicking "Replace data source" you will see the complete list of your available data sources (stored in your MapTiler account). You can even use the search bar at the top left corner of the context window. ![2.png](./17374853364369_5f833f2eb8.png) After you find the right data source, click it and a comparison preview will appear in the right part of the context window. This will help you quickly check what changes will be done to the map if you decide to complete the replacement of the data sources.  ![3.png](./17374853365265_be978310ec.png) Once you are satisfied with the preview, click the blue "Continue" button in the lower left part of the context window. ![4.png](./17374853370897_7a69bed917.png) The Map Designer tool will let you know if this action would cause any style layers to be changed or removed from your map. ![5.png](./17374890424337_56659dad3e.png) To complete the replacement process click the blue "Replace" button in the lower right part of the context window. ![6.png](./17374890424977_10bfc2cc67.png) Why can't you replace a data source with any other random data source --------------------------------------------------------------------- All data sources aren't created equal. Data sources tend to have various structures which can not be easily combined with each other. Needless to say that you simply cannot replace a vector dataset with a raster one. Why is that? In the case of vector datasets, the MapTiler Map Designer tool works with style.json files that define the looks of the map in the editing tool you can see in your MapTiler account. Any change of a parameter or movement of a slider equals a change in the definition of the style.json of the map. This style.json also contains references to the data sources used in the map. Therefore replacing a data source from your map with a completely different one (different layers, different structure) would completely break your map and possibly render many other layers missing (although the two data sources might have several common layers).  The bottom line is that the original and the new data source must have a compatible schema where the respective features (roads, rivers, lakes...) are represented in the same structure and naming. [Read more about the schemas of MapTiler data sets.](https://docs.maptiler.com/schema/) Conclusion ---------- Replacing data sources is a very useful feature, especially during map updates when you can easily switch one data source for another one, let's say for an updated version. Just keep in mind that the structure (layers) and the format (raster or vector) of the data source must be the same for the original and the newly installed data source. ## Next steps Continue to [Replacing name label](/guides/map-design/replacing-name-label/) to learn how to replace and create new names for cities and streets. Useful links ------------ [Origin of the MapTiler Planet data](/guides/map-tiling-hosting/data-hosting/origin-of-the-maptiler-planet-data) [OpenStreetMap vector data](/guides/self-hosting/self-hosted-maps/openstreetmap-vector-data) [MapTiler Countries dataset](/guides/map-tiling-hosting/data-hosting/maptiler-countries-dataset) [MapTiler Planet updates](/guides/map-tiling-hosting/data-hosting/maptiler-planet-updates) # Replacing name label Source: https://docs.maptiler.com/guides/map-design/replacing-name-label/ This page aims to provide guidance on replacing and creating new names for cities and streets. Understanding this process is crucial for several reasons. We will explore the use of [**MapTiler Vector Data Editor**](/guides/map-design/creating-a-custom-vector-dataset-geojson) and [**MapTiler Map Designer**](/guides/map-design/how-to-make-custom-map-design-in-maptiler-cloud) tools. Common Reasons for Changing Names --------------------------------- * A name could have been changed officially recently, and this change has not been populated in the [**various sources**](/guides/map-tiling-hosting/data-hosting/origin-of-the-maptiler-planet-data) we are using, for example, OpenStreetMap. * You want to use fixed names across all languages. * You just want to make a funny map. Step-by-Step Guide -------------------- ### Step 1: Create a New Dataset As a first step, you will need to create a new dataset. This can be done directly in the Cloud by going to [**Data**](https://cloud.maptiler.com/data/new/) and starting a new dataset. ![mceclip0.png](./26237888154129_ce51ef9d20.png) Follow by opening the vector editor itself. ![mceclip1.png](./26237868903057_4cfa1cd5f9.png) ### Step 2: Create a Data Point for City Label The following video will showcase how you can create a data point with the name you want to have displayed on the map. In the example, I have decided to create a new data point to replace the name of the city “Kopřivnice” with “Tatra City” as it is known for manufacturing famous Tatra trucks. 1. Search for the city you want to rename. 2. Change the basemap to either any of your custom maps or our standard maps; I have chosen Streets. 3. Create a **point** over the label we will be replacing. 4. Add a **new property** (name) and populate it with the desired name for our point (Tatra City). 5. Save and publish the changes in the vector editor. 6. You have prepared the **data point** with the new name. ### Step 3: Add Data Point to the Map In the cloud, go to [**Maps**](https://cloud.maptiler.com/maps/) and choose the map you want to edit. In my case, I will be editing our base Streets style, but you can use any of your already made custom maps or any of our standard maps. ![mceclip2.png](./26237868903569_bc98f84f1c.png) ![Screenshot 2024-06-25 125632.png](./26237868904209_f92669dcbf.png) We are in our customize tool where you can style the map to fit your needs. The following video will showcase how you can hide the original name and add the new layer with the data point we have created. 1. Zoom to the location of the city we will be replacing. 2. You can directly click on the label to open the **specific layer**. 3. Then switch from **Style** to **Data** and click on the specific point to copy the “name” tag. 4. You need to create a **filter** to hide the label for this specific name. To do that, click on add a filter and choose a name. 5. Paste the name into the field and hit enter or click on \+. 6. Click on the **green** dot to make it **red**—this will hide the city with that name from our map. 7. We will add our newly created data as a **layer** to our map. 8. Press Alt\+N or hit \+ in Layers. 9. Search for the name we have saved the data point under, “Tatra City.” 10. Choose the data and hit Continue. 11. Select the **Geometry**. In this case, we are using Point followed by **Visualization**. As we want to see the name, we will choose **Symbol**. You can also add the name for the layer for better organizing. 12. Now, you can style the layer manually or copy the style from the Town Layer (right\-click and copy layer properties, then right\-click on our new layer and paste style properties) to make it identical to the other city labels. 13. What's left to do is to save and publish the map. **Congratulations, you have now successfully changed the name of the city.** ### Street Name We can use the same process for the entire street. The main difference is that instead of creating a single point, we will have to create a **LineString** over the specific street we want to rename. In this article, we have provided a comprehensive guide on how to replace and create new names for cities and streets using the MapTiler Vector Data Editor and MapTiler Map Designer tools. The key steps involve creating a new dataset, adding and editing data points, and then integrating these changes into your map. **Key Takeaways:** 1. **Creating a New Dataset:** Begin by creating a new dataset in MapTiler to house your custom data. 2. **Editing Names:** Use the vector editor to create a data point you want to rename, and assign it a new name. 3. **Adding Data to Maps:** Integrate the new data point into your map using the MapTiler Map Designer tool, ensuring that the original name is hidden and your new name is displayed. ## Next steps Continue to [Editing JSON](/guides/map-design/editing-json/) to learn how to edit JSON in MapTiler Map Designer. # Editing JSON Source: https://docs.maptiler.com/guides/map-design/editing-json/ This page explains how to edit JSON in MapTiler Map Designer. The **JSON editor** in **MapTiler Map Designer** allows the writing or adjustment of any **style.json code**. Cartographers and other advanced users can leverage this to **manipulate complex data expressions** that are not editable on the UI. JSON editor ----------- JSON editor can be accessed after **clicking on a specific layer**. Either navigate to the bottom of the page and click the **{ } symbol** or use the **Alt\+E shortcut**. ![json-editor.png](./17141988221969_5a5fd2ca82.png) After opening the JSON editor, you will see the JSON syntax of the selected layer. You can directly type or paste into the editor, and in case of a **syntax error**, you will be notified with **code marked in red**. After hovering a mouse over it, you will get suggestions for fixes. MapTiler Map Designer is compliant with [GL Style Specification](/gl-style-specification/).  ![json-error.png](./17141979335569_c3c484909e.png) Search functions ---------------- When working with complex JSON layers, the search functions might come in handy. You can use the **search dialogue** directly in the JSON editor to look for specific text sequences or use **focus functionality**. With the **search**, it is possible to use **find & replace** based on match case, whole words, or regular expressions. Search is available through the magnifier icon. ![json-search.png](./17141988226065_fe30de6a5a.png) With the **focus**, you can have only specific JSON properties visible in the editor: layout, paint, metadata, or filter. Focus is a drop\-down menu atop the JSON field. ![json-focus.png](./17141979347089_0f094aaff8.png) Fallback on complex expressions ------------------------------- MapTiler Map Designer UI currently **does not support the editing of complex data expressions** (such as  "match", "case" or "get") or **nested** ones. If such an expression is used in a map style, Map Designer will let you know by the **"Set by expression"** button that will switch to JSON editor with a click. There, it is possible to edit or write any expression compliant with JSON syntax. ![json-expression.png](./17141988230673_edb75ebbc6.png) Conclusion ---------- With the JSON editor in MapTiler Map Designer, it is possible to do **advanced editing or writing style JSON codes by hand**. If there is a complex or nested expression used in a map style, UI will switch to the JSON editor, where you can edit any part of your code. ## Next steps Continue to [Map data visualization with MapTiler](/guides/map-design/map-data-visualization-with-maptiler-cloud/) to learn how to create three different types of data visualizations in MapTiler: Circles, Heatmaps, and Choropleth. Useful links ------------ [GL Style Specification](/gl-style-specification/) # Map data visualization with MapTiler Source: https://docs.maptiler.com/guides/map-design/map-data-visualization-with-maptiler-cloud/ This tutorial shows how to create three different types of **data visualizations** in MapTiler: **Circles**, **Heatmaps,** and **Choropleth**. As a background for your data, we recommend using the **MapTiler Dataviz** map style created specifically for data visualization, data overlay, analytics, or dashboard use cases. ## MapTiler Dataviz Basemap MapTiler Dataviz is a **simple background map style** for data visualization. You can find it listed as a **Standard map** in your MapTiler account's [Maps section](https://cloud.maptiler.com/maps/stage/). To view all the variants of the Dataviz map, click on the **NEW MAP** button and switch to the Simple category. ![dataviz.png](./13042728912785_b1509edacd.png) There are two other variants of the Dataviz map \- **Dark** and **Light**. The Dark mode is based on black and dark grey colors. It's a perfect choice for usage in dark user interfaces or during **night hours**. The Light mode uses a **pared\-down** color palette based on light greys and pure white colors. Both style variants won't distract the map users so they can focus on your data. ![dataviz-light.png](./13042732048017_182ebee5fc.png) All Dataviz variants are **optimized for data overlay**. There is a focus on **boundaries** and **place names** across the zooms but other than that, the map contains only a **minimum amount of information**. This way your visualizations won't be disrupted but your users will still benefit from the much\-needed geographical **context**. ## Data Overlay You can **use your own datasets** in various formats in the MapTiler [Data section](https://cloud.maptiler.com/data/). You can either start drawing by hand **from scratch** or **upload your prepared data**. Supported formats for the upload include GeoJSON, GPX, KML, SHP, or zipped SHP. The file size limit is 10 MB with 10 000 features. For larger datasets, you should use [MapTiler Engine](https://www.maptiler.com/engine/) software to [convert them into **optimized MBTiles**](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-vector-data). Then you can upload the tiles into your [Tiles section](https://cloud.maptiler.com/tiles/). Another supported container for vector or raster tiles is the GeoPackage format. Once you have your data ready in MapTiler, you can add them to your map in the **Map Designer** tool (access via **Customize** button under your map). Go to the Layer tab, click on the **"Plus" button** and choose adding a layer. You can move the newly created layer in the **Verticality** tab to change the layer order in your map. For most cases, we recommend **aligning your data directly under the labels**. ## Circles Dataviz For the **Circles data visualization**, we are using a modified point dataset of Earthquakes from [USGS](https://earthquake.usgs.gov/). There are many other free sources of cool point data such as Meteorite Landings from [NASA](https://data.nasa.gov/dataset/meteorite-landings) or Global Airports from [HDX](https://data.humdata.org/dataset/global-airports). When adding the data as a layer to your map, be sure to select a **circle** visualization. Color is based on the **magnitude value** of the point varying from 6 to 0\.5\. We are using the `case` expression below. You can adjust the expressions from this example or write your own based on the [GL Style Specification](/gl-style-specification/). Expressions can be written in the JSON editor tab (accessible by Alt\+E shortcut). This particular piece of code needs to go to the "paint"{} section as "circle-color." ```json [ "case", [">", ["get", "mag"], 6], ["literal", "hsl(0,0%,0%)"], [">", ["get", "mag"], 5], ["literal", "hsl(351,100%,51%)"], [">", ["get", "mag"], 4], ["literal", "hsl(277.2,94.7%,14.7%)"], [">", ["get", "mag"], 3], ["literal", "hsl(300,79.4%,19%)"], [">", ["get", "mag"], 2], ["literal", "hsl(319,83%,36%)"], [">=", ["get", "mag"], 1.5], ["literal", "hsl(310,95%,50%)"], [">=", ["get", "mag"], 1], ["literal", "hsl(311, 100%, 73%)"], [">=", ["get", "mag"], 0.5], ["literal", "hsl(312, 100%, 83%)"], ["literal", "hsl(312, 100%, 91%)"] ] ``` You can also adjust the **Opacity** and **Stroke** color of the circles. The circle size depending on the magnitude value is achieved with the `interpolate` expression varying based on the zoom level. This particular expression is a property of "circle-radius". ```json [ "interpolate", ["linear"], ["zoom"], 0, ["*", 1, ["get", "mag"]], 12, ["*", 10, ["get", "mag"]] ] ``` Now you have your Circle map ready. With the use of Dataviz as a basemap, there are no map features disturbing your data but your users can still see the cities most affected by earthquakes. ## Heatmap Dataviz We are using the same modified Earthquakes datasets for the **Heatmap** as well. This time, you need to select a **heatmap** **visualization** when adding the data as a layer. You can adjust the **Radius**, **Weight**, **Intensity,** and **Opacity** of your heatmap. In this example, we have the Radius set to 5 from zoom 1, and to 25 from zoom 7\. The Opacity is 0\.5\. The remaining parameters have default settings. ```json { "paint": { "heatmap-radius": { "stops": [ [1, 5], [7, 25] ] } } } ``` The color scheme is generated **automatically** by MapTiler. And by that, your Heatmap is ready to be used. ## Choropleth Dataviz For the Choropleth, you can use **various polygon datasets** available for free such as [Natural Earth](https://www.naturalearthdata.com/) or [MapLibre Rwanda provinces](https://maplibre.org/maplibre-gl-js/docs/assets/rwanda-provinces.geojson) dataset. We used example data on the **Mean age of women at first marriage** from EUROSTAT available [here](/sdk-js/assets/Mean_age_of_women_at_first_marriage_in_2019.geojson) as a GeoJSON. When adding your data to the map, you have to select the **Polygon visualization** to color the polygons based on your data attributes. In this example, we used the `get` an expression that works with the name of your attribute. ```json [ "interpolate", ["linear"], ["get", "age"], 23, "#FFFFFF", 24, "#FCE622", 25, "#B0DD2D", 26, "#5ECA60", 27, "#24AA82", 28, "#228B8D", 29, "#355F8C", 30, "#472A7A" ] ``` Feel free to play with the **Country labels' colors** to ensure they are visible on the Choropleth. You can adjust the **Color**, **Opacity,** or the **Halo** around them. You can also follow our [Choropleth tutorial](/guides/map-design/how-to-style-a-choropleth-map-in-the-customize) and use MapTiler Countries as a source dataset. ## Conclusion The **MapTiler Dataviz** map is the perfect match for the **data visualization use cases**. As shown above, you can create various visualizations of your **own custom data** with MapTiler atop this map. Integrate it seamlessly into your **data dashboards or applications** and enjoy the **minimalistic background emphasizing your spatial data**. ## Next steps Continue to [Preparing gridded raster data for visualization](/guides/map-design/preparing-gridded-raster-data-for-visualization/) to learn how to select and prepare raster data for use in a data visualization created with the MapTiler SDK and weather module. ## Useful Links [MapTiler Dataviz Map](https://cloud.maptiler.com/maps//) [How to add a custom dataset or tileset to your map in MapTiler](/guides/maps-apis/maps-platform/dataset-upload-formats-and-limits) [How to upload map tiles to MapTiler](/guides/map-tiling-hosting/data-processing/how-to-upload-a-tileset-to-maptiler-cloud) [How to style a choropleth map in the Edit Tool](/guides/map-design/how-to-style-a-choropleth-map-in-the-customize) [MapTiler Planet Schema](https://docs.maptiler.com/schema/planet/) # Preparing gridded raster data for visualization Source: https://docs.maptiler.com/guides/map-design/preparing-gridded-raster-data-for-visualization/ This page shows how to select and prepare raster data for use in a data visualization created with the MapTiler SDK and weather module. Data from different time slices are prepared to create an animation in the browser. The document highlights the different steps required to get the best results when visualizing the data. ## Data visualization Data visualization is a key use of maps and is growing in popularity using specialist software. While it can be easy to produce simple spatial data visualizations such as basic choropleths using JavaScript mapping libraries, controlling the finer details or presenting data differently for people with different needs can be difficult. I wanted to create an interactive data visualization taking the form of a map showing how the global population has changed over time. To reveal the details, the user needs to be able to zoom and pan the map and move backward and forward in time. In this blog, I will take you through the processes and thinking behind the decisions made while building it using the MapTiler SDK Weather module.
Get the code > View Fullscreen >
This tutorial documents how the data was acquired and the processing and design decisions made to get the data ready for visualizing with the MapTiler SDK. Along with this tutorial, there is a news article about advanced data visualization and two more tutorials on how to process the data in MapTiler Engine and how to code the demo using the MapTiler SDK: 1. [Visualizing population density on JavaScript Maps](https://www.maptiler.com/news/2024/08/visualizing-population-density-on-javascript-maps/) 2. [Global Population Density Data Processing](/guides/map-tiling-hosting/data-processing/global-population-density-data-processing-with-maptiler-engine) 3. [Visualize and animate population data in a browser](https://docs.maptiler.com/sdk-js/examples/weather-custom-dataset-population-density/) ## Data preparation Visualizing global Population density data over time will require aligning datasets from different time points in terms of their spatial extent and format. Proper data preparation is key to any good data visualization. Sketches and planning will help you better understand what is possible and give you a better idea of the attributes and IDs you may need to display the data correctly or join it to other datasets. ### Global population dataset For this project, I used a gridded population of the world dataset from NASA’s Socioeconomic Data and Applications Center ([SEDAC](https://sedac.ciesin.columbia.edu/)), namely the [Population Density v4\.11 dataset](https://earth.gov/ghgcenter/data-catalog/sedac-popdensity-yeargrid5yr-v4.11). I opted for the GeoTIFF format with the highest resolution (30 seconds, which is approximately 1km squares) and downloaded the data for 2000, 2005, 2010, 2015, and 2020\. *Note: Downloading the data from SEDAC is free but requires you to be logged in.* ![SEDAC.png](./27702307473937_6f3896f463.png) The data are float 32 rasters where each pixel's value contains the average population density in “the number of people per square kilometer”. More information about this data can be found in the very comprehensive [sidecar document from SEDAC](https://sedac.ciesin.columbia.edu/binaries/web/sedac/collections/gpw-v4/gpw-v4-documentation-rev11.pdf) (p. 14 *"2\. Population Density, v4\.11 (2000, 2005, 2010, 2015, 2020\)"*). ## Data processing I am using MapTiler’s weather Library for this data visualization, as it is designed to display raster maps that change over time. We want the maps to display on the web, so we’ll use the Web Mercator projection, which all JavaScript Mapping Libraries can handle. We’ll also want the data to be in PNG format to ensure they are compact enough to load fast enough to be interactive maps. The maps should zoom in to at least level 7 to see all the details. First, let's look at the **output size**. Here, I made decisions to ensure the output is manageable and has enough detail. The [MapTiler Weather](https://docs.maptiler.com/sdk-js/modules/weather/) module uses square\-shaped web Mercator tiles. The total size of the data depends on the maximum zoom level and individual tile size. Let's see how far we can go: | **Zoom Level** | **No. of tiles on each axis** | **Total size in pixels** | **No. of tiles** | | --- | --- | --- | --- | | 0 | 1 | 512 | 1 | | 1 | 2 | 1024 | 4 | | 2 | 4 | 2048 | 16 | | 3 | 8 | 4096 | 64 | | 4 | 16 | 8192 | 256 | | 5 | 32 | 16 384 | 1024 | | 6 | 64 | 32 768 | 4096 | | 7 | 128 | 65 536 | 16 384 | The original data is 43 200 x 21 600px and could be reprojected to a 43 200 x 43 200px image in Web Mercator without losing detail along the longitude axis. Since the total size of a tiled dataset can only be in powers of 2, we need to choose wisely which zoom level (z) we want to generate tiles up to. In this situation, we have two possibilities: * I downsample from 43 200 to 32 768, targeting a max zoom level of 6 * I upsample from 43 200 to 65 536, targeting a max zoom level of 7 To avoid losing precision, we'll upsample and generate tiles up to zoom level 7\. (spoiler: each yearly tileset up to zoom level 7 will be \~100 MB, for a total of 21 845 tiles!) Next we need to look at the **scaling of the data.** I’ve chosen to use PNG tiles, though you could also use WebP or JPEG. PNG pixel values are limited to integer values between 0\-255\. Since the population density greatly exceeds 255, we must scale the density values. We can find the max value by reading the highest pixel value in each tiff file using **gdalinfo** or any image analysis software. Be aware that if there are errors in the data, the software will pick these up. ***Note:** If your data contains an erroneous outlier, it could lead to a mistake at this point. Cross\-check any maximum value results with trusted research on the topic of your data! The data used in this example contained a peak value of over 800 000 people per km2\. Research on the topic reveals a sensible value to be nearer 80 000\.* These are peak values found at the heart of the densest urban areas such as Macau, Paris, or Manhattan. When it comes to linear scaling down to a smaller integer range, there is no “*one size fits all*” strategy. We can include the maximum densities, but this will create larger "bins": each value from the range \[0\-255] will represent more people, hence losing granularity. Example: * scaling 0\-20 000 down to 0\-255 will result in a precision step of 78 * scaling 0\-40 000 down to 0\-255 will result in a precision step of 156 * scaling 0\-80 000 down to 0\-255 will result in a precision step of 312 In terms of data visualization, capturing the peak values is great as they often play the role of a reference point (at least visually) to compare to the rest of the data. However, capturing the fluctuations where values are minimal is important in less populated places. As we see above, if we chose a maximum value of 40 000, we won't be able to represent places with a density somewhere between 0 and 156 people per square kilometer, and this granularity is too coarse for this project. It especially matters for visualizing changes in rural areas. But scaling does not have to be linear! For capturing peak values and fine variations on the lower end, it’s better to encode the square root (*sqrt*) of the values. Let's see how the two compare once decoded: | Tile value (uint8\) | Population density (linear) | Population density (sqrt) | | --- | --- | --- | | 0 | 0 | 0 | | 1 | 156 | 1 | | 2 | 313 | 4 | | 3 | 470 | 9 | | 4 | 627 | 16 | | ... | ... | ... | | 120 | 18 823 | 14 400 | | 121 | 18 980 | 14 641 | | 122 | 19 137 | 14 884 | | ... | ... | ... | | 251 | 39 372 | 63 001 | | 252 | 39 529 | 63 504 | | 253 | 39 686 | 64 009 | | 254 | 39 843 | 64 516 | | 255 | 40 000 | 65 025 | While the linear encoding applies the same step on the whole range, the sqrt method applies a much finer step on small values and a larger one on the upper end. As a bonus, sqrt can also encode larger peak values so the cap is now 65 025! Here's how they compare in a more graphical form (green is linear, red is sqrt, black is 255, the maximum value possible on the PNG). I have swapped the axes to make it easier to decode the values. ![encoding.png](./27702323752081_eb11c75ce9.png) Having a fine granularity on the lower end also makes our visualization more interesting in less crowded areas. Here is the East Coast of the US seen with the TURBO color ramp capped at 40 000 (year 2000\): | Population density (linear, max: 40000\) | Population density (*sqrt*, max: 65025\) | | --- | --- | | ![linear40k.jpeg](./27702323765137_6cb9b68945.jpg) | ![linear65k.jpeg](./27702323770897_c55789378d.jpg) | We can already spot patterns at a semi\-global scale thanks to the sqrt encoding and its smaller steps at low density. Have a look at the Appalachian terrain and its population density: | Appalachian Terrain | Appalachian Population density (*sqrt*) | | --- | --- | | ![AppalachianTerrain.jpeg](./27702307486225_86561b7537.jpg) | ![AppalachianSqrt.jpeg](./27702307487505_35d8047a80.jpg) | To compute the *sqrt* form from the original GeoTiff provided by SEDAC, we can use the following GDAL command: ``` bash gdal_calc.py -A gpw_v4_population_density_rev11_2000_30_sec.tif --outfile=density_2000_sqrt.tif --calc="numpy.where(A<0, 0, numpy.sqrt(A))" --hideNoData ``` In the above, we also put all the *no\-data* values from \-3\.402823e\+38 to 0. As a result, we get a GeoTiff that is still *float32* and the original projection, but with scaled values and *no\-data* replaced by zeros (which makes sense in our case because no\-data was placed only where population density is zero). Global Population data conversion --------------------------------- The final step in data processing is to convert from the data’s original projection, Plate\-Carrée, to Web Mercator. The most convenient method to tile a GeoTiff, regardless of its source projection, is to use [MapTiler Engine](https://www.maptiler.com/engine/). Once you open MapTiler Engine, you must follow a few steps to convert a GeoTiff, export it as *mbtiles,* and host it on MapTiler. The steps are detailed in the [**Global Population Density Data Processing with MapTiler Engine tutorial.**](/guides/map-tiling-hosting/data-processing/global-population-density-data-processing-with-maptiler-engine) ![engine.png](./27702402125329_c3270636b3.png) We will have to repeat these steps again for the years 2005, 2010, 2015, and 2020\. At the end of the process, the new raster tilesets are available under the **My Tiles** section in your [MapTiler](https://cloud.maptiler.com/tiles/) space, where you can get some info, including their tileset IDs (this will be useful later!) Building an interactive JavaScript Web Map Visualization -------------------------------------------------------- Now that our data is ready for visualization, we need to use technology that can handle zooming, panning, and timelapse animation. At MapTiler, we have developed the [Weather Library](https://docs.maptiler.com/sdk-js/modules/weather/) module for our web mapping SDK. This JavaScript library and the data layers we provide with it let you show many different animated layer types (temperature, wind with particles, cloud coverage, etc.) in a super easy way. This library could also be used for non\-weather raster data visualization, animated and interpolated over time; this is exactly what I did with the population density! The complete source code for the interface seen in the demo at the top of this article can be found in the [**Visualize and animate the evolution of population data**](https://docs.maptiler.com/sdk-js/examples/weather-custom-dataset-population-density/) tutorial. ## Next steps Continue to [How to add MapTiler attribution to a map](/guides/map-design/attribution/add-attribution/) to learn how to include an appropriate copyright attribution. # How to make a retro map Source: https://docs.maptiler.com/guides/map-design/tutorials/how-to-style-a-retro-map/ In this tutorial, you'll learn how to create this beautiful **retro map** using our visual map editor [Map Designer](/guides/getting-started/map-design/): > [!WARNING] > Please note that this tutorial uses an [older generation of MapTiler maps](/guides/updates/#2025-11-new-generation-of-maptiler-maps) and the described workflows **might not be accurate anymore**. We recommend to use this guide as a **source of design tips and tricks** from our cartographers rather than relying on detailed step-by-step instructions. ## Source files To create this exact map, you'll need these files: - [retro_icons.zip](./retro_icons.zip) ## Color palette For a vintage-feel map, you need to select the right colors, fonts, and features. Choice of colors is key as retro maps typically use **pastel colors**: variations of brown, beige, and dusty pink to imitate the aged and worn feeling. Start from deeper zoom levels and then adjust as you go up. I started from the [Bright](https://cloud.maptiler.com/maps/editor?map=bright-v2) map style and zoomed in so that I could see buildings. ![color_palette.jpg](./19950465261713_5303affb08.jpg) To create additional colors in the same style, I use different opacity or lightness values. ## Map features The next step is the selection of features that should be included in the map. The Bright map style I started from is quite rich, so I decided to get rid of a few layers: * Sand * Water offset * River tunnel * Tunnel path * Ferry * Ferry labels * Oneway road * Highway shields * Building top * Transport * Shopping * Sport * Food * Drink * Other POI To reduce the number of POIs further, I went into the Amenity Data tab and included only bank, cemetery, library, park, post, and town\_hall classes. I also removed all icons except for the star in Capital City labels and the circle in City labels. ## Fonts and labels What's typical for old\-looking maps is the use of **Serif fonts** to imitate the look of traditional typefaces from the age of Johannes Gutenberg. In MapTiler Map Designer, you can choose from multiple Serif font families: Cinzel, Libre Baskerville, Merriweather, Noto Serif, PT Serif, and Vollkorn.  Next, you should think about different font types to **differentiate between labels** or to create a hierarchy. For more important features, use Bold types; for emphasizing a difference, use Italic.  I used the following Merriweather types for label layers: * Bold: Continent, Country, and Capital city labels * Regular: City, Island, Town, and Road labels * Italic: State, Place, Lake, Sea, and Ocean labels * Light: Village labels * Light Italic: River labels For POI layers, I used Light Italic up to Zoom 16, then from Zoom 16 a classic Italic so that the labels are readable on top of the Buildings. To differentiate between different kinds of labels, I also leveraged the **letter spacing**. * 0em (none): Town, Village labels * 0\.1em: Lake, Sea, Lakeline, River, Island, Airport labels, and all POI layers * 0\.2em: Capital city, State, and City labels * 0\.3em: Continent and Country labels * 0\.4em: Road labels You can also transform some of the labels to **uppercase,** which I did for Continent, Country, Capital city, State, Island, and Place labels. ![retro_fonts.png](./19945326971665_3d321ab2e1.png) For better readability, I added a halo to all labels, using \#F9F1DC color, 80% opacity, width ranging from 1 to 1\.5px, and a bit of blur. ## Patterns and icons Many old maps are easily recognizable by their imperfect paper texture and patina, indicating usage over the years. This feeling can be mimicked by creating an **SVG** **seamless dot pattern** designed in graphic software such as Inkscape.  The key here is not to make all the dots the same. You can start from perfectly symmetrical dots and then distort them randomly. The background needs to be transparent. ![retro_pattern.png](./19945326979473_3de4db8d1a.png) I tried to keep it simple with icons, as there are usually not that many on vintage maps. It is more common to have unique drawings alongside the actual map, but that would take a lot more work in Inkscape! I kept only **star** and **circle** icons for Capital cities and Cities. I recommend you keep these kind of icons around 15x15 px in size. ![retro_icons.png](./19950977592337_053499cb79.png) Compress all files into one ZIP and upload it to your map. The **Icons** upload is available in the menu in the top\-right corner. I toggled off the **Convert to customizable icons (SDF sprite)**option to have the icons rasterized.  ![icons-upload.png](./28481481906449_22d5cdb7a1.png) For the pattern styling, I created two additional layers: The background pattern on top of the Background and the Water pattern on top of the Water layer and made their opacity 5%. ![retro_pattern_styling.png](./19946541518097_71357dd1f5.png) ## Use your map When done, you can [publish](/guides/map-design/how-to-publish-a-map/) your custom map and share it with the world. The options are the same as when [using a ready-made map](/guides/getting-started/use-map/). > [!IDEA] > The easiest way is to add the map to your website [as an iFrame](/guides/getting-started/use-map/iframe/). Put your retro map out there and let everyone see their favourite locations, zoom around, and enjoy the blast from the past. # How to make a pop art map Source: https://docs.maptiler.com/guides/map-design/tutorials/how-to-style-a-pop-art-map/ In this tutorial, you'll learn how to create this cool **pop art map** using our visual map editor [Map Designer](/guides/getting-started/map-design/): > [!WARNING] > Please note that this tutorial uses an [older generation of MapTiler maps](/guides/updates/#2025-11-new-generation-of-maptiler-maps) and the described workflows **might not be accurate anymore**. We recommend to use this guide as a **source of design tips and tricks** from our cartographers rather than relying on detailed step-by-step instructions. ## Source files To create this exact map, you'll need these files: - [pop-art.zip](./pop-art.zip) ## Toner map style Love the look of **classic comic books**? Create a **pop\-art** map using a bit of contrast, halftone dots, and add cool icons. If there is one style that rules them all when it comes to pop art, it's [Toner](https://cloud.maptiler.com/maps/toner-v2/). Toner was originally developed by Stamen Design as a black and white map, rendered as raster tiles.  MapTiler's Toner is a vector tile GL JS style adapted by our team.   ![toner.png](./20350820970513_c7673f00d4.png) We will start from this map style and adjust it with the [Map Designer tool](https://cloud.maptiler.com/maps/editor?map=toner-v2) so it's more pop\-arty. First, I removed a few label layers that would crowd our map too much once I added more patterns and icons over the top: - Town labels - Village labels - Ocean labels - Lake labels - Lakeline labels - Park labels ## Icons & patterns Now, let's prepare some pop\-arty icons and patterns. For the **halftone dot pattern**, I recommend following this amazing blog about **[Halftone Bathymetry in MapLibre GL JS](https://snailbones.medium.com/halftone-bathymetry-in-maplibre-gl-js-b143651410c2)**. You can download the SVG circles of different sizes, adjust them in Inkscape, and then upload them to MapTiler. I also prepared some **starburst and bubble speech icons** typical for comic books. I got inspired by the great works on the [Noun project](https://thenounproject.com/), where you can again download SVGs and use them for your maps. Just don't forget to credit the author. These starburst icons come from [Lucas Helle](https://thenounproject.com/lucashelle/). ![pop-art-icons.png](./20350850690833_9ccb1868e8.png) On top of this, I also want to use the **existing Toner patterns**. These can be found on the [OpenMapTiles GitHub](https://github.com/openmaptiles/maptiler-toner-gl-style/tree/master/icons). Compress all SVG files into one ZIP and upload it to your map. The **icons upload** is available in the menu in the top-right corner. Choose **vector icons** (we are uploading SVGs) and **toggle off** the **Convert to Customizable icons (SDF sprite)** option to have the icons rasterized. This way the patterns will work properly. ![convert.png](./image-20241031-123913.png) If you don't want to create your own icons and patterns, I attached my [ZIP file](./pop-art.zip) at the end of this article. You can upload this one straight away to your map. ## Styling the map Let's return to the map and style it using the icons and patterns. Add the Ocean bathymetry layer: **Ocean** \> **contour** as a Polygon. Go to the Verticality tab and move it above the Water layer. Using the JSON Editor (Alt\+E), add **different dot patterns based on the depth**. Your code for the layer should look something like this: ```json { "id": "Contour", "type": "fill", "source": "ocean", "source-layer": "contour", "layout": { "visibility": "visible" }, "paint": { "fill-pattern": [ "step", ["get", "depth"], "dot-1", -6000, "dot-1", -5000, "dot-2", -4000, "dot-3", -3000, "dot-4", -2000, "dot-5", -1000, "dot-6", -500, "dot-7", -100, "dot-8" ] }, "filter": ["==", ["geometry-type"], "Polygon"] } ``` ![pop-art-ocean.png](./20351574456721_12c991c357.png) For the **Country labels**, I changed the font to Nunito Black, adjusted the size to 16 on Zoom 3 and 18 on Zoom 5, and transformed it to uppercase. If you change the Outline Width to a size of about 50px, you will get a nice newspaper effect underneath. ![toner-countries.png](./20353710781841_1acf6763f1.png) I also want to **differentiate Capital cities from regular cities**. Duplicate the City labels layer and name it Capitals labels. Go to the Data tab and filter out only capital of value 2 (all the others need to be red). The opposite needs to be done for the City labels. ![toner-capitals.png](./20381581892753_f32d9fa322.png) For the Capitals, you can adjust the visibility and move the min zoom to 3 so the labels will appear sooner. Now add the `boom-1` icon or any other starburst icon. For City labels, I added the `boom` icon. You can also adjust the text size and other properties. Your map can now look like this: ![toner-starburst.png](./20353737722513_4c6769593b.png) ## Finetuning Now that the map looks pop\-arty and pretty, it's time to play with details! As for me, I choose to add **US Highway shields** and **Art galleries**.  You can add highway shields from **MapTiler Planet** \> **transportation_name**. When adding the layer, use the **Filter network** to select only `us-interstate` highways and choose the **Symbol** visualization. In the Verticality tab, move the layer just on top of the Road labels.  Change the text field to `ref` and add an icon of your choice \- I used `bubble`. Now you can adjust other properties such as color, font, or size. ![toner-shields.png](./20354287768849_144ca79dc4.png) If the icon doesn't fit, you can move it using the Layout section \> Advanced layout properties under Ofset (same for the text). ![toner-offset.png](./20381581900945_c9102a1080.png) As for the Art galleries, I decided to add them so that the deeper zooms are also not without any pop\-arty icons. Add the layer from **MapTiler Planet** \> **poi.** Go to **Filter class**, add value `art_gallery` and disable "All other values" and "No value". Choose the Symbol visualization.  To see the galleries, you need to go to Zoom 14\+.  You can again adjust the text color, font, and add an outline and icon.  ![toner-gallery.png](./20355172909457_0db63417ea.png) ## Use your map When done, you can [publish](/guides/map-design/how-to-publish-a-map/) your custom map and share it with the world. The options are the same as when [using a ready-made map](/guides/getting-started/use-map/). > [!IDEA] > The easiest way is to add the map to your website [as an iFrame](/guides/getting-started/use-map/iframe/). Let your black and white pop art map catch everyone's eye like comic books once did! # How to make a picture-inspired map Source: https://docs.maptiler.com/guides/map-design/tutorials/map-styled-like-a-picture/ In this tutorial, you'll learn how to create a map **color-toned to match a selected picture** using our visual map editor [Map Designer](/guides/getting-started/map-design/): > [!WARNING] > Please note that this tutorial uses an [older generation of MapTiler maps](/guides/updates/#2025-11-new-generation-of-maptiler-maps) and the described workflows **might not be accurate anymore**. We recommend to use this guide as a **source of design tips and tricks** from our cartographers rather than relying on detailed step-by-step instructions. ## Source files To create this exact map, you'll need these files: - [dots.zip](./dots.zip) ## Get image color palette Do you have a **cool photo** with a great **color palette**? Sunset at sea, urban scenery, or it can be even a black & white photo! I chose this picture of a Favorit bike (source: [https://www.favorit.cz/technical\-data](https://www.favorit.cz/technical-data)) similar to what my grandfather used to ride. ![favorit_bycicle.png](./20526168729489_47b1a4c84d.png) To extract the colors, there are a number of tools, such as [Image Picker](https://coolors.co/image-picker) from Coolors, or you can do it yourself in Inkscape using the Color Picker. This is the color palette I got from this image. ![Favorit_palette.png](./20532661617681_12105fefb3.png) ## Modify colors for map Sometimes it happens that when you assign the colors to the map features in [Map Designer](https://cloud.maptiler.com/maps/editor), the map doesn't look that good. You either need to play with the **hue and contrast** or **add more colors**. The key here is to try different combinations and keep the **color theory** in mind. If the extracted colours suit the map right away, that's a win. I started with the [Dataviz](https://cloud.maptiler.com/maps//) map style. For this map, I realized I needed to modify and add a bunch of colors. Here are some of the changes I made: - modified the light grey color to beige for the background - gave the old rose color a bit more red for the road network and borders - added some dark colors for outlines and shadows - added light green for landcover - added dark purple for buildings ![color_palette.jpg](./20529967433745_a76b3b0f94.jpg) Just so you can quickly replicate this, here is the **list of all colors and layers** in my map. - \#F8EBD3: Background, Water labels, Bridge, Pier road, Outlines of Administrative labels - \#B2D3A6: Landcover, Forest (with 15\-35% opacity) - \#7DB0AE: River, Water - \#364449: Water shadow - \#C74D57: Railway, Road network, Railway tunnel, Tunnel, Tunnel path (all tunnels with 70% opacity), Aeroway, Residential (with 20% opacity) - \#D9D9D9: Tunnel outline - \#FFFFFF: Railway dash, Path outline, Railway tunnel dash, Fill of Road labels - \#FBF8F4: Pier - \#483519: Road network outline - \#000000: Outline of Road labels, Fill of Administrative labels, Building shadow - \#E5E1BD: Cemetery - \#463E74: Building top - \#AB3640: Border - \#545454: Fill of State labels ## Finetune details Now it's time to adjust fonts, text sizes and add some patterns. As for the font, I decided to switch to **Frutiger Neue Condensed Medium,** and I changed the **Letter spacing** (under Advanced text properties). Continent and Country labels were changed to 0\.2em and City labels to 0\.1em. I adjusted **sizes** for all Administrative labels by adding \+2 to \+3 points on each zoom using the JSON Editor. I also increased the **Outline width** to 2px.  ![favorit_labels.png](./20529973358225_1a8455eeb7.png) Then I thought some polka\-dot patterns might suit the map as it gives a bit of a retro vibe. For a **seamless pattern**, create a single dot in Inkscape (or other graphics software) and position it in the middle of the canvas. To have bigger dots, increase the size of the dot but also adjust the size of the whole canvas.  ![dot_pattern.png](./20529973366289_1b92904b1c.png) Once you have your dots ready as SVGs, ZIP them and upload them to your map (Close Map Designer \> three dots \> Symbols). I added the dots to water and buildings. In order to do this, you need to **duplicate** the layers and add the patterns to the layer **above**. ![dot_buildings.png](./20529973369361_9d35b686b6.png) Both my patterns are black, but a nice trick to have subtle dots on water is to add opacity of 10 %. ![ot_water.png](./20529967471377_98a6f2383c.png) ## Use your map When done, you can [publish](/guides/map-design/how-to-publish-a-map/) your custom map and share it with the world. The options are the same as when [using a ready-made map](/guides/getting-started/use-map/). > [!IDEA] > The easiest way is to add the map to your website [as an iFrame](/guides/getting-started/use-map/iframe/). # How to make an Oktoberfest map Source: https://docs.maptiler.com/guides/map-design/tutorials/how-to-make-an-oktoberfest-map/ In this tutorial, you'll learn how to create this themed **Oktoberfest map** using our visual map editor [Map Designer](/guides/getting-started/map-design/): > [!WARNING] > Please note that this tutorial uses an [older generation of MapTiler maps](/guides/updates/#2025-11-new-generation-of-maptiler-maps) and the described workflows **might not be accurate anymore**. We recommend to use this guide as a **source of design tips and tricks** from our cartographers rather than relying on detailed step-by-step instructions. ## Source files To create this exact map, you'll need these files: - [icons.zip](./data/icons.zip) - [beer_poi.mbtiles](./data/beer_poi.mbtiles) ## Preparing the data The `beer_poi.mbtiles` data file is a selection of POIs (points of interest) such as restaurant, pub, bar, biergarten, or brewery for the German region of Bayern. We processed the data into MBTiles using [MapTiler Engine](https://www.maptiler.com/engine/), and you'll need them to show these places on your map using the custom beer mug icon. **Upload the data file to your MapTiler account:** 1. Go to the [Tiles section](https://cloud.maptiler.com/tiles/) of your cloud account and click on the **New Tileset** button. 2. Choose your `beer_poi.mbtiles` file you've downloaded from Source files to upload to your account. Find the dataset in the list and click on it to inspect it. You can check the details such as min and max zoom, data attributes, and location if you switch on the **Show basemap** button and zoom out a bit. ![upload-tileset.png](./18538162639121_dae2aafe4d.png) ## Creating a map Open [Map Designer](https://cloud.maptiler.com/maps/editor?map=bright-v2) with the Bright map. We'll use it as a base for your own custom map. ![customize-bright.png](./18538203656337_d24a28a219.png) ### 1. Adjust map colors In the Quick Edits, click on the **Map Colors Palette** and adjust the **Hue** to a value of around 47°. ![adjust-colors.png](./18538162646417_44609b6aa0.png) To polish the borders slightly, go to the **Layers** (Alt\+L), then to **Administrative** block, and select all border layers (Country, Disputed, Other) while holding Shift. Reset and change the **Color** to `#C28B00`. Then **Save** and **publish** the map, and close it by clicking on the **X**. ![adjust-borders.png](./18538203667217_d1e0c70201.png) ### 2. Add custom icons For Oktoberfest, we prepared a special beer icon along with two icons for cities. We've packed them into the `icons.zip` source file. To upload them to your map, go to the Quick Edits, section **Map icons**. If you need more detailed info, see [Customizing map icons](/guides/map-design/icons/). ### 3. Add beer POIs As we replaced the symbols, we are now missing some of the icons on the map. It’s no problem, however, as we will **switch off the visibility** of the affected layers to let the beer POIs shine. In the **Layers** panel, turn off the following layers by clicking on the **Eye** icon: * In Transport \- Oneway road, Highway shield, Highway shield (US) * The whole POI Block. Now Zoom to the München area. Next, click on the **Plus** button to Add a new layer. Search for the beer\_poi data, select a Point geometry, then choose a Parent Block (you can create a new one called Beer, for example), Symbol visualization, and preferred layer name. Then **Add the layer**. ![add-layer.png](./18538162665233_6dd4054ba6.png) ### 4. Adjust visualization Now you should see a lot of text added to your map. This is because the data is added with default styling. Change the following values: * **Font** to **Open Sans Semi Bold**. * **Adjust the size** with zoom range styling (three dots) to 14px at zoom 10, 16px at zoom 14 and 18px at zoom 22\. * **Change the color** to `#97741C`. * **Add outline** with `#FFF9EB` color, 80% opacity, 2\.5px width and 0\.2px blur. * **Add icon** with beer image. * **Adjust the icon size** with zoom range styling (three dots) to 0\.7× on zoom 9 and 1× on zoom 11\. * Open **Layout** and set the **Text Layout** anchor to **Top**. This will move the breweries' labels nicely under the icons. Adjust padding as needed. ![style.png](./18538877312785_a7fce56e61.png) Adjust the **filter**. Just replace the filter section with the following code. ``` json "filter": [ "has", "name" ], ``` This will ensure that only breweries with names will be displayed. Switch to the **Verticality tab** and move the Beer layer under Place labels so that you can see cities, villages, and other administrative names above the new labels we have added. ![verticality.png](./18538877317137_59efdcfb88.png) To add a **blurry effect**, go to the Background Block and duplicate the background. **Adjust the opacity** with zoom range styling to 100% on zoom 0, 90% on zoom 4, 60% on zoom 6 and 0% on zoom 9\. ![opacity.png](./18538862466449_0f0b049a1b.png) Switch to the **Verticality** tab and move this layer to the very top. If you zoom out of München so that you can see the whole of Germany or Europe, you'll see that the map goes blurry. ![blur.png](./18538862468241_0934aed5d0.png) ## Use your map When done, you can [publish](/guides/map-design/how-to-publish-a-map/) your custom map and share it with the world. The options are the same as when [using a ready-made map](/guides/getting-started/use-map/). > [!IDEA] > The easiest way is to add the map to your website [as an iFrame](/guides/getting-started/use-map/iframe/). Enjoy the Oktoberfest vibes! 🍻 # How to make a custom ocean map Source: https://docs.maptiler.com/guides/map-design/tutorials/how-to-use-maptiler-ocean/ Most web maps focus on the land features, and the ocean is often left as a flat blue polygon. Our [Ocean map](https://cloud.maptiler.com/maps/ocean-v4/) provides global bathymetry, including sea floors, depth contours and labels, and shaded relief. This guide explains how to customize the ocean depth styling in **Map Designer** to get your own maritime map. ## Get started To start customizing the Ocean map, open it in our map design editor. Open Ocean map in editor The editor loads with the **Quick edit** panel open, allowing you to make simple modifications of the map color range and fonts. ## Fine-tune colors and shading The Ocean map uses several dataset to render sea floor elevation and give it beautiful shading. You can use various styling methods that apply to both land terrain and sea floors. 1. Go to **Layers** → block **Ocean** → layer **Ocean RGB**. 2. In the layer settings panel, set the **Visualization** method: - To use sea floor **shading (3D)**, select `Hillshade` and adjust the shading method, color, opacity, and other properties. See the [hillshading guide](/guides/map-design/terrain/hillshading/) to learn more. - To use **color relief (flat)**, select `Color relief` and choose a **Color ramp** from the presets. See the [color relief guide](/guides/map-design/terrain/color-relief/) to learn more. ![Adjusting the Ocean map's color ramp](./ocean-color-ramp.png) ## Customize grid lines The latest version of our Ocean (v4) uses the [Grid](https://docs.maptiler.com/schema/grid/) dataset to show lines for time zones, meridians, circles of latitude, tropical circles, and their labels. - Go to **Layers** → block **Grid**. Now you can adjust the line styling and label fonts. - To hide the grid lines, click the little eye icon to hide all the lines and labels. - If you need more granularity, expand the **Grid** block and work with individual layers. ![Adjusting the grid lines](./ocean-grid.png) ## Add country borders By default, the Ocean map is "clean" and contains no land-based administrative boundaries. You can add these from the [MapTiler Planet](/schema/planet-v4/) dataset. 1. Go to **Layers** and click the **(+) Plus** button to add a new layer. 2. Select the **MapTiler Planet** data source. 3. Add the `country_border` layer. 4. Switch to the **Style** tab and adjust the color and width of the country borders. > [!IDEA] > To display only countries with a coastline, switch to the **Data** tab and add a **Filter** for the `maritime` attribute. If you also want to show the names of the countries, follow the same steps to add the `country_label` layer. ![Adding country borders to Ocean map](./ocean-country-borders.png) ## Customize depth layers For the ocean floor changing based on the **depth values**, there are fully customizable layers of different colors, going from the lightest blue for a depth of 0 m to \-50 m to the darkest for a depth of \-11,000 m to \-12,000 m. We are keeping consistent intervals between the depths, but you can modify the breakpoints if needed. The **depth labels** on contours are also changing based on the ocean floor. With the depth getting lower than \-4,000 m, the labels are paled out to stand out in the dark waters. Keep this in mind when modifying the depth layer and/or labels color. ![Ocean depth labels styling](./ocean-depth-labels.png) ## Use your map When done, you can [publish](/guides/map-design/how-to-publish-a-map/) your custom map and share it with the world. The options are the same as when [using a ready-made map](/guides/getting-started/use-map/). > [!IDEA] > The easiest way is to add the map to your website [as an iFrame](/guides/getting-started/use-map/iframe/). # How to create a custom 3D globe Source: https://docs.maptiler.com/guides/map-design/tutorials/how-to-create-a-3d-online-globe/ An interactive 3D globe is a modern way of presenting your online map. MapTiler has all the tools you need to create a map and apply the [globe projection](/sdk-js/#globe-or-mercator-projection) to it, turning a flat surface into a more accurate spherical shape. You can choose any of our [ready-made maps](https://www.maptiler.com/maps/) and use MapTiler SDK JS to [turn on the globe projection](/sdk-js/examples/globe-projection/) with a single line of code, and voilà! Get a 3D globe in the selected map design. In this tutorial, we'll teach you something a bit more advanced: creating a 3D globe with custom texture, using an image of your choice. As an example, we'll use Cassini's terrestrial globe from [David Rumsey's website](https://www.davidrumsey.com/blog/2009/9/7/cassini-terrestrial-and-celestial-globes-1790). If you follow along, you'll get this beautiful 18th century globe up and running: Custom 3D globe – result ## Before you start Before you dive into globemaking, make sure that: - You're logged in to your [MapTiler account](https://cloud.maptiler.com/). If you don’t have one, create it—it’s fast and free. - You have MapTiler Engine installed on your computer. It's free for non-commercial use. ## Get source data The source data for your historical globe is the image of its surface. Here's how to get it: 1. [Download the texture of Cassini's terrestrial globe here.](https://rumseygeo.s3.amazonaws.com/CassiniWorldGlobe1790_TIF.zip) Note that some web browsers may consider the file suspicious, because it's a ZIP archive. If the download gets blocked, allow it manually. For your ease of mind, scan the file with an antivirus program before opening it. 2. Unpack the ZIP archive. It contains a single GeoTIFF file named *CassiniWorldGlobe1790.tif*. Alternatively, you can use any picture with **side ratio 2 : 1** (fits the total 360 degrees of longitude and 180 degrees of latitude). The bigger the size and resolution of the image, the more you'll be able to zoom in without the globe surface going blurry. ## Prepare source data Before you can use the texture image, you'll need to transform it into **map tiles**. That's the raw map-ready material for a zoomable map. The map tiles come in a container file called a **tileset**. To prepare your tileset, run **MapTiler Engine** and open your texture image in it. MapTiler Engine will guide you through the whole tiling setup, step by step. Here's the information you'll need along the way: 1. On the first screen, open your texture image. 2. The next step depends on whether the image contains geodata or not. If it does, you get a preview of the image with the geodata displayed next to it. If not, MapTiler Engine asks you to specify it. Use these settings: - For **Geolocation**, select **Bounding box** and enter the values `-180 -90 180 90` to cover the whole world. - For **Coordinates**, enter the EPSG code `4326` to look up and use *WGS84*. That's the standard system. 3. On the **Output format** screen, select *GeoPackage*. 4. On the **Output settings** screen, check the box *Non-commercial use*. Otherwise keep the recommended values. 5. Select where to save the resultant file on your local drive. 6. On the **Upload options** screen, select *MapTiler Cloud*. 7. On the **Upload** screen, you can edit the name which your new tileset will have in MapTiler. 8. If you're using MapTiler Engine for the first time, you'll be asked to log in to your MapTiler account as the last step. When all the tiling parameters are set, MapTiler Engine automatically starts processing your image. Once it's done, you'll find your new tileset in MapTiler in the Tiles section, ready for use. > [!IDEA] > Tiling is also possible directly in your MapTiler account, **online**. Check the [compatible formats](/guides/maps-apis/maps-platform/dataset-upload-formats-and-limits/), and if your custom image is compliant, you can [upload it](https://cloud.maptiler.com/tiles/new) to have it processed and prepared fully automatically. ## Create map in Map Designer You've got the material ready, let's use it to create the globe. If you're a seasoned developer, you can do it programmatically with the help of **MapTiler SDK JS**: first [add the tiled image as a raster source](/sdk-js/examples/map-tiles/), then [turn on the globe projection](/sdk-js/examples/globe-projection/). If you prefer a no-code approach, use our Map Designer tool: 1. In MapTiler, go to **Maps** > **New map** > [Create blank map](https://cloud.maptiler.com/maps/create/empty). Give a name to your map. Then you'll land on a page with the map preview (which is now, as expected, blank). 2. Use the **Customize** button to open the map design editor. 3. In the menu panel, go to **Data sources** and add a new map data source using the plus button. From a list of all data sources available in your MapTiler account, select your globe texture tileset. If you kept the default name, it will be listed as *CassiniWorldGlobe1790*. 4. The data source is now associated with the map, but not actually used yet. Go to **Layers** and add a new map layer. You'll get a list of data sources to choose from, including the one you added in the previous step. Select the layer in the source (there will be only one) and add it to the map. This should fill the editor with your texture image. 5. Now go to **Settings**, section **Projection**, and switch the type to **Globe**. The flat texture image transforms into a sphere. Rotate it around and enjoy! 6. Before you leave Map Designer, don't forget to **Save** and **Publish** your work. *Publishing* means that the globe is ready to be shared with the world, but it's not actually visible to anyone unless you take further steps. ![Customize menu](./Customize_menu.png) ## Get map source code To use the prepared 3D globe in your web application, you'll need the source code. Here's how to get it: In MapTiler, go to [Maps](https://cloud.maptiler.com/maps/) and open your new globe map. The page lists ready-to-use examples, API calls and links to code snippets, so it depends on where and how you want to showcase your globe. > [!WARNING] > All the prepared examples on the map page already contain your **default MapTiler API key**. This means that any links or code that you copy here will work out of the box. However! The API key is not protected in any way, so you should only use it for testing. Make sure to **replace it** with a [new, protected API key](/cloud/api/authentication-key/) before sharing or publishing! Here are the two most common options: - **Get a link to your globe.** Copy it in the *Embeddable viewer* section. This is the simplest option. Note that it's very basic, no background etc. You can just [configure the link](/guides/map-design/how-to-make-maps-with-maptiler-cloud-api-use-cases-and-examples/#21-how-to-create-a-link-to-a-map) to set the initial display of your globe to a specific zoom and location. - **Get a complete HTML code.** Go to *Prepared examples* and click on **MapTiler SDK JS**. On the page that opens, scroll down to the preview of your custom globe. Copy the source code below and use it for your web app. This gives you many more possibilities, like adding sky, animating your globe, and other effects—[see examples](/sdk-js/examples/?q=globe). ![Prepared code examples](./prepared-code.png) If you prefer the **Cesium JS** library, you can [build your globe with Cesium JS](https://docs.maptiler.com/cesium/) instead. ## Useful links - [Globe vs Mercator (flat) projection](/sdk-js/#globe-or-mercator-projection) - [How to turn on the globe projection](/sdk-js/examples/globe-projection/) - [More globe examples and tutorials](/sdk-js/examples/?q=globe) # Add your data to the map Source: https://docs.maptiler.com/guides/map-data/add-your-data/ Once you have [selected a ready-made map](/guides/getting-started/use-map/), you'll most likely want to show something in it: the location of your shop, trail you've trekked, visualization of a future building, weather forecast... Whatever you need to share with the world, we have tools and services to help you prepare the data and put it on the map. This page explains the basics and helps you get started based on what type of data you want to add. ## Add points, lines, polygons Most objects on a map are essentially geometric shapes: **points** (single spots such as bus stops, lamps, trees), straight or curved **lines** (paths, roads, rivers), and area-covering **polygons** (buildings, forests, lakes). These object representations are called vector features, and they're especially suitable for adding your own to a map. 👉 [How to prepare and use vector data](/guides/map-data/use-vector-data/) ## Add images There's many different types of imagery you might want to use in your map, from simple icons to large sets of images taken from a drone, or even digitized historical maps. How to add them depends on the complexity of the task at hand. The easiest way is to add an image to your map as a linked data source, but it's only possible if the image has a public URL, and only advisable for simple tasks like adding a single image. Here's how to add an  image using [MapTiler SDK JS](/sdk-js/): - [Drone image](/sdk-js/examples/raster-layer/) - [PNG image (icon)](/sdk-js/examples/add-image/) - [Dynamically generated image](/sdk-js/examples/add-image-generated/) If you need anything more advanced than that, it becomes much easier to create a **raster tileset**. It's especially useful if your image is very large or if you have many of them. 👉 [How to prepare and use a raster tileset](/guides/map-data/use-raster-data/) ## Add elevation Enriching your maps with the 3rd dimension gives you additional options like visually enhancing hills and ocean depths, or providing helpful info to map users for their route planning. Elevation data can be stored and integrated as part of common formats that hold other information as well, like GeoTIFF. For pure elevation data, you don't need to create a custom dataset – we have global data ready for you. 👉 [How to use elevation data](/guides/location-services/elevation/) ## Add weather data Weather data is a special type of dynamic data describing atmospheric conditions such as temperature, humidity, precipitation, wind, and other information. To show it on a map, you first need to process the data into a suitable format. We have a separate section describing where you can get this data (if you don't have your own), how to prepare it, and how to build a weather app with it. 👉 [How to make weather maps](/guides/maps-apis/weather/how-to-make-weather-maps/) ## Add 3D objects It's possible to add 3D objects of many types. You can get a simple GLB model from 3D modelling software or an elaborate animated model, and make it rotate and move across your map, like in [this fun demo](https://www.maptiler.com/showcase/xmas/). We also support other object types, like ones created by photogrammetry or scanned with LiDAR into a point cloud. 👉 [See all 3D code examples](/sdk-js/examples/?q=model) ## Add a video 👉 [How to add a video to map](/sdk-js/examples/video-on-a-map/) # Upload your files to MapTiler Source: https://docs.maptiler.com/guides/map-data/upload-files/ If you have any existing files with map data and want to use them in a map, then the first step to do is to get them into your MapTiler account. There's several ways to do it so you can select the best one for your needs. > [!INFO] > You can only upload files in [supported formats and sizes](/guides/maps-apis/maps-platform/dataset-upload-formats-and-limits/). These limitations apply to all options described on this page. ## Visual interface The easiest way is to drag & drop your files to the [upload page](https://cloud.maptiler.com/tiles/new) in your MapTiler account. It's the best option if you're only uploading a few files and don't need any kind of automation. ## Upload API & CLI tool The [Upload API](/cloud/admin-api/tileset_ingest/) is a service API which you can use through our [CLI tool](https://github.com/maptiler/maptiler-cloud-cli). This makes it possible to integrate the upload process into your pipeline and automate it. See the complete guide 👉 [How to upload your data using API & CLI](/guides/map-tiling-hosting/data-hosting/how-to-upload-mbtiles-or-geopackage-into-maptiler-cloud-using-api/). ## Upload JS library The [Upload JS library](/upload-js/) is a helper library which you can use in your JavaScript/TypeScript projects. It's faster and more convenient to use than the CLI, and also offers extra features such as detailed progress reporting and multipart upload. - [Overview and how to use](/upload-js/) - [Reference](/upload-js/api/) - [GitHub](https://github.com/maptiler/maptiler-upload-js/) ## MapTiler Engine [MapTiler Engine](/guides/map-tiling-hosting/data-processing/) can upload your files quickly and easily, so if you have it installed, it might be quite convenient to use for this purpose: 1. Open MapTiler Engine and use the three-dot options button on the first screen. 2. Select **Upload to cloud** and follow the steps on screen. ![Upload files with MapTiler Engine](/guides/map-tiling-hosting/data-processing/intelligent-workflows/Engine-home-upload-to-cloud.png) With a paid Engine license, you can alternatively use the [CLI Upload utility](/engine/map-hosting/#maptiler-cloud). # Dataset upload – formats and limits Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/dataset-upload-formats-and-limits/ Our Cloud platform supports various geographical data formats, ensuring compatibility with popular mapping tools and libraries. Easily upload files directly through the Upload form in the Admin interface. Currently, we are supporting: * **Raster files** \- georeferenced files like drone imagery, old maps, or charts. Rasters are automatically optimized for use on the website \- tiled into tile packages * **Vector files** \- geographical vector formats from surveys, GPS logs, and government data. Vectors are automatically optimized for use on the website \- tiled into tile packages or imported as vector features editable in the Vector data editor * **Tilesets** (containers of tiles) \- read\-only; we recommend using clean tilesets produced by [MapTiler Engine](https://www.maptiler.com/engine/) ## Supported formats for tiling | **Format** | **Type** | **Max file size limit** | | --- | --- | --- | | [GeoTIFF](https://www.ogc.org/standard/geotiff/) | raster file | 1 GB | | [TIFF](https://www.adobe.com/creativecloud/file-types/image/raster/tiff-file.html) | raster file | 1 GB | | [ECW](https://hexagon.com/products/ecw-compression) | raster file | 1 GB | | [MrSID](https://www.extensis.com/mrsid-file-format) | raster file | 1 GB | | [GeoJPEG2000](http://giswiki.org/wiki/GeoJPEG2000) | raster file | 1 GB | | [JPEG](https://jpeg.org/about.html) | raster file | 1 GB | | [GeoPDF](https://www.loc.gov/preservation/digital/formats/fdd/fdd000522.shtml) | raster file | 1 GB | | [PDF](https://www.adobe.com/acrobat/about-adobe-pdf.html) | raster file | 1 GB | | [PNG](https://www.libpng.org/pub/png/) | raster file | 1 GB | | [WebP](https://developers.google.com/speed/webp/) | raster file | 1 GB | | [GeoPackage](https://www.geopackage.org/) | vector file | 1 GB | | [GeoJSON](https://geojson.org/) | vector file | 1 GB | | [GPX](https://www.topografix.com/gpx.asp) | vector file | 1 GB | | [KML](https://www.ogc.org/standard/kml/) | vector file | 1 GB | | [SHP](https://en.wikipedia.org/wiki/Shapefile) | zipped vector file | 1 GB | ## Supported editable vector features formats | **Format** | **Type** | **Max file size limit** | | --- | --- | --- | | [GeoJSON](https://geojson.org/) | vector features | 10 MB or 10 000 features | | [GPX](https://www.topografix.com/gpx.asp) | vector features | 10 MB or 10 000 features | | [KML](https://www.ogc.org/standard/kml/) | vector features | 10 MB or 10 000 features | | [SHP](https://en.wikipedia.org/wiki/Shapefile) | vector features | 10 MB or 10 000 features | ## Supported tileset containers | **Format** | **Type** | **Max file size limit** | | --- | --- | --- | | [GeoPackage](https://www.geopackage.org/) | container (SQLite file) | 100 GB | | [MBTiles](https://github.com/mapbox/mbtiles-spec) | container (SQLite file) | 100 GB | ## Supported tileset containers content | **Format** | **Type** | | --- | --- | | PNG | raster tiles | | JPG | raster tiles | | WebP | raster tiles | | [MVT](https://github.com/mapbox/vector-tile-spec) | vector tiles | Missing format? Send us a [request](/support/requests/)! # Host and use your image data Source: https://docs.maptiler.com/guides/map-data/use-raster-data/ MapTiler provides hosting for your map data of any size and type. You can integrate it with a map and serve to your audience without having to manage the hosting infrastructure. This page explains how to prepare, host, and use **raster geodata (images)**. For vector data, see [how to edit custom vector data](/guides/map-tiling-hosting/data-hosting/how-to-edit-your-vector-data-in-maptiler-cloud/). ## Prepare your image Although it is possible to [add an image to a map directly](/guides/getting-started/add-data/#add-images), in most cases, it's practical to turn it into a special map-ready format. This preparation is called *geoprocessing* and it cuts your image into a set of [raster map tiles](/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/#raster-map-tiles). Here's how to do it: 1. [Upload your image](https://cloud.maptiler.com/tiles/new) to your MapTiler account. 2. [Georeference your image](/guides/georeferencer/get-started/). *This step is only required if we don't find any location metadata (coordinates) in the image.* 3. When georeferenced, we automatically cut your image into map tiles. You'll find your new tileset on page [**Tiles**](https://cloud.maptiler.com/tiles/). Note that there are format and size limits for the upload. If your image data doesn't comply, or you just prefer to use your own hardware, check out [**MapTiler Engine**](/guides/map-tiling-hosting/data-processing/) for processing virtually any type or volume of data on-prem. ## Add your image to map {#add-your-image-to-map} Now that your image is ready in your MapTiler account, you can proceed to showing it on a map. Select your preferred way, with or without code: #### Add image to map programmatically A convenient option for developers is to use the **MapTiler SDK JS**. To get the code, go to the example [Add a raster tile source](/sdk-js/examples/map-tiles/). Don't forget you'll need a [MapTiler API key](/cloud/api/authentication-key/) for the code to work. #### Add image in visual editor For a no-code approach, use our visual map editor **Map Designer**. Here's the steps: 1. Go to page [**Maps**](https://cloud.maptiler.com/maps/) in your MapTiler account and click on **New map**. 2. Select a map you'd like to use and click **Customize**. This takes you to the map editor. 3. In the left menu panel, go to **Data sources** and add a new map data source using the plus button. From a list of all available data sources, select your raster tileset. 4. The data source is now associated with the map, but not actually used yet. Go to **Layers** and add a new map layer. You'll get a list of data sources to choose from, including the one you added in the previous step. Select the layer in the source (there will be just one raster layer) and add it to the map. *If you don't see the image on the map now, make sure you're in the right place and on the right zoom level.* ![Ebedding raster tiles in your map](./use-raster-tiles.png) 5. By default, the image layer gets added on top of the map. If you want to display some of the map features over your image, switch from the **Blocks** to **Verticality** view and reorder the layers, so that the desired features get on top. 6. Once you're happy with the result, **save** and **publish** your map. *Publishing* means that the map is ready to be shared with the world, but it's not actually visible to anyone unless you take further steps to [use the map](/guides/getting-started/use-map/) on a website or in your app. # Prepare and use custom vector data Source: https://docs.maptiler.com/guides/map-data/use-vector-data/ This page explains the different ways how you can prepare and add custom [vector features](/guides/map-tiling-hosting/data-processing/vector-feature/) (points, lines, polygons) to your map. Selecting the best way depends mainly on whether you have the features ready in some format or not, and how many you need to add. Let's look at the options, from simplest to most complex. ## Add features directly The easiest way is to define your features right in the map code or URL. It's useful if you only need to add a few simple features to your map, such as a couple of markers (pins) to show where something is, or lines showing how to get from place A to place B. You don't have to create any data file; all you need is the coordinates of whatever you want to show on the map. If your use case is more complex than that, it's better to create a vector file to keep your data separate. 👉 How to add features to a [static map (image)](/guides/maps-apis/static-maps/static-maps-for-your-web/): - [Markers](/guides/maps-apis/static-maps/static-map-with-markers/) - [Lines and polygons](/guides/maps-apis/static-maps/static-map-with-lines/) 👉 How to add features to an **interactive map** using [MapTiler SDK JS](/sdk-js/): - [Default marker](/sdk-js/examples/default-marker/) - [Animated marker](/sdk-js/examples/add-image-animated/) - [Custom marker](/sdk-js/examples/custom-marker-icons/) - [Colored lines](/sdk-js/examples/data-driven-lines/) - [Gradient line](/sdk-js/examples/line-gradient/) ## Use a vector data file Another way of adding vector features to a map is to link a separate file in compatible format, typically [GeoJSON](https://geojson.org/). This keeps your data decoupled from the app code and thus easier to maintain, share, and reuse. It becomes practical especially if you have many complex features. 👉 To prepare a vector data file, use our friendly no-code [**Vector data editor**](/guides/vector-data-editor/). ## Use a vector tileset A vector tileset contains your custom vector features processed into [map tiles](/google-maps-coordinates-tile-bounds-projection/). This processing is required if a simple vector file would exceed the size limit. To prepare a vector tileset, use our geoprocessing tool [MapTiler Engine](/guides/map-tiling-hosting/data-processing/). After tiling, it can upload the finished tileset right to your MapTiler account, and then you can add it to your map: - [Add the data programmatically](https://docs.maptiler.com/sdk-js/examples/vector-source/) using **MapTiler SDK JS** - [Add the data without coding](/guides/map-design/data-sources/) in our visual editor **Map Designer** # Custom LIDAR data and Cesium Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/custom-lidar-data-and-cesium/ [Cesium](https://cesium.com/) is a platform for 3D Geospatial data and software applications designed to unleash the power of 3D data. It is mainly the (open source) [JavaScript library](https://cesium.com/learn/cesiumjs/ref-doc/), [3D data publishing portal](https://cesium.com/ion), and [a private company](https://cesium.com/contact/), which is developing the whole platform. The platform allows to display and interaction with 3D geospatial data, which can be buildings, terrain data, or point clouds (e.g. created with lidar). MapTiler is providing global terrain 3D data tiles, which can be used along with the CesiumJS library to present the maps in the 3D context. ## Custom LIDAR data They are usually stored in LAZ or LAS data formats in form of so\-called point clouds. For your approach, we need the LAS format as input. The LAS file will later be converted to Cesium 3D tiles file structure. ### LAZ to LAS The [**LAS**](https://en.wikipedia.org/wiki/LAS_file_format) (LASer) format is a file format designed for the interchange and archiving of [lidar](https://en.wikipedia.org/wiki/Lidar) [point cloud](https://en.wikipedia.org/wiki/Point_cloud) data. It is an open, [binary](https://en.wikipedia.org/wiki/Binary_file) format specified by the [American Society for Photogrammetry and Remote Sensing](https://en.wikipedia.org/wiki/American_Society_for_Photogrammetry_and_Remote_Sensing) (ASPRS). The format is widely used and regarded as an industry standard for lidar data. LAZ is just compressed (zipped) LAS file without information loss. To convert between LAZ and LAS formats, we can you the [PDAL](https://pdal.org) library and tools. PDAL project is very similar to [GDAL](https://gdal.org) so the command used for data transformation should seem known. ``` bash $> pdal translate file.laz file.las ``` LAS can be rendered in QGIS using the Point Cloud data input. ![cd2274a0-7d21-4476-a1f6-879ff673addd.png](./cd2274a0-7d21-4476-a1f6-879ff673addd_d3e4b88308.png) And after setting it up, it can be also displayed in the 3D view. ![b0ceda9e-8e48-4ffb-b75a-62426b77e455.png](./b0ceda9e-8e48-4ffb-b75a-62426b77e455_1ee9a8bad0.png) ### LAS to Cesium 3D tiles format [Cesium 3D tiles](https://cesium.com/blog/2015/08/10/introducing-3d-tiles/) is open specification, which can be used for storing 3D data of buildings, trees, point clouds, and vectors. For converting the data into Cesium 3D tiles, there are various tools around. We made good experience with the [gocesiumtiler](https://github.com/mfbonfigli/gocesiumtiler) project. The runtime requires Go language. To covert the LAS file to 3D tiles structure, you should run ``` bash $> mkdir 3dtiles $> gocesiumtiler -srid 3045 -input file.las -output 3dtiles ``` > [!INFO] > We had to specify EPSG code for the input data file (4326 is assumed by default). Resulting data will be stored in the 3dtiles directory. Adding 3D data to Cesium web application ---------------------------------------- If you have already Cesium web application running, you can easy add 3DTileset: ``` js // javascript import {Cesium3DTileset} from 'cesium'; const lidar = new Cesium3DTileset({ url: "http://server/3dtiles3/tileset.json" }); ... viewer.scene.primitives.add(lidar); ... ``` ![6aa88ba4-f1c3-4689-bf92-fc13f9115dc7.png](./6aa88ba4-f1c3-4689-bf92-fc13f9115dc7_e1952a27af.png) Example running at [https://labs.maptiler.com/samples/cesium/custom\-lidar](https://labs.maptiler.com/samples/cesium/custom-lidar) Conclusion ---------- As result, we are now able to display a custom lidar dataset on the MapTiler quantized\-mesh surface. The main task is, to convert the input LAS dataset into 3D tiled format specification. For this, an external tool *gocesiumtlier* can be used.  Useful links ------------ [Cesium Webpack example](https://github.com/maptiler/cesium-webpack-example) [Cesium 3D tiles generator](https://github.com/mfbonfigli/gocesiumtiler) [PDAL project](https://pdal.org) [Quantized mesh specification](https://github.com/CesiumGS/quantized-mesh) [3D tiles specification](https://github.com/CesiumGS/3d-tiles) # Vector data editor Source: https://docs.maptiler.com/guides/vector-data-editor/ Our **Vector Data Editor** is a no-code tool for creating and editing [vector data (features)](/guides/map-tiling-hosting/data-processing/vector-feature/), which is an ideal format for adding custom objects to a map. Vector features represent real-life objects as simple geometric shapes: **points** for individual objects, **lines** for paths and trails, and **polygons** for areas. These shapes are fairly easy to add and edit, their storage size is very small, and it's possible to change their visual style without reworking the whole map. ## Get custom points, lines, and polygons There are [multiple ways to add custom points, lines, and polygons](/guides/getting-started/add-data/#add-points-lines-polygons) to a map, but the most practical and user-friendly option is to create a custom dataset in our Vector Data Editor. To get going, either [start with your existing data](/guides/vector-data-editor/prepare-data-file/), or open a new data file: Create blank dataset When you're in the editor, go ahead and 👉 [start adding your features](/guides/vector-data-editor/add-vector-data/). # Upload existing data Source: https://docs.maptiler.com/guides/vector-data-editor/prepare-data-file/ If you already have a vector dataset, for example from a GPS tracking device, you can get started by uploading that dataset for editing. > [!IDEA] > Do you want to add your data to an existing file rather than creating a new file? See how to [import your data](/guides/vector-data-editor/add-vector-data/#import). Uploading any common format is supported, but you can check the [formats and size limits](/guides/maps-apis/maps-platform/dataset-upload-formats-and-limits/#supported-editable-vector-features-formats) to be sure. If your vector data file is too large, you'll need to process it into a vector tileset. 1. Go to the [**Data** page](https://cloud.maptiler.com/data/) in your MapTiler account and click **New dataset**. 2. Drag and drop your file onto the screen, or browse your computer. After a successful upload, you'll see the details and preview of your vector features. 3. Click on **Edit dataset** to open your file in the vector editor. Now you can [modify your features](/guides/vector-data-editor/modify-vector-data/) or [add new ones](/guides/vector-data-editor/add-vector-data/). # Add features to your dataset Source: https://docs.maptiler.com/guides/vector-data-editor/add-vector-data/ Our [Vector Data Editor](/guides/vector-data-editor/) allows you to add new features to your dataset in several ways. You can either create them manually, search and add, or import from an existing file. This page explains these methods and points you to next steps. ## Add features manually {#manually} When you open the editor, the tools panel on the right shows that you're in the **select** mode. To be able to add features, you need to switch to one of the **create** modes. ![Add points, line, polygons](/guides/vector-data-editor/img/VDE-create.png) 1. In the tools panel, select your mode to create **points**, **lines**, or **polygons**. 2. Click in the map to start drawing. If you're drawing lines or polygons, each click adds a new point. Double-click to stop drawing. 3. The **Features** panel opens, showing basic details about the feature you've just created. To define custom details, proceed to [add feature properties](/guides/vector-data-editor/edit-properties/). > [!IDEA] > It's often cleaner to store each feature type (points, lines, polygons) in its own file, since they typically need different properties. ## Add features via search {#search} In addition to creating geometries from scratch, you can search for existing objects on a map and add the search results as new features. Here's how to do it: 1. In the left menu, open **Search**. 2. Type a keyword: name of a city, state, street, etc. 3. Select an item from the search results to see it on the map. 4. Each search result has one or more geometry icons on it, indicating how you can add it. Hover over the icon to show the **Add** button. If you save a geometry as a line or polygon, the system automatically calculates its center point and length or area. Alternatively, you can save any line and polygon as its center point only. 5. The name of the feature is added as its property. You can edit it and then [add more properties](/guides/vector-data-editor/edit-properties/) as needed. ## Import features from file {#import} To add existing vector features to your working file, import them directly in the editor: 1. Open the menu in the top right corner and select **Import data**. 2. Choose how to import the new data: - **Append** preserves any features in the working file. You can use this option to merge multiple datasets. - **Replace** deletes all current features before uploading new ones. We recommend saving your file before you do this. ## What's next? You've added your features, now you can [add feature properties](/guides/vector-data-editor/edit-properties/) to capture all their details in your dataset. If you need to change, move or delete any shapes, see how to [modify features](/guides/vector-data-editor/modify-vector-data/). # Modify your vector features Source: https://docs.maptiler.com/guides/vector-data-editor/modify-vector-data/ After you [upload an existing dataset](/guides/vector-data-editor/prepare-data-file/) or [add new vector features](/guides/vector-data-editor/add-vector-data/), you can modify the features. This page explains how to change their geometry (shape or position). To modify properties, see [editing properties](/guides/vector-data-editor/edit-properties/). ## Zoom to feature To be able to edit a feature, first you need to find it on the map, which gets challenging in a large dataset with many features. Here's how to make it easier: 1. In the left menu, open **Features**. 2. In the list, select the feature you want to edit. *Note that search in the menu is for searching the map, not your list of features.* 3. Under Geometry, click **Zoom to feature**. The map will smoothly move and zoom into the right place. (Alternatively, right-click on a feature and select **Zoom to feature** from the context menu.) ![Zoom to feature](/guides/vector-data-editor/img/VDE-zoom.png) ## Select feature or nodes {#select} To select one or more features: 1. Open the **Features** list. 2. Right-click on a feature to show the context menu and click **Select in map**. For multiple features, first hold down `Shift` or `Ctrl` to select them in the list and then use the right-click. To select specific nodes in a line or polygon: 1. In the tools panel on the right, activate the **Select** mode. 2. Click on the desired nodes in the feature. Hold down `Shift` to select consecutive nodes or `Ctrl` to cherry-pick nodes. ## Move features {#move} Moving features is by default turned off, so first you need to enable it: 1. In the left menu, open **Settings**. 2. In the **Draw** section, enable **Dragging**. *Note that if there are many properties, the Draw section will be at the bottom.* ![Switch on dragging](/guides/vector-data-editor/img/VDE-dragging.png) 3. [Select](#select) the feature or individual nodes you want to move, and drag them to a new position. > [!WARNING] > Note that when you move a geometry with [elevation](/guides/vector-data-editor/edit-properties/#calculate-elevation) filled in, the elevation value is lost. ## Duplicate features {#duplicate} 1. In the left menu, open **Features**. 2. Right-click on a feature to show the context menu and click **Duplicate**. ## Transform features {#transform} The editor also offers advanced methods to transform your lines and polygons: 1. [Select](#select) the features or individual nodes you want to transform and click **Transform geometry**. ![Transform geometry](/guides/vector-data-editor/img/VDE-transform.png) 2. Select the transformation method: **Simplify** or **Smoothen**. ### Simplify Simplification removes points (nodes) from a feature. This is handy if the feature is too detailed, for example if the points are created by a GPS tracking device. Adjust the **tolerance** to see how many points there will be in the simplified result. Simplification works best for shapes with many excessive nodes that don't improve precision. Removing these nodes makes no visible difference and the feature is easier to work with. Also, you need fewer API requests to [calculate elevation](/guides/vector-data-editor/edit-properties/#calculate-elevation). However, keep in mind that horizontally straight lines aren't necessarily flat vertically, and simplification might reduce accuracy that's critical for elevation profiles and terrain analysis. Consider your needs and keep enough nodes to preserve meaningful detail in your data. ### Smoothen Smoothening adds points (nodes) to a feature. This method is helpful when you've created your lines or polygons by hand and want to change their pointy edges into smooth curves for a more polished look. - Smoothening **lines** provides better results if applied to specific nodes rather than a whole line. **Sharpness** determines how round the edges will be. - Smoothening **polygons** adds new nodes evenly between existing nodes. **Levels** determine how many nodes will be added per edge, with each level doubling the count. ## Delete features {#delete} 1. In the tools panel on the right, activate the **Select mode**. 2. [Select](#select) the feature or individual nodes you want to delete. 3. Use the **Delete feature** button. It appears under the tools panel on the right side when a feature is selected. Alternatively, you can use a keyboard shortcut. ## Keyboard shortcuts {#shortcuts} When working with Vector Data Editor frequently, you can be more efficient with keyboard shortcuts. Click **Help** in the bottom left corner of the editor and select **Keyboard shortcuts** to see what's available. ## What's next? When you're happy with the feature geometries, review and [edit their properties](/guides/vector-data-editor/edit-properties/). If you consider the dataset final, go ahead and [add the features to your map](/guides/vector-data-editor/use-vector-data/). # Edit properties of vector features Source: https://docs.maptiler.com/guides/vector-data-editor/edit-properties/ [Properties](/guides/map-tiling-hosting/data-processing/vector-feature/#properties) hold additional information about features. They're useful for adding extra information to each feature in a dataset, and you can define as many as you need. Properties are added on dataset level, not on indiviual feature level. This means that you can define your properties even before you add the first features to your dataset, but in practice you'll often add geometries first and then think about what properties you need for them. Either way, once you define a new property, you can use it for every feature in the dataset. ## Add new property 1. In the left menu, open **Settings**. 2. Under **Properties**, click the **Add** button. 3. Fill in the property key (name) and select type: - **String** stores textual data. Use it for names, dates, alphanumeric IDs, and any other data that should be treated as text. - **Number** stores numerical values. It's useful to be consistent with the value format, for example, use `1.0` instead of `1` if you want floating point numbers. - **Boolean** stores one of the two possible values: `true` or `false`. 4. Optionally, add a default value for all features in the dataset. Any existing or newly added feature will use this value, unless you change it. ## Calculate elevation Basic geometry description also includes elevation of a point, that is, the height of the point above mean sea level. Elevation isn't filled in by default, but you can add it to any feature manually. > [!WARNING] > Please note that calculating elevation counts towards [your API quota](https://cloud.maptiler.com/account/settings). To see how many elevation requests you've made so far, check your account [analytics](https://cloud.maptiler.com/account/analytics) at any time. 1. In the left menu, open **Features** and select a feature. 2. Under Geometry, click **Fill elevation** to add the value. In case of lines and polygons, the system will fetch elevation of all nodes that don't have it yet, and calculate the average elevation for the whole feature. This can be many nodes, so you may want to [simplify](/guides/vector-data-editor/modify-vector-data/#simplify) your feature first. ![Fill elevation](/guides/vector-data-editor/img/VDE-elevation.png) ## What's next? With your dataset ready, it's time to [add the features to your map](/guides/vector-data-editor/use-vector-data/). # Show your vector data on a map Source: https://docs.maptiler.com/guides/vector-data-editor/use-vector-data/ When you've prepared your dataset in [Vector Data Editor](/guides/vector-data-editor/), you can add your vector features to a map. There's a code and no-code way to do this. Before you get to work, make sure to **Save** and **Publish** your vector file. This gets the dataset ready for integration in publicly available maps and applications. Your dataset is now saved in [GeoJSON](https://geojson.org/) format and hosted in your MapTiler account on the [**Data** page](https://cloud.maptiler.com/data/). ## Add data programmatically As a developer, you'll probably prefer using the [MapTiler SDK JS](/sdk-js/), where adding a vector data source and styling the features is a matter of a few lines of code. We have basic examples for you to copy and modify as needed: - [Show points](/sdk-js/examples/geojson-point/) - [Show lines](/sdk-js/examples/geojson-line/) - [Show polygons](/sdk-js/examples/geojson-polygon/) For more inspiration, [see all related examples](/sdk-js/examples/?q=geojson). ## Use a visual editor For a no-code approach, use our map design editor. Follow these steps: 1. Go to the [**Maps** page](https://cloud.maptiler.com/maps/) in your MapTiler account and click on **New map**. 2. Select a map you'd like to use and click **Customize**. This takes you to the map editor. 3. In the left menu panel, go to **Layers** and add a new layer using the plus button. Search available data sources and select your new vector dataset. 5. Style your features by adjusting color, opacity, outline, or any other visual properties. When done, [save and publish your changes](/guides/map-design/how-to-publish-a-map/). If you'd like to learn more about how to style vector maps and visualize your vector features, check out our [map design tutorials](/guides/getting-started/map-design-tutorials/), especially series *Custom data visualization*. # Export your vector data to GeoJSON Source: https://docs.maptiler.com/guides/vector-data-editor/export-vector-data/ When you've prepared your vector data in [Vector Data Editor](/guides/vector-data-editor/), you can use it in desktop GIS software such as QGIS or ArcGIS. To make that possible, download the dataset as a GeoJSON file: 1. **Save** your dataset to make it available for download. 2. Open the menu in the top right corner and select **Download dataset**. ![Download your vector data](/guides/vector-data-editor/img/VDE-export.png) Now you can upload your dataset to a GIS application and use it there. ### Convert GPX, KML, and Shapefile to GeoJSON Our Vector Data Editor also works as a geodata converter. [Import your data](/guides/vector-data-editor/add-vector-data/#import) in any supported format (GPX, KML, Shapefile) and download in GeoJSON format as described on this page. # Georeferencer Source: https://docs.maptiler.com/guides/georeferencer/ To georeference an object means to assign it a precise location on Earth. Our **Georeferencer** tool provides a simple interface to do so, allowing you to visually assign location to your digital imagery like scanned maps, floor plans, or drone photos. **Georeferencer** supports setting control points against a reference map to define the geographic location (latitude and longitude) and scale of your image. Once georeferenced, the file is automatically tiled into [raster map tiles](https://docs.maptiler.com/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/) and hosted in your account, ready for use in any map or via API. ## Georeference your image To get started, see 👉 [How to georeference your image](/guides/georeferencer/get-started/). ### On-prem georeferencing If you're looking for an on-prem rather than cloud-based georeferencing solution, check out [MapTiler Engine](/guides/map-tiling-hosting/data-processing/getting-started/). It's a powerful desktop alternative that allows you to process large amounts of data locally. It also provides advanced options like manual fine-tuning of coordinates and cutline, multi-image processing, transformation method selection, and customizable output formats. # How to georeference your image Source: https://docs.maptiler.com/guides/georeferencer/get-started/ This page explains how to use our cloud [Georeferencer tool](/guides/georeferencer/) to visually assign map location to your images. ## Upload your image 1. In your MapTiler account, go to page **Tiles** → [**New tileset**](https://cloud.maptiler.dev/tiles/new) and upload your image. 2. In the image preview, click **Georeference image**. ![Georeference your image](/guides/georeferencer/img/georeferencer-start.png) ## Assign geolocation 1. **Find the location:** In the visual editor, you'll see your image and a map. The map is for reference only: use it to find the location where the image should be placed. The default map with satellite imagery is best for georeferencing drone photos and other real-world data. You can choose a different map using the **Basemap** button in the left menu. 2. **Add a control point:** Click on a spot in the image and then on the same spot on the map (or vice versa). This creates a point which ties your image to the map location. ![Georeferencing points added](../img/georeferencer-split-screen-satellite.png) 3. **Place at least 3 points:** Repeat the previous step in different parts of the image to get three or more points. Place them as accurately as possible. To place the points, pick visually distinctive spots such as building corners or path crossings. If you make a mistake, move the point, or delete it with `Delete` or `Backspace` key. 4. **Preview the image on map:** Click the **Overlay** button on the right to see your image placed over the map. If it looks incorrect, go back to the split screen view to fix the points. ![Georeferenced image as overlay on map](../img/georeferencer-overlay-base.png) 5. **Save and exit:** When done, click **Finalize** to save your control points and start processing the image into map tiles. #### Technical note Your image will be processed using the [affine](/guides/map-tiling-hosting/data-processing/map-transformations/#affine) transformation method. ## Next steps Your image is now processed into a proper georeferenced set of [raster map tiles](https://docs.maptiler.com/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/). You can find it in your MapTiler account on page [**Tiles**](https://cloud.maptiler.dev/tiles/) and use it just like any other raster tileset. 👉 [How to add your georeferenced image to a map](/guides/map-data/use-raster-data/#add-your-image-to-map) # Search and location services Source: https://docs.maptiler.com/guides/location-services/ MapTiler location services provide geographic context for your applications and can be used with or without a map. They're built into our SDKs, but you can also call the API endpoints directly. ## Search and geocoding Use our search and geocoding service to convert addresses or place names into geographic coordinates (forward geocoding) and coordinates into addresses (reverse geocoding). - **Guide:** [Get started with geocoding and search](/guides/location-services/geocoding-search/) - **Reference:** [Geocoding API](/cloud/api/geocoding/) ## IP geolocation Identify the approximate location of users based on their IP address, so that you can customize their experience with localized content or regional settings. - **Guide:** [How to detect and use IP geolocation](/guides/location-services/ip-geolocation/) - **Reference:** [IP geolocation API](/cloud/api/geolocation/) ## Elevation Retrieve the elevation of specific coordinates or along a path to generate elevation profiles, calculate terrain statistics, or create flood maps. - **Guide:** [How to work with elevation](/guides/location-services/elevation/) - **Reference:** [Elevation API](/cloud/api/elevation/) ## Coordinates Convert coordinates between different spatial reference systems and projections to consolidate them for further use. - **Guide:** [Search coordinate systems and convert between them](/guides/location-services/coordinates/) - **Reference:** [Coordinates API](/cloud/api/coordinates/) # Use place and address search Source: https://docs.maptiler.com/guides/location-services/geocoding-search/ Place and address search is typically available in a map as a simple [search box](#geocoding-control). Behind the scenes, it hides a complex functionality that can be configured and used in many ways. See our interactive **place search demo** to get an idea! ## How it works The process that makes place search possible is called **geocoding**. - **Forward geocoding** turns a human-friendly place name or address into geographical coordinates. - **Reverse geocoding** does the same in the opposite direction, turning coordinates to the nearest place names and addresses. The key component of place search is a **geocoding index**, which is a database that maps place names to their coordinates. Contents of the index determine the [place types](/cloud/api/geocoding/#PlaceType) you're able to find: - Addresses, streets, postal codes, and administrative units - Natural features such as mountains, forests, bodies of water - Points of interest (**POIs**), which can be anything from shops and services to tourist attractions; there's usually hundreds of POI categories. ## How to integrate Our place search is available via the [**Search and geocoding API**](/cloud/api/geocoding/). The API page explains how to use geocoding programmatically and which libraries (including 3rd party) you can use to query it, and provides complete API reference. ## Use cases There's various real-life applications of geocoding. Here are the ones you'll be most likely looking for: ### Add a search box to map {#geocoding-control} A popular need is to add a place search box to your map or online form. To make this easy, we've prepared a [**geocoding control** module](https://github.com/maptiler/maptiler-geocoding-control) which can be used with our maps or standalone. Add it using your favorite mapping library or JavaScript framework: - [MapTiler SDK JS](/sdk-js/modules/geocoding/) – **recommended** for seamless integration with our maps. We provide a rich selection of [configuration examples](/sdk-js/examples/?q=geocoding) for the SDK, as well as [React](/react/sdk-js/geocoding-control/) and [Svelte](/svelte/sdk-js/geocoding-control/) tutorials. - [MapLibre GL JS](/sdk-js/modules/geocoding/api/usage/maplibre-gl-js/) – open-source vector map renderer. [React](/react/maplibre-gl-js/geocoding-control/) and [Svelte](/svelte/maplibre-gl-js/geocoding-control/) components are also available. - [Leaflet](/leaflet/examples/geocoding-control/) – popular, lightweight mapping library - [OpenLayers](/openlayers/examples/geocoding-control/) – powerful library for complex mapping needs - [Vanilla JS](/sdk-js/modules/geocoding/api/usage/vanilla-js/) – pure HTML and JavaScript, **no map** ### Zoom to first result To get a simple application of geocoding without a search box, you can build a map which automatically shows the location of the first search result. The search query is a part of the URL that loads the map. 👉 [Search and zoom to the result](/sdk-js/examples/geocoding/) ### Find by coordinates Identify map locations on mouse click, track GPS positions of wildlife collars, monitor IoT devices in real time – all that is possible with **reverse geocoding**. It converts coordinates into meaningful place names by showing the nearest road, city, or point of interest, adding the required context to raw coordinate data. 👉 [How to use reverse geocoding](/sdk-js/examples/reverse-geocoding/) ### Show close-by results If you want to make place search more relevant to users, you can combine [IP geolocation](/guides/location-services/ip-geolocation/) with the search to prioritize results near the user's location. 👉 [How to search places using visitor's location](/sdk-js/examples/geocoding-reverse-json/) ### Batch geocoding Sometimes, you need to convert hundreds or even thousands of addresses to coordinates (or vice versa), for example when you're looking to optimize delivery routes to customers. With our geocoding service, you can process your entire address list in one batch. 👉 [How to use batch geocoding](/guides/geocoding/batch-geocoding-api/) ### Offline search You can also use place search in your self-hosted maps and offline environments. There's just some extra steps needed to add the functionality to the on-prem setup. 👉 [How to implement on-prem geocoding](/guides/geocoding/on-premise-geocoding-in-maptiler-server/) ## Links - [SDK JS – code examples](/sdk-js/examples/?q=geocoding) - [SDK JS – geocoding control](/sdk-js/modules/geocoding/) - [Search & geocoding API – reference](/cloud/api/geocoding/) - [Search & geocoding API – Client JS](/client-js/#-geocoding) # Basic geocoding parameters Source: https://docs.maptiler.com/guides/location-services/geocoding-search/parameters The [Search & Geocoding API](/cloud/api/geocoding/) provides parameters that give you greater control over the geocoding configuration. Here's some practical advice on how the parameters work and how to use them. ### country Limits searches to a specific country or countries. Specify one or more countries as comma-separated [ISO 3166 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes. **Example:** When searching for places exclusively in Norway, you can effectively distinguish between Oslo, the capital of Norway, and Oslo in Minnesota, USA. ### types Filter results to include only a subset of available feature types. Multiple options can be comma-separated. See the [PlaceType Values](/cloud/api/geocoding/#PlaceTypeValues) for accepted values. Note that every country has a different hierarchical division system, making a universal approach challenging. MapTiler Geocoding defines an approximate global hierarchy that maps each country by best effort. Not every country has administrative areas present at every level. ### autocomplete Specifies whether to return autocomplete results (`true`) or not (`false`). When enabled, results include entries that start with the requested string, rather than only exact matches. For example, querying "India" might return both "India" and "Indiana" when autocomplete is enabled, but only "India" when disabled. The default behavior combines exact results with autocomplete. > [!WARNING] > When autocomplete is enabled, each user keystroke counts as one request to the Geocoding API. For example, searching for "coff" generates four separate API requests. To reduce total requests, configure your application to call the API only after a specific number of characters are typed. ### fuzzyMatch Determines whether the API should attempt approximate matching in addition to exact matching (`true`, default), or only exact matching (`false`). For example, with the default setting enabled, searching for "wahsington" might return "Washington, DC" despite the misspelling. > [!NOTE] > Setting both `autocomplete` and `fuzzyMatch` to `false` ensures results contain only exact matches without typo correction or partial name completion. For instance, if searching for "koln" with the language set to German, results will include "Köln" but exclude similar places like "Kolin" (in Czechia) or "Kola" (in Russia). ### limit Controls the maximum number of results to return. The default is `5` and the maximum supported value is `10`. # Locate users by IP address Source: https://docs.maptiler.com/guides/location-services/ip-geolocation/ IP geolocation is a feature that identifies a visitor's approximate location based on their IP address. This makes it possible to customize the map, website or application for your users based on where they are. The service is designed with security in mind and doesn't collect or store user data. ## How it works IP geolocation retrieves location (country, region, city) from specialized IP-to-geolocation databases. It relies solely on the IP address, so it's good to keep in mind that the process won't work correctly if the real IP address is masked – for example when visitors use VPNs, proxies, or mobile ISPs. ## How to integrate Our IP geolocation service is available via the [**Geolocation API**](/cloud/api/geolocation/). The API page explains how to get geolocation programmatically and which libraries you can use, and provides complete API reference. ## Use cases Our [code examples](/sdk-js/examples/?q=geolocation) show how you can use geolocation for various needs. See most popular options here: ### Show user's location Using IP geolocation, you can automatically center a map to the visitor's location. If they're at home, they'll see a familiar area, and if travelling, they can find their way around faster. 👉 [How to center a map on visitor’s location](/sdk-js/examples/ip-center-map/) ### Use local language MapTiler maps can be [manually set](/guides/map-design/change-language-in-a-map/) to show labels in virtually any language. Take this a step further by setting the language automatically based on visitor's current location. 👉 [How to change the map language based on visitor's location](/sdk-js/examples/ip-map-language/) ### Customize cookies IP geolocation can help display cookie information dynamically, for example, show the consent bar to visitors located in the European Union where it is required by law. 👉 [How to display the cookies consent bar based on visitor's location](/sdk-js/examples/ip-cookie-bar/) ### Set disputed borders Some areas of the world face territorial disputes that often make it unclear what the correct country borders are. The topic can be quite sensitive, so it's a good idea to configure your map to show the borders based on how each involved country sees them. 👉 [How to automatically change disputed borders based on visitor's country](/sdk-js/examples/ip-disputed-borders/) ## Links - [SDK JS – code examples](/sdk-js/examples/?q=geolocation) - [Geolocation API – reference](/cloud/api/geolocation/) - [Geolocation API – Client JS](/client-js/#%EF%B8%8F%EF%B8%8F-geolocation) # Use elevation Source: https://docs.maptiler.com/guides/location-services/elevation/ Elevation data adds a vertical dimension to your maps and applications. Whether it's planning hiking routes or enhancing and analyzing terrain, our elevation service provides accurate **height** (altitude above sea level) for any location on Earth. ## How it works The elevation data comes from a high-resolution *digital elevation model (DEM)* that covers the entire planet. To dive deeper and learn how exactly it works, see the documentation of our [Terrain RGB (raster-DEM) dataset](/guides/map-tiling-hosting/data-hosting/rgb-terrain-by-maptiler/). ## How to integrate Our elevation data is available via the [**Elevation API**](/cloud/api/elevation/). The API page explains how to get elevation programmatically and which libraries you can use to query it, and provides complete API reference. If you're looking for a no-code way to enrich your custom map features (points, lines, polygons) with elevation values, you can do that in our [**Vector Data Editor**](/guides/vector-data-editor/edit-properties/#calculate-elevation). ## Use cases Check out the [code examples](/sdk-js/examples/?q=elevation) to see how to build apps using elevation. Here are the most popular scenarios: ### Show elevation on click A popular option to use elevation is to simply show the value when users interact with your map. This is perfect for hiking apps, real estate sites, or any application where terrain height matters. 👉 [How to show elevation on click](/sdk-js/examples/elevation-at/) ### Create elevation profile Elevation profiles help users understand the difficulty of a route by visualizing climbs and descents. You can add a control to your map that creates a detailed terrain profile along the selected route. 👉 [How to add elevation profile control to your app](/sdk-js/examples/elevation-profile-control-simple/) ## Links - [SDK JS – code examples](/sdk-js/examples/?q=elevation) - [SDK JS – elevation profile control](/sdk-js/modules/elevation-profile/) - [Elevation API – reference](/cloud/api/elevation/) - [Elevation API – Client JS](/client-js/#%EF%B8%8F-elevation) # Transform coordinates Source: https://docs.maptiler.com/guides/location-services/coordinates/ Geographical coordinates specify where something is located on Earth, and thus where to find it on a map. A [coordinate system](/guides/maps-apis/maps-platform/what-are-map-coordinate-systems/) defines the exact method of encoding a physical location into coordinates. Common map coordinate systems are based on a combination of longitude and latitude, but there are other standards as well. Our service lets you search these systems and convert coordinates from one to another. ## When you need it Although most web maps and services today use the [Mercator](/google-maps-coordinates-tile-bounds-projection/#Spherical_Mercator) coordinate system, geodata can come in many other flavors. If you have data in a different system, you'll need to transform the coordinates to Mercator first – this is required for example by our [geocoding](/guides/geocoding/geocoding-api/) and [IP geolocation](/guides/geocoding/ip-geolocation-api/) services. These are the most typical scenarios when you need to convert coordinates: - Transform data for a tool or task that requires the standard Mercator system - Unify data collected from various national coordinate systems - Merge multiple datasets from different projections ## How it works Our coordinates service is powered by an open\-source database of geographic coordinate systems used in maps worldwide. That makes it possible to provide programmatic access to more than 10,000 coordinate systems, from simple search to batch-converting data between them. ## How to use The coordinate systems service is available via the [**Coordinates API**](/cloud/api/coordinates/). The API page explains basic integration options and lists the API reference. Examples of how to use the API are here: - [How to search coordinate systems](/guides/location-services/coordinates/search-coordinate-systems) - [How to transform coordinates](/guides/location-services/coordinates/convert-coordinates) - [How to transform coordinates in batch](/guides/location-services/coordinates/convert-coordinates-in-batch) ## Links - [Coordinates API](/cloud/api/coordinates/) - [Coordinates API – JS client](/client-js/#-coordinates) - [About coordinate systems](/guides/maps-apis/maps-platform/what-are-map-coordinate-systems/) # Search coordinate systems Source: https://docs.maptiler.com/guides/location-services/coordinates/search-coordinate-systems/ This page shows how to search coordinate systems using our [Coordinates API](/cloud/api/coordinates/). You can also use this service with the [API client JS](/client-js/#search). For a beginner intro into the service, see [Work with coordinate systems](/guides/location-services/coordinates/). > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). The universal search URL format is: ``` https://api.maptiler.com/coordinates/search/{QUERY}.json?{PARAMS}&key=YOUR_MAPTILER_API_KEY_HERE ``` |**Parameters**|**Description**|**Example**| |--------------|---------------|-----------| | QUERY | Query on CRS | 2056.json
swiss.json
czechia deprecated:1.json | | PARAMS | Parameter for showing exports in WKT and Proj4, limit the number of results of show transformations. | swiss.json?limit=1
exports=true&limit=5 | #### Example **Request** ``` https://api.maptiler.com/coordinates/search/swiss lv95.json?exports=true&key=YOUR_MAPTILER_API_KEY_HERE ``` **Response** ``` json { "results": [ { "id": { "authority": "EPSG", "code": 2056 }, "kind": "CRS-PROJCRS", "name": "CH1903+ / LV95", "exports": { "proj4": "+proj=somerc +lat_0=46.9524055555556 +lon_0=7.43958333333333 +k_0=1 +x_0=2600000 +y_0=1200000 +ellps=bessel +towgs84=674.374,15.056,405.346,0,0,0,0 +units=m +no_defs +type=crs", "wkt": "PROJCS[\"CH1903+ / LV95\",GEOGCS[\"CH1903+\",DATUM[\"CH1903+\",SPHEROID[\"Bessel 1841\",6377397.155,299.1528128],TOWGS84[674.374,15.056,405.346,0,0,0,0]],PRIMEM[\"Greenwich\",0,AUTHORITY[\"EPSG\",\"8901\"]],UNIT[\"degree\",0.0174532925199433,AUTHORITY[\"EPSG\",\"9122\"]],AUTHORITY[\"EPSG\",\"4150\"]],PROJECTION[\"Hotine_Oblique_Mercator_Azimuth_Center\"],PARAMETER[\"latitude_of_center\",46.9524055555556],PARAMETER[\"longitude_of_center\",7.43958333333333],PARAMETER[\"azimuth\",90],PARAMETER[\"rectified_grid_angle\",90],PARAMETER[\"scale_factor\",1],PARAMETER[\"false_easting\",2600000],PARAMETER[\"false_northing\",1200000],UNIT[\"metre\",1,AUTHORITY[\"EPSG\",\"9001\"]],AXIS[\"Easting\",EAST],AXIS[\"Northing\",NORTH],AUTHORITY[\"EPSG\",\"2056\"]]" }, "unit": "metre", "accuracy": 1, "area": "Liechtenstein; Switzerland.", "bbox": [ 5.96, 45.82, 10.49, 47.81 ], "deprecated": false, "default_transformation": { "authority": "EPSG", "code": 1676 }, "transformations": [ 1509, 1647, 1676, 8457 ] } ], "total": 1 } ``` For more details, see the [Coordinates API `Search` reference](/cloud/api/coordinates/#search-coordinate-systems). # Transform coordinates to another system Source: https://docs.maptiler.com/guides/location-services/coordinates/convert-coordinates/ This page shows how to transform coordinates from one system to another using our [Coordinates API](/cloud/api/coordinates/). You can also use this service with the [API client JS](/client-js/#transform). For a beginner intro into the service, see [Work with coordinate systems](/guides/location-services/coordinates/). > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). The universal transform URL format is: ``` https://api.maptiler.com/coordinates/transform/{COORDS}.json?s_srs={CODE}&to_srs={CODE}&key=YOUR_MAPTILER_API_KEY_HERE ``` |**Parameters**|**Description**|**Example**| |--------------|---------------|-----------| | COORDS | Pair (`x,y`) or triplets (`x,y,x`) of coordinates separated by comma (`,`) | 17,50
17,50,300 | | s_srs | Source coordinate reference system | 4326 | | t_srs | Target coordinate reference system definition | 5514 | | ops | List of coordinate of operations separated by `|` | 1623 | Example of a coordinate transformation URL call: ``` https://api.maptiler.com/coordinates/transform/17,50.json?s_srs=4326&t_srs=5514&ops=1623&key=YOUR_MAPTILER_API_KEY_HERE ``` For more details, see the [Coordinates API `Transform` reference](/cloud/api/coordinates/#transform-coordinates). # Transform coordinates in batch Source: https://docs.maptiler.com/guides/location-services/coordinates/convert-coordinates-in-batch/ This page shows how to transform coordinates from one system to another in bulk using our [Coordinates API](/cloud/api/coordinates/). For a beginner intro into the service, see [Work with coordinate systems](/guides/location-services/coordinates/). > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). MapTiler Coordinates API supports batch transform coordinates, transforming more than one point pair (`x,y`) or triplets (`x,y,z`) request in a single API call. You can perform batch coordinate transformation by calling the standard Coordinate API transform endpoint `https://api.maptiler.com/coordinates/transform/{COORDS}.json`. **Just make sure you use semicolons `;` to separate individual point pairs** (up to 50 points). Note that each pair or triplet of coordinates counts separately towards your API quota. #### Example **Request** ``` https://api.maptiler.com/coordinates/transform/17,50;17.1,50.1.json?s_srs=4326&t_srs=5514&key=YOUR_MAPTILER_API_KEY_HERE ``` **Response** ``` json { "transformer_selection_strategy": "auto", "results": [ { "x": -560595.6992028592, "y": -1074706.2565340507, "z": 0 }, { "x": -552340.3607729311, "y": -1064368.376869001, "z": 0 } ] } ``` The result is JSON format with nested point pairs under the `results` key. For more details, see the [Coordinates API `TransformResult` reference](/cloud/api/coordinates/#TransformResult). # Map usage: Sessions vs requests Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/tile-requests-and-map-sessions-compared/ MapTiler offers two models of measuring map traffic: **map sessions** and **tile requests**. Each [pricing plan](https://www.maptiler.com/cloud/pricing/) including the free one defines a monthly limit on sessions and requests. When you hit either of these two limits, you get charged extra (on a paid plan) or your maps get suspended for the rest of the month (on a free plan). > [!IDEA] > To see which plan you're on and how many sessions and requests you get, go to your [Account settings](https://cloud.maptiler.com/account/settings). To check your current usage stats, see the [Analytics](https://cloud.maptiler.com/account/analytics) page. ## Tile requests A tile request counts each individual request for map tiles. When the user is moving around the map and zooming in and out, the map application needs to load more [map tiles](/google-maps-coordinates-tile-bounds-projection/) (pieces of the map) to show the required areas or details. This happens by requesting new tiles via an API call, and each of these API calls counts as a tile request. To see how exactly it works, check out our interactive [**tile request counter**](https://www.maptiler.com/cloud/requests/). ## Map sessions A map session, sometimes also called **map load**, starts when a user opens a webpage with your map. Then the user can freely interact with the map, zoom, pan, change map theme, and it counts as a single map session. For billing purposes, a new session starts when: - User reloads the browser tab (with F5, Ctrl+R, Reload button), - A single continuous session duration exceeds **6 hours**, - The session reaches a total of **10,000 requests**. Map sessions are generally much easier to estimate: One session equals one page view, so it's easy to check your web analytics and estimate map traffic costs. Sessions also tend to be more cost-effective than tile requests, because a single map session typically includes many tile requests: a few tiles to load the initial map view, and then additional tiles as needed when the user interacts with the map. ## Comparison | | **Map sessions** | **Tile requests** | |-------------------------|---------------------------------------------------------------|------------------------------------------------------| | **What's measured** | Map (re)load on a web page | Each individual API call for a map tile | | **Duration** | Until page refresh (F5, Ctrl+R) or up to 6 hours/10k requests | N/A (usage is per request) | | **Availability** | Only with MapTiler SDK JS or MapTiler plugin for Leaflet | General availability with MapTiler API | | **Benefits** | Much easier to calculate and predict | More granular | | **Best use case** | Applications with heavy user interaction per map view | Many map page views with little user interaction | ## Are you using sessions or requests? Each of your maps can be measured differently, per session or per request; there's no global setting for the model used. So which one applies? That depends on implementation: - If a map is implemented with [MapTiler SDK JS](/sdk-js/) (or the [MapTiler plugin for the Leaflet library](https://github.com/maptiler/leaflet-maptilersdk) which also uses the MapTiler SDK), then the map traffic is by default tracked **by session**. For special use cases where it makes sense, you can optionally [switch to requests](#switch). - If you built your map using [MapTiler API](/cloud/api/) combined with 3rd party clients and libraries, then the traffic is tracked **by request**. Switching to sessions is not technically possible in this case. ## Switching to requests in MapTiler SDK If you're using [**MapTiler SDK JS**](/sdk-js/), you can optionally switch from map sessions to tile requests. This might be the preferred way to track your map usage in special cases where you expect many map views with little interaction. For example, you're building a holiday booking app in which users browse many pages to see available options, but they don't interact with the maps on those pages. Switching from sessions to requests is done per map. Use the map config option [session](/sdk-js/api/config/#session) and add this line to the code of each map which you want tracked per request: `maptilersdk.config.session = false` ## Useful links - [Tile request counter](https://www.maptiler.com/cloud/requests/) - [MapTiler pricing](https://www.maptiler.com/cloud/pricing/) - [How to use your traffic analytics](/guides/maps-apis/maps-platform/usage-analytics-for-sessions-and-requests/) - [How to control your expenses](/guides/maps-apis/maps-platform/how-to-control-expenses-in-your-user-account) - [SDK JS reference: sessions config](/sdk-js/api/config/#session) # Usage analytics for sessions and requests Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/usage-analytics-for-sessions-and-requests/ The amount of usage is visualized in your MapTiler account with interactive charts. [Requests and sessions](/guides/maps-apis/maps-platform/tile-requests-and-map-sessions-compared) are displayed and billed separately. Visit the [analytics page](https://cloud.maptiler.com/account/analytics) in your account. * [Your traffic analytics](https://cloud.maptiler.com/account/analytics) * [Tile requests and map sessions compared](/guides/maps-apis/maps-platform/tile-requests-and-map-sessions-compared) Periods, filtering ------------------ Usage data are aggregated into days or months. Only the whole day is always displayed. Daily statistics are available for the past 90 days or you can display monthly statistics for all the time. Charts display the list of used Services from [api.maptiler.com](https://api.maptiler.com) by default. Switching it to view divided by API keys or Service credentials is also possible. ![Frame 4.png](./21424413719185_cba24b5538.png) Estimate -------- The estimated amount for the current period is computed as the daily average (of the past 28 days) multiplied by the remaining days. It’s an “extra day” in a chart and it is added to daily periods for 30 or 90 days. Estime is not present in the exported file. ![Frame 6.png](./21424413733777_c5d3d8db9a.png) Export data ----------- On the right side, a “Download” button will allow you to download a CSV file for a filtered view. For export automation, see the API section below. ![Frame 3.png](./21424408623889_0d9ebc5f7d.png) Project or website filtration with API key ------------------------------------------ It is highly recommended to always use a designated API key for your website/project. Except for safety reasons, it opens the possibility to analyze traffic separately. Don’t forget to set the description and origin for each key. ![Frame 5.png](./21424408635409_2b72ce8ac6.png) API for analytics ----------------- The API endpoint is available for fetching usage data with Service credentials. There is a possibility to export data in CSV or JSON format. The detailed endpoint description is documented [in the API reference](https://docs.maptiler.com/cloud/admin-api). ![Frame 2.png](./21424413762833_1c1f9a35b9.png) # Team Account Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/team-account/ The following text provides all the details about the MapTiler Team account feature. There are different roles and permissions explained in the article and you will also find out what role is for whom, why you should have the Team account, and how you can get it. Summary ------- * The team account is available on the [Unlimited and Custom plans](https://www.maptiler.com/cloud/pricing/). * The basic Team account is limited to 5 team members, the limit can be increased by [MapTiler Support](/support/requests/) (upon request) if necessary. * Each team member can be of a different role (Owner, Editor, Viewer). * You can set up and manage your team on [the Team account page](https://cloud.maptiler.com/account/team/). What is a MapTiler Team account? -------------------------------------- The standard [MapTiler](https://www.maptiler.com/cloud/) account is associated with a single email address. This is perfect for freelancers or small companies where there is only one person taking care of the maps administration. In larger teams, there are usually more people who manage the maps and each of them needs to access the same MapTiler account. That is what the Team account is used for. The Team account is an account associated with a single company or entity and consists of multiple single\-user MapTiler accounts. Team members log into MapTiler administration with their own credentials but they all can access the same Team account. How to get the Team account? ---------------------------- You can create your team in the Account section in Maptiler Cloud. Open the "Team" link in the navigation. Create a team by pressing the button. Set up the Team name (you can change it later) and invite your colleagues. After creating a Team, all maps, tiles, and plan settings are transferred to the Team Account Team account is available on Unlimited or Custom plans. If you need higher limits or a special use case contact the MapTiler Sales team through the web [contact form](https://www.maptiler.com/#contact) or via email at [MapTiler Sales](mailto:sales@maptiler.com). Roles and permissions for accounts in the Team ---------------------------------------------- * **Owner**: edit access to all sections of the MapTiler account. * **Editor**: edit access to all sections of the account except for the subscription settings and billing. * **Viewer**: view\-only access to all sections of the MapTiler account except for the billing. How do I switch between accounts? --------------------------------- * **1st** any team member logs into their MapTiler Account. * **2nd**they go top right, click their Account name and select the Team Account. * **3rd** by clicking the Team Account name they switch and access the Team Account's content. ![mceclip1.png](./10645405561617_507985c97f.png) Members management ------------------ You can set up and manage your team on the [MapTiler Team Account page](https://cloud.maptiler.com/account/team/). All members are listed in the table. The owner of the account can invite new members, change rights or remove them. ![mceclip0.png](./10645229606161_8fdc2b0470.png) Benefits for you ---------------- Different people in your company have different responsibilities, and some of them might want to play with the [map colors](/guides/map-design/how-to-make-custom-map-design-in-maptiler-cloud) to find the perfect match for your company brand. Others might need to customize the [map styles](/guides/map-design/layer-styling) to offer the best\-fitting maps in the applications for your customers. And there are, of course, people who take care of the administrative parts, like the invoices or the subscription management itself. with MapTiler’s Team account add\-on, you can ensure that all relevant people have access to the account without the risky sharing of a single password between each other and do their jobs easily, independently, or collaboratively. Useful links ------------ [MapTiler product page](https://www.maptiler.com/cloud/) [Make your own map design](/guides/map-design/how-to-make-custom-map-design-in-maptiler-cloud) [Advanced map customization](/guides/map-design/layer-styling) [MapTiler Plans](https://www.maptiler.com/cloud/plans/) [Contact Form](https://www.maptiler.com/#contact) # Developer resources Source: https://docs.maptiler.com/guides/getting-started/developer/ Building a map application for your website is possible with a number of JavaScript libraries and frameworks. For the most popular ones, we've prepared [customized code examples](/guides/maps-apis/maps-platform/use-maps-interactively-with-javascript/) in your MapTiler account, so you can get started simply by copying the code. Or check out the resources below. ## MapTiler SDK JS [MapTiler SDK JS](/sdk-js/) is a JavaScript/TypeScript map library and a toolkit for building web map applications. It provides all the key functionalities in an easy-to-use package, so it's the most comfortable option to integrate our maps. - [Get started](/sdk-js/#get-started) - [Examples & tutorials](/sdk-js/examples/) - Usage with JS frameworks: [React](/react/) • [Angular](/angular/) • [Svelte](/svelte/) • [Vue.js](/vuejs/) • [Vite](/vite/) - [Reference](/sdk-js/api/) - [NPM](https://www.npmjs.com/package/@maptiler/sdk) - [GitHub](https://github.com/maptiler/maptiler-sdk-js) ### Modules MapTiler SDK JS is extensible with several [modules](/sdk-js/modules/), which you can install on top of the SDK and use them to implement additional map functions: - [Geocoding control](/sdk-js/modules/geocoding) to add a search box to your map - [Elevation profile control](/sdk-js/modules/elevation-profile) to add an elevation graph - [Marker layout](/sdk-js/modules/marker-layout) to add marker overlays with rich content - [3D objects](/sdk-js/modules/3d) to add 3D models to your map - [Augmented reality (AR) control](/sdk-js/modules/ar) to add a button turning the map into a 3D model - [**Weather SDK**](/sdk-js/modules/weather) to build maps with weather animation ## Other map libraries - [Leaflet](/leaflet/) – a lightweight open-source library to build pretty apps quickly - [OpenLayers](/openlayers/) – a robust open-source library to build complex apps - [Deck.gl](/deck-gl/) – a powerful framework for visualization of large data - [Cesium](/cesium/) – a popular library to build 3D maps, offering also plugins for **game engines**: [Unreal](/unreal/) • [Unity](/unity/) ## Mobile apps If you're specifically looking to build map applications for mobile platforms, you'll find everything related to that under [Mobile SDKs](/guides/getting-started/mobile/). ## APIs - [Public APIs](/cloud/api/) for end-user applications (read-only access) - [Service APIs](/cloud/admin-api/) for MapTiler account administration (full access) # MapTiler API Source: https://docs.maptiler.com/cloud/api/

MapTiler API

v1.0

Using the API from JavaScript?
Client Libraries
API Base URL
MapTiler API: https://api.maptiler.com/
MapTiler API allows you to programmatically access all the data, maps, services, and resources available in your MapTiler account. Access to your resources via MapTiler API is read-only, and therefore safe and well suited for public end-user applications. You can use it to add a map directly to your website, request map tiles, create an image with a location map for your business, search for addresses, and more. The universal public API request format is: ``` https://api.maptiler.com/{METHOD}/{QUERY}.json?{PARAMS}&key=YOUR_MAPTILER_API_KEY_HERE ``` > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). ## Additional Information [Contact Support](https://docs.maptiler.com/support/requests/) [Premium support](https://www.maptiler.com/support/) [Terms of Service](https://www.maptiler.com/terms/) # Maps API Source: https://docs.maptiler.com/cloud/api/maps/ _No overview content available._ # Static maps API Source: https://docs.maptiler.com/cloud/api/static-maps/ **Static maps API** makes it possible to use our maps as non-interactive, non-zoomable images. Adding [markers](/guides/maps-apis/static-maps/static-map-with-markers/) or [lines](/guides/maps-apis/static-maps/static-map-with-lines/) to static maps is also supported.
Static maps don't work with a free plan. Get them with any paid plan, including our most affordable tier.
### How to use the API - Directly - With the [Static maps Client JS](/client-js/#%EF%B8%8F-static-maps) library > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). ### Getting started - Use our [visual generator](https://www.maptiler.com/cloud/static-maps/generator/) to test the API and quickly build your static map's URL. - See the [static maps guide](/guides/maps-apis/static-maps/static-maps-for-your-web/) to learn how to configure static maps and see practical usage examples. - Learn how to [make a map non-interactive](/sdk-js/examples/interactive-false/) with MapTiler SDK JS. --- # Tiles API Source: https://docs.maptiler.com/cloud/api/tiles/ _No overview content available._ # Data API Source: https://docs.maptiler.com/cloud/api/data/
Using the API from JavaScript?
Client Libraries
# Images API Source: https://docs.maptiler.com/cloud/api/images/ _No overview content available._ # Search and geocoding API Source: https://docs.maptiler.com/cloud/api/geocoding/ The MapTiler **Search and geocoding API** makes it possible to search for any place on Earth and get accurate location data in return. See the [intro to place search](/guides/location-services/geocoding-search/) to learn how it works and what you can use it for. ## How to use the API - Directly from your web or backend applications. - Via the [Geocoding API client](/client-js/api/variables/services_geocoding.geocoding/) library, which wraps the API calls in ready-made functions for easier use in JavaScript. The client library is a good choice for JavaScript if you only need to use geocoding but not a map. - With our complete JavaScript SDK. It provides a [geocoding control module](/sdk-js/modules/geocoding/) to quickly integrate place search into your application. The SDK is best if you need the geocoding functionality plus a complete map dev kit. - With other JavaScript libraries: [MapLibre GL JS](/sdk-js/modules/geocoding/api/usage/maplibre-gl-js/) • [Leaflet](/leaflet/examples/geocoding-control/) • [OpenLayers](/openlayers/examples/geocoding-control/) - Without a map: [Vanilla JS](/sdk-js/modules/geocoding/api/usage/vanilla-js/) > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). ## Getting started For practical guidance on how to use this API, check out: - Check the geocoding playground to see how to construct the API calls - Explanation and usage tips for the most used [search parameters](/guides/location-services/geocoding-search/parameters) ### Basic example ```js import { geocoding } from "@maptiler/client"; // in an async function, or as a 'thenable': const result = await geocoding.forward("paris"); ``` # Geolocation API Source: https://docs.maptiler.com/cloud/api/geolocation/ The MapTiler **Geolocation API** makes it possible to get approximate location of the incoming request, so you can localize your maps and applications. See the [intro to IP geolocation](/guides/location-services/elevation/) to learn how geolocation works and what you can use it for. ## How to use the API - Directly from your web or backend applications. - Via the [Geolocation API client](/client-js/#%EF%B8%8F%EF%B8%8F-geolocation) library, which wraps the API calls in ready-made functions for easier use in JavaScript. Recommended if you don't need a map. - With our complete map [SDK JS](/sdk-js/). This is the best choice if you want the geolocation service plus a map. See related [code examples](/sdk-js/examples/?q=geolocation) for inspiration. > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). --- # Coordinates API Source: https://docs.maptiler.com/cloud/api/coordinates/ The MapTiler **Coordinates API** makes it possible to search map coordinate systems and transform coordinates from one to another. See the [intro to working with coordinate systems](/guides/location-services/coordinates/) to learn about how it works and when it's useful. ## How to use the API - Directly from any application, CLI, backend, pipeline. - Via the [Coordinates API client](/client-js/#-coordinates) library, which wraps the API calls in ready-made functions for easier implementation in JavaScript. > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). ## Getting started For practical guidance and sample API calls, see: - [Search coordinate systems](/guides/location-services/coordinates/search-coordinate-systems) - [Transform coordinates](/guides/location-services/coordinates/convert-coordinates) - [Transform coordinates in batch](/guides/location-services/coordinates/convert-coordinates-in-batch) ---

The results provided by the Coordinates API are based on the EPSG database version .

# Elevation API Source: https://docs.maptiler.com/cloud/api/elevation/ The MapTiler **Elevation API** makes it possible to get accurate altitude above mean sea level for any place on Earth. See the [intro to elevation](/guides/location-services/elevation/) to learn how it works and what you can use it for. ## How to use the API - Directly from your web or backend applications. - Via the [Elevation API client](/client-js/#%EF%B8%8F-elevation) library, which wraps the API calls in ready-made functions for easier use in JavaScript. This is the best option if you don't need a map. - With our complete map SDK for JavaScript. It provides an [elevation profile module](/sdk-js/modules/elevation-profile/) to add a control to your map which draws the elevation profile for a specified route. > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). You can get elevation for a single point or multiple points at once by providing their coordinates. Note that each pair of coordinates counts separately towards your API quota. ----- # Weather API Source: https://docs.maptiler.com/cloud/api/weather/
Using the API from JavaScript?
Weather Module
# Other Source: https://docs.maptiler.com/cloud/api/other/ _No overview content available._ # API Client Libraries and CLI Source: https://docs.maptiler.com/api-clients/ The API client libraries and command-line utilities provide you with helper functions that make it easier to call MapTiler APIs from your software and scripts. The **API client libraries** allow access to all your data, maps, and resources in your [MapTiler account](https://www.maptiler.com/cloud/). You can use them to quickly add a map directly to your website, create an image with a location map for your business, search for addresses, and much more. The **Upload JS library** makes it easy to upload your data to MapTiler and automate the process. You can use it with JavaScript or TypeScript. The **Command-line utility** serves for uploading your data, too. It has fewer features than the Upload JS library, but you can use it with any tech stack. ### [Client Libraries](/client-js) ![TypescriptLogo](/assets/img/ts.svg) ![JavaScriptLogo](/assets/img/js.svg) JavaScript package to add geocoding, geolocation, and more functions to your software and scripts. ### [Upload JS](/upload-js) ![TypescriptLogo](/assets/img/ts.svg) ![JavaScriptLogo](/assets/img/js.svg) A TypeScript library for uploading files to MapTiler. Features multipart support and progress tracking. ### [CLI](https://github.com/maptiler/maptiler-cloud-cli) ![Terminal logo](/assets/img/terminal.svg) Command-line utility for uploading your files to MapTiler. Works with any language. # API Client Library for JavaScript / TypeScript Source: https://docs.maptiler.com/client-js/ The **MapTiler Client JS** exposes a number of handy functions that wrap API calls to [MapTiler Cloud API services](https://docs.maptiler.com/cloud/api), such as: - [Geocoding forward and reverse](#-geocoding) - [Geolocation from visitor's IP address](#%EF%B8%8F%EF%B8%8F-geolocation) - [Coordinate systems search and transform](#-coordinates) - [User data fetching as GeoJSON](#-data) - [Static maps of all sorts](#%EF%B8%8F-static-maps) - [Elevation lookup with batch features](#-elevation) The project is entirely written in TypeScript and all the function arguments are nicely documented and typed. - Better developer experience of working with APIs in the code editor - with parameter info, quick info, and member lists. - Code completion: reducing typos and other common mistakes - Content assist and code hinting providing contextual help - Type safety - for higher quality code and testing - Backward compatibility: guaranteed on changes to API endpoints - Runs: in Node.js or in browser - Open source license
If you need this API wrapper and a complete SDK to display beautiful interactive maps, check out MapTiler SDK JS, it contains it all!
## 📦 Installation ### ES module from NPM ```shell npm install --save @maptiler/client ``` ### From NodeJS NodeJS includes a stable `fetch()` function only from version *18*, and this client does not contain a polyfill. If the `fetch()` function exists (browser or Node >= 18) then it is going to be resolved automatically. Yet, a custom `fetch()` function can be provided to the `config` object for Node < 18. In [this NodeJS example](examples/test-node.js), you can see that the package [Node Fetch](https://www.npmjs.com/package/node-fetch) has been `npm install`ed and is passed to the config object of the *MapTiler Client*. ```js import { config, // ... } from '@maptiler/client'; // For this example to work, you must bring your own node-compatible fetch, // unles you are using a version of Nodejs that already contains fetch (>=18) import fetch from 'node-fetch'; config.fetch = fetch; // ... ``` ## 🚀 Basic Usage ```ts // Import the whole library import * as maptilerClient from '@maptiler/client'; // Or import only the bits you need import { config, geocoding, geolocation, coordinates, data, staticMaps, elevation, math, } from '@maptiler/client'; ``` ## 📘 API Reference For detailed guides, API reference, and advanced examples, visit our comprehensive documentation: [API documentation](https://docs.maptiler.com/client-js/) ### Easy access to MapTiler API Here is the list of service wrapper functions that are built-in: ### 🔍 Geocoding > ✅ Please, use geocoding functions only from client-side (browser) and do not 🚫 **store** or **redistribute** MapTiler Cloud API data. In case of doubt, consult the [terms](https://www.maptiler.com/cloud/terms/#explicitly-prohibited-use) ⚖️ #### Forward You want to know the longitude and latitude of a specific place, use the forward geocoding: ```ts // in an async function, or as a 'thenable': const result = await maptilerClient.geocoding.forward('paris'); ``` You can provide some options, such as: - the proximity, given a lon-lat position, to sort the results - one of more languages to get the results into - a bounding geo box, to restrict the search to a given window Read more about forward geocoding, as well as feature ID query and batch forward geocoding, on our [official documentation](https://docs.maptiler.com/client-js/geocoding/#forward). #### Reverse You want to know the name of a place, given a longitude-latitude? Use the reverse geocoding: ```ts // in an async function, or as a 'thenable': const result = await maptilerClient.geocoding.reverse([6.249638, 46.402056]); ``` The same option object as the forward geocoding can be provided. Read more about reverse geocoding on our [official documentation](https://docs.maptiler.com/client-js/geocoding/#reverse). #### Language For both *forward* and *reverse* geocoding, this library provides a list of supported languages as shorthands that include [ISO language codes](https://en.wikipedia.org/wiki/ISO_639-1). The result will be provided in multiple languages if the `language` options are an array: ```ts const result = await maptilerClient.geocoding.forward('paris', {language: [maptilerClient.Language.SPANISH, maptilerClient.geocoding.Language.KOREAN]}) ``` The special language `AUTO` will detect the platform/browser preferred language. If the language is not specified as options, MapTiler Cloud will use the `Accept-language` from the HTTP header of the request. The language selected this way is generally similar to the `Language.AUTO` mode, but can still differ in some cases ([read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language)). ### 🕵️‍♂️ Geolocation The geolocation service provides location information of a visitor using its IP address. The geolocation uses the IP address of a visitor to provide information about their location, such as city, region, country, timezone, etc. The precision is lower than GPS, but it does not require visitors to explicitly enable the location service from their web browser. There is only a single function: ```ts // in an async function, or as a 'thenable': const result = await maptilerClient.geolocation.info(); ``` Read more about geolocation on our [official documentation](https://docs.maptiler.com/client-js/geolocation/). ### 🌐 Coordinates If you are already familiar with [epsg.io](https://epsg.io/) (created by MapTiler), then you may find it convenient to access the details of more than 10 thousands of coordinate reference systems (CRS) programmatically, as well as transforming coordinates from one system to another! #### Search The `search` lets you perform a query in a free form fashion. Here are some examples: ```ts // in an async function, or as a 'thenable': const resultA = await maptilerClient.coordinates.search('mercator'); const resultB = await maptilerClient.coordinates.search('plate carree'); const resultC = await maptilerClient.coordinates.search('france'); const resultD = await maptilerClient.coordinates.search('code:4326', {transformations: true})); ``` The `transformations` options retrieve a lot more details about the CRS that MapTiler API is able to transform to/from than just their IDs. Read more about searching coordinate systems in our [official documentation](https://docs.maptiler.com/client-js/coordinates/#search). #### Transform Transforming a couple of coordinates from one system to another can be challenging, for example, most countries have their own official system, yet web mapping tools are more often than not exclusive to [WGS84](https://epsg.io/4326). If not provided, both the source (`sourceCrs`) and the destination (`targetCrs`) are defaulted to **EPSG:4326** (in other words, [WGS84](https://epsg.io/4326)). Here is how to use this feature: ```ts // in an async function, or as a 'thenable': // Providing one coordinate to transform, with a target CRS being EPSG:9793 (RGF93 v2 / Lambert-93, France official CRS) const resultA = await maptilerClient.coordinates.transform([1, 45], {targetCrs: 9793}) // Using the same logic, we can pass up to 50 coordinates to be transformed const resultB = await maptilerClient.coordinates.transform([[10, 48], [1, 45]], {targetCrs: 9793}) ``` Read more about transforming coordinates on our [official documentation](https://docs.maptiler.com/client-js/coordinates/#transform). ### 💽 Data MapTiler Cloud give its users the possibility to [upload and create data](https://cloud.maptiler.com/data/), manually with a user interface or by uploading a GPX, GeoJSON, KML or shp file. A unique ID is associated with each dataset so that we can later on access it programmatically to retrieve a GeoJSON equivalent of it: ```ts // in an async function, or as a 'thenable': const result = await maptilerClient.data.get('my-dataset-unique-id') ``` Since the result is a GeoJSON, it can easily be added to a `map` with `.addSource()` and `.addLayer()`. Read more about fetching your own data on our [official documentation](https://docs.maptiler.com/client-js/data/). ### 🗺️ Static maps > ✅ Please, use static maps URLs only from client side `` elements, and do not 🚫 store or redistribute the static map files. In case of doubt, consult the [terms](https://www.maptiler.com/cloud/terms/#explicitly-prohibited-use) ⚖️ Maptiler Cloud provides many possibilities for creating static maps as PNG, JPEG or WebP images. They all offer the possibilities to: - Choose from one of the MapTiler styles or your own - Add markers with a custom icon (or default icon with custom color) - Add path or polygon, with a parametric line width and color and a parametric filling color Three modes are available: `centered`, `bounded` and `automatic`. > 📣 *__important:__* only image **URLs** are returned. > Contrary to the other functions of this library, the static map functions **do not** perform any query to MapTiler Cloud API, instead they build the image URL for you to use in `` elements. #### Map Styles In the following static map functions, the `option` object features a `style` property that can be a string or one of the built-in style shorthands. Here is the full list: - `MapStyle.STREETS`, reference style for navigation and city exploration - `MapStyle.STREETS.DARK` (variant) - `MapStyle.STREETS.LIGHT` (variant) - `MapStyle.STREETS.PASTEL` (variant) - `MapStyle.OUTDOOR` reference style for adventure - `MapStyle.DATAVIZ`, the perfect style for data visualization, with very little noise - `MapStyle.DATAVIZ.DARK` (variant) - `MapStyle.DATAVIZ.LIGHT` (variant) - `MapStyle.BACKDROP`, the perfect style for data visualization, with very little noise - `MapStyle.BACKDROP.DARK` (variant) - `MapStyle.BACKDROP.LIGHT` (variant) - `MapStyle.WINTER` reference style for winter adventure - `MapStyle.SATELLITE` reference style satellite and airborne imagery (no variants) - `MapStyle.HYBRID` reference style satellite and airborne imagery with labels (no variants) - `MapStyle.BASIC` reference style for minimalist design and general purpose - `MapStyle.BASIC.DARK` (variant) - `MapStyle.BASIC.LIGHT` (variant) - `MapStyle.BRIGHT` reference style for high contrast navigation - `MapStyle.BRIGHT.DARK` (variant) - `MapStyle.BRIGHT.LIGHT` (variant) - `MapStyle.BRIGHT.PASTEL` (variant) - `MapStyle.TOPO` reference style for topographic study - `MapStyle.TOPO.SHINY` (variant) - `MapStyle.TOPO.PASTEL` (variant) - `MapStyle.TOPO.TOPOGRAPHIQUE` (variant) - `MapStyle.VOYAGER` reference style for stylish yet minimalist maps - `MapStyle.VOYAGER.DARK` (variant) - `MapStyle.VOYAGER.LIGHT` (variant) - `MapStyle.VOYAGER.VINTAGE` (variant) - `MapStyle.TONER` reference style for very high contrast stylish maps - `MapStyle.TONER.BACKGROUND` (variant) - `MapStyle.TONER.LITE` (variant) - `MapStyle.TONER.LINES` (variant) - `MapStyle.OPENSTREETMAP` (reference style, this one does not have any variants) - `MapStyle.OCEAN` (reference style, this one does not have any variants) #### Centered static maps This type of map is centered on a longitude-latitude coordinate and the zoom level must also be provided (from `0`: very zoomed out, to `22`: very zoomed in). Note that if a path or markers are provided, the framing of the map will not automatically adapt to include those (use the `automatic` mode for that). ```ts const imageLink = maptilerClient.staticMaps.centered( // center position (Boston) [-71.06080, 42.362114], // zoom level 12.5, // Options { // Request a hiDPI/Retina image hiDPI: true, // Output image size width: 1000, height: 1000, // Map style style: maptilerClient.MapStyle.OUTDOOR, }); ``` Read more about centered static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#center-based-image). #### Bounded static maps This type of map requires a bounding box made of two points: the south-west bound and the north-east bound. The zoom level cannot be provided and is automatically deduced from the size of the bounding box. ```ts const imageLink = maptilerClient.staticMaps.bounded( // The bounding box on Europe [ -24, // west bound (min x) 34.5, // south bound (min y) 32, // east bound (max x) 71, // north bound (max y) ], // Options { hiDPI: true, width: 2048, height: 2048, style: maptilerClient.MapStyle.STREETS.DARK, // Extra space that will be added around the bounding box, in percentage // (0.1 = 10% is actually the default) padding: 0.1 }); ``` Since the zoom level cannot be provided, the level of detail is dictated by the size of the output image. Here is an example: | `2048 x 2048` | `1024 x 1024` | | :-----------: | :-----------: | | ![](images/screenshots/static-bounded-europe-2048.png) | ![](images/screenshots/static-bounded-europe-1024.png) | As you may notice, the geo bounding box could have very different proportions than the output image size. In the following example, we place the very same bounding box around Portugal, which has a this particular strip looking shape. We also add a `path` that repeats exactly the same bounding box to show the difference between the provided bounding box and the final image. We kept the default padding of 10%: | `2048 x 2048` | `1024 x 2048` | | :-----------: | :-----------: | | ![](images/screenshots/static-bounded-portugal-2048x2048.png) | ![](images/screenshots/static-bounded-portugal-1024x2048.png) | Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#bounds-based-image). #### Automatic static maps As we have seen with centered and bounded maps, providing all the parameters is nice, but it can be cumbersome for the simplest use cases. This is why MapTiler Cloud also provides static maps that fit automatically whatever you need to place inside: path or markers. In the following example, we are going to load a cycling track recorded by one of our team members in Montreal, Canada. The track, originally a GPX file, was pushed to MapTiler Data and is now made available as a GeoJSON: ```ts // Fetching the GeoJSON const bikeTrack = await maptilerClient.data.get('the-id-of-a-bike-track-in-montreal'); // Extracting the track points with the shape [[lng, lat], [lng, lat], ...] const trackPoints = bikeTrack.features[0].geometry.coordinates[0] .map(p => p.slice(0, 2)); const imageLink = maptilerClient.staticMaps.automatic({ // hiDPI/Retina precision hiDPI: true, // A fairly large output image width: 2048, height: 1024 , // A grey style on which the track will pop! style: maptilerClient.MapStyle.STREETS.LIGHT, // Draw a path with the trackpoints path: trackPoints, // Adding a marker for the starting point, with a custom color (array of shape [lng, lat, color]) marker: [trackPoints[0][0], trackPoints[0][1], '#0a0'], // Showing the track in red pathStrokeColor: 'red', }); ``` And voila! ![static map with bike path](images/screenshots/static-with-path.png) > 📣 *__Note:__* The GeoJSON for this track contains 9380 pairs of coordinates, which is a lot! In order to send the track to MapTiler Cloud static maps API, the client simplifies the long paths while keeping a high degree of precision using a very fast [Ramer-Douglas-Peucker algorithm](https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm). Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#auto-fitted-image). ### 🏔️ Elevation With the elevation API, it's possible to get the elevation in meters from any location. It's possible to lookup and compute elevation for a single location, to provide a batch of points, from a GeoJSON LineString or from a GeoJSON MultiLineString! > ℹ️ Under the hood, the elevation API is fueled by MapTiler Cloud's **RGB Terrain** raster tileset, which is a composite of many high-resolution DEMs from all over the world, curated and processed by our geodata team! The same dataset is also fueling our SDK's elevation (3D terrain) and the hillshading we use in many of our styles. > 📣 Note for **TypeScript** users: internally, the elevation feature relies on some *GeoJSON* type definitions that can be found in this NPM package: `@types/geojson`. Namely `LineString`, `MultiLineString` and `Position`. It may improve your developer experience to also use these types. Let's see how to use it: #### At a single location ```ts // Not mandatory, but it's to explain where the type comes from: import { Position } from "geojson"; const montBlancPeak: Position = [6.864884, 45.832743]; const elevatedPosition = await maptilerClient.elevation.at(montBlancPeak); ``` The returned value is also a *GeoJSON* `Position` array, but with three elements: `[lng, lat, elevation]`. Read more about elevation lookup for a single location in our [official documentation](https://docs.maptiler.com/client-js/elevation/#at). #### Batch mode ```ts // Not mandatory, but it's to explain where the type comes from: import { Position } from "geojson"; const peaks: Position[] = [ [6.864884, 45.832743], // Mont Blanc, Alps [86.9250, 27.9881], // Mount Everest, Himalayas [-70.0109, -32.6532], // Aconcagua, Andes [-151.0064, 63.0695], // Denali, Alaska [37.3556, -3.0674], // Mount Kilimanjaro [42.4453, 43.3499], // Mount Elbrus, Caucasus [137.1595, -4.0784], // Puncak Jaya, Sudirman Range [-140.4055, 60.5672], // Mount Logan, Saint Elias Mountains [138.73111, 35.358055], // Mount Fuji ]; const elevatedPeaks = await maptilerClient.elevation.batch(peaks); ``` Read more about elevation lookup for a batch of locations in our [official documentation](https://docs.maptiler.com/client-js/elevation/#batch). #### From a GeoJSON LineString In the *GeoJSON* LineString case, it clones the entire structure and the positions arrays of the clone will contain three elements: `[lng, lat, elevation]`. The original LineString is not mutated nor pointed at. ```ts // Not mandatory, but it's to explain where the type comes from: import { LineString } from "geojson"; const someLineString: LineString = { type: "LineString", coordinates: [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]] }; const someElevatedLineString = await maptilerClient.elevation.fromLineString(someLineString); // someElevatedLineString is also of type LineString ``` Read more about elevation lookup for a `LineString` in our [official documentation](https://docs.maptiler.com/client-js/elevation/#linestring). #### From a GeoJSON MultiLineString In the *GeoJSON* MultiLineString case, it clones the entire structure and the positions arrays of the clone will contain three elements: `[lng, lat, elevation]`. The original MultiLineString is not mutated nor pointed at. ```ts // Not mandatory, but it's to explain where the type comes from: import { MultiLineString } from "geojson"; const someMultiLineString: MultiLineString = { type: "LineString", coordinates: [ [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]], [[-151.0064, 63.0695], [37.3556, -3.0674], [42.4453, 43.3499]], [[137.1595, -4.0784], [-140.4055, 60.5672], [138.73111, 35.358055]], ] }; const someElevatedMultiLineString = await maptilerClient.elevation.fromMultiLineString(someMultiLineString); // someElevatedMultiLineString is also of type MultiLineString ``` Read more about elevation lookup for a `MultiLineString` in our [official documentation](https://docs.maptiler.com/client-js/elevation/#multilinestring). #### Caching In order to increase performance while reducing unnecessary elevation data fetching, the elevation tiles are cached. This is particularly important for the LineString and MultiLineString lookups because GeoJSON data are likely to come from a recorded or planned route, where position points are very close to one another. ### 🧮 Math Some operations can be fairly repetitive: WGS84 to Mercator, WGS84 to *zxy* tile index, distance between two points with Haversine formula, etc. As a result, we have decided to expose a `math` package providing the most recurrent feature, so that, just like us at MapTiler, you no longer need to copy-paste the same function from your previous project! The `math` package differs from the others in the sense that it does not call the MapTiler Cloud API, instead it operates fully on the machine it's running on. Here are some examples: ```ts // Not mandatory, but it's to explain where the type comes from: import { Position } from "geojson"; // Some constants const earthRadius = maptilerClient.math.EARTH_RADIUS; const earthCircumference = maptilerClient.math.EARTH_CIRCUMFERENCE; const montBlancPeakWgs84: Position = [6.864884, 45.832743]; // From WGS84 to Mercator const montBlancPeakMerc = maptilerClient.math.wgs84ToMercator(montBlancPeakWgs84); // also of type Position // From Mercator to WGS84 const montBlancPeakWgs84Again = maptilerClient.math.mercatorToWgs84(montBlancPeakMerc); // A great-circle distance in meters: const from: Position = /* ... */; const to: Position = /* ... */; const distance = maptilerClient.math.haversineDistanceWgs84(from, to); // Full distance of a route made of many positions const route: Position[] = /* ... */; const totalDistance = maptilerClient.math.haversineCumulatedDistanceWgs84(route); // Lon lat to tile index, given a zoom level. An [x, y] array is returned const tileXY = maptilerClient.math.wgs84ToTileIndex(montBlancPeakWgs84, 14); // Possible to have floating point tile indices with a third argument to `false` // and many more! ``` Please find out more about the math package in our [official documentation](https://docs.maptiler.com/client-js/math). # MapTiler Client - v3.0.1 Source: https://docs.maptiler.com/client-js/api/ MapTiler Client - v3.0.1 Modules config index language services/coordinates services/data services/elevation services/geocoding services/geolocation services/math services/ServiceError services/staticMaps On This Page Modules config index language services/coordinates services/data services/elevation services/geocoding services/geolocation services/math services/ Service Error services/static Maps Client JS config Client Config Fetch Function config index Map Style Variant Reference Map Style Buffer To Pixel Data Function Map Style Preset Map Style Type Pixel Data Tile J S O N default Reference Style Map Map Style map Style Preset List misc buffer To Pixel Data Browser can Parse Pixel Data expand Map Style get Buffer To Pixel Data Parser get Tile Cache style To Style are Same Languages Automatic Static Map Options Base Geocoding Options Bounded Static Map Options By Id Geocoding Options Centered Static Map Options circumference At Latitude Client Config Common Forward And Reverse Geocoding Options config Coordinate Export Coordinate Grid Coordinate Id coordinates Coordinates Coordinate Search Coordinate Search Result Coordinates Search Options Coordinates Transform Options Coordinate Transformation Coordinate Transform Result data Default Transformation elevation Elevation At Options Elevation Batch Options Feature Hierarchy Fetch Function geocoding Geocoding Feature Geocoding Options Geocoding Place Type Geocoding Search Result geolocation Geolocation Info Options Geolocation Result get Auto Language Get Data Options get Language Info From Code get Language Info From Flag get Language Info From Key is Language Info I S O Language Language Language Geocoding Options Language Info math Non I S O Language Reverse Geocoding Options Service Error Static Map Base Options Static Map Marker static Maps to Language Info X Y Z language Language Info I S O Language Language Non I S O Language are Same Languages get Auto Language get Language Info From Code get Language Info From Flag get Language Info From Key is Language Info to Language Info services coordinates Coordinate Export Coordinate Grid Coordinate Id Coordinate Search Coordinate Search Result Coordinates Search Options Coordinates Transform Options Coordinate Transformation Coordinate Transform Result Default Transformation X Y Z coordinates data Get Data Options data elevation Elevation At Options Elevation Batch Options elevation geocoding Base Geocoding Options By Id Geocoding Options Common Forward And Reverse Geocoding Options Coordinates Feature Hierarchy Geocoding Feature Geocoding Options Geocoding Place Type Geocoding Search Result Language Geocoding Options Reverse Geocoding Options geocoding geolocation Geolocation Info Options Geolocation Result geolocation math math circumference At Latitude Service Error Service Error static Maps Automatic Static Map Options Bounded Static Map Options Centered Static Map Options Static Map Base Options Static Map Marker static Maps # Upload JS API Library Source: https://docs.maptiler.com/upload-js/ This library provides a simple and convenient way to upload large files to MapTiler, track progress, and handle errors. You can use it in any JavaScript or TypeScript project. Alternatively, check out [other ways to upload your files](/guides/getting-started/upload-files/). ## Features * Multipart file upload support * Progress tracking with detailed statistics (total file size, uploaded bytes, elapsed time, bitrate, estimated remaining time) * Error handling and status reporting * React integration * TypeScript type safety * Customizable upload endpoints * Support for different output types * Cancel upload functionality ## How to use 1. [Install the library.](https://github.com/maptiler/maptiler-upload-js/tree/main?tab=readme-ov-file#installation) 2. [Get your MapTiler service token.](https://docs.maptiler.com/cloud/api/authentication-token/#get-your-service-token) You'll need it for the next step. The token grants access to your MapTiler account and enables the library to upload files on your behalf. 3. Implement the Upload API endpoints [in your backend](https://github.com/maptiler/maptiler-upload-js/tree/main?tab=readme-ov-file#server-side). 4. Initialize the Upload API endpoints [on the client side](https://github.com/maptiler/maptiler-upload-js/tree/main?tab=readme-ov-file#client-side). 5. Try the [Next.js example](https://github.com/maptiler/maptiler-upload-js/tree/main?tab=readme-ov-file#-example) to see how to use the library in practice. ## Reference The [reference](/upload-js/api/) documents every object, class, type, and method available in the MapTiler Upload JS. # Upload JS Source: https://docs.maptiler.com/upload-js/api/ Upload JS Enumerations Status Classes UploadAPI Type Aliases ApiConfig ApiError ChangeCallback ErrorCallback GenericError InitUploadResponse InternalPart OutputType Part ProcessPayload Progress UploadConfig UploadPart Functions cancelUpload initUpload processUpload replaceUpload On This Page Enumerations Status Classes Upload API Type Aliases Api Config Api Error Change Callback Error Callback Generic Error Init Upload Response Internal Part Output Type Part Process Payload Progress Upload Config Upload Part Functions cancel Upload init Upload process Upload replace Upload Upload JS Status Upload A P I Api Config Api Error Change Callback Error Callback Generic Error Init Upload Response Internal Part Output Type Part Process Payload Progress Upload Config Upload Part cancel Upload init Upload process Upload replace Upload # Upload your data using API & CLI Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/how-to-upload-mbtiles-or-geopackage-into-maptiler-cloud-using-api/ This tutorial shows how to securely upload tiles in GeoPackage or MBTiles to MapTiler using the command\-line utility. All requests are authorized by a token, which is much more secure than an API key. If you want to automate the uploading of your assets to MapTiler or just don't want to bother with using the browser interface, we have developed a `maptiler-cloud-cli` utility to serve your needs. For more control over tileset management, you can use the [Service API](https://docs.maptiler.com/cloud/admin-api/). The Service API allows you to create, update or delete a tileset, among other actions. Using tokens for secure authentication -------------------------------------- To successfully upload your resources using the command\-line utility, you must acquire your own token for authentication. Navigate to the "[Credentials](https://cloud.maptiler.com/account/credentials/)" section of your account administration pages and click on New Credentials if you haven't set any up already. ![](./file_07f0c3120b.png) After creating the credentials, you will be able to copy the token: ![](./file_898834d184.png) The documentation has more information about [securely signing requests to the MapTiler API](/guides/maps-apis/maps-platform/how-to-use-credentials-to-securely-sign-requests-to-maptiler-cloud-api). Using the CLI utility --------------------- You will need a Python 3 environment on your machine to use this utility. We will start with an empty project, but the steps will be similar if you integrate this utility into an existing project. We will be using standard Python tools; virtual environment and pip, alternatively you can use a different package manager like [Poetry](https://python-poetry.org/). #### 1\. Creating a virtual environment Let's make sure you are using the correct version of python by running `python -V`, the output should indicate Python 3\.6 or above, in our case it's `Python 3.8.9`. If not, please install a more up\-to\-date version, follow the instructions on the [Python web](https://wiki.python.org/moin/BeginnersGuide). > [!WARNING] > Some distributions split it into a separate distribution package, like python3-venv on Ubuntu/Debian. In these cases, you will have to install the python3-venv package to create the virtual environment. Now we are going to create our project folder and make a virtual environment inside of it: ``` bash mkdir test_cli; cd test_cli python -m venv test_cli_venv ``` You should be able to see the newly created folder `test_cli_venv` inside the project folder. #### 2\. Installing the maptiler\-cloud\-cli We are going to source the virtual environment and install `maptiler-cloud-cli` inside of it. ``` bash source test_cli_venv/bin/activate pip install maptiler-cloud-cli ``` #### 3\. Uploading a new tileset This code snippet assumes that your desired file is placed in the project directory however, you could use an absolute path to reference files outside the project folder.  ``` bash maptiler-cloud --token=MY_TOKEN tiles ingest ISLANDS.mbtiles ``` > [!NOTE] > The GeoPackage must have a tile matrix set. Read the [Vector tiles generating (basic)](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-vector-data) article to learn how to create a valid GeoPackage or MBTiles from the [MapTiler Engine application](https://www.maptiler.com/engine/). > [!IDEA] > If you reach the tileset limit for your account, you will not be able to upload new tilesets, and you will get an error. Check out our [plans](https://www.maptiler.com/cloud/plans/) to increase the number of tilesets you can have. #### 4\. Update a tileset You can use the tileset ID to upload a new file to the same tileset. ``` bash maptiler-cloud --token=MY_TOKEN tiles ingest --document-id=EXISTING_TILESET_ID ISLANDS_v2.mbtiles ``` > [!WARNING] > This option **replaces** the tileset data with the data from the new file. It does **NOT** add the new data to the existing tileset. Conclusion ---------- Useful Links ------------ [**Service API documentation**](https://docs.maptiler.com/cloud/admin-api/) [**MapTiler Support \- Service API**](/guides/maps-apis/maps-platform/managing-maps-using-the-admin-api) [MapTiler CLI](https://github.com/maptiler/maptiler-cloud-cli) # MapTiler Service API Source: https://docs.maptiler.com/cloud/admin-api/ v1.0
API Base URL
MapTiler API: https://api.maptiler.com/
MapTiler API allows you to programmatically access all the data, maps, services, and resources available in your MapTiler account. Access to your resources via MapTiler API is read-only, and therefore safe and well suited for public end-user applications. You can use it to add a map directly to your website, request map tiles, create an image with a location map for your business, search for addresses, and more. The universal public API request format is: ``` https://api.maptiler.com/{METHOD}/{QUERY}.json?{PARAMS}&key=YOUR_MAPTILER_API_KEY_HERE ``` > [!KEY] > You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/). ## Additional Information [Contact Support](https://docs.maptiler.com/support/requests/) [Premium support](https://www.maptiler.com/support/) [Terms of Service](https://www.maptiler.com/terms/) # Upload API Source: https://docs.maptiler.com/cloud/admin-api/tileset_ingest/ MapTiler's Upload API allows you to add new datasets or update existing ones from the command line. To make it easier, you can use the [CLI tool](https://github.com/maptiler/maptiler-cloud-cli) to run the commands. See the complete guide: [How to upload your data using API & CLI](/guides/map-tiling-hosting/data-hosting/how-to-upload-mbtiles-or-geopackage-into-maptiler-cloud-using-api/) > [!IDEA] > If you're working with JavaScript/TypeScript, we highly recommend to use this API via the [Upload JS library](/upload-js/). It has extra features and is much more comfortable to use. # Tileset API Source: https://docs.maptiler.com/cloud/admin-api/tileset/ MapTiler’s Tileset API allows you to manage your uploaded data via API. You can update the metadata, delete unwanted maps from your account, and much more. # API keys API Source: https://docs.maptiler.com/cloud/admin-api/api-keys/ _No overview content available._ # Analytics API Source: https://docs.maptiler.com/cloud/admin-api/analytics/ _No overview content available._ # Managing maps using the Service API Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/managing-maps-using-the-admin-api/ This article provides an overview of the Service API for uploading and management of tilesets. Both these APIs require secure authentication, provided by tokens which can be found in the credentials section of your account. What does the Service API do? --------------------------- If you want to add new tilesets, update them, change their metadata, or delete them, you can now do so without opening a browser. The new API can be accessed at `https://service.maptiler.com/v1`. The API specification for it is located on the [MapTiler API documentation Page](https://docs.maptiler.com/cloud/admin-api/). All of the requests to the API have to be authorized using the secure token that can be obtained from  your account web page. More information on authentication and tokens can be found on the [MapTiler authentication documentation page.](/guides/maps-apis/maps-platform/how-to-use-credentials-to-securely-sign-requests-to-maptiler-cloud-api) Using tokens for secure authentication -------------------------------------- Navigate to the **Credentials** section of your **Account** and click on the create new credentials if you have not done so yet. ![](./file_2cdc622246.png) After creating the credentials, you will be able to copy the token: ![](./file_e301474ea1.png) Using the Service API --------------------- You can send your requests to the Service API using any of our [API clients](/api-clients/) or even curl. You must set the `Authorization` HTTP header in the form of `Token {YOUR_TOKEN}`, so we know it's you making the requests. To make your life easier we highly recommend you use the [upload JS library](/upload-js/) or the CLI utility to upload the tilesets. There is a very good guide on how to install and use it the command-line tool in the [MapTiler Documentation](/guides/map-tiling-hosting/data-hosting/how-to-upload-mbtiles-or-geopackage-into-maptiler-cloud-using-api). Limitations ----------- The standard storage limits from price plans apply to the API. # Authentication Source: https://docs.maptiler.com/cloud/api/authentication/ Authentication is a way of proving someone's identity. In case of MapTiler's online maps and services, every API request must be authenticated, so that we know it's you or your map users making the request. For example, if you embed a MapTiler map on your website, then whenever someone visits that page, their browser sends a request to MapTiler servers to get the map. This request must be authenticated, otherwise the map won't show up on the page. ## How to authenticate? MapTiler offers two authentication methods. Which one is best depends on your needs: #### API key An **API key** is a simple and easy-to-use authentication for client-side use such as web apps. If you want to use a map on your website or build a mobile application using MapTiler's online maps and [API services](/cloud/api/), an API key is ideal. 👉 [Use an API key](/cloud/api/authentication-key) #### Service token A **service token** provides advanced and highly secure authentication for backend use. You’ll need it in these scenarios: - You're planning to use the [Service API](/cloud/admin-api/). These API calls make it possible to not only read, but also modify and delete your cloud resources, so the highest security is in order. - You’re building a map application, but you don’t want to use an API key. Using a service token for better security is possible, but remember! The token itself must never get exposed, so if your app’s source code is public (for example on the web frontend), you’ll need to do some extra work to keep the token hidden in the backend. 👉 [Use a service token](/cloud/api/authentication-token/) # API key Source: https://docs.maptiler.com/cloud/api/authentication-key/ An API key is one of the [authentication methods](/cloud/api/authentication/) that enables you to use our maps and access various services [via our API](/cloud/api/). In practice, an API key is a string of letters and numbers in unique combinations, so that it makes clear identification of map and service requests possible. Example of an API request authenticated with an API key: ``` https://api.maptiler.com/maps//?key=YOUR_MAPTILER_API_KEY_HERE#1.0/0.00000/0.00000 ``` If you replace `YOUR_MAPTILER_API_KEY_HERE` with a valid API key and paste the URL in your browser’s address bar, you’ll see the map. If you don't provide a key, the request won't work because it's not identified. ## [Get a testing key](#get-a-testing-key) To get your API key for testing purposes, make sure you're logged in to your [MapTiler account](https://cloud.maptiler.com/). Then follow these steps: 1. Go to page [API keys](https://cloud.maptiler.com/account/keys/). 2. Copy the **default key** and use it to play around and test your maps. _Never use it publicly!_ > [!WARNING] > The default API key has no protection, so if you use it publicly, it might get stolen and misused. The primary purpose of the default key is to make all the examples in your MapTiler account work; you can use it too, but make sure it's only ever for testing or other internal purposes! For public use in production, please create a new, protected key. ## [Get a protected key for production](#get-a-protected-key-for-production) The requests authenticated with an API key are visible to the world, which means that anyone can see and potentially steal your API key. The thief cannot change or break your maps, because the API calls are read-only, but their usage counts towards your API request quota and can lead to extra costs (if you’re on a paid plan) or suspending your maps. To protect your API key from misuse, create a new key for each of your applications with a set origin (specific web domain or software allowed to use the key). Using a separate key per application makes it easy to replace the key if it does get compromised. You can even create a separate API key for each of your maps to better track its traffic in your [analytics](https://cloud.maptiler.com/account/analytics). > [!IDEA] > To see how many API keys you can create, go to [Account > Settings](https://cloud.maptiler.com/account/settings) > section **Usage** > **Keys**. Your default key doesn't count towards the limit. If you need more keys, please [contact our Sales](https://www.maptiler.com/contacts/). To create a new key, protected from misuse, follow these steps: 1. Go to page [API keys](https://cloud.maptiler.com/account/keys/). 2. Click on **New key**. 3. Enter a short descriptive name for the key. 4. Select one of the available methods to protect your key: - **Allowed HTTP origins** – restricts the API calls made with the key to specific web domains. If somebody steals your key and uses it on a different domain, it won't work. Choose this option if you want to show a MapTiler map on your website which has a unique domain name. - **Allowed user-agent header** – restricts the API calls made with the key to a specific desktop or mobile application. This option is handy if you want to use a MapTiler map in your own custom application which you've built and in which you can set the `User-Agent` HTTP header. 👉 [Learn more about the protection methods](/guides/maps-apis/maps-platform/how-to-protect-your-map-key) 5. Click **Create**. Your new key appears on the API keys page, where you can copy it anytime. # How to protect your map key Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/how-to-protect-your-map-key/ If you publish a map, you are also exposing your [API key](/cloud/api/authentication-key/). There are several ways to protect your key and prevent misuse, and we describe them in detail on this page. > [!WARNING] > Initially, your MapTiler account only contains the **default key**, which is special and *can't be protected*. To apply any of the described protection methods, you need to [create a new key](https://cloud.maptiler.com/account/keys/new). ## Allow map usage only on listed websites If the map is only published on certain websites, list these websites in the **Allowed HTTP origins** field. For example, enter `mydomain.com` to ensure that only requests coming from `mydomain.com` get processed. To allow requests from subdomains, use `*.mydomain.com`. Put each rule on a separate line. Make sure your applications send the `Origin` (or `Referer`) header, otherwise the requests will be treated as "unknown" and will be rejected if any origin is specified here. You can use the `?` placeholder to explicitly allow unknown origins. *Requests with the `Origin` header coming from a domain that is not on this list will still be rejected.* ## Allow map usage only in listed software For other usage where the map is not used on a specific URL, like in mobile apps or desktop GIS software, you can whitelist software with a specific user-agent. Only this software will be then able to use the map. In the **Allowed user-agent header** field, fill in a substring of your software's user-agent. Note the field is *case-sensitive*. The saved substring gets compared with the `User-Agent` HTTP header of each request, and if there is a match, the request is processed. Otherwise, it is denied.  > [!INFO] > Only a substring is compared with the `User-Agent` HTTP header. So for example "coolest-mobile-map-app" will work with user-agent headers such as "coolest-mobile-map-app-0.5", "coolest-mobile-map-app-1.1", etc. but it will also work with "my-friend's-coolest-mobile-map-app". Make sure the substring is unique. ## Use digital signature instead of API key Extra tip: If the code of your application isn't public, you can prevent misuse completely by securing API requests with a digital signature rather than using API keys. This is especially practical for mobile and desktop apps, or enterprise applications calculating signature for every map tile request. ## What's next To create an API key with the described restrictions, go to your MapTiler account, page [API keys](https://cloud.maptiler.com/account/keys/) and click **New key**. > [!WARNING] > If your key gets misused, **replace it with a new key and delete the old one**. # Authentication Service Token Source: https://docs.maptiler.com/cloud/api/authentication-token/ * All API requests must be [authenticated](/cloud/api/authentication/) using an **API key** or **signature** made with service token. * All Service API requests must be submitted with the "Authorization" header containing the service token. Usage of the **Service token** is the most secure way, while ensuring correct HTTPS transmission. ## When to use a service token with public APIs Service tokens are ideal for use in desktop, server, or mobile applications. They add a digital signature to each request, so it's impossible to steal the credentials during transmission. The secret token provided as part of your credentials is much more secure and prevents misuse. It is designed for internal use in companies to manage MapTiler account. If you want to add new tilesets, update them, change their metadata, or delete them, read [Managing maps using the Service API](/guides/maps-apis/maps-platform/managing-maps-using-the-admin-api). > [!CAUTION] > **Do not** use this type of authorization in environments where the source code of your application is visible to the potential attacker (such as client-side web applications). Keep this token private – treat it the same way as you would a password. If your source code is visible, always use [API key](/cloud/api/authentication-key/) instead. ## Get your service token To create a service token, go to your MapTiler account, page [Credentials](https://cloud.maptiler.com/account/credentials/). Create **New Credential** and copy the token. The token will look like this (but you need yours): ```cd43c591d8404400a11e2fre48afedc9_f80f4be2adf86dfb6bc489229669877d6cfcad293f48ffe6e77898f25ab65607``` To learn how to use the token, go to: - [How to securely sign requests to public API](/guides/maps-apis/maps-platform/how-to-use-credentials-to-securely-sign-requests-to-maptiler-cloud-api). - [How to use the Service API and upload maps](/guides/maps-apis/maps-platform/managing-maps-using-the-admin-api/). # MapTiler SDK JS Source: https://docs.maptiler.com/sdk-js/ MapTiler SDK JS is your complete toolkit for building web maps. At its core, it bundles everything needed to render interactive maps in the browser. On top of that, it provides features to make integration of MapTiler [maps](https://www.maptiler.com/maps/) and [API services](/cloud/api/) as easy as possible. It's also open-source so you can check how it handles your data under the hood. #### Designed for frontend devs This SDK was built for JavaScript developers who work on map-based web applications. Focus on your app while the SDK handles all the heavy lifting! *If you only need a specific [location service](/guides/location-services/) without a map, using our [APIs](/cloud/api/) directly or via [JS client](/api-clients/) might be a lighter fit.* #### In-built maps MapTiler SDK JS comes with built-in [map styles](https://www.maptiler.com/maps/) to pick from, showing detailed street-level information, 3D terrain, and satellite imagery for the entire world. Each map can be displayed in either [flat (Mercator) or globe projection](#projection). #### Rich data visualization Your data can be displayed in many ways, from simple maps with markers to dynamic heatmaps and filtered visualizations of millions of features, all using WebGL technology in a browser. There's [hundreds of code examples](/sdk-js/examples) for inspiration. #### Modules for added functions The SDK has many modules with pre-built functions, so it's possible to quickly implement search and other geocoding features, show 3D models in the maps, build weather applications, and much more. Check out [all modules](/sdk-js/modules/). #### Favorable usage tracking MapTiler SDK JS by default uses the session-based model of tracking map usage. To learn more about what this means, how it affects your map traffic billing, and how to change the model if desired, go to Map usage: Sessions vs requests. #### Open source at heart The core of MapTiler SDK JS is MapLibre GL JS, an open-source web map library based on WebGL. Our SDK extends MapLibre GL JS with functions related to the MapTiler mapping platform. MapTiler SDK JS itself has [public source code](https://github.com/maptiler/maptiler-sdk-js) and is BSD-licensed.

Examples

Browse code examples

Go to examples

Modules

Get ready-to-use functions

Go to modules

Reference

Read full SDK JS reference

Go to reference
## Get started To integrate a map using MapTiler SDK JS, simply use the code below the map. For a more detailed tutorial on how to initialize a map and load the style, see [Learn the basics – How to use the MapTiler SDK JS](./examples/how-to-use/). ## Map projection The **Web Mercator projection** has been the go-to standard in cartography since the early days of web mapping. It is great for navigation and shows the entire world in one screen, with no hidden face. However, Mercator's heavy distortion at high latitudes and discontinuity at the poles can be a limitation for data visualization. There's been also criticism of providing a biased view of the world. Learn more about Mercator projection on [*Wikipedia*](https://en.wikipedia.org/wiki/Web_Mercator_projection). The **globe projection**, available from MapTiler SDK v3, does not suffer from these biases and can feel overall more playfull than Mercator. It's a great choice for semi-global data visualization, especially for data close to the poles, thanks to its geographic continuity. To learn how to set the projection in your map using SDK JS, see the related [projection examples](/sdk-js/examples/?q=projection). | Mercator projection | Globe projection | | :--------: | :-------: | | ![](/sdk-js/assets/mercator_projection.jpeg) | ![](/sdk-js/assets/globe_projection.jpeg) | # MapTiler SDK Examples Source: https://docs.maptiler.com/sdk-js/examples/ _No overview content available._ # SDK JS Reference Source: https://docs.maptiler.com/sdk-js/api/ This reference documents every object and method available in the **MapTiler SDK JS**. The SDK uses WebGL in the browser to take advantage of hardware graphics acceleration provided by the user's device. ## Objects and methods Each section describes classes or objects as well as their **properties, parameters, methods**, and associated **events**. Many sections also include inline code examples and related resources.

## About MapTiler SDK The SDK allows create interactive maps from vector tiles data (in PBF format) and raster tiles data. Take a look at [What are vector tiles and why you should care?](https://www.maptiler.com/news/2019/02/what-are-vector-tiles-and-why-you-should-care/) It provides all the functions and data required to fuel a complete web mapping experience: vector tiles, satellite raster tiles, DEM with Terrain RGB, etc. Allows you to tailor the visual appearance of a map: what data to draw, the order to draw it, and how to lay out the data when drawing following the [GL style specification](/gl-style-specification/). Under the hood, this SDK is opinionated as it's being fed by MapTiler services, but its MapLibre GL JS[^1] (``) core makes it 100% compatible with other sources. The MapTiler mapping platform provides a number of built-in [Map Styles](./map-styles), that are integrated into the SDK. These styles use data from the [MapTiler tileset](/schema/). There is no need to load external plugins for the most basic things like adding common map controls or enabling 3D terrain every time you start a project. All this is built-in, loaded when needed, or exposed with simple functions. ![GitHubLogo](/assets/img/github.svg)[View complete source code on GitHub](https://github.com/maptiler/maptiler-sdk-js) [^1]: MapLibre GL JS is a open-source web map library based on WebGL. # Map Source: https://docs.maptiler.com/sdk-js/api/map/ Map src/Map.ts The Map object represents the map on your page. It exposes methods and properties that enable you to programmatically change the map, and fires events as users interact with it. You create a Map by specifying a container and other options. Then SDK JS initializes the map on the page and returns your Map object. Extends Evented . Example Parameters options (MapOptions) Options to provide to the Map constructor ( MapOptions ) Properties options.apiKey string ? Define the MapTiler API key to be used. This is equivalent to setting config.apiKey and will overwrite it. options.container ( HTMLElement | string ) The HTML element in which SDK JS will render the map, or the element's string id . The specified element must have no children. options.style ( ReferenceMapStyle | MapStyleVariant | string | StyleSpecification )? The map's style. This must be: ReferenceMapStyle (e.g. MapStyle.STREETS) MapStyleVariant (e.g. MapStyle.STREETS.DARK) MapTIler Style ID (e.g. “”) uuid of custom style an a JSON object conforming to the schema described in the GL Style Specification a URL to such JSON. options.language ( string | Language )? Define the language of the map. This can be done directly with a language ISO code (eg. "en") or with a built-in Languages shorthand (eg. Language.ENGLISH) This applies only for the map instance, supersedes the config.primaryLanguage . options.center LngLatLike ? default: [0,0] The initial geographical centerpoint of the map. If center is not specified in the constructor options, SDKJS will look for it in the map's style object. If it is not specified in the style, either, it will default to [0, 0] Note: SDK JS uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON. options.zoom number ? default: 0 The initial zoom level of the map. If zoom is not specified in the constructor options, SDK JS will look for it in the map's style object. If it is not specified in the style, either, it will default to 0 . options.projection string ? default: 'mercator' This will overwrite the projection property from the style (if any) and will persist it later if the map style was to change. Valid options are mercator , globe . options.bearing number ? default: 0 The initial bearing (rotation) of the map, measured in degrees counter-clockwise from north. If bearing is not specified in the constructor options, SDK JS will look for it in the map's style object. If it is not specified in the style, either, it will default to 0 . options.pitch number ? default: 0 The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-85). If pitch is not specified in the constructor options, SDK JS will look for it in the map's style object. If it is not specified in the style, either, it will default to 0 . Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the MapLibre project. options.attributionControl boolean ? default: true If true , an AttributionControl will be added to the map. options.bearingSnap number ? default: 7 The threshold, measured in degrees, that determines when the map's bearing will snap to north. For example, with a bearingSnap of 7, if the user rotates the map within 7 degrees of north, the map will automatically snap to exact north. options.bounds LngLatBoundsLike ? The initial bounds of the map. If bounds is specified, it overrides center and zoom constructor options. options.boxZoom boolean ? default: true If true , the "box zoom" interaction is enabled (see BoxZoomHandler ). options.cancelPendingTileRequestsWhileZooming boolean ? default: true Determines whether to cancel, or retain, tiles from the current viewport which are still loading but which belong to a farther (smaller) zoom level than the current one. If true , when zooming in, tiles which didn't manage to load for previous zoom levels will become canceled. This might save some computing resources for slower devices, but the map details might appear more abruptly at the end of the zoom. If false , when zooming in, the previous zoom level(s) tiles will progressively appear, giving a smoother map details experience. However, more tiles will be rendered in a short period of time. options.canvasContextAttributes WebGLContextAttributesWithType ? default: antialias: false, powerPreference: 'high-performance', preserveDrawingBuffer: false, failIfMajorPerformanceCaveat: false, desynchronized: false, contextType: 'webgl2withfallback' Set of WebGLContextAttributes that are applied to the WebGL context of the map. See getContext for more details. contextType , can be set to webgl2 or webgl to force a WebGL version. Not setting it, MapTiler SDK will do it's best to get a suitable context. options.centerClampedToGround boolean ? default: true If true , the elevation of the center point will automatically be set to the terrain elevation (or zero if terrain is not enabled). If false , the elevation of the center point will default to sea level and will not automatically update. Needs to be set to false to keep the camera above ground when pitch > 90 degrees. options.clickTolerance number ? default: 3 The max number of pixels a user can shift the mouse pointer during a click for it to be considered a valid click (as opposed to a mouse drag). options.collectResourceTiming boolean ? default: false If true , Resource Timing API information will be collected for requests made by GeoJSON and Vector Tile web workers (this information is normally inaccessible from the main Javascript thread). Information will be returned in a resourceTiming property of relevant data events. options.cooperativeGestures ( boolean | GestureOptions)? default: false If true or set to an options object, map is only accessible on desktop while holding Command/Ctrl and only accessible on mobile with two fingers. Interacting with the map using normal gestures will trigger an informational screen. With this option enabled, "drag to pitch" requires a three-finger gesture. Cooperative gestures are disabled when a map enters fullscreen using FullscreenControl . A valid options object includes the following properties to customize the text on the informational screen. The values below are the defaults. { windowsHelpText: "Use Ctrl + scroll to zoom the map", macHelpText: "Use ⌘ + scroll to zoom the map", mobileHelpText: "Use two fingers to move the map", } options.crossSourceCollisions boolean ? default: true If true , symbols from multiple sources can collide with each other during collision detection. If false , collision detection is run separately for the symbols in each source. options.customControls ( boolean | string )? default: false Detect custom external controls. Alternatively, customControls can be set to a CSS selector string , restricting autodetection to: Elements matching the selector directly Or elements whose ancestor matches the selector const map = new maptilersdk.Map({ container: "map", customControls: true, // or ".custom-ui" }); options.doubleClickZoom boolean ? default: true If true , the "double click to zoom" interaction is enabled (see DoubleClickZoomHandler ). options.dragPan ( boolean | Object )? default: true If true , the "drag to pan" interaction is enabled. An Object value is passed as options to DragPanHandler#enable . options.dragRotate boolean ? default: true If true , the "drag to rotate" interaction is enabled (see DragRotateHandler ). options.elevation number ? default: 0 The elevation of the initial geographical centerpoint of the map, in meters above sea level. If elevation is not specified in the constructor options, it will default to 0 . options.fadeDuration number ? default: 300 Controls the duration of the fade-in/fade-out animation for label collisions, in milliseconds. This setting affects all symbol layers. This setting does not affect the duration of runtime styling transitions or raster tile cross-fading. options.fitBoundsOptions Object ? A Map#fitBounds options object to use only when fitting the initial bounds provided above. options.fullscreenControl ( boolean | string )? default: false If true , an FullscreenControl will be added to the map. Valid options are top-left , top-right , bottom-left , bottom-right . options.geolocate ( boolean | GeolocationType.POINT | GeolocationType.COUNTRY )? default: false Center map on the visitor's location by using the IP geolocation API . There are two strategies: GeolocationType.POINT : centering the map on the actual visitor location, optionnaly using the zoom option (zoom level 13 if none is provided). As a more precise option, if the user has previously granted access to the browser location (more precise) then this is going to be used. GeolocationType.COUNTRY : fitting the map view on the bounding box of the visitor's country. In this case, the zoom option, if provided, will be ignored The geolocate options will not be taken into consideration in the following cases: if the center options is provided, then it prevails if the hash options is provided with the value true AND a location hash is already part of the URL. If hash is true but there is not yet a location hash in the URL, then the geolocation will work. options.geolocateControl ( boolean | string )? default: true If true , an MaptilerGeolocateControl will be added to the map. Valid options are top-left , top-right , bottom-left , bottom-right . options.halo ( boolean | RadialGradientLayerConstructorOptions )? default: false Adds a gradient-based atmospheric glow around the globe, simulating the visual effect of Earth's atmosphere when viewed from space. You can enable a simple halo by setting it to true . For more customization, check RadialGradientLayerConstructorOptions This option only takes effect when used in conjunction with the projection: 'globe' parameter. options.hash ( boolean | string )? default: false If true , the map's position (zoom, center latitude, center longitude, bearing, and pitch) will be synced with the hash fragment of the page's URL. For example, http://path/to/my/page.html#2.59/39.26/53.07/-24.1/60 . An additional string may optionally be provided to indicate a parameter-styled hash, e.g. http://path/to/my/page.html#map=2.59/39.26/53.07/-24.1/60&foo=bar , where foo is a custom parameter and bar is an arbitrary hash distinct from the map hash. options.interactive boolean ? default: true If false , no mouse, touch, or keyboard listeners will be attached to the map, so it will not respond to interaction. options.keyboard boolean ? default: true If true , keyboard shortcuts are enabled (see KeyboardHandler ). options.locale Object ? default: null A patch to apply to the default localization table for UI strings, e.g. control tooltips. The locale object maps namespaced UI string IDs to translated strings in the target language; see src/ui/default_locale.js for an example with all supported string IDs. The object may specify all UI strings (thereby adding support for a new translation) or only a subset of strings (thereby patching the default translation table). options.localIdeographFontFamily string ? default: 'sans-serif' Defines a CSS font-family for locally overriding generation of glyphs in the 'CJK Unified Ideographs', 'Hiragana', 'Katakana' and 'Hangul Syllables' ranges. In these ranges, font settings from the map's style will be ignored, except for font-weight keywords (light/regular/medium/bold). Set to false , to enable font settings from the map's style for these glyph ranges. The purpose of this option is to avoid bandwidth-intensive glyph server requests. (See Use locally generated ideographs .) options.logoPosition string ? default: 'bottom-left' A string representing the position of the MapTiler wordmark on the map. Valid options are top-left , top-right , bottom-left , bottom-right . options.maptilerLogo boolean ? default: false This setting doesn't apply to free plans. On paid plans, the logo is hidden by default. To show it, add this option and set it to true . options.maxBounds LngLatBoundsLike ? If set, the map will be constrained to the given bounds. options.maxCanvasSize [ number , number ]? default: [4096, 4096] The canvas' width and height max size. The values are passed as an array where the first element is max width and the second element is max height. You shouldn't set this above WebGl MAX_TEXTURE_SIZE options.maxPitch number ? default: 60 The maximum pitch of the map (0-180). options.maxTileCacheSize number ? default: null The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport. options.maxTileCacheZoomLevels number default: 5 The maximum number of zoom levels for which to store tiles for a given source. Tile cache dynamic size is calculated by multiplying maxTileCacheZoomLevels with the approximate number of tiles in the viewport for a given source. options.maxZoom number ? default: 22 The maximum zoom level of the map (0-24). options.minimap ( boolean | string | MinimapOptionsInput )? default: false If true , an MaptilerMinimapControl will be added to the map. Valid options are top-left , top-right , bottom-left , bottom-right . or MinimapOptionsInput options.minPitch number ? default: 0 The minimum pitch of the map (0-85). Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the MapLibre project. options.minZoom number ? default: 0 The minimum zoom level of the map (0-24). options.navigationControl ( boolean | string )? default: true If true , an MaptilerNavigationControl will be added to the map. Valid options are top-left , top-right , bottom-left , bottom-right . options.pitchWithRotate boolean ? default: true If false , the map's pitch (tilt) control with "drag to rotate" interaction will be disabled. options.pixelRatio number ? The pixel ratio. The canvas' width attribute will be container.clientWidth * pixelRatio and its height attribute will be container.clientHeight * pixelRatio . Defaults to devicePixelRatio if not specified. options.projectionControl ( boolean | string )? default: false If true , an MaptilerProjectionControl will be added to the map. Valid options are top-left , top-right , bottom-left , bottom-right . options.refreshExpiredTiles boolean ? default: true If false , the map won't attempt to re-request tiles once they expire per their HTTP cacheControl / expires headers. options.renderWorldCopies boolean ? default: true If true , multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to false : When the map is zoomed out far enough that a single representation of the world does not fill the map's entire container, there will be blank space beyond 180 and -180 degrees longitude. Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the map and the other on the left edge of the map) at every zoom level. options.roll number ? default: 0 The initial roll angle of the map, measured in degrees counter-clockwise about the camera boresight. If roll is not specified in the constructor options, MapTiler SDK will look for it in the map's style object. If it is not specified in the style, either, it will default to 0 . options.rollEnabled boolean ? default: false If false , the map's roll control with "drag to rotate" interaction will be disabled. options.scaleControl ( boolean | string )? default: false If true , an ScaleControl will be added to the map. Valid options are top-left , top-right , bottom-left , bottom-right . options.scrollZoom ( boolean | Object )? default: true If true , the "scroll to zoom" interaction is enabled. An Object value is passed as options to ScrollZoomHandler#enable . options.space ( boolean | CubemapLayerConstructorOptions )? default: false The space option allows customizing the background environment of the globe, simulating deep space or skybox effects. You can enable a start space background by setting it to true . For more customization, check CubemapLayerConstructorOptions This option only takes effect when used in conjunction with the projection: 'globe' parameter. options.terrain boolean ? default: false If true , the map's loads a 3D terrain, based on a MapTiler "raster-dem" source . options.terrainControl ( boolean | string )? default: false If true , an MaptilerTerrainControl will be added to the map. Valid options are top-left , top-right , bottom-left , bottom-right . options.terrainExaggeration number ? default: 1 3D terrain exaggeration factor. options.touchPitch ( boolean | Object )? default: true If true , the "drag to pitch" interaction is enabled. An Object value is passed as options to TouchPitchHandler#enable . options.touchZoomRotate ( boolean | Object )? default: true If true , the "pinch to rotate and zoom" interaction is enabled. An Object value is passed as options to TouchZoomRotateHandler#enable . options.trackResize boolean ? default: true If true , the map will automatically resize when the browser window resizes. options.transformCameraUpdate CameraUpdateTransformFunction ? default: null A callback run before the map's camera is moved due to user input or animation. The callback can be used to modify the new center, zoom, pitch and bearing. Expected to return an object containing center, zoom, pitch or bearing values to overwrite. options.transformRequest RequestTransformFunction ? default: null A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests. Expected to return an object with a url property and optionally headers and credentials properties. Example options.validateStyle boolean ? default: true If false , style validation will be skipped. Useful in production environment. Methods addControl (control, position?) Adds an IControl to the map, calling control.onAdd(this) . Parameters control ( IControl ) : The IControl to add. position ( string ? ) : position on the map to which the control will be added. Valid values are 'top-left' , 'top-right' , 'bottom-left' , and 'bottom-right' . Defaults to 'top-right' . Returns Map : this Example Related examples Display map navigation controls addImage (id, image, options) Add an image to the style. This image can be displayed on the map like any other icon in the style's sprite using the image's ID with icon-image , background-pattern , fill-pattern , or line-pattern . A Map.event:error event will be fired if there is not enough space in the sprite to add this image. Parameters id ( string ) : The ID of the image. image ( ( HTMLImageElement | ImageBitmap | ImageData | {width: number , height: number , data: ( Uint8Array | Uint8ClampedArray )} | StyleImageInterface ) ) : The image as an HTMLImageElement , ImageData , ImageBitmap or object with width , height , and data properties with the same format as ImageData . options ( Partial<StyleImageMetadata> ) : Options object. Defaults to {} options.pixelRatio any? default: 1 The ratio of pixels in the image to physical pixels on the screen options.sdf any? default: false Whether the image should be interpreted as an SDF image options.stretchX any? [[x1, x2], ...] If icon-text-fit is used in a layer with this image, this option defines the part(s) of the image that can be stretched horizontally. options.stretchY any? [[y1, y2], ...] If icon-text-fit is used in a layer with this image, this option defines the part(s) of the image that can be stretched vertically. options.content any? [x1, y1, x2, y2] If icon-text-fit is used in a layer with this image, this option defines the part of the image that can be covered by the content in text-field . Example Related examples Use HTMLImageElement : Add an icon to the map Use ImageData : Add a generated icon to the map addLayer (layer, beforeId?) Adds a GL style layer to the map's style. A layer defines how data from a specified source will be styled. Read more about layer types and available paint and layout properties in the GL Style Specification . Parameters layer ( Object ) : conforming to either the GL Style Specification's layer definition or, less commonly, the CustomLayerInterface specification. The GL Style Specification's layer definition is appropriate for most layers. layer.id string A unique identifer that you define. layer.type string The type of layer (for example fill or symbol ). A list of layer types is available in the GL Style Specification . (This can also be custom . For more information, see CustomLayerInterface .) layer.source ( string | SourceSpecification)? The data source for the layer. Reference a source that has already been defined using the source's unique id. Reference a new source using a source object (as defined in the GL Style Specification ) directly. This is required for all layer.type options except for custom and background . layer.sourceLayer string ? (optional) The name of the source layer within the specified layer.source to use for this style layer. This is only applicable for vector tile sources and is required when layer.source is of the type vector . layer.filter array ? (optional) An expression specifying conditions on source features. Only features that match the filter are displayed. The GL Style Specification includes more information on the limitations of the filter parameter and a complete list of available expressions . If no filter is provided, all features in the source (or source layer for vector tilesets) will be displayed. layer.paint Object ? (optional) Paint properties for the layer. Available paint properties vary by layer.type . A full list of paint properties for each layer type is available in the GL Style Specification . If no paint properties are specified, default values will be used. layer.layout Object ? (optional) Layout properties for the layer. Available layout properties vary by layer.type . A full list of layout properties for each layer type is available in the GL Style Specification . If no layout properties are specified, default values will be used. layer.maxzoom number ? (optional) The maximum zoom level for the layer. At zoom levels equal to or greater than the maxzoom, the layer will be hidden. The value can be any number between 0 and 24 (inclusive). If no maxzoom is provided, the layer will be visible at all zoom levels for which there are tiles available. layer.minzoom number ? (optional) The minimum zoom level for the layer. At zoom levels less than the minzoom, the layer will be hidden. The value can be any number between 0 and 24 (inclusive). If no minzoom is provided, the layer will be visible at all zoom levels for which there are tiles available. layer.metadata Object ? (optional) Arbitrary properties useful to track with the layer, but do not influence rendering. layer.renderingMode string ? This is only applicable for layers with the type custom . See CustomLayerInterface for more information. beforeId ( string ? ) : The ID of an existing layer to insert the new layer before, resulting in the new layer appearing visually beneath the existing layer. If this argument is not specified, the layer will be appended to the end of the layers array and appear visually above all other layers. Returns Map : this Example Related examples Create and style clusters Add a vector tile source Add a WMS source addSource (id, source) Adds a source to the map's style. Parameters id ( string ) : The ID of the source to add. Must not conflict with existing sources. source ( Object ) : The source object, conforming to the GL Style Specification's source definition or CanvasSourceOptions . Returns Map : this Example Related examples GeoJSON source: Add live realtime data addSprite (id, url, options?) Adds a sprite to the map's style. Fires the style event. Parameters id ( string ) : The ID of the sprite to add. Must not conflict with existing sprites. url ( string ) : The URL to load the sprite from. options ( StyleSetterOptions ) : Options object. Returns Map : this Example areTilesLoaded () Returns a Boolean indicating whether all tiles in the viewport from all sources on the style are loaded. Returns boolean : A Boolean indicating whether all tiles are loaded. Example boxZoom The map's BoxZoomHandler , which implements zooming using a drag gesture with the Shift key pressed. Find more details and examples using boxZoom in the BoxZoomHandler section. calculateCameraOptionsFromCameraLngLatAltRotation (cameraLngLat, cameraAlt, bearing, pitch, roll) Given a camera position and rotation, calculates zoom and center point and returns them as as Cameraoptions. Parameters cameraLngLat ( LngLatLike ) : The lng, lat of the camera to look from cameraAlt ( number ) : The altitude of the camera to look from, in meters above sea level bearing ( number ) : Bearing of the camera, in degrees pitch ( number ) : Pitch of the camera, in degrees roll ( number ? ) : Roll of the camera, in degrees Returns CameraOptions : the calculated camera options calculateCameraOptionsFromTo (from, altitudeFrom, to, altitudeTo) Calculates pitch, zoom and bearing for looking at @param newCenter with the camera position being @param newCenter and returns them as Cameraoptions. Parameters from ( LngLat ) : The camera to look from altitudeFrom ( number ) : The altitude of the camera to look from to ( LngLat ) : The center to look at altitudeTo ( number ) : Optional altitude of the center to look at. If none given the ground height will be used. Defaults to 0 Returns CameraOptions : the calculated camera options cameraForBounds (bounds, options?) Parameters bounds ( LngLatBoundsLike ) Calculate the center for these bounds in the viewport and use the highest zoom level up to and including Map#getMaxZoom() that fits in the viewport. LngLatBounds represent a box that is always axis-aligned with bearing 0. options ( CameraForBoundsOptions? ) Options object options.padding ( number | PaddingOptions )? The amount of padding in pixels to add to the given bounds. options.bearing number default: 0 Desired map bearing at end of animation, in degrees. options.offset PointLike default: [0,0] The center of the given bounds relative to the map's center, measured in pixels. options.maxZoom number ? The maximum zoom level to allow when the camera would transition to the specified bounds. Returns CenterZoomBearing : If map is able to fit to provided bounds, returns center , zoom , and bearing . If map is unable to fit, method will warn and return undefined. Example centerOnIpPoint (zoom) Centering the map on the actual visitor location. Used when geolocate is to POINT but could be triggered manually. As a more precise option, if the user has previously granted access to the browser location (more precise) then this is going to be used. Parameters zoom ( number ) The zoom level to set. Returns Promise : void Example cooperativeGestures The map's CooperativeGesturesHandler , which allows the user to see cooperative gesture info when user tries to zoom in/out. Find more details and examples using cooperativeGestures in the CooperativeGesturesHandler section. disableTerrain () Disable the 3D terrain visualization. Example disableHaloAnimations () Disable transitions between halo states, making it change instantly. Example disableSpaceAnimations () Disable transitions between space colors and backgrounds, making them change instantly (or as soon as the images have loaded) Example doubleClickZoom The map's DoubleClickZoomHandler , which allows the user to zoom by double clicking. Find more details and examples using doubleClickZoom in the DoubleClickZoomHandler section. dragPan The map's DragPanHandler , which implements dragging the map with a mouse or touch gesture. Find more details and examples using dragPan in the DragPanHandler section. dragRotate The map's DragRotateHandler , which implements rotating the map while dragging with the right mouse button or with the Control key pressed. Find more details and examples using dragRotate in the DragRotateHandler section. easeTo (options, eventData?) Changes any combination of center , zoom , bearing , pitch , and padding with an animated transition between old and new values. The map will retain its current values for any details not specified in options . Note: The transition will happen instantly if the user has enabled the reduced motion accesibility feature enabled in their operating system, unless options includes essential: true . Parameters options ( any ) Options describing the destination and animation of the transition. Accepts CameraOptions and AnimationOptions . eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Related examples Navigate the map with game-like controls enableHaloAnimations () Enable transitions between halo states, making it transition between states (on by default). Example enableSpaceAnimations () Enable transitions between space colors and backgrounds, making them transition between colours and images. Example enableTerrain (exaggeration?) Enables the 3D terrain visualization. Parameters exaggeration ( number? ) Enables the 3D terrain visualization and sets the terrain exaggeration factor Example fitBounds (bounds, options?, eventData?) Pans and zooms the map to contain its visible area within the specified geographical bounds. This function will also reset the map's bearing to 0 if bearing is nonzero. Parameters bounds ( LngLatBoundsLike ) Center these bounds in the viewport and use the highest zoom level up to and including Map#getMaxZoom() that fits them in the viewport. options ( FitBoundsOptions? ) Options supports all properties from AnimationOptions and CameraOptions in addition to the fields below. options.padding ( number | PaddingOptions )? The amount of padding in pixels to add to the given bounds. options.linear boolean default: false If true , the map transitions using Map#easeTo . If false , the map transitions using Map#flyTo . See those functions and AnimationOptions for information about options available. options.easing Function ? An easing function for the animated transition. See AnimationOptions . options.offset PointLike default: [0,0] The center of the given bounds relative to the map's center, measured in pixels. options.maxZoom number ? The maximum zoom level to allow when the map view transitions to the specified bounds. eventData ( Object ? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example Related examples Fit a map to a bounding box fitScreenCoordinates (p0, p1, bearing, options?, eventData?) Pans, rotates and zooms the map to to fit the box made by points p0 and p1 once the map is rotated to the specified bearing. To zoom without rotating, pass in the current map bearing. Parameters p0 ( PointLike ) First point on screen, in pixel coordinates p1 ( PointLike ) Second point on screen, in pixel coordinates bearing ( number ) Desired map bearing at end of animation, in degrees options ( FitBoundsOptions? ) Options object options.padding ( number | PaddingOptions )? The amount of padding in pixels to add to the given bounds. options.linear boolean default: false If true , the map transitions using Map#easeTo . If false , the map transitions using Map#flyTo . See those functions and AnimationOptions for information about options available. options.easing Function ? An easing function for the animated transition. See AnimationOptions . options.offset PointLike default: [0,0] The center of the given bounds relative to the map's center, measured in pixels. options.maxZoom number ? The maximum zoom level to allow when the map view transitions to the specified bounds. eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example Related examples Used by BoxZoomHandler fitToIpBounds () Fit the map view on the bounding box of the visitor's country. Used when geolocate is to COUNTRY but could be triggered manually. Returns Promise : void Example flyTo (options, eventData?) Changes any combination of center, zoom, bearing, and pitch, animating the transition along a curve that evokes flight. The animation seamlessly incorporates zooming and panning to help the user maintain her bearings even after traversing a great distance. Note: The animation will be skipped, and this will behave equivalently to jumpTo if the user has the reduced motion accesibility feature enabled in their operating system, unless 'options' includes essential: true . Parameters options ( FlyToOptions ) Options describing the destination and animation of the transition. Accepts CameraOptions , AnimationOptions , and the following additional options. options.curve number default: 1.42 The zooming "curve" that will occur along the flight path. A high value maximizes zooming for an exaggerated animation, while a low value minimizes zooming for an effect closer to Map#easeTo . 1.42 is the average value selected by participants in the user study discussed in van Wijk (2003) . A value of Math.pow(6, 0.25) would be equivalent to the root mean squared average velocity. A value of 1 would produce a circular motion. options.minZoom number ? The zero-based zoom level at the peak of the flight path. If options.curve is specified, this option is ignored. options.speed number default: 1.2 The average speed of the animation defined in relation to options.curve . A speed of 1.2 means that the map appears to move along the flight path by 1.2 times options.curve screenfuls every second. A screenful is the map's visible span. It does not correspond to a fixed physical distance, but varies by zoom level. options.screenSpeed number ? The average speed of the animation measured in screenfuls per second, assuming a linear timing curve. If options.speed is specified, this option is ignored. options.maxDuration number ? The animation's maximum duration, measured in milliseconds. If duration exceeds maximum duration, it resets to 0. eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example Related examples Fly to a location Slowly fly to a location Fly to a location based on scroll position getBearing () Returns the map's current bearing. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up. Returns number : The map's current bearing. Related examples Navigate the map with game-like controls getBounds () Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region. Returns LngLatBounds : The geographical bounds of the map as LngLatBounds . Example getCameraHash () Compute a base64 string hash that is unique for camera settings (to check if a user a moved in the process of geolocation) Returns string : The camera hash base64 string. Example getCameraTargetElevation () Returns the elevation for the point where the camera is looking. This value corresponds to: "meters above sea level" * "exaggeration" Returns number : The elevation. Example getCanvas () Returns the map's <canvas> element. Returns HTMLCanvasElement : The map's <canvas> element. Related examples Measure distances Display a popup on hover Center the map on a clicked symbol getCanvasContainer () Returns the HTML element containing the map's <canvas> element. If you want to add non-GL overlays to the map, you should append them to this element. This is the element to which event bindings for map interactivity (such as panning and zooming) are attached. It will receive bubbled events from child elements such as the <canvas> , but not from map controls. Returns HTMLElement : The container of the map's <canvas> . Related examples Create a draggable point getCenter () Returns the map's geographical centerpoint. Returns LngLat : The map's geographical centerpoint. Example getCenterClampedToGround () Returns the value of centerClampedToGround . If true, the elevation of the center point will automatically be set to the terrain elevation (or zero if terrain is not enabled). If false, the elevation of the center point will default to sea level and will not automatically update. Defaults to true. Needs to be set to false to keep the camera above ground when pitch > 90 degrees. Returns boolean getCenterElevation () Returns the elevation of the map's center point. Returns number : The elevation of the map's center point, in meters above sea level. getContainer () Returns the map's containing HTML element. Returns HTMLElement : The map's container. getFeatureState (feature) Gets the state of a feature. A feature's state is a set of user-defined key-value pairs that are assigned to a feature at runtime. Features are identified by their feature.id attribute, which can be any number or string. Note: To access the values in a feature's state object for the purposes of styling the feature, use the feature-state expression . Parameters feature ( Object ) Feature identifier. Feature objects returned from Map#queryRenderedFeatures or event handlers can be used as feature identifiers. feature.id ( string | number ) Unique id of the feature. feature.source string The id of the vector or GeoJSON source for the feature. feature.sourceLayer string ? (optional) For vector tile sources, sourceLayer is required. Returns Object : The state of the feature: a set of key-value pairs that was assigned to the feature at runtime. Example getFilter (layerId) Returns the filter applied to the specified style layer. Parameters layerId ( string ) The ID of the style layer whose filter to get. Returns Array : The layer's filter. getGlobalState () Returns the global map state. Returns Record<string, any> : The map state object. getGlyphs (layerId) Returns the filter applied to the specified style layer. Returns string : The glyphs Style's glyphs url. getHalo () Returns the map's halo (atmospheric glow) of the globe. Returns ( RadialGradientLayer | undefined ) : Halo (atmospheric glow) of the globe or undefined if the halo was not set in the map. Example getImage (id) Returns an image, specified by ID, currently available in the map. This includes both images from the style's original sprite and any images that have been added at runtime using addImage. Parameters id ( string ) The The ID of the image. Returns StyleImage : An image in the map with the specified ID. Example getLayer (id) Returns the layer with the specified ID in the map's style. Parameters id ( string ) The ID of the layer to get. Returns StyleLayer : The layer with the specified ID, or undefined if the ID corresponds to no existing layers. Example Related examples Filter symbols by toggling a list Filter symbols by text input getLayersOrder () Return the ids of all layers currently in the style, including custom layers, in order. Returns string[] : ids of layers, in order. Example getLayoutProperty (layerId, name) Returns the value of a layout property in the specified style layer. Parameters layerId ( string ) The ID of the layer to get the layout property from. name ( string ) The name of the layout property to get. Returns any : The value of the specified layout property. getLight () Returns the value of the light object. Returns Object : light Light properties of the style. getMaptilerSessionId () Get the MapTiler session ID. Convenient to dispatch to externaly built component that do not directly have access to the SDK configuration but do have access to a Map instance. Returns string : the MapTiler session ID Example getMaxBounds () Returns the maximum geographical bounds the map is constrained to, or null if none set. Returns ( LngLatBounds | null) : The map object. Example getMaxPitch () Returns the map's maximum allowable pitch. Returns number : maxPitch getMaxZoom () Returns the map's maximum allowable zoom level. Returns number : maxZoom Example getMinPitch () Returns the map's minimum allowable pitch. Returns number : minPitch getMinZoom () Returns the map's minimum allowable zoom level. Returns number : minZoom Example getPadding () Returns the current padding applied around the map viewport. Returns PaddingOptions : The current padding around the map viewport. getPaintProperty (layerId, name) Returns the value of a paint property in the specified style layer. Parameters layerId ( string ) The ID of the layer to get the paint property from. name ( string ) The name of a paint property to get. Returns any : The value of the specified paint property. getPitch () Returns the map's current pitch (tilt). Returns number : The map's current pitch, measured in degrees away from the plane of the screen. getPixelRatio () Returns the map's pixel ratio. Returns number : The pixel ratio. getProjection () Gets the ProjectionSpecification Returns ProjectionSpecification : the projection specification. Example getRenderWorldCopies () Returns the state of renderWorldCopies . If true , multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to false : When the map is zoomed out far enough that a single representation of the world does not fill the map's entire container, there will be blank space beyond 180 and -180 degrees longitude. Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the map and the other on the left edge of the map) at every zoom level. Returns boolean : renderWorldCopies Example Related examples Render world copies getRoll () Returns the map's current roll angle. Returns number : The map's current roll, measured in degrees about the camera boresight. Example getSdkConfig () Get the SDK config object. This is convenient to dispatch the SDK configuration to externally built layers that do not directly have access to the SDK configuration but do have access to a Map instance. Returns config : the SDK config object Example getSky () Returns the value of the style's sky. Returns SkySpecification : the sky properties of the style. Example getSource (id) Returns the source with the specified ID in the map's style. This method is often used to update a source using the instance members for the relevant source type as defined in Sources . For example, setting the data for a GeoJSON source or updating the url and coordinates of an image source. Parameters id ( string ) The ID of the source to get. Returns (Source | undefined ) : The style source with the specified ID or undefined if the ID corresponds to no existing sources. The shape of the object varies by source type. A list of options for each source type is available on the GL Style Specification's Sources page. Example Related examples Create a draggable point Animate a point Add live realtime data getSpace () Returns the map's space (background environment) of the globe. Returns ( CubemapLayer | undefined ) : Space (background environment) of the globe or undefined if the space was not set in the map. Example getSprite () Returns the map's GL style object, a JSON object which can be used to recreate the map's style. Returns Array : Style's sprite list of id-url pairs. Example getStyle () Returns the map's GL style object, a JSON object which can be used to recreate the map's style. Returns Object : The map's style JSON object. Example getTerrain () Get the terrain-options if terrain is loaded Returns TerrainSpecification : the TerrainSpecification passed to setTerrain Example getTerrainExaggeration () Get the terrain exaggeration factor if terrain is loaded Returns number : the terrain exaggeration factor Example getVerticalFieldOfView () Returns the map's current vertical field of view, in degrees. Returns number : The map's current vertical field of view. Default Value: 36.87 Example getZoom () Returns the map's current zoom level. Returns number : The map's current zoom level. Example hasControl (control) Checks if a control exists on the map. Parameters control ( IControl ) The IControl to check. Returns boolean : True if map contains control. Example hasImage (id) Check whether or not an image with a specific ID exists in the style. This checks both images in the style's original sprite and any images that have been added at runtime using Map#addImage . Parameters id ( string ) The ID of the image. Returns boolean : A Boolean indicating whether the image exists. Example hasTerrain () Check whether or not the terrian is enabled. Returns boolean : A Boolean indicating whether the terrain exists. Example isGlobeProjection () Returns whether a globe projection is currently being used. Returns boolean : True if the map projection is globe. Example isLanguageUpdated () Returns true is the language was ever updated, meaning changed from what is delivered in the style. Returns false if language in use is the language from the style and has never been changed. Returns boolean : True is the language was ever updated. Example isMoving () Returns true if the map is panning, zooming, rotating, or pitching due to a camera animation or user gesture. Returns boolean : True if the map is moving. Example isRotating () Returns true if the map is rotating due to a camera animation or user gesture. Returns boolean : True if the map is rotating. Example isSourceLoaded (id) Returns a Boolean indicating whether the source is loaded. Returns true if the source with the given ID in the map's style has no outstanding network requests, otherwise false . Parameters id ( string ) The ID of the source to be checked. Returns boolean : A Boolean indicating whether the source is loaded. Example isStyleLoaded () Returns a Boolean indicating whether the map's style is fully loaded. Returns boolean : A Boolean indicating whether the style is fully loaded. Example isZooming () Returns true if the map is zooming due to a camera animation or user gesture. Returns boolean : True if the map is zooming. Example jumpTo (options, eventData?) Changes any combination of center, zoom, bearing, and pitch, without an animated transition. The map will retain its current values for any details not specified in options . Parameters options ( JumpToOptions ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example Related examples Jump to a series of locations Update a feature in realtime keyboard The map's KeyboardHandler , which allows the user to zoom, rotate, and pan the map using keyboard shortcuts. Find more details and examples using keyboard in the KeyboardHandler section. listens (type) Returns a true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type. Parameters type ( string ) The The event type. Returns boolean : true if there is at least one registered listener for specified event type, false otherwise listImages () Returns an Array of strings containing the IDs of all images currently available in the map. This includes both images from the style's original sprite and any images that have been added at runtime using Map#addImage . Returns Array < string > : An Array of strings containing the names of all sprites/images currently available in the map. Example loaded () Returns a Boolean indicating whether the map is fully loaded. Returns false if the style is not yet fully loaded, or if there has been a change to the sources or style that has not yet fully loaded. Returns boolean : A Boolean indicating whether the map is fully loaded. loadImage (url) Load an image from an external URL to be used with Map#addImage . External domains must support CORS . Parameters url ( string ) The URL of the image file. Image file must be in png, webp, or jpg format. Returns Promise<GetResourceResponse<ImageBitmap | HTMLImageElement>> : A promise that is resolved when the image is loaded. Example Related examples Add an icon to the map moveLayer (id, beforeId?) Moves a layer to a different z-position. Parameters id ( string ) The ID of the layer to move. beforeId ( string ? ) The ID of an existing layer to insert the new layer before. When viewing the map, the id layer will appear beneath the beforeId layer. If beforeId is omitted, the layer will be appended to the end of the layers array and appear above all other layers on the map. Returns Map : this Example off (type, layer, listener) Removes an event listener for layer-specific events previously added with Map#on . See Map Events for a full list of events and their description. Parameters type ( string ) The event type previously used to install the listener. layer ( string ) The layer ID or listener previously used to install the listener. listener ( Function ) The function previously installed as a listener. Returns Map : this off (type, layerIds, listener) Overload of the off method that allows to listen to events specifying multiple layers. Parameters type ( string ) The event type previously used to install the listener. layerIds ( string[] ) The array of style layer IDs or listener previously used to install the listener. listener ( Function ) The function previously installed as a listener. Returns Map : this off (type, listener) Overload of the off method that allows to listen to events without specifying a layer. See Map off method for parameters, returns, and other descriptions. on (type, layer, listener) Adds a listener for events of a specified type, optionally limited to features in a specified style layer. See Map Events for a full list of events and their description. Parameters type ( string ) The event type to listen for. Events compatible with the optional layerIds parameter are triggered when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas. layerIds ( string ) The ID of a style layer. Event will only be triggered if its location is within a visible feature in this layer. The event will have a features property containing an array of the matching features. If layer is not supplied, the event will not have a features property. Please note that many event types are not compatible with the optional layer parameter. listener ( Function ) The function to be called when the event is fired. Returns Subscription Example Related examples Display popup on click Center the map on a clicked symbol Create a hover effect Create a draggable marker on (type, layerIds, listener) Overload of the on method that allows to listen to events specifying multiple layers. Parameters type ( string ) The event type to listen for. Events compatible with the optional layerIds parameter are triggered when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas. layerIds ( string[] ) The array of style layer IDs. Event will only be triggered if its location is within a visible feature in this layer. The event will have a features property containing an array of the matching features. If layer is not supplied, the event will not have a features property. Please note that many event types are not compatible with the optional layer parameter. listener ( Function ) The function to be called when the event is fired. Returns Subscription Example on (type, listener) Overload of the on method that allows to listen to events without specifying a layer. See Map on method for parameters, returns, and other descriptions. once (type, layer, listener) Adds a listener that will be called only once to a specified event type occurring on features in a specified style layer. See Map Events for a full list of events and their description. Parameters type ( string ) The event type to listen for; one of 'mousedown' , 'mouseup' , 'click' , 'dblclick' , 'mousemove' , 'mouseenter' , 'mouseleave' , 'mouseover' , 'mouseout' , 'contextmenu' , 'touchstart' , 'touchend' , or 'touchcancel' . mouseenter and mouseover events are triggered when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas. mouseleave and mouseout events are triggered when the cursor leaves a visible portion of the specified layer, or leaves the map canvas. layer ( string ) The ID of a style layer. Only events whose location is within a visible feature in this layer will trigger the listener. The event will have a features property containing an array of the matching features. listener ( Function ) The function to be called when the event is fired. Returns Map : this once (type, layerIds, listener) Overload of the once method that allows to listen to events specifying multiple layers. Parameters type ( string ) The event type to listen for; one of 'mousedown' , 'mouseup' , 'click' , 'dblclick' , 'mousemove' , 'mouseenter' , 'mouseleave' , 'mouseover' , 'mouseout' , 'contextmenu' , 'touchstart' , 'touchend' , or 'touchcancel' . mouseenter and mouseover events are triggered when the cursor enters a visible portion of the specified layer from outside that layer or outside the map canvas. mouseleave and mouseout events are triggered when the cursor leaves a visible portion of the specified layer, or leaves the map canvas. layerIds ( string[] ) The array of style layer IDs. Only events whose location is within a visible feature in this layer will trigger the listener. The event will have a features property containing an array of the matching features. listener ( Function ) The function to be called when the event is fired. Returns Map : this once (type, listener) Overload of the once method that allows to listen to events without specifying a layer. See Map once method for parameters, returns, and other descriptions. onLoadAsync () Awaits for the Map instance to be "loaded" and returns a Promise to the Map. If the Map instance is already loaded, the Promise is resolved directly, otherwise, it is resolved as a result of the "load" event. Returns Map : this Example onLoadWithTerrainAsync () Awaits for the Map instance to be "loaded" as well as with terrain being non-null for the first time and returns a Promise to the Map. If the Map instance is already loaded with terrain, the Promise is resolved directly, otherwise, it is resolved as a result of the "loadWithTerrain" event. Returns Map : this Example onReadyAsync () Awaits for the Map instance to be "ready" and returns a Promise to the Map. If the Map instance is already loaded, the Promise is resolved directly, otherwise, it is resolved as a result of the "ready" event. Returns Map : this Example panBy (offset, options?, eventData?) Pans the map by the specified offset. Parameters offset ( PointLike ) x and y coordinates by which to pan the map. options ( AnimationOptions ? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Related examples Navigate the map with game-like controls panTo (lnglat, options?, eventData?) Pans the map to the specified location with an animated transition. Parameters lnglat ( LngLatLike ) The location to pan the map to. options ( AnimationOptions ? ) Options describing the destination and animation of the transition. eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example Related examples Update a feature in realtime project (lnglat) Returns a Point representing pixel coordinates, relative to the map's container , that correspond to the specified geographical location. Parameters lnglat ( LngLatLike ) The geographical location to project. Returns Point : The Point corresponding to lnglat , relative to the map's container . Example queryRenderedFeatures (geometry?, options?) Returns an array of MapGeoJSONFeature objects representing visible features that satisfy the query parameters. Parameters geometry ( ( PointLike | Array < PointLike >)? ) The geometry of the query region: either a single point or southwest and northeast points describing a bounding box. Omitting this parameter (i.e. calling Map#queryRenderedFeatures with zero arguments, or with only a options argument) is equivalent to passing a bounding box encompassing the entire map viewport. options ( Object ? ) Options object. options.layers Array < string >? An array of style layer IDs for the query to inspect. Only features within these layers will be returned. If this parameter is undefined, all layers will be checked. options.filter Array ? A filter to limit query results. options.validate boolean default: true Whether to check if the [options.filter] conforms to the MapLibre GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. Returns Array <MapGeoJSONFeature> : An array of MapGeoJSONFeature objects. The properties value of each returned feature object contains the properties of its source feature. For GeoJSON sources, only string and numeric property values are supported (i.e. null , Array , and Object values are not supported). Each feature includes top-level layer , source , and sourceLayer properties. The layer property is an object representing the style layer to which the feature belongs. Layout and paint properties in this object contain values which are fully evaluated for the given zoom level and feature. Only features that are currently rendered are included. Some features will not be included, like: Features from layers whose visibility property is "none" . Features from layers whose zoom range excludes the current zoom level. Symbol features that have been hidden due to text or icon collision. Features from all other layers are included, including features that may have no visible contribution to the rendered result; for example, because the layer's opacity or color alpha component is set to The topmost rendered feature appears first in the returned array, and subsequent features are sorted by descending z-order. Features that are rendered multiple times (due to wrapping across the antimeridian at low zoom levels) are returned only once (though subject to the following caveat). Because features come from tiled vector data or GeoJSON data that is converted to tiles internally, feature geometries may be split or duplicated across tile boundaries and, as a result, features may appear multiple times in query results. For example, suppose there is a highway running through the bounding rectangle of a query. The results of the query will be those parts of the highway that lie within the map tiles covering the bounding rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile will be returned as a separate feature. Similarly, a point feature near a tile boundary may appear in multiple tiles due to tile buffering. Example Related examples Get features under the mouse pointer querySourceFeatures (sourceId, parameters?) Returns an array of MapGeoJSONFeature objects representing features within the specified vector tile or GeoJSON source that satisfy the query parameters. Parameters sourceId ( string ) The ID of the vector tile or GeoJSON source to query. parameters ( Object ? ) Options object. parameters.sourceLayer string ? The name of the source layer to query. For vector tile sources, this parameter is required. For GeoJSON sources, it is ignored. parameters.filter Array ? A filter to limit query results. parameters.validate boolean default: true Whether to check if the [parameters.filter] conforms to the MapLibre GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. Returns Array <MapGeoJSONFeature> : An array of MapGeoJSONFeature objects. In contrast to Map#queryRenderedFeatures , this function returns all features matching the query parameters, whether or not they are rendered by the current style (i.e. visible). The domain of the query includes all currently-loaded vector tiles and GeoJSON source tiles: this function does not check tiles outside the currently visible viewport. Because features come from tiled vector data or GeoJSON data that is converted to tiles internally, feature geometries may be split or duplicated across tile boundaries and, as a result, features may appear multiple times in query results. For example, suppose there is a highway running through the bounding rectangle of a query. The results of the query will be those parts of the highway that lie within the map tiles covering the bounding rectangle, even if the highway extends into other tiles, and the portion of the highway within each map tile will be returned as a separate feature. Similarly, a point feature near a tile boundary may appear in multiple tiles due to tile buffering. Example queryTerrainElevation (lngLatLike) Get the elevation difference between a given point and a point that is currently in the middle of the screen. This method should be used for proper positioning of custom 3d objects. Returns null if terrain is not enabled. This method is subject to change in Maplibre GL JS v5. Parameters lngLatLike ( LngLatLike ) [x,y] or LngLat coordinates of the location. Returns number elevation offset in meters Example redraw () Force a synchronous redraw of the map. Returns Map : this Example refreshTiles (sourceId, tileIds?) Triggers a reload of the selected tiles. Parameters sourceId (string) The ID of the source. tileIds? (object[]) An array of tile IDs to be reloaded. If not defined, all tiles will be reloaded. Returns void Example remove () Clean up and release all internal resources associated with this map. This includes DOM elements, event bindings, web workers, and WebGL resources. Use this method when you are done using the map and wish to ensure that it no longer consumes browser resources. Afterwards, you must not call any other methods on the map. removeControl (control) Removes the control from the map. Parameters control ( IControl ) The IControl to remove. Returns Map : this Example removeFeatureState (target, key) Removes the state of a feature, setting it back to the default behavior. If only a target.source is specified, it will remove the state for all features from that source. If target.id is also specified, it will remove all keys for that feature's state. If key is also specified, it removes only that key from that feature's state. Features are identified by their feature.id attribute, which can be any number or string. Parameters target ( Object ) Identifier of where to remove state. It can be a source, a feature, or a specific key of feature. Feature objects returned from Map#queryRenderedFeatures or event handlers can be used as feature identifiers. target.id ( string | number ) (optional) Unique id of the feature. Optional if key is not specified. target.source string The id of the vector or GeoJSON source for the feature. target.sourceLayer string ? (optional) For vector tile sources, sourceLayer is required. key ( string ) (optional) The key in the feature state to reset. Example removeImage (id) Remove an image from a style. This can be an image from the style's original sprite or any images that have been added at runtime using Map#addImage . Parameters id ( string ) The ID of the image. Example removeLayer (id) Removes the layer with the given ID from the map's style. If no such layer exists, an error event is fired. Parameters id ( string ) id of the layer to remove Example removeSource (id) Removes a source from the map's style. Parameters id ( string ) The ID of the source to remove. Returns Map : this Example removeSprite (id) Removes the sprite from the map's style. Fires the style event. Parameters id ( string ) The The ID of the sprite to remove. If the sprite is declared as a single URL, the ID must be "default". Returns Map : this Example repaint Gets and sets a Boolean indicating whether the map will continuously repaint. This information is useful for analyzing performance. resetNorth (options?, eventData?) Rotates the map so that north is up (0° bearing), with an animated transition. Parameters options ( AnimationOptions ? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this resetNorthPitch (options?, eventData?) Rotates and pitches the map so that north is up (0° bearing) and pitch is 0°, with an animated transition. Parameters options ( AnimationOptions ? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this resize (eventData?) Resizes the map according to the dimensions of its container element. Checks if the map container size changed and updates the map if it has changed. This method must be called after the map's container is resized programmatically or when the map is shown after being initially hidden with CSS. Parameters eventData ( any? ) Additional properties to be passed to movestart , move , resize , and moveend events that get triggered as a result of resize. This can be useful for differentiating the source of an event (for example, user-initiated or programmatically-triggered events). Returns Map : this Example rotateTo (bearing, options?, eventData?) Rotates the map to the specified bearing, with an animated transition. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up. Parameters bearing ( number ) The desired bearing. options ( AnimationOptions ? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this scrollZoom The map's ScrollZoomHandler , which implements zooming in and out with a scroll wheel or trackpad. Find more details and examples using scrollZoom in the ScrollZoomHandler section. setBearing (bearing, eventData?) Sets the map's bearing (rotation). The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up. Equivalent to jumpTo({bearing: bearing}) . Parameters bearing ( number ) The desired bearing. eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example setCenter (center, eventData?) Sets the map's geographical centerpoint. Equivalent to jumpTo({center: center}) . Parameters center ( LngLatLike ) The centerpoint to set. eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example setCenterClampedToGround (centerClampedToGround) Sets the value of centerClampedToGround . If true, the elevation of the center point will automatically be set to the terrain elevation (or zero if terrain is not enabled). If false, the elevation of the center point will default to sea level and will not automatically update. Defaults to true. Needs to be set to false to keep the camera above ground when pitch > 90 degrees. Parameters centerClampedToGround (boolean) Returns void setCenterElevation (elevation, eventData?) Sets the elevation of the map's center point, in meters above sea level. Equivalent to jumpTo({elevation: elevation}) . Triggers the following events: movestart and moveend . Parameters elevation (number) The elevation to set, in meters above sea level. eventData (any?) Additional properties to be added to event objects of events triggered by this method. Returns Map : this setEventedParent (parent, data?) Bubble all events fired by this instance of Evented to this parent instance of Evented. Parameters parent (Evented?) data (any?) Returns Map : this setFeatureState (feature, state) Sets the state of a feature. A feature's state is a set of user-defined key-value pairs that are assigned to a feature at runtime. When using this method, the state object is merged with any existing key-value pairs in the feature's state. Features are identified by their feature.id attribute, which can be any number or string. This method can only be used with sources that have a feature.id attribute. The feature.id attribute can be defined in three ways: For vector or GeoJSON sources, including an id attribute in the original data file. For vector or GeoJSON sources, using the promoteId option at the time the source is defined. For GeoJSON sources, using the generateId option to auto-assign an id based on the feature's index in the source data. If you change feature data using map.getSource('some id').setData(..) , you may need to re-apply state taking into account updated id values. Note: You can use the feature-state expression to access the values in a feature's state object for the purposes of styling. Parameters feature ( Object ) Feature identifier. Feature objects returned from Map#queryRenderedFeatures or event handlers can be used as feature identifiers. feature.id ( string | number ) Unique id of the feature. feature.source string The id of the vector or GeoJSON source for the feature. feature.sourceLayer string ? (optional) For vector tile sources, sourceLayer is required. state ( Object ) A set of key-value pairs. The values should be valid JSON types. Example Related examples Create a hover effect setFilter (layerId, filter, options = {}) Sets the filter for the specified style layer. Filters control which features a style layer renders from its source. Any feature for which the filter expression evaluates to true will be rendered on the map. Those that are false will be hidden. Use setFilter to show a subset of your source data. To clear the filter, pass null or undefined as the second parameter. Parameters layerId ( string ) The ID of the layer to which the filter will be applied. filter ( ( Array | null | undefined ) ) The filter, conforming to the GL Style Specification's filter definition . If null or undefined is provided, the function removes any existing filter from the layer. options ( Object ? ) (default {} ) Options object. options.validate boolean default: true Whether to check if the filter conforms to the MapLibre GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. Returns Map : this Example Related examples Create a timeline animation setGlobalStateProperty (propertyName, value) Sets a global state property that can be retrieved with the global-state expression. If the value is null, it resets the property to its default value defined in the state style property. Note that changing global-state values defined in layout properties is not supported, and will be ignored. Parameters propertyName (string) The name of the state property to set. value (any) The value of the state property to set. Returns Map : this setGlyphs (glyphsUrl, options?) Sets the value of the style's glyphs property. Parameters glyphsUrl ( string ) The Glyph URL to set. Must conform to the GL Style Specification . options ( StyleSetterOptions ? ) The Options object. Returns Map : this Example setHalo (halo) Sets the halo (atmospheric glow) for the map. Parameters halo ( RadialGradientLayerConstructorOptions ) Example setLanguage (language) Sets the map labels language. Note: not all the languages shorthands provided are available. Parameters language ( string | Language ) The language to be applied. The language generally depends on the style. Whenever a label is not supported in the defined language, it falls back to maptilersdk.Language.LATIN . Languages that are written right-to-left such as arabic and hebrew are fully supported by default. No need to install any plugin! Returns Map : this Example Related examples How to change the default map labels language How to change the map labels language based on visitor's location Change a map's language setLayerZoomRange (layerId, minzoom, maxzoom) Sets the zoom extent for the specified style layer. The zoom extent includes the minimum zoom level and maximum zoom level ) at which the layer will be rendered. Note: For style layers using vector sources, style layers cannot be rendered at zoom levels lower than the minimum zoom level of the source layer because the data does not exist at those zoom levels. If the minimum zoom level of the source layer is higher than the minimum zoom level defined in the style layer, the style layer will not be rendered at all zoom levels in the zoom range. Parameters layerId ( string ) The ID of the layer to which the zoom extent will be applied. minzoom ( number ) The minimum zoom to set (0-24). maxzoom ( number ) The maximum zoom to set (0-24). Returns Map : this Example setLayoutProperty (layerId, name, value, options = {}) Sets the value of a layout property in the specified style layer. Parameters layerId ( string ) The ID of the layer to set the layout property in. name ( string ) The name of the layout property to set. value ( any ) The value of the layout property. Must be of a type appropriate for the property, as defined in the GL Style Specification . options ( Object ? ) (default {} ) Options object. options.validate boolean default: true Whether to check if value conforms to the MapLibre GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. Returns Map : this Example setLight (light, options = {}) Sets the any combination of light values. Parameters light ( LightSpecification ) Light properties to set. Must conform to the GL Style Specification . options ( Object ? ) (default {} ) Options object. options.validate boolean default: true Whether to check if the filter conforms to the GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. Returns Map : this setMaxBounds (bounds) Sets or clears the map's geographical bounds. Pan and zoom operations are constrained within these bounds. If a pan or zoom is performed that would display regions outside these bounds, the map will instead display a position and zoom level as close as possible to the operation's request while still remaining within the bounds. Parameters bounds ( ( LngLatBoundsLike | null | undefined ) ) The maximum bounds to set. If null or undefined is provided, the function removes the map's maximum bounds. Returns Map : this Example setMaxPitch (maxPitch) Sets or clears the map's maximum pitch. If the map's current pitch is higher than the new maximum, the map will pitch to the new maximum. Parameters maxPitch ( ( number | null | undefined ) ) The maximum pitch to set (0-85). Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the MapLibre project. If null or undefined is provided, the function removes the current maximum pitch (sets it to 60). Returns Map : this setMaxZoom (maxZoom) Sets or clears the map's maximum zoom level. If the map's current zoom level is higher than the new maximum, the map will zoom to the new maximum. Parameters maxZoom ( ( number | null | undefined ) ) The maximum zoom level to set. If null or undefined is provided, the function removes the current maximum zoom (sets it to 22). Returns Map : this Example setMinPitch (minPitch) Sets or clears the map's minimum pitch. If the map's current pitch is lower than the new minimum, the map will pitch to the new minimum. Parameters minPitch ( ( number | null | undefined ) ) The minimum pitch to set (0-85). Values greater than 60 degrees are experimental and may result in rendering issues. If you encounter any, please raise an issue with details in the MapLibre project. If null or undefined is provided, the function removes the current minimum pitch (i.e. sets it to 0). Returns Map : this setMinZoom (minZoom) Sets or clears the map's minimum zoom level. If the map's current zoom level is lower than the new minimum, the map will zoom to the new minimum. It is not always possible to zoom out and reach the set minZoom . Other factors such as map height may restrict zooming. For example, if the map is 512px tall it will not be possible to zoom below zoom 0 no matter what the minZoom is set to. Parameters minZoom ( ( number | null | undefined ) ) The minimum zoom level to set (-2 - 24). If null or undefined is provided, the function removes the current minimum zoom (i.e. sets it to -2). Returns Map : this Example setPadding (padding, eventData?) Sets the padding in pixels around the viewport. Equivalent to jumpTo({padding: padding}) . Parameters padding ( PaddingOptions ) The desired padding. Format: { left: number, right: number, top: number, bottom: number } eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example setPaintProperty (layerId, name, value, options = {}) Sets the value of a paint property in the specified style layer. Parameters layerId ( string ) The ID of the layer to set the paint property in. name ( string ) The name of the paint property to set. value ( any ) The value of the paint property to set. Must be of a type appropriate for the property, as defined in the GL Style Specification . options ( Object ? ) (default {} ) Options object. options.validate boolean default: true Whether to check if value conforms to the MapLibre GL Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. Returns Map : this Example Related examples Change a layer's color with buttons Create a draggable point setPitch (pitch, eventData?) Sets the map's pitch (tilt). Equivalent to jumpTo({pitch: pitch}) . Parameters pitch ( number ) The pitch to set, measured in degrees away from the plane of the screen (0-60). eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this setPixelRatio (pixelRatio) Sets the map's pixel ratio. This allows to override devicePixelRatio . After this call, the canvas' width attribute will be container.clientWidth * pixelRatio and its height attribute will be container.clientHeight * pixelRatio . Parameters pixelRatio ( number ) The pixel ratio. setProjection (projection?, options?) Sets the ProjectionSpecification Accepts types: "mercator" for Web Mercator Projection "vertical-perspective" for General Perspective projection And preset "globe" for adaptive globe (interpolates from vertical-perspective to mercator projection between zoom levels 10 and 12.) ProjectionChangeOptions Whether the new projection should be persisted for any future style changes. If true , the new projection is persisted and is applied after all future style changes. If false or not specified, the new projection will be used only until the next style change, when it will get replaced with the first applicable value from this list: a previously persisted projection a projection specified in Map constructor options a projection specified in projection property of the style itself the Mercator projection projection (ProjectionSpecification?) options (ProjectionChangeOptions?) This will set the map projection Example Returns Map : this setRenderWorldCopies (renderWorldCopies) Sets the state of renderWorldCopies . Parameters renderWorldCopies ( boolean ) If true , multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to false : When the map is zoomed out far enough that a single representation of the world does not fill the map's entire container, there will be blank space beyond 180 and -180 degrees longitude. Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the map and the other on the left edge of the map) at every zoom level. undefined is treated as true , null is treated as false . Returns Map : this Example Related examples Render world copies setRoll (roll, eventData?) Sets the map's roll angle. Equivalent to jumpTo({roll: roll}) . Triggers the following events: movestart , moveend , rollstart , and rollend . Parameters roll ( number ) The roll to set, measured in degrees about the camera boresight eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this setSecondaryLanguage (language) Sets the map labels secondary language. Parameters language ( string | Language ) The language to be applied. The language generally depends on the style. Whenever a label is not supported in the defined language, it falls back to maptilersdk.Language.LATIN . Languages that are written right-to-left such as arabic and hebrew are fully supported by default. No need to install any plugin! Returns Map : this Example setSky (sky, options?) Sets the value of style's sky properties. Parameters sky (SkySpecification) Sky properties to set. Must conform to the GL Style Specification . options ( StyleSetterOptions ?) Options object. Returns Map : this Example setSourceTileLodParams (maxZoomLevelsOnScreen, tileCountMaxMinRatio, sourceId?) Change the tile Level of Detail behavior of the specified source. These parameters have no effect when pitch == 0, and the largest effect when the horizon is visible on screen. Parameters maxZoomLevelsOnScreen (number) The maximum number of distinct zoom levels allowed on screen at a time. There will generally be fewer zoom levels on the screen, the maximum can only be reached when the horizon is at the top of the screen. Increasing the maximum number of zoom levels causes the zoom level to decay faster toward the horizon. tileCountMaxMinRatio (number) The ratio of the maximum number of tiles loaded (at high pitch) to the minimum number of tiles loaded. Increasing this ratio allows more tiles to be loaded at high pitch angles. If the ratio would otherwise be exceeded, the zoom level is reduced uniformly to keep the number of tiles within the limit. sourceId? (string) The ID of the source to set tile LOD parameters for. All sources will be updated if unspecified. If sourceId is specified but a corresponding source does not exist, an error is thrown. Returns Map : this Example setSpace (space) Sets the space for the map. This method, at present, **overwrites** the current config. If an option is not set it will internally revert to the default option unless explicitly set when calling. Parameters space ( CubemapLayerConstructorOptions ) Example setSprite (spriteUrl, options?) Sets the value of style's sky properties. Parameters spriteUrl (string) Sprite URL to set. options ( StyleSetterOptions ?) Options object. Returns Map : this Example setStyle (style, options?) Updates the map's style object with a new value. If a style is already set when this is used and options.diff is set to true, the map renderer will attempt to compare the given style against the map's current state and perform only the changes necessary to make the map style match the desired state. Changes in sprites (images used for icons and patterns) and glyphs (fonts for label text) cannot be diffed. If the sprites or fonts used in the current style and the given style are different in any way, the map renderer will force a full update, removing the current style and building the given one from scratch. Parameters style ( ( ReferenceMapStyle | MapStyleVariant | string | StyleSpecification | null) ) The map's style. This must be: ReferenceMapStyle (e.g. MapStyle.STREETS) MapStyleVariant (e.g. MapStyle.STREETS.DARK) MapTIler Style ID (e.g. “”) uuid of custom style an a JSON object conforming to the schema described in the GL Style Specification a URL to such JSON null options ( Object ? ) Options object. options.diff boolean default: true If false, force a 'full' update, removing the current style and building the given one instead of attempting a diff-based update. options.transformStyle TransformStyleFunction TransformStyleFunction is a convenience function that allows to modify a style after it is fetched but before it is committed to the map state. options.localIdeographFontFamily string default: 'sans-serif' Defines a CSS font-family for locally overriding generation of glyphs in the 'CJK Unified Ideographs', 'Hiragana', 'Katakana' and 'Hangul Syllables' ranges. In these ranges, font settings from the map's style will be ignored, except for font-weight keywords (light/regular/medium/bold). Set to false , to enable font settings from the map's style for these glyph ranges. Forces a full update. options.validate boolean If false, style validation will be skipped. Useful in production environment. Returns Map : this Example Related examples Built-in map styles How to display a style switcher control setTerrain (options?) Loads a 3D terrain mesh, based on a "raster-dem" source. Parameters options ( TerrainSpecification? ) Options object. Returns Map : this Example setTerrainAnimationDuration (duration) Set the duration (millisec) of the terrain animation for growing or flattening. Parameters duration ( number ) Sets the terrain animation duration in milliseconds Example setTerrainExaggeration (exaggeration) Sets the 3D terrain exageration factor. This method is just a shortcut to .enableTerrain Parameters exaggeration ( number ) Sets the terrain exaggeration factor Example setTransformRequest (transformRequest) Updates the requestManager's transform request with a new function Parameters transformRequest ( RequestTransformFunction ) A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests. Expected to return an object with a url property and optionally headers and credentials properties Returns Map : this Example setVerticalFieldOfView (fov, eventData?) Sets the map's vertical field of view, in degrees. Default 36.87 . Triggers the following events: movestart , move , and moveend . The internal camera has a default vertical field of view ( wikipedia ) of a wide ~36.86 degrees. In globe mode, such a large FOV reduces the amount of the Earth that can be seen at once and exaggerates the central part, comparably to a fisheye lens. In many cases, a narrower FOV is preferable. FOV comparison: 01° 50° Parameters fov ( number ) The vertical field of view to set, in degrees (0-180). eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example setZoom (zoom, eventData?) Sets the map's zoom level. Equivalent to jumpTo({zoom: zoom}) . Parameters zoom ( number ) The zoom level to set (0-20). eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example showCollisionBoxes Gets and sets a Boolean indicating whether the map will render boxes around all symbols in the data source, revealing which symbols were rendered or which were hidden due to collisions. This information is useful for debugging. showOverdrawInspector Gets and sets a Boolean indicating whether the map should color-code each fragment to show how many times it has been shaded. White fragments have been shaded 8 or more times. Black fragments have been shaded 0 times. This information is useful for debugging. showPadding Gets and sets a Boolean indicating whether the map will visualize the padding offsets. showTileBoundaries Gets and sets a Boolean indicating whether the map will render an outline around each tile and the tile ID. These tile boundaries are useful for debugging. The uncompressed file size of the first vector source is drawn in the top left corner of each tile, next to the tile ID. Example snapToNorth (options?, eventData?) Snaps the map so that north is up (0° bearing), if the current bearing is close enough to it (i.e. within the bearingSnap threshold). Parameters options ( AnimationOptions ? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this stop () Stops any animated transition underway. Returns Map : this touchPitch The map's TouchPitchHandler , which allows the user to pitch the map with touch gestures. Find more details and examples using touchPitch in the TouchPitchHandler section. touchZoomRotate The map's TouchZoomRotateHandler , which allows the user to zoom or rotate the map with touch gestures. Find more details and examples using touchZoomRotate in the TouchZoomRotateHandler section. transformCameraUpdate A callback ( CameraUpdateTransformFunction ) used to defer camera updates or apply arbitrary constraints. If specified, this Camera instance can be used as a stateless component in React etc. triggerRepaint () Trigger the rendering of a single frame. Use this method with custom layers to repaint the map when the layer changes. Calling this multiple times before the next frame is rendered will still result in only a single frame being rendered. Example Related examples Add a 3D model Add an animated icon to the map unproject (point) Returns a LngLat representing geographical coordinates that correspond to the specified pixel coordinates. Parameters point ( PointLike ) The pixel coordinates to unproject. Returns LngLat : The LngLat corresponding to point . Example updateImage (id, image) Update an existing image in a style. This image can be displayed on the map like any other icon in the style's sprite using the image's ID with icon-image , background-pattern , fill-pattern , or line-pattern . Parameters id ( string ) The ID of the image. image ( ( HTMLImageElement | ImageBitmap | ImageData | {width: number , height: number , data: ( Uint8Array | Uint8ClampedArray )} | StyleImageInterface ) ) The image as an HTMLImageElement , ImageData , ImageBitmap or object with width , height , and data properties with the same format as ImageData . Example version Returns the package version of the library Returns string : Package version of the library zoomIn (options?, eventData?) Increases the map's zoom level by 1. Parameters options ( AnimationOptions ? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example zoomOut (options?, eventData?) Decreases the map's zoom level by 1. Parameters options ( AnimationOptions ? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example zoomTo (zoom, options?, eventData?) Zooms the map to the specified zoom level, with an animated transition. Parameters zoom ( number ) The zoom level to transition to. options ( ( AnimationOptions | null)? ) Options object eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns Map : this Example Events boxzoomcancel Fired when the user cancels a "box zoom" interaction, or when the bounding box does not meet the minimum size threshold. See BoxZoomHandler . Properties data ( MapLibreZoomEvent ) Example boxzoomend Fired when a "box zoom" interaction ends. See BoxZoomHandler . Properties data ( MapLibreZoomEvent ) Example boxzoomstart Fired when a "box zoom" interaction starts. See BoxZoomHandler . Properties data ( MapLibreZoomEvent ) Example click Fired when a pointing device (usually a mouse) is pressed and released at the same point on the map. Note: This event is compatible with the optional layerId parameter. If layerId is included as the second argument in Map#on , the event listener will fire only when the point that is pressed and released contains a visible portion of the specifed layer. Properties data ( MapMouseEvent ) Example Related examples Measure distances Center the map on a clicked symbol contextmenu Fired when the right button of the mouse is clicked or the context menu key is pressed within the map. Properties data ( MapMouseEvent ) Example cooperativegestureprevented Fired whenever the cooperativeGestures option prevents a gesture from being handled by the map. This is useful for showing your own UI when this happens. Properties data ( WheelEvent | TouchEvent ) & object Type declaration gestureType ( "wheel_zoom" | "touch_pan" ) Example data Fired when any map data loads or changes. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example Related examples Display HTML clusters with custom properties dataabort Fired when a request for one of the map's sources' tiles is aborted. Fired when a request for one of the map's sources' data is aborted. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example dataloading Fired when any map data (style, source, tile, etc) begins loading or changing asyncronously. All dataloading events are followed by a data , dataabort or error event. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example dblclick Fired when a pointing device (usually a mouse) is pressed and released twice at the same point on the map in rapid succession. Note: This event is compatible with the optional layerId parameter. If layerId is included as the second argument in Map#on , the event listener will fire only when the point that is clicked twice contains a visible portion of the specifed layer. Properties data ( MapMouseEvent ) Example drag Fired repeatedly during a "drag to pan" interaction. See DragPanHandler . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example dragend Fired when a "drag to pan" interaction ends. See DragPanHandler . Properties data ( {originalEvent: DragEvent } ) Example Related examples Create a draggable marker dragstart Fired when a "drag to pan" interaction starts. See DragPanHandler . Properties data ( {originalEvent: DragEvent } ) Example error Fired when an error occurs. This is GL JS's primary error reporting mechanism. We use an event instead of throw to better accommodate asyncronous operations. If no listeners are bound to the error event, the error will be printed to the console. Properties data ( {error: {message: string }} ) Example idle Fired after the last frame rendered before the map enters an "idle" state: No camera transitions are in progress All currently requested tiles have loaded All fade/transition animations have completed Example load Fired immediately after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred. Example Related examples Draw GeoJSON points Add live realtime data Animate a point loadWithTerrain Fired only once in a Map instance lifecycle, when both the load event and the terrain event with non-null terrain are fired. Example mousedown Fired when a pointing device (usually a mouse) is pressed within the map. Note: This event is compatible with the optional layerId parameter. If layerId is included as the second argument in Map#on , the event listener will fire only when the the cursor is pressed while inside a visible portion of the specifed layer. Properties data ( MapMouseEvent ) Example Related examples Create a draggable point mouseenter Fired when a pointing device (usually a mouse) enters a visible portion of a specified layer from outside that layer or outside the map canvas. Important: This event can only be listened for when Map#on includes three arguments, where the second argument specifies the desired layer. Properties data ( MapMouseEvent ) Example Related examples Center the map on a clicked symbol Display a popup on click mouseleave Fired when a pointing device (usually a mouse) leaves a visible portion of a specified layer, or leaves the map canvas. Important: This event can only be listened for when Map#on includes three arguements, where the second argument specifies the desired layer. Properties data ( MapMouseEvent ) Example Related examples Highlight features under the mouse pointer Display a popup on click mousemove Fired when a pointing device (usually a mouse) is moved while the cursor is inside the map. As you move the cursor across the map, the event will fire every time the cursor changes position within the map. Note: This event is compatible with the optional layerId parameter. If layerId is included as the second argument in Map#on , the event listener will fire only when the the cursor is inside a visible portion of the specified layer. Properties data ( MapMouseEvent ) Example Related examples Get coordinates of the mouse pointer Highlight features under the mouse pointer Display a popup on over mouseout Fired when a point device (usually a mouse) leaves the map's canvas. Properties data ( MapMouseEvent ) Example mouseover Fired when a pointing device (usually a mouse) is moved within the map. As you move the cursor across a web page containing a map, the event will fire each time it enters the map or any child elements. Note: This event is compatible with the optional layerId parameter. If layerId is included as the second argument in Map#on , the event listener will fire only when the the cursor is moved inside a visible portion of the specifed layer. Properties data ( MapMouseEvent ) Example Related examples Get coordinates of the mouse pointer Highlight features under the mouse pointer Display a popup on hover mouseup Fired when a pointing device (usually a mouse) is released within the map. Note: This event is compatible with the optional layerId parameter. If layerId is included as the second argument in Map#on , the event listener will fire only when the the cursor is released while inside a visible portion of the specifed layer. Properties data ( MapMouseEvent ) Example Related examples Create a draggable point move Fired repeatedly during an animated transition from one view to another, as the result of either user interaction or methods such as Map#flyTo . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example Related examples Display HTML clusters with custom properties moveend Fired just after the map completes a transition from one view to another, as the result of either user interaction or methods such as Map#jumpTo . Properties data ( {originalEvent: DragEvent } ) Example Related examples Display HTML clusters with custom properties movestart Fired just before the map begins a transition from one view to another, as the result of either user interaction or methods such as Map#jumpTo . Properties data ( {originalEvent: DragEvent } ) Example pitch Fired repeatedly during the map's pitch (tilt) animation between one state and another as the result of either user interaction or methods such as Map#flyTo . Properties data ( MapEventData ) Example pitchend Fired immediately after the map's pitch (tilt) finishes changing as the result of either user interaction or methods such as Map#flyTo . Properties data ( MapEventData ) Example pitchstart Fired whenever the map's pitch (tilt) begins a change as the result of either user interaction or methods such as Map#flyTo . Properties data ( MapEventData ) Example projectiontransition Fired when map's projection is modified in other ways than by map being moved. Properties data ( MapProjectionEvent ) Example ready Called only once after load and wait for all the controls managed by the Map constructor to be dealt with (as one relies on async logic). Since the ready event waits that all the basic controls are nicely positioned, it is safer to use ready than load if you plan to add other custom comtrols with the .addControl() method. Example Related examples Draw GeoJSON points Add live realtime data Animate a point remove Fired immediately after the map has been removed with Map.event:remove . Example render Fired whenever the map is drawn to the screen, as the result of a change to the map's position, zoom, pitch, or bearing a change to the map's style a change to a GeoJSON source the loading of a vector tile, GeoJSON file, glyph, or sprite Example resize Fired immediately after the map has been resized. Example rotate Fired repeatedly during a "drag to rotate" interaction. See DragRotateHandler . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example rotateend Fired when a "drag to rotate" interaction ends. See DragRotateHandler . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example rotatestart Fired when a "drag to rotate" interaction starts. See DragRotateHandler . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example sourcedata Fired when one of the map's sources loads or changes, including if a tile belonging to a source loads or changes. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example sourcedataabort Fired when a request for one of the map's sources' data is aborted. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example sourcedataloading Fired when one of the map's sources begins loading or changing asyncronously. All sourcedataloading events are followed by a sourcedata , sourcedataabort or error event. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example styledata Fired when the map's style loads or changes. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example styledataloading Fired when the map's style begins loading or changing asyncronously. All styledataloading events are followed by a styledata or error event. See MapDataEvent for more information. Properties data ( MapDataEvent ) Example styleimagemissing Fired when an icon or pattern needed by the style is missing. The missing image can be added with Map#addImage within this event listener callback to prevent the image from being skipped. This event can be used to dynamically generate icons and patterns. Properties id ( string ) : The id of the missing image. Example Related examples Generate and add a missing icon to the map terrain Fired when a terrain event occurs within the map. Example terrainAnimationStart The terrainAnimationStart event is fired when the animation begins transitioning between terrain and non-terrain states. Example terrainAnimationStop The terrainAnimationStop event is fired when the animation between terrain and non-terrain states ends. Example touchcancel Fired when a touchcancel event occurs within the map. Properties data ( MapTouchEvent ) Example touchend Fired when a touchend event occurs within the map. Properties data ( MapTouchEvent ) Example Related examples Create a draggable point touchmove Fired when a touchmove event occurs within the map. Properties data ( MapTouchEvent ) Example Related examples Create a draggable point touchstart Fired when a touchstart event occurs within the map. Properties data ( MapTouchEvent ) Example Related examples Create a draggable point webglcontextlost Fired when the WebGL context is lost. The maps is rendered with WebGL, that leverages the GPU to provide high-performance graphics. In some cases, the host machine, operating system or the graphics driver, can decide that continuing to run such high performance graphics is unsustainable, and will abort the process. This is called a "WebGL context loss". Such situation happens when the ressources are running low or when multiple browser tabs are competing to access graphics memory. Example webglcontextrestored Fired when the WebGL context is restored. Example wheel Fired when a wheel event occurs within the map. Properties data ( MapWheelEvent ) Example zoom Fired repeatedly during an animated transition from one zoom level to another, as the result of either user interaction or methods such as Map#flyTo . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example zoomend Fired just after the map completes a transition from one zoom level to another, as the result of either user interaction or methods such as Map#flyTo . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example zoomstart Fired just before the map begins a transition from one zoom level to another, as the result of either user interaction or methods such as Map#flyTo . Properties data ( ( MapMouseEvent | MapTouchEvent ) ) Example Related examples Display a map # Map Styles Source: https://docs.maptiler.com/sdk-js/api/map-styles/ Map Styles src/mapstyle.ts The built-in map styles defined in the Client JS library are exposed by the SDK so that they can easily be used. MapTiler teams maintains a few styles that we have decided to expose as style shorthand from the SDK. Our built-in styles are designed to make it easier for you to create beautiful maps, without the need for extra coding or worrying about outdated versions. This has several advantages: If we make an update to a style, you won't have to modify your codebase. Always use the latest version of styles. They are easier to remember, no need to type along style URL. No more putting the API key in every URL. Code completion: reducing typos and other common mistakes. The built-in styles generaly defines a purpose for which this style is the most relevant: street navigation, outdoor adventure, minimalist dashboard, etc. Then, each style offers a range of variants that contain the same level of information and has the same purpose but using different colors schemes like dark, light, etc. ReferenceMapStyle A reference syle sets some guidelines about what kind of information is displayed, the granularity of the information, and more generaly defines a purpose for which this style is the most relevant: street navigation, outdoor adventure, minimalist dashboard, etc. The MapStyle.REFERENCE_MAP_STYLE is an instance of the class ReferenceMapStyle (with a proxy layer). Example MapStyle.STREETS The classic default style, perfect for urban areas. MapStyle.SATELLITE High resolution satellite images. MapStyle.HYBRID High resolution satellite with labels, landmarks, roads ways and political borders. MapStyle.OUTDOOR A solid hiking companion, with peaks, parks, isolines and more. MapStyle.WINTER A map for developing skiing, snowboarding and other winter activities and adventures. MapStyle.BASIC A minimalist alternative to STREETS, with a touch of flat design. Methods addVariant (v) Add a variant to the reference style Parameters v ( MapStyleVariant ) Map style variant to add. getDefaultVariant () Get the defualt variant for the reference style. Returns MapStyleVariant getId () Get the id of the reference style Returns string : id of the style getName () Get the human-friendly name of the reference style Returns string : human-friendly name of the style getVariant (variantType) Get a given variant. If the given type of variant does not exist for this reference style, then the most relevant default variant is returned instead. Parameters variantType ( string ) Name of the style variant to get. Returns MapStyleVariant getVariants () Get the list of variants for this reference style. Returns Array[MapStyleVariant] : list of variants hasVariant (variantType) Check if a given variant type exists for this reference style Parameters variantType ( string ) Name of the style variant to check. Returns boolean MapStyleVariant Each reference style offers a range of variants that contain the same level of information and has the same purpose but using different colors schemes. The MapStyle.REFERENCE_MAP_STYLE.MAP_STYLE_VARIANT is an instance of the class MapStyleVariant . The proxy layer on top of each ReferenceMapStyle instance is useful to catch any inexistant variant and still fallback on the default one. For example, MapStyle.STREETS is an proxied instance of ReferenceMapStyle and if we look for the DARK variant (instance of the class MapStyleVariant), we need to type MapStyle.STREETS.DARK but if we were looking for an inexisting variant, such as MapStyle.STREETS.INDIGO then MapStyle.STREETS will fallback on MapStyle.STREETS.DEFAULT (the advantage of a proxy compared to a classic getter is the dynamic resolution of the property) Example MapStyle.DATAVIZ.DARK A minimalist style for data visualization. Also available in color and light mode MapStyle.DATAVIZ.LIGHT A minimalist style for data visualization. Also available in color and dark mode MapStyle.BRIGHT.PASTEL A minimalist style for high contrast navigation. Also available in color, dark and light mode Methods getDescription () Get the human-friendly description Returns string : human-friendly description of the style getExpandedStyleURL () Get the style as usable by MapLibre, a string (URL) or a plain style description (StyleSpecification) Returns string : string (URL) or a plain style description (StyleSpecification) getFullName () Get the full name of the style variant Returns string : full name of the style getId () Get the MapTiler id Returns string : id of the style getImageURL () Get the image URL that represent this variant Returns string : image url of the style getName () Get the human-friendly name Returns string : human-friendly name of the style getReferenceStyle () Get the reference style this variant belongs to. Returns ReferenceMapStyle getType () Get the variant type (eg. "DEFAULT", "DARK", "PASTEL", etc.) Returns string : varian type getVariant (variantType) Retrieve the variant of a given type. If not found, will return the "DEFAULT" variant. (eg. _this_ "DARK" variant does not have any "PASTEL" variant, then the "DEFAULT" is returned). Parameters variantType ( string ) Name of the style variant to get. Returns MapStyleVariant getVariants () Get all the variants for this variants, except this current one. Returns Array[MapStyleVariant] : list of variants hasVariant (variantType) Check if a variant of a given type exists for this variants (eg. if this is a "DARK", then we can check if there is a "LIGHT" variant of it). Parameters variantType ( string ) Name of the style variant to check. Returns boolean Map Styles list MapTiler provides some reference styles as well as some variants for each. Here is the full list: Related examples Built-in map styles How to display a style switcher control How to display your custom map on the web page # Markers and popups Source: https://docs.maptiler.com/sdk-js/api/markers/ Markers and popups Elements that can be added to the map. The items in this section exist outside of the map's canvas element. Marker src/ui/marker.ts Creates a marker component Extends Evented . Example Parameters options ( Object ? ) options.anchor string default: 'center' A string indicating the part of the Marker that should be positioned closest to the coordinate set via Marker#setLngLat . Options are 'center' , 'top' , 'bottom' , 'left' , 'right' , 'top-left' , 'top-right' , 'bottom-left' , and 'bottom-right' . options.className string Space-separated CSS class names to add to marker element. options.clickTolerance number default: 0 The max number of pixels a user can shift the mouse pointer during a click on the marker for it to be considered a valid click (as opposed to a marker drag). The default is to inherit map's clickTolerance. options.color string default: '#3FB1CE' The color to use for the default marker if options.element is not provided. The default is light blue. options.draggable boolean default: false A boolean indicating whether or not a marker is able to be dragged to a new position on the map. options.element HTMLElement DOM element to use as a marker. The default is a light blue, droplet-shaped SVG marker. options.offset PointLike The offset in pixels as a PointLike object to apply relative to the element's center. Negatives indicate left and up. options.opacity number Marker's opacity when it's in clear view (not behind 3d terrain). The default is 1 options.opacityWhenCovered number Marker's opacity when it's behind 3d terrain. The default is 0.2 options.pitchAlignment string default: 'auto' map aligns the Marker to the plane of the map. viewport aligns the Marker to the plane of the viewport. auto automatically matches the value of rotationAlignment . options.rotation number default: 0 The rotation angle of the marker in degrees, relative to its respective rotationAlignment setting. A positive value will rotate the marker clockwise. options.rotationAlignment string default: 'auto' map aligns the Marker 's rotation relative to the map, maintaining a bearing as the map rotates. viewport aligns the Marker 's rotation relative to the viewport, agnostic to map rotations. auto is equivalent to viewport . options.scale number default: 1 The scale to use for the default marker if options.element is not provided. The default scale corresponds to a height of 41px and a width of 27px . options.subpixelPositioning boolean default: false If true , rounding is disabled for placement of the marker, allowing for subpixel positioning and smoother movement when the marker is translated. legacyOptions ( MarkerOptions? ) Methods addClassName (className) Adds a CSS class to the marker element. Parameters className ( string ) Non-empty string with CSS class name to add to marker element. Example addTo (map) Attaches the Marker to a Map object. Parameters map ( Map ) The SDK JS map to add the marker to. Returns Marker : this Example getElement () Returns the Marker 's HTML element. Returns HTMLElement : element getLngLat () Get the marker's geographical location. The longitude of the result may differ by a multiple of 360 degrees from the longitude previously set by setLngLat because Marker wraps the anchor longitude across copies of the world to keep the marker on screen. Returns LngLat : A LngLat describing the marker's location. Example Related examples Create a draggable Marker getOffset () Get the marker's offset. Returns Point : The marker's screen coordinates in pixels. getPitchAlignment () Returns the current pitchAlignment property of the marker. Returns string : The current pitch alignment of the marker in degrees. getPopup () Returns the Popup instance that is bound to the Marker . Returns Popup : popup Example getRotation () Returns the current rotation angle of the marker (in degrees). Returns number : The current rotation angle of the marker. getRotationAlignment () Returns the current rotationAlignment property of the marker. Returns string : The current rotational alignment of the marker. isDraggable () Returns true if the marker can be dragged Returns boolean : True if the marker is draggable. listens (type) Returns a true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type. Parameters type ( string ) The The event type. Returns boolean : true if there is at least one registered listener for specified event type, false otherwise off (type, listener) Removes a previously registered event listener. Parameters type ( string ) The event type previously used to install the listener. listener ( Function ) The function previously installed as a listener. Returns Marker : this on (type, layer, listener) Adds a listener for events of a specified type, optionally limited to features in a specified style layer. Parameters type ( string ) The event type to add a listen for. listener ( Function ) The function to be called when the event is fired. The listener function is called with the data object passed to fire , extended with target and type properties Returns Marker : this once (type, listener?) Adds a listener that will be called only once to a specified event type. The listener will be called first time the event fires after the listener is registered. Parameters type ( string ? ) The event type to listen for. listener ( Function ) The function to be called when the event is fired the first time. Returns ( Marker | Promise <any> ) : this or a promise if a listener is not provided remove () Removes the marker from a map Returns Marker : this Example removeClassName (className) Removes a CSS class from the marker element. Parameters className ( string ) Non-empty string with CSS class name to remove from marker element. Example setDraggable (shouldBeDraggable) Sets the draggable property and functionality of the marker Parameters shouldBeDraggable ( boolean ) (default false ) Turns drag functionality on/off Returns Marker : this setLngLat (lnglat) Set the marker's geographical position and move it. Parameters lnglat ( LngLat ) A LngLat describing where the marker should be located. Returns Marker : this Example Related examples Add custom icons with Markers Create a draggable Marker setOffset (offset) Sets the offset of the marker Parameters offset ( PointLike ) The offset in pixels as a PointLike object to apply relative to the element's center. Negatives indicate left and up. Returns Marker : this setPitchAlignment (alignment?) Sets the pitchAlignment property of the marker. Parameters alignment ( string ? ) Sets the pitchAlignment property of the marker. If alignment is 'auto', it will automatically match rotationAlignment . Returns Marker : this setPopup (popup?) Binds a Popup to the Marker . Parameters popup ( ( Popup | null)? ) An instance of the Popup class. If undefined or null, any popup set on this Marker instance is unset. Returns Marker : this Example Related examples Attach a popup to a marker instance setRotation (rotation) Sets the rotation property of the marker. Parameters rotation ( number ) (default 0 ) The rotation angle of the marker (clockwise, in degrees), relative to its respective Marker#setRotationAlignment setting. Returns Marker : this setRotationAlignment (alignment) Sets the rotationAlignment property of the marker. Parameters alignment ( string ) (default 'auto' ) Sets the rotationAlignment property of the marker. Returns Marker : this toggleClassName (className) Add or remove the given CSS class on the marker element, depending on whether the element currently has that class. Parameters className ( string ) Non-empty string with CSS class name to add/remove. Returns boolean : if the class was removed return false , if class was added, then return true Example togglePopup () Opens or closes the Popup instance that is bound to the Marker , depending on the current state of the Popup . Returns Marker : this Example Events drag Fired while dragging Properties marker ( Marker ) : object that is being dragged dragend Fired when the marker is finished being dragged Properties marker ( Marker ) : object that was dragged dragstart Fired when dragging starts Properties marker ( Marker ) : object that is being dragged Related examples Add custom icons with Markers Create a draggable Marker ImageViewerMarker src/ImageViewer/ImageViewerMarker.ts Creates a ImageViewerMarker component. This is, for all intents and purposes, the same as Marker with the exception of working in image pixels , not lat/lon . It composes the the internal logic of the Marker class so the behaviour should be exactly the same. Extends Evented . Example Methods Lists the methods that are different or exclusive to the ImageViewerMarker class. For the complete list of methods, check out Marker.Methods addTo (viewer) Attaches the ImageViewerMarker to a ImageViewer instance. Parameters viewer ( ImageViewer ) The SDK JS imageViewer to add the marker to. Returns ImageViewerMarker : this Example getPosition () Gets the position of the ImageViewerMarker. This is the equivalent of the getLngLat function of the markers on the map Returns PointLike : A Point or an array [number, number] of two numbers representing x and y screen coordinates in pixels. Example setPosition (px) Sets the position of the ImageViewerMarker. This is the equivalent of the setLngLat function of the markers on the map Parameters px ([number, number]) The position of the ImageViewerMarker in image pixels. Returns ImageViewerMarker : this Example Related examples Add markers to a non-georeferenced image Popup src/ui/popup.ts A popup component. Extends Evented . Example Parameters options ( Object ? ) options.closeButton boolean default: true If true , a close button will appear in the top right corner of the popup. options.closeOnClick boolean default: true If true , the popup will closed when the map is clicked. options.closeOnMove boolean default: false If true , the popup will closed when the map moves. options.focusAfterOpen boolean default: true If true , the popup will try to focus the first focusable element inside the popup. options.anchor string ? A string indicating the part of the Popup that should be positioned closest to the coordinate set via Popup#setLngLat . Options are 'center' , 'top' , 'bottom' , 'left' , 'right' , 'top-left' , 'top-right' , 'bottom-left' , and 'bottom-right' . If unset the anchor will be dynamically set to ensure the popup falls within the map container with a preference for 'bottom' . options.offset ( number | PointLike | Object )? A pixel offset applied to the popup's location specified as: a single number specifying a distance from the popup's location a PointLike specifying a constant offset an object of Point s specifing an offset for each anchor position Negative offsets indicate left and up. options.className string ? Space-separated CSS class names to add to popup container options.maxWidth string default: '240px' A string that sets the CSS property of the popup's maximum width, eg '300px' . To ensure the popup resizes to fit its content, set this property to 'none' . Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width Methods addClassName (className) Adds a CSS class to the popup container element. Parameters className ( string ) Non-empty string with CSS class name to add to popup container Returns Popup : this Example addTo (map) Adds the popup to a map. Parameters map ( Map ) The SDK JS map to add the popup to. Returns Popup : this Example Related examples Display a popup Display a popup on hover Display a popup on click Show polygon information on click getElement () Returns the Popup 's HTML element. Returns HTMLElement : element Example getLngLat () Returns the geographical location of the popup's anchor. The longitude of the result may differ by a multiple of 360 degrees from the longitude previously set by setLngLat because Popup wraps the anchor longitude across copies of the world to keep the popup on screen. Returns LngLat : The geographical location of the popup's anchor. getMaxWidth () Returns the popup's maximum width. Returns string : The maximum width of the popup. isOpen () Returns boolean : true if the popup is open, false if it is closed. listens (type) Returns a true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type. Parameters type ( string ) The The event type. Returns boolean : true if there is at least one registered listener for specified event type, false otherwise off (type, listener) Removes a previously registered event listener. Parameters type ( string ) The event type previously used to install the listener. listener ( Function ) The function previously installed as a listener. Returns Popup : this on (type, layer, listener) Adds a listener for events of a specified type, optionally limited to features in a specified style layer. Parameters type ( string ) The event type to add a listen for. listener ( Function ) The function to be called when the event is fired. The listener function is called with the data object passed to fire , extended with target and type properties Returns Popup : this once (type, listener?) Adds a listener that will be called only once to a specified event type. The listener will be called first time the event fires after the listener is registered. Parameters type ( string ? ) The event type to listen for. listener ( Function ) The function to be called when the event is fired the first time. Returns ( Popup | Promise <any> ) : this or a promise if a listener is not provided remove () Removes the popup from the map it has been added to. Returns Popup : this Example removeClassName (className) Removes a CSS class from the popup container element. Parameters className ( string ) Non-empty string with CSS class name to remove from popup container Returns Popup : this Example setDOMContent (htmlNode) Sets the popup's content to the element provided as a DOM node. Parameters htmlNode ( Node ) A DOM node to be used as content for the popup. Returns Popup : this Example setHTML (html) Sets the popup's content to the HTML provided as a string. This method does not perform HTML filtering or sanitization, and must be used only with trusted content. Consider Popup#setText if the content is an untrusted text string. Parameters html ( string ) A string representing HTML content for the popup. Returns Popup : this Example Related examples Display a popup Display a popup on hover Display a popup on click Attach a popup to a marker instance setLngLat (lnglat) Sets the geographical location of the popup's anchor, and moves the popup to it. Replaces trackPointer() behavior. Parameters lnglat ( LngLatLike ) The geographical location to set as the popup's anchor. Returns Popup : this setMaxWidth (maxWidth) Sets the popup's maximum width. This is setting the CSS property max-width . Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width Parameters maxWidth ( string ) A string representing the value for the maximum width. Returns Popup : this setOffset (offset?) Sets the popup's offset. Parameters offset ( Offset? ) Sets the popup's offset. Returns Popup : this setSubpixelPositioning (value) Set the option to allow subpixel positioning of the popup by passing a boolean Parameters value ( boolean ) When boolean is true, subpixel positioning is enabled for the popup. Example setText (text) Sets the popup's content to a string of text. This function creates a Text node in the DOM, so it cannot insert raw HTML. Use this method for security against XSS if the popup content is user-provided. Parameters text ( string ) Textual content for the popup. Returns Popup : this Example toggleClassName (className) Add or remove the given CSS class on the popup container, depending on whether the container currently has that class. Parameters className ( string ) Non-empty string with CSS class name to add/remove Returns boolean : if the class was removed return false, if class was added, then return true Example trackPointer () Tracks the popup anchor to the cursor position on screens with a pointer device (it will be hidden on touchscreens). Replaces the setLngLat behavior. For most use cases, set closeOnClick and closeButton to false . Returns Popup : this Example Events close Fired when the popup is closed manually or programatically. Properties popup ( Popup ) : object that was closed Example open Fired when the popup is opened manually or programatically. Properties popup ( Popup ) : object that was opened Example Related examples Display a popup Display a popup on hover Display a popup on click Attach a popup to a marker instance # Sources Source: https://docs.maptiler.com/sdk-js/api/sources/ Sources A source provides the data that is displayed on a map. Sources are defined by the GL Style Specification . Vector Tile src/source/vector_tile_source.ts A vector tile source. Tiles must be in Vector Tile format . All layers that use a vector source must specify a "source-layer" value. (See the Style Specification for detailed documentation of options.) Extends Evented . Example Methods setTiles (tiles) Sets the source tiles property and re-renders the map. Parameters tiles ( Array < string > ) An array of one or more tile source URLs, as in the TileJSON spec. Returns VectorTileSource : this setUrl (url) Sets the source url property and re-renders the map. Parameters url ( string ) A URL to a TileJSON resource. Supported protocols are http: and https:. Returns VectorTileSource : this Related examples Add a vector tile source Add a third party vector tile source Raster Tile src/source/raster_tile_source.ts A raster tile source. Tiles must be in ZXY or TMS tile format. (See the Style Specification for detailed documentation of options.) Extends Evented . Example Methods setTiles (tiles) Sets the source tiles property and re-renders the map. Parameters tiles ( Array < string > ) An array of one or more tile source URLs, as in the raster tiles spec Returns RasterTileSource : this setUrl (url) Sets the source url property and re-renders the map. Parameters url ( string ) A URL to a TileJSON resource. Supported protocols are http: and https:. Returns RasterTileSource : this Related examples Add a raster tile source Add a WMS source GeoJSON src/source/geojson_source.ts A source containing GeoJSON. (See the Style Specification for detailed documentation of options.) Extends Evented . Example Methods _updateWorkerData (diff?) Responsible for invoking WorkerSource's geojson.loadData target, which handles loading the geojson data and preparing to serve it up as tiles, using geojson-vt or supercluster as appropriate. Parameters diff ( GeoJSONSourceDiff ) The diff object callback ( Callback< Array <GeoJSON.Feature>> ) A callback to be called when the features are retrieved ( (error, features) => { ... } ). Returns Promise<void[]> abortTile (tile) Allows to abort a tile loading. Parameters tile ( Tile ) The tile to abort Returns Promise<void[]> getBounds () Allows getting the source's boundaries. If there's a problem with the source's data, it will return an empty LngLatBounds . Returns Promise<LngLatBounds> : A promise which resolves to the source's boundaries. getClusterChildren (clusterId) For clustered sources, fetches the children of the given cluster on the next zoom level (as an array of GeoJSON features). Parameters clusterId ( number ) The value of the cluster's cluster_id property. Returns Promise<Feature<Geometry,{ [name: string]: any; }>[]> : A promise that is resolved when the features are retrieved. getClusterExpansionZoom (clusterId) For clustered sources, fetches the zoom at which the given cluster expands. Parameters clusterId ( number ) The value of the cluster's cluster_id property. Returns Promise<number> : A promise that is resolved with the zoom number. getClusterLeaves (clusterId, limit, offset) For clustered sources, fetches the original points that belong to the cluster (as an array of GeoJSON features). Parameters clusterId ( number ) The value of the cluster's cluster_id property. limit ( number ) The maximum number of features to return. offset ( number ) The number of features to skip (e.g. for pagination). Returns Promise<Feature<Geometry,{ [name: string]: any; }>[]> : A promise that is resolved when the features are retrieved. Example getData () Allows to get the source's actual GeoJSON data. Returns A promise which resolves to the source's actual GeoJSON data. Promise < GeoJSON > hasTransition () True if the source has transition, false otherwise. Returns boolean loaded () True if the source is loaded, false otherwise. Returns boolean loadTile (tile) This method does the heavy lifting of loading a tile. In most cases it will defer the work to the relevant worker source. Parameters tile ( Tile ) The tile to load Returns Promise<void[]> serialize () This method returns a plain (stringifiable) JS object representing the current state of the source. Creating a source using the returned object as the options should result in a Source that is equivalent to this one. Returns GeoJSONSourceSpecification setClusterOptions (options) To disable/enable clustering on the source options. Parameters options ( SetClusterOptions ) The options to set Returns GeoJSONSource : this Example setData (data) Sets the GeoJSON data and re-renders the map. Parameters data ( ( Object | string ) ) A GeoJSON data object or a URL to one. The latter is preferable in the case of large GeoJSON files. Returns GeoJSONSource : this unloadTile (tile) Allows to unload a tile. Parameters tile ( Tile ) The tile to unload Returns Promise<void[]> updateData (diff) Updates the source's GeoJSON, and re-renders the map. For sources with lots of features, this method can be used to make updates more quickly. This approach requires unique IDs for every feature in the source. The IDs can either be specified on the feature, or by using the promoteId option to specify which property should be used as the ID. It is an error to call updateData on a source that did not have unique IDs for each of its features already. Updates are applied on a best-effort basis, updating an ID that does not exist will not result in an error. Parameters diff ( GeoJSONSourceDiff ) The changes that need to be applied. Returns GeoJSONSource : this Related examples Draw GeoJSON points Add a GeoJSON line Create a heatmap from points Create and style clusters Raster DEM Tile src/source/raster_dem_tile_source.ts A raster DEM source. Only supports Terrain RGB format . (See the Style Specification for detailed documentation of options.) Extends Evented . Example Methods setTiles (tiles) Sets the source tiles property and re-renders the map. Parameters tiles ( Array < string > ) An array of one or more tile source URLs, as in the raster tiles spec Returns RasterDEMTileSource : this setUrl (url) Sets the source url property and re-renders the map. Parameters url ( string ) A URL to a TileJSON resource. Supported protocols are http: and https:. Returns RasterDEMTileSource : this Related examples Add hillshading Image src/source/image_source.ts A data source containing an image. (See the Style Specification for detailed documentation of options.) Extends Evented . Example Methods setCoordinates (coordinates) Sets the image's coordinates and re-renders the map. Parameters coordinates ( Array < Array < number >> ) Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle. Returns ImageSource : this updateImage (options) Updates the image URL and, optionally, the coordinates. To avoid having the image flash after changing, set the raster-fade-duration paint property on the raster layer to 0. Parameters options ( Object ) Options object. options.url string ? Required image URL. options.coordinates Array < Array < number >>? Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle. Returns ImageSource : this Video src/source/video_source.ts A data source containing video. (See the Style Specification for detailed documentation of options.) Extends ImageSource . Example Methods getVideo () Returns the HTML video element. Returns HTMLVideoElement : The HTML video element. pause () Pauses the video. play () Plays the video. prepare () Sets the video's coordinates and re-renders the map. Returns VideoSource : this seek (seconds) Sets playback to a timestamp, in seconds. Parameters seconds ( number ) setCoordinates (coordinates) Sets the video's coordinates and re-renders the map. Parameters coordinates ( Array < Array < number >> ) Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle. Returns VideoSource : this updateImage (options) Updates the image URL and, optionally, the coordinates. To avoid having the image flash after changing, set the raster-fade-duration paint property on the raster layer to 0. Parameters options ( Object ) Options object. options.url string ? Required image URL. options.coordinates Array < Array < number >>? Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle. Returns VideoSource : this Related examples Add a video Canvas src/source/canvas_source.ts A data source containing the contents of an HTML canvas. See canvas source properties for detailed documentation of options. Extends ImageSource . Example Properties options.type string Source type. Must be "canvas" . options.canvas ( string | HTMLCanvasElement ) Canvas source from which to read pixels. Can be a string representing the ID of the canvas element, or the HTMLCanvasElement itself. options.coordinates Array < Array < number >> Four geographical coordinates denoting where to place the corners of the canvas, specified in [longitude, latitude] pairs. options.animate boolean ? Whether the canvas source is animated. If the canvas is static (i.e. pixels do not need to be re-read on every frame), animate should be set to false to improve performance. Methods getCanvas () Returns the HTML canvas element. Returns HTMLCanvasElement : The HTML canvas element. pause () Disables animation. The map will display a static copy of the canvas image. play () Enables animation. The image will be copied from the canvas to the map on each frame. setCoordinates (coordinates) Sets the video's coordinates and re-renders the map. Parameters coordinates ( Array < Array < number >> ) Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle. Returns CanvasSource : this updateImage (options) Updates the image URL and, optionally, the coordinates. To avoid having the image flash after changing, set the raster-fade-duration paint property on the raster layer to 0. Parameters options ( Object ) Options object. options.url string ? Required image URL. options.coordinates Array < Array < number >>? Four geographical coordinates, represented as arrays of longitude and latitude numbers, which define the corners of the image. The coordinates start at the top left corner of the image and proceed in clockwise order. They do not have to represent a rectangle. Returns CanvasSource : this # Layers Source: https://docs.maptiler.com/sdk-js/api/layers/ Layers A layer , also known as a style layer , provides style instructions that describe the visual properties that apply when rendering the layer on a map. The required properties and available options are defined by the GL Style Specification . Except for layers of the background type, each layer needs to refer to a source. Layers take the data that they get from a source, optionally filter features, and then define how those features are styled. # Helpers Source: https://docs.maptiler.com/sdk-js/api/helpers/ Helpers are a set of functions to facilitate the creation of sources and layers. All the helpers are made available under the `helpers` object. ###### Example
```js maptilersdk.helpers.addPolyline(map, { // dataset UUID, a URL (relative or absolute) data: "some-trace.geojson", }); ```
```js import { helpers } from "@maptiler/sdk"; helpers.addPolyline(map, { // dataset UUID, a URL (relative or absolute) data: "some-trace.geojson", }); ```
## Vector layer helpers **Let's make vector layers easy!** Originally, you'd have to add a source and then proceed to the styling of your layer, which can be tricky because there are a lot of paint and layout options and they vary a lot from one type of layer to another. **But we have helpers for this!** Vector Layer Helpers: - [Polyline layer helper](#polyline) - [Polygon layer helper](#polygon) - [Point layer helper](#point) - [Heatmap layer helper](#heatmap) ## Shared logic Helpers come with a lot of **built-in defaults** and some fail-proof logic that makes creating vector layers much easier! As a result, a dataset can be displayed in one call, creating both the datasource and the layer(s) in one go! Depending on the type of feature to add ([point](#point), [polyline](#polyline), [polygon](#polygon) or [heatmap](#heatmap)), a different helper function needs to be used, but datasource could contain mixed types of feature and the helper will only display a specific type. **Example:** we have a *geoJSON* file that contains both *polygons* and *point* and we use it as the data property on the `helpers.addPoint(map, {options})`, this will only add the *points*. In addition to easy styling, helper's datasource can be: - a URL to a geoJSON file or its string content - a URL to a GPX or KML file (only for the polyline helper) or its string content - a UUID of a [MapTiler dataset](https://cloud.maptiler.com/data/) ### Multiple layers The key design principle of these vector layers helpers is **it's easy to make what you want**. Helpers can create multiple layers to represent the symbolization of a layer, if necessary. ###### Example To create a road with an outline with the [polyline layer helper](#polyline), you just say if you want an outline and specify its size (or even a zoom dependant size) and everything is handled for you. As a result, the `helpers.addPolyline` method will return an object with **multiple IDs**: ID of the top/main layer, ID of the outline layer (could be `null`) and the ID of the data source. This makes further layer and source manipulation possible. Without the helpers to create a road with an outline, one must draw two layers: a wider base layer and a narrower top layer, fueled by the same polyline data. This requires ordering the layers properly and computing not the width of the outline, but rather the width of the polyline underneath so that it outgrows the top road layer of the desired number of pixels. ### CommonShapeLayerOptions The vector layer helper also share some *I/O* logic: each of them can take many options but a subset of them is common across all the helpers:
options.layerId?
(string)
ID to give to the layer. If not provided, an auto-generated ID like "maptiler-layer-xxxxxx" will be auto-generated, with "xxxxxx" being a random string.
options.sourceId?
(string)
ID to give to the source. If not provided, an auto-generated ID like "maptiler-source-xxxxxx" will be auto-generated, with "xxxxxx" being a random string.
options.data
(FeatureCollection | string)
A geojson Feature collection or a URL to a geojson or the UUID of a MapTiler dataset.
options.beforeId?
(string)
The ID of an existing layer to insert the new layer before, resulting in the new layer appearing visually beneath the existing layer. If this argument is not specified, the layer will be appended to the end of the layers array and appear visually above all other layers.
options.minzoom?
(number)
default: 0
 Zoom level at which it starts to show.
options.maxzoom?
(number)
default: 22
 Zoom level after which it no longer show.
options.outline?
(boolean)
default: false
 Whether or not to add an outline.
options.outlineColor?
(string | ZoomStringValues)
default: white
 Color of the outline. This is can be a constant color string or a definition based on zoom levels. Applies only if .outline is true.
options.outlineWidth?
(number | ZoomNumberValues)
default: 1
 Width of the outline (relative to screen-space). This is can be a constant width or a definition based on zoom levels. Applies only if .outline is true.
options.outlineOpacity?
(number | ZoomNumberValues)
default: 1
 Opacity of the outline. This is can be a constant opacity in [0, 1] or a definition based on zoom levels. Applies only if .outline is true.
## Polyline layer helper The polyline helper makes it easy to create vector layers that contain polylines. Whenever it's possible and it makes sense, we use the same terminology across the different helpers. ### Methods The method `helpers.addPolyline` is not only compatible with the traditionnal **GeoJSON** source but also with **GPX** and **KML** files and the `data` option can be a MapTiler dataset UUID and will be resolved automatically. Minimal usage, with the default line width and a random color (withing a selected list): ```js import { helpers } from "@maptiler/sdk"; helpers.addPolyline(map, { // dataset UUID, a URL (relative or absolute) data: "some-trace.geojson", }); ``` ### PolylineLayerOptions Extends [CommonShapeLayerOptions](#CommonShapeLayerOptions)
options.lineColor?
(string | ZoomStringValues)
default: a color randomly pick from a list
 Color of the line (or polyline). This is can be a constant color string or a definition based on zoom levels.
options.lineWidth?
(number | ZoomNumberValues)
default: 3
 Width of the line (relative to screen-space). This is can be a constant width or a definition based on zoom levels.
options.lineOpacity?
(number | ZoomNumberValues)
default: 1
 Opacity of the line. This is can be a constant opacity in [0, 1] or a definition based on zoom levels.
options.lineBlur?
(number | ZoomNumberValues)
default: 0
 How blury the line is, with `0` being no blur and `10` and beyond being quite blurry.
options.lineGapWidth?
(number | ZoomNumberValues)
default: 0
 Draws a line casing outside of a line's actual path. Value indicates the width of the inner gap.
options.lineDashArray?
(Array<number> | string)
default: no dash pattern

Sequence of line and void to create a dash pattern. The unit is the line width so that a dash array value of [3, 1] will create a segment worth 3 times the width of the line, followed by a spacing worth 1 time the line width, and then repeat.

Alternatively, this property can be a string made of underscore and whitespace characters such as "___ _ " and internaly this will be translated into [3, 1, 1, 1]. Note that this way of describing dash arrays with a string only works for integer values.

Dash arrays can contain more than 2 element to create more complex patters. For instance a dash array value of [3, 2, 1, 2] will create the following sequence:

  • a segment worth 3 times the width
  • a spacing worth 2 times the width
  • a segment worth 1 times the width
  • a spacing worth 2 times the width
  • repeat
options.lineCap?
("butt" | "round" | "square")
default: "round"
 The display of line endings for both the line and the outline (if .outline is true).
  • "butt": A cap with a squared-off end which is drawn to the exact endpoint of the line.
  • "round": A cap with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
  • "square": A cap with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
options.lineJoin?
("bevel" | "round" | "miter")
default: "round"
 The display of lines when joining for both the line and the outline (if .outline is true).
  • "bevel": A join with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
  • "round": A join with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
  • "miter": A join with a sharp, angled corner which is drawn with the outer sides beyond the endpoint of the path until they meet.
options.outlineBlur?
(number | ZoomNumberValues)
default: 0
 How blury the outline is, with `0` being no blur and `10` and beyond being quite blurry. Applies only if .outline is true.
### Examples Check out the full list of [examples](/sdk-js/examples/?q=polyline+helper). We can add many options, such a a specific color, a custom width or a dash pattern, this time sourcing the data from MapTiler, using the UUID of a dataset: ```js import { helpers } from "@maptiler/sdk"; helpers.addPolyline(map, { data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05", lineColor: "#FF6666", lineWidth: 4, lineDashArray: "____ _ ", lineCap: "butt", }); ``` As you can see, we've come up with a fun and easy way to create **dash arrays**, just use underscores and white spaces and this pattern will repeat! Adding an outline is also pretty straightforward: ```js import { helpers } from "@maptiler/sdk"; helpers.addPolyline(map, { data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05", lineColor: "#880000", outline: true, }); ``` Endless possibilities, what about a glowing wire? ```js import { helpers } from "@maptiler/sdk"; helpers.addPolyline(map, { data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05", lineColor: "#fff", lineWidth: 1, outline: true, outlineColor: "#ca57ff", outlineWidth: 2, outlineWidth: 10, outlineBlur: 10, outlineOpacity: 0.5, }); ``` View more [Polyline layer helper examples](/sdk-js/examples/?q=polyline+helper). ## Polygon layer helper The polygon helper makes it easy to create vector layers that contain polygons, whether they are *multipolygons*, *holedpolygons* or just simple *polygons*. Whenever it's possible and it makes sense, we use the same terminology across the different helpers. ### Methods Minimal usage, with a half-transparent and a random color (withing a selected list) polygon of Switzerland, from a local file: ```js import { helpers } from "@maptiler/sdk"; helpers.addPolygon(map, { data: "switzerland.geojson", fillOpacity: 0.5, }); ``` ### PolygonLayerOptions Extends [CommonShapeLayerOptions](#CommonShapeLayerOptions)
options.fillColor?
(string | ZoomStringValues)
default: a color randomly pick from a list
 Color of the polygon. This is can be a constant color string or a definition based on zoom levels.
options.fillOpacity?
(number | ZoomNumberValues)
default: 1
 Opacity of the polygon. This is can be a constant opacity in [0, 1] or a definition based on zoom levels.
options.outlinePosition?
("center" | "inside" | "outside")
default: "center"
 Position of the outline with regard to the polygon edge (when .outline is true).
options.outlineDashArray?
(Array<number> | string)
default: no dash pattern

Sequence of line and void to create a dash pattern. The unit is the line width so that a dash array value of [3, 1] will create a segment worth 3 times the width of the line, followed by a spacing worth 1 time the line width, and then repeat.

Alternatively, this property can be a string made of underscore and whitespace characters such as "___ _ " and internaly this will be translated into [3, 1, 1, 1]. Note that this way of describing dash arrays with a string only works for integer values.

Dash arrays can contain more than 2 element to create more complex patters. For instance a dash array value of [3, 2, 1, 2] will create the following sequence:

  • a segment worth 3 times the width
  • a spacing worth 2 times the width
  • a segment worth 1 times the width
  • a spacing worth 2 times the width
  • repeat
options.outlineCap?
("butt" | "round" | "square")
default: "round"
 The display of line endings for both the line and the outline (if .outline is true).
  • "butt": A cap with a squared-off end which is drawn to the exact endpoint of the line.
  • "round": A cap with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
  • "square": A cap with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
options.outlineJoin?
("bevel" | "round" | "miter")
default: "round"
 The display of lines when joining for both the line and the outline (if .outline is true).
  • "bevel": A join with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.
  • "round": A join with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.
  • "miter": A join with a sharp, angled corner which is drawn with the outer sides beyond the endpoint of the path until they meet.
options.pattern?
(string | null)
default: null (no pattern, fillColor will be used)
 The pattern is an image URL to be put as a repeated background pattern of the polygon.
options.outlineBlur?
(number | ZoomNumberValues)
default: 0
 How blury the outline is, with `0` being no blur and `10` and beyond being quite blurry. Applies only if .outline is true.
### Examples Check out the full list of [examples](/sdk-js/examples/?q=polygon+helper). We can add many options, such a a specific color, a custom width or a pattern, this time sourcing the data from MapTiler, using the UUID of a dataset: ```js import { helpers } from "@maptiler/sdk"; helpers.addPolygon(map, { data: "aa203ccf-25ee-4447-bef3-55f90916897a", pattern: "cheese512.png", outline: true, outlineWidth: 3, outlineColor: "white", outlineDashArray: "_ ", fillOpacity: 0.7, }); ``` View more [Polygon layer helper examples](/sdk-js/examples/?q=polygon+helper). ## Point layer helper A point visualisation may appear like the simplest of all, but we noticed this is where people get the most creative: cluster, data-drive variable radius, but also scaled with zoom, with or without labels, data-driven colors, etc. Our helper supports all of these and will fill-in with built-in default for what's missing. Whenever it's possible and it makes sense, we use the same terminology across the different helpers. ### Methods Here is the simplest example, with a dataset loaded from a local file (if no color is specified, a random color is used and the default radius is ramped over the zoom level): ```js import { helpers } from "@maptiler/sdk"; helpers.addPoint(map, { data: "public-schools.geojson", }); ``` ### PointLayerOptions Extends [CommonShapeLayerOptions](#CommonShapeLayerOptions)
options.pointColor?
(string | ZoomStringValues)
default: a color randomly pick from a list

Color of the point. This is can be a constant color string or a definition based on zoom levels.

Can be a unique point color as a string (CSS color such as "#FF0000" or "red"). Alternatively, the color can be a ColorRamp with a range.

In case of .cluster being true, the range of the ColorRamp will be addressed with the number of elements in the cluster. If .cluster is false, the color will be addressed using the value of the .property. If no .property is given but .pointColor is a ColorRamp, the chosen color is the one at the lower bound of the ColorRamp.

options.pointRadius?
(number | ZoomNumberValues)
default: The radius will be between .minPointRadius and .maxPointRadius

Radius of the points. Can be a fixed size or a value dependant on the zoom.

If .pointRadius is not provided, the radius will depend on the size of each cluster (if .cluster is true) or on the value of each point (if .property is provided and .pointColor is a ColorRamp).

options.minPointRadius?
(number)
default: 10
 The minimum point radius posible.
options.maxPointRadius?
(number)
default: 40
 The maximum point radius posible.
options.property?
(string)
default: none
 The point property to observe and apply the radius and color upon. This is ignored if .cluster is true as the observed value will be fiorced to being the number of elements in each cluster.
options.pointOpacity?
(number | ZoomNumberValues)
default: 1

Opacity of the point or icon. This is can be a constant opacity in [0, 1] or a definition based on zoom levels.

Alternatively, if not provided but the .pointColor is a ColorRamp, the opacity will be extracted from tha alpha component if present.

options.alignOnViewport?
(boolean)
default: true
 If true, the points will keep their circular shape align with the wiewport. If false, the points will be like flatten on the map. This difference shows when the map is tilted.
options.cluster?
(boolean)
default: false
 Whether the points should cluster
options.showLabel?
(boolean)
default: true if .cluster or dataDrivenStyleProperty are used, false otherwise
 Shows a label with the numerical value id true. If .cluster is true, the value will be the number of elements in the cluster.
options.labelColor?
(string)
default: white
 Text color used for the number elements in each cluster. Applicable only when .cluster is true or dataDrivenStyleProperty are used.
options.labelSize?
(number)
default: 12
 Text size used for the number elements in each cluster. Applicable only when .cluster is true.
options.zoomCompensation?
(boolean)
default: true
 Only if .cluster is false. If the radius is driven by a property, then it will also scale by zoomming if .zoomCompensation is true. If false, the radius will not adapt according to the zoom level.
### Examples Check out the full list of [examples](/sdk-js/examples/?q=point+helper). Here is the same dataset, but with point clustering enabled: ```js import { helpers } from "@maptiler/sdk"; helpers.addPoint(map, { data: "public-schools.geojson", cluster: true, }); ``` On the other hand, if clusters are enabled, the default color is fueled by the color ramp `TURBO` scaled from `10` to `10000` non-linearly resampled with the method `"ease-out-square"`. The size also varies from `minPointradius` (default: `10`) to `maxPointRadius` (default: `50`): With the point helper, it's also possible to adapt the color and the radius based on a property. In the following example, we display a point for each public school, with the scaling factor being the number of students: ```js import { helpers } from "@maptiler/sdk"; helpers.addPoint(map, { data: "public-schools.geojson", property: "students", pointColor: ColorRampCollection.PORTLAND.scale(200, 2000).resample("ease-out-sqrt"), pointOpacity: 0.8, minPointRadius: 6, maxPointRadius: 30, showLabel: true, zoomCompensation: false, }) ``` Here, the `PORTLAND` color ramp is going to be used so that schools with `200` students or less will have the colors at the very begining of the color ramp and schools with `2000` or more will have the color defined at the very end. Schools in between will be attributed a colors in a non-linear fashion, following the `"ease-out-sqrt"` method (read [Color ramps](/sdk-js/api/color-ramp/) section for more info). View more [Point layer helper examples](/sdk-js/examples/?q=point+helper). ## Heatmap layer helper The heatmap layer is a great alternative for visualizing a collection of sparse data, but they can be challenging to use, especially when one has to come up with their own color ramp from scratch. **The helper makes this much easier!** Whenever it's possible and it makes sense, we use the same terminology across the different helpers. ### Methods Here is a minimalist example, using the default built-in `TURBO` color ramp: ```js import { helpers } from "@maptiler/sdk"; helpers.addHeatmap(map, { data: "public-schools.geojson", }); ``` ### HeatmapLayerOptions
options.layerId?
(string)
ID to give to the layer. If not provided, an auto-generated ID like "maptiler-layer-xxxxxx" will be auto-generated, with "xxxxxx" being a random string.
options.sourceId?
(string)
ID to give to the source. If not provided, an auto-generated ID like "maptiler-source-xxxxxx" will be auto-generated, with "xxxxxx" being a random string.
options.data
(FeatureCollection | string)
A geojson Feature collection or a URL to a geojson or the UUID of a MapTiler dataset.
options.beforeId?
(string)
The ID of an existing layer to insert the new layer before, resulting in the new layer appearing visually beneath the existing layer. If this argument is not specified, the layer will be appended to the end of the layers array and appear visually above all other layers.
options.minzoom?
(number)
default: 0
 Zoom level at which it starts to show.
options.maxzoom?
(number)
default: 22
 Zoom level after which it no longer show.
options.colorRamp?
(ColorRamp)
default: ColorRampCollection.TURBO
 The ColorRamp instance to use for visualization. The color ramp is expected to be defined in the range [0, 1] or else will be forced to this range.
options.property?
(string)
default: none, the points will all have a weight of 1
 Use a property to apply a weight to each data point. Using a property requires also using the options .propertyValueWeight or otherwise will be ignored.
options.weight?
(number | PropertyValues )

The weight to give to each data point. If of type PropertyValueWeights , then the options .property must also be provided. If used a number, all data points will be weighted by the same number (which is of little interest).

options.radius?
(number | ZoomNumberValues | PropertyValues )

Radius in screenspace. Can be:

  • A fixed number that will be constant across zoom level.
  • A type ZoomNumberValues to be ramped accoding to zoom level (.zoomCompensation will then be ignored).
  • A type PropertyValues to be driven by the value of a property. If so, the option .property must be provided and will still be resized according to zoom level, unless the option .zoomCompensation is set to false.
options.opacity?
(number | ZoomNumberValues)
default: fades-in 0.25z after minzoom and fade-out 0.25z before maxzoom

The opacity can be a fixed value or zoom-driven.

options.intensity?
(number | ZoomNumberValues)
default: the intensity is going to be scaled by zoom to preserve a natural aspect or the data distribution

The intensity is zoom-dependent.

options.zoomCompensation?
(boolean)
default: true
 If the radius is driven by a property, then it will also scale by zoomming if .zoomCompensation is true. If false, the radius will not adapt according to the zoom level.
### Examples Check out the full list of [examples](/sdk-js/examples/?q=heatmap+helper). Some visualisations are created with a fixed geographic extent or zoom level in mind, whether it's a survey at the scale of a single neigbohood, or statitics at country scale. In this case, we want to tailor the color, radius, weight and intensity of the heatmap blobs exactely for this precise settings. In the following example, we disable the zoom compensation to make sure radii and intensity is never zoom-dependant: ```js import { helpers } from "@maptiler/sdk"; helpers.addHeatmap(map, { data: "public-schools.geojson", property: "students", // radius: how wide are the blobs radius: [ {propertyValue: 100, value: 15}, {propertyValue: 800, value: 50}, ], // weight: how intense are the blob, as fueled by a property weight: [ {propertyValue: 100, value: 0.1}, {propertyValue: 800, value: 1}, ], // A custom color ramp, must be used with its default interval of [0, 1] colorRamp: ColorRampCollection.MAGMA, zoomCompensation: false, opacity: 0.6, // a global factor applied to all the blobs, regardless of the property or zoom intensity: 1.2, }); ``` Turning off *zoom compensation* allows for more accurate adjustments to the visualization at a specific zoom level, but it may not adapt as smoothly when zooming in or out. View more [Heatmap layer helper examples](/sdk-js/examples/?q=heatmap+helper). ## Take screenshot helper The screenshot helper provides a quick and easy solution for capturing the current map view as a PNG image file, making it the most convenient way to save map snapshots. > [!WARNING] > Screenshots will not contain *DOM elements* such as `Marker` and `Popup`, since those are not part of the rendering context. ### Methods Here is a minimalist example to get a `blob` (PNG encoded): ```js import { Map, helpers } from "@maptiler/sdk"; // ... initialize a Map instance, wait for the "load" or "ready" event ... // Inside an async function, or with using .then() const blob = await helpers.takeScreenshot(map); ``` ### TakeScreenshotOptions
options.download?
(boolean)
default: false
 If true, this function will trigger a download in addition to returning a blob.
options.filename?
(string)
default: "maptiler_screenshot.png"
 Only if options.download is true. Indicates the filename under which the file will be downloaded.
### Examples Check out the full list of [examples](/sdk-js/examples/?q=screenshot+helper). There are two different ways to create screenshot, corresponding to two very different usecases. Note that screenshots will not contain *DOM elements* such as `Marker` and `Popup`, since those are not part of the rendering context. ##### Get a `blob` of a screenshot, PNG encoded ```js import { Map, helpers } from "@maptiler/sdk"; // ... initialize a Map instance, wait for the "load" or "ready" event ... // Inside an async function, or with using .then() const blob = await helpers.takeScreenshot(map); ``` The returned `blob` of a PNG image file can be very handy if the goal is to programmatically further manipulate the screenshot, such as sending it to some feedback endpoint with a POST request. ##### Download a PNG file ```js import { Map, helpers } from "@maptiler/sdk"; // ... initialize a Map instance, wait for the "load" or "ready" event ... // No need to be inside an async function, the download will be triggered when the file is ready maptilersdk.helpers.takeScreenshot(map, { download: true, filename: "map_screenshot.png" }); ``` Getting a file directly is a nice option that can be useful to share some debugging context with colleagues, compare multiple styles, or share your creation on social media. > [!INFO] > Keep in mind that MapTiler data are copyrighted and their usage is restricted. This include MapTiler built-in styles and tilesets, among others. In case of doubt, do not hesitate to read our [terms](https://www.maptiler.com/terms/) or to ask our [support team](https://www.maptiler.com/contacts/). ## Other helpers ### Convert GPX and KML to GeoJSON In the [Polyline layer helper](#polyline) section above, we have seen that one can feed the helper directly with a path to a GPX or KML file, that is then converted under the hood client-side into a GeoJSON `FeatureCollection` object. This conversion feature is also exposed and can be used as such: ```js import { gpx } from "@maptiler/sdk"; // ... assuming inside an async function // Fetching the GPX file as a string: const gpxFilePath = "some_gps_trace.gpx"; const gpxResponse = await fetch(gpxFilePath); const gpxStr = await gpxResponse.text(); // Converting the GPX payload into a GeoJSON FeatureCollection: const features = maptilersdk.gpx(gpxStr); //or const features = gpx(gpxStr); ``` And for KML files: ```js import { kml } from "@maptiler/sdk"; // ... assuming inside an async function // Fetching the KML file as a string: const kmlFilePath = "some_gps_trace.kml"; const kmlResponse = await fetch(kmlFilePath); const kmlStr = await kmlResponse.text(); // Converting the KML payload into a GeoJSON FeatureCollection: const features = maptilersdk.kml(kmlStr); //or const features = kml(kmlStr); ``` ##### Types and interfaces ###### ZoomStringValues Array of string values that depend on zoom level ```js Array<{ zoom: number, // Zoom level value: string // Value for the given zoom level }> ``` ###### ZoomNumberValues Array of number values that depend on zoom level ```js Array<{ zoom: number, // Zoom level value: number // Value for the given zoom level }> ``` ###### PropertyValues ```js Array<{ propertyValue: number, // Value of the property (input) value: number // Value to associate it with (output) }> ``` # Controls Source: https://docs.maptiler.com/sdk-js/api/controls/ The term "control" is commonly used for all sorts of buttons and information display that take place in one of the corner of the map area. The most well know are probably the `[+]` and `[-]` zoom buttons as well as the attribution information. User interface elements that can be added to the map. The items in this section exist outside of the map's `canvas` element. ## Easy to add controls ![MapTiler logo](/favicon.ico) The easiest way to add the most used controls is through the [Map constructor options](/sdk-js/api/map/#map-options). To add a control in the map constructor, you must indicate the name of the control and one of these values: `true` to add the control or `false` to hide the control. You can also indicate in which position we are going to add the control: `top-left`, `top-right`, `bottom-left`, `bottom-right`. ### Example ```js const map = new maptilersdk.Map({ container: document.getElementById("my-container-div"), terrainControl: true, scaleControl: true, fullscreenControl: "top-left", geolocateControl: false }) ``` These are the controls that are directly accessible in the map constructor: - `navigationControl`: Shows the `[+]`, `[-]` zoom buttons and tilt/bearing/compass buttons. Showing on the `top-right` by default. - `geolocateControl`: Shows a arrow-shaped locate button. When clicked, it adds a marker and center the map. If clicked again, the marker disapears (unless the map was moved since first clicked). Showing on the `top-right` by default. - `terrainControl`: Shows a button to enable/disable the 3D terrain (does not tilt the map). Hidden by default, showing on the `top-right` if true. - `scaleControl`: Shows a distance scale. The unit ("metric", "imperial" or "nautical") can be set in the [config object](/sdk-js/api/config/) config.unit (default: "metric"). Hidden by default, showing on the `bottom-right` if true. - `fullscreenControl`: Shows a button that toggles the map into fullscreen. Hidden by default, showing on the `top-right` if true. ## Custom controls ![MapTiler logo](/favicon.ico) MapTiler SDK JS supports two flexible ways to add custom controls to your map interface, depending on the level of control and flexibility you need. ### Related examples - [How to add a custom control programmatically](/sdk-js/examples/custom-controls-programmatic/) - [Add a custom control declarative way](/sdk-js/examples/custom-controls-declarative/) ### Programmatic Controls Programmatic controls allow developers to have more control and register custom control elements manually by calling `map.addControl()` and providing a control implementation. This method is ideal for applications that require dynamic logic, event-based behaviour, or a deeper integration with a framework like React. Custom controls are instantiated using the [`MaptilerCustomControl`](#maptilercustomcontrol) class. The element that should be used can be provided either as the **element itself**, or as its **CSS selector**. Optionally, two callback functions can be provided: - `onClick` function that is called when the element is clicked, and - `onRender` function that is called every time the map renders a new state. Both callbacks receive the active `Map` instance, the associated control element itself, and an event object associated with the original event (`PointerEvent` and `MapLibreEvent` respectively). #### Example ```js const panControl = new maptilersdk.MaptilerCustomControl( ".pan-control", (map) => map.panBy([10, 10]), // Move southeast when clicked (map, el) => el.classList.toggle( // Change class based on current hemisphere "northern-hemisphere", map.getCenter().lat > 0 ) ); map.addControl(panControl); const element = document.createElement("button"); element.className = "btn btn-primary pan-nw" element.textContent = "Pan NW"; map.addControl( new maptilersdk.MaptilerCustomControl( element, (map) => map.panBy([-10, -10]) // Move northwest when clicked ), "top-left" ); ``` Example: [How to add a custom control programmatically](/sdk-js/examples/custom-controls-programmatic/) #### Behaviour Overview - Upon adding, the control element is removed from its original DOM position and inserted into the map UI. - The `onClick` callback binds an action to user interaction. - The `onRender` callback can be used for state-based updates, styling, or other custom logic. - The control is treated as a native part of the map UI but maintains its own DOM context. - Upon removing, the control element is moved back into its original DOM position (if any) to not interfere with DOM handling of frameworks like React. ### Declarative Controls Declarative controls offer a simple way to add interactive UI elements to the map by using HTML attributes alone. Instead of instantiating controls through JavaScript, developers annotate DOM elements and allow the SDK to discover and wire them automatically. Declarative controls are instantiated under the hood using the [`MaptilerExternalControl`](#maptilerexternalcontrol) class. #### Example [Add a custom control declarative way](/sdk-js/examples/custom-controls-declarative/) #### Enabling Detection To activate declarative control detection: - Set the `customControls` option to `true` in the map initialization configuration, to enable detection globally. - Alternatively, `customControls` may be set to a **CSS selector string**, to scope the autodetection to: - Elements matching the selector directly - Or elements whose **ancestor** matches the selector ```js const map = new maptilersdk.Map({ container: "map", customControls: true, // or ".custom-ui" }); ``` #### Declaring a Control To declare a control element, use the `data-maptiler-control` attribute: ```html ``` The attribute’s value must be one of the predefined keywords, or an empty value. The element is automatically registered as a control and moved into the map UI. Supported values: | Value | Description | |---|---| | `zoom-in` | zooms the map in | | `zoom-out` | zooms the map out | | `toggle-projection` | toggles between Mercator and Globe projections | | `toggle-terrain` | turns Terrain layer on and off | | `reset-view` | resets bearing, pitch, and roll to 0 (heading north, no pitch, no roll) | | `reset-bearing` | resets bearing to 0 (heading north) | | `reset-pitch` | resets pitch to 0 (no pitch) | | `reset-roll` | resets roll to 0 (no roll) | | *empty value* | registers the element as control but does not add any functionality automatically | > [!WARNING] > An Error is thrown when an unrecognized value is used. #### Grouping Controls For grouping related controls together, use the `data-maptiler-control-group` attribute. This approach is ideal for styling multiple buttons as a single floating UI block. ```html
``` - The **group container** (`data-maptiler-control-group`) is registered as a control and moved into the map UI. - It does **not** receive any automatic functionality. - Functional behaviour is attached to valid descendant elements with `data-maptiler-control`. #### Positioning Controls To set a specific position for a control or group, use the `data-maptiler-position`. The allowed values are the same as in [addControl](/sdk-js/api/map/#map#addcontrol) method. ```html
``` #### State Styling via CSS To support dynamic styling based on map state (without relying on JavaScript), custom CSS variables are set directly on the map container when declarative controls are enabled. Available CSS properties: | Property | Description | Data type | |---|---|---| | `--maptiler-center-lng` | Longitude of map center | unitless number | | `--maptiler-center-lat` | Latitude of map center | unitless number | | `--maptiler-zoom` | Current zoom level | unitless number | | `--maptiler-bearing` | Current map bearing (rotation) | unitless number | | `--maptiler-pitch` | Pitch angle | unitless number | | `--maptiler-roll` | Roll angle | unitless number | | `--maptiler-is-globe-projection` | `true` if globe view is enabled, `false` otherwise | string | | `--maptiler-has-terrain` | `true` if terrain is active, `false` otherwise | string | This enables responsive UI tweaks via pure CSS, for example: ```css /* transform compass icon based on bearing and pitch */ .compass-icon { transform: rotateX(calc(var(--maptiler-pitch) * 1deg)) rotateZ(calc(var(--maptiler-bearing) * -1deg)); } /* change projection button icon when Globe projection is on */ @container style(--maptiler-is-globe-projection: true) { .projection-icon { content: "globe"; } } ``` ## MaptilerNavigationControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/ui/control/globe_control.ts

A `MaptilerNavigationControl` control contains zoom buttons and a compass. Behavior changes: - When enabled, the pitch button is always present. - The pitch button now pitches the map if it was not (and as before, unpitches the map if pitched). - The compass icon on the pitch button has a capped “squeeziness” factor to prevent it from looking extra flat and wide when pitch is set higher than 60. ### Example ```js const nav = new maptilersdk.MaptilerNavigationControl(); map.addControl(nav, 'top-left'); ``` ### Parameters **options** (`Object?`)
options.showCompass
Boolean
default: true
 If true the compass button is included.
options.showZoom
Boolean
default: true
 If true the zoom-in and zoom-out buttons are included.
options.visualizePitch
Boolean
default: false
 If true the pitch is visualized by rotating X-axis of compass.
### Related examples - [Display map navigation controls](/sdk-js/examples/navigation/) - [Add a third party vector tile source](/sdk-js/examples/third-party/) ## MaptilerGeolocateControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/MaptilerGeolocateControl.ts

A `MaptilerGeolocateControl` control provides a button that uses the browser's geolocation API to locate the user on the map. Not all browsers support geolocation, and some users may disable the feature. Geolocation support for modern browsers including Chrome requires sites to be served over HTTPS. If geolocation support is not available, the `MaptilerGeolocateControl` will show as disabled. The zoom level applied will depend on the accuracy of the geolocation provided by the device. The `MaptilerGeolocateControl` has two modes. If `trackUserLocation` is `false` (default) the control acts as a button, which when pressed will set the map's camera to target the user location. If the user moves, the map won't update. This is most suited for the desktop. If `trackUserLocation` is `true` the control acts as a toggle button that when active the user's location is actively monitored for changes. In this mode the `MaptilerGeolocateControl` has three interaction states: - **active** - the map's camera automatically updates as the user's location changes, keeping the location dot in the center. Initial state and upon clicking the `MaptilerGeolocateControl` button. - **passive** - the user's location dot automatically updates, but the map's camera does not. Occurs upon the user initiating a map movement. - **disabled** - occurs if Geolocation is not available, disabled or denied. These interaction states can't be controlled programmatically, rather they are set based on user interactions. Behavior changes: - Now with these defaults: - `enableHighAccuracy`: true (uses browser location, probably GPS) - `maximumAge`: 0 (not using any cached location) - `Timeout`: 6000 (6 seconds) - `trackUserLocation`: true - When geolocate is “active”, zooming/rotating/pitching the map no longer changes the status to “background” because it does not change the center of the map. The center of the map must move of at least 1 m (world) from the active locked position in order for the status to change to “background” (note: the “background” status means the location is still refreshed but if the user moves, the map will no longer continue to be centered on them). - The method to update the blue disc (location precision radius) has been improved as we zoom in. It is now less shaky and behave according to perspective when the camera is tilted. Extends [Evented](/sdk-js/api/events/#evented). ### Example ```js map.addControl(new maptilersdk.MaptilerGeolocateControl({ positionOptions: { enableHighAccuracy: true }, trackUserLocation: true }), 'top-left'); ``` ### Parameters **options** (`Object?`)
options.positionOptions
Object
default: {enableHighAccuracy:false,timeout:6000}
 A Geolocation API PositionOptions object.
options.fitBoundsOptions
Object
default: {maxZoom:15}
 A Map#fitBounds options object to use when the map is panned and zoomed to the user's location. The default is to use a maxZoom of 15 to limit how far the map will zoom in for very accurate locations.
options.trackUserLocation
Object
default: false
 If true the Geolocate Control becomes a toggle button and when active the map will receive updates to the user's location as it changes.
options.showAccuracyCircle
Object
default: true
 By default, if showUserLocation is true, a transparent circle will be drawn around the user location indicating the accuracy (95% confidence level) of the user's location. Set to false to disable. Always disabled when showUserLocation is false.
options.showUserLocation
Object
default: true
 By default a dot will be shown on the map at the user's location. Set to false to disable.
### Methods ### Events ### Related examples - [Locate the user](/sdk-js/examples/geolocate-control/) ## MaptilerTerrainControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/MaptilerTerrainControl.ts

The `MaptilerTerrainControl` shows a button to enable/disable the 3D terrain (does not tilt the map). ### Example ```js const terrain3d = new maptilersdk.MaptilerTerrainControl(); map.addControl(terrain3d, 'top-left'); ``` ### Related examples - [Display a 3D terrain map](/sdk-js/examples/3d-map/) ## AttributionControl

GitHubLogosrc/ui/control/attribution_control.ts

An `AttributionControl` control presents the map's attribution information. By default, the attribution control is expanded (regardless of map width). ### Example ```js const map = new maptilersdk.Map({attributionControl: false}) .addControl(new maptilersdk.AttributionControl({ compact: true })); ``` ### Parameters **options** (`Object?`) (default `{}`)
options.compact
boolean?
If true, the attribution control will always collapse when moving the map.
If false (default), use expanded attribution control that is always visible.
If "auto" or undefined, use responsive attribution that collapses when the user moves the map on maps less than 640 pixels wide.
Attribution should not be collapsed if it can comfortably fit on the map. compact should only be used to modify default attribution when map size makes it impossible to fit default attribution and when the automatic compact resizing for default settings are not sufficient. Always prefer "auto" to true to show the attribution uncollapsed on large maps.
options.customAttribution
(string | Array<string>)?
String or strings to show in addition to any other attributions.
## ScaleControl

GitHubLogosrc/ui/control/scale_control.ts

A `ScaleControl` control displays the ratio of a distance on the map to the corresponding distance on the ground. ### Example ```js const scale = new maptilersdk.ScaleControl({ maxWidth: 80, unit: 'imperial' }); map.addControl(scale); scale.setUnit('metric'); ``` ### Parameters **options** (`Object?`)
options.maxWidth
number
default: '100'
 The maximum length of the scale control in pixels.
options.unit
string
default: 'metric'
 Unit of the distance ('imperial', 'metric' or 'nautical').
### Methods ## FullscreenControl

GitHubLogosrc/ui/control/fullscreen_control.ts

A `FullscreenControl` control contains a button for toggling the map in and out of fullscreen mode. ### Example ```js map.addControl(new maptilersdk.FullscreenControl({container: document.querySelector('body')})); ``` ### Parameters **options** (`Object?`)
options.container
HTMLElement?
 container is the compatible DOM element which should be made full screen. By default, the map container element will be made full screen.
### Related examples - [View a fullscreen map](/sdk-js/examples/fullscreen/) ## MaptilerLogoControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/MaptilerLogoControl.ts

A `MaptilerLogoControl` replaces MaplibreLogoControl. Can be used only with paid account. ### Example ```js const logo = new maptilersdk.MaptilerLogoControl({ logoURL: "https://api.maptiler.com/resources/logo.svg", linkURL: "https://www.maptiler.com" }); map.addControl(logo, 'bottom-left'); ``` ### Parameters **options** (`Object?`)
options.logoURL
string
default: ""
 Image logo URL.
options.linkURL
string
default: ""
 Logo link URL
## MaptilerMinimapControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/Minimap.ts

A `MaptilerMinimapControl` control. Display a overview (minimap) in a user defined corner of the map. ### Parameters **options** (`Object?`)
options.style MapTiler logo
(ReferenceMapStyle | MapStyleVariant | string | StyleSpecification)?
The map's style. This must be:
  • ReferenceMapStyle (e.g. MapStyle.STREETS)
  • MapStyleVariant (e.g. MapStyle.STREETS.DARK)
  • MapTIler Style ID (e.g. “”)
  • uuid of custom style
  • an a JSON object conforming to the schema described in the GL Style Specification
  • a URL to such JSON.
options.zoomAdjust
number?
default: -4
 Set the zoom difference between the parent and the minimap. If the parent is zoomed to 10 and the minimap is zoomed to 8, the zoomAdjust should be 2.
options.lockZoom
number?
Set a zoom of the minimap and don't allow any future changes.
options.pitchAdjust
boolean?
default: false
 Adjust the pitch only if the user requests.
options.containerStyle
Record<string, string>?
Set CSS properties of the container using object key-values.
options.position
string?
default: 'bottom-left'
 Set the position of the minimap. Valid values are 'top-left', 'top-right', 'bottom-left', and 'bottom-right'.
options.parentRect
ParentRect?
Set the parentRect fill and/or line options.
## MaptilerProjectionControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/ui/control/globe_control.ts

A `MaptilerProjectionControl` control contains a button for toggling the map projection between "mercator" and "globe". ### Example ```js map.addControl(new maptilersdk.MaptilerProjectionControl()); ``` ### Related examples - [Projection control how to toggle the map between mercator and globe projection](/sdk-js/examples/globe-control/) ## MaptilerExternalControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/controls/MaptilerExternalControl.ts

The `MaptilerExternalControl` allows any existing element to automatically become a map control. Used for detected controls if `customControls` config is turned on. ### Example ```js const zoomInControl = new maptilersdk.MaptilerExternalControl( ".zoom-in-control", "zoom-in" ); ``` ### Parameters - **controlElement** (`HTMLElement`): Element to be used as control, specified as either reference to element itself or a CSS selector to find the element in DOM - **controlType** (`MaptilerExternalControlType`): One of the predefined types of functionality. Allowed values: `zoom-in` | `zoom-out` | `toggle-projection` | `toggle-terrain` | `reset-view` | `reset-bearing` | `reset-pitch` | `reset-roll` ## MaptilerCustomControl ![MapTiler logo](/favicon.ico)

GitHubLogosrc/controls/MaptilerCustomControl.ts

The `MaptilerCustomControl` allows any existing element to become a map control. ### Example ```js const panControl = new maptilersdk.MaptilerCustomControl( ".pan-control", (map) => map.panBy([10, 10]), // Move southeast when clicked (map, el) => el.classList.toggle( // Change class based on current hemisphere "northern-hemisphere", map.getCenter().lat > 0 ) ); ``` ### Parameters - **selectorOrElement** (`string` | `HTMLElement`): Element to be used as control, specified as either reference to element itself or a CSS selector to find the element in DOM - **onClick** (`MaptilerCustomControlCallback?`): Function called when the element is clicked - **onRender** (`MaptilerCustomControlCallback?`): Function called every time the underlying map renders a new state > [!INFO] > Both callbacks receive the active `Map` instance, the associated control element itself, and an event object associated with the original event (`PointerEvent` and `MapLibreEvent` respectively). ### Related examples - [How to add a custom control programmatically](/sdk-js/examples/custom-controls-programmatic/) ## IControl

GitHubLogosrc/ui/control/control.ts

Interface for interactive controls added to the map. This is a specification for implementers to model: it is not an exported method or class. This interface is the one to use to create custom controls. Controls must implement `onAdd` and `onRemove`, and must own an element, which is often a `div` element. To use MapLibre GL JS's default control styling, add the `maplibregl-ctrl` class to your control's node. ### Example ```js // Control implemented as ES6 class class HelloWorldControl { onAdd(map) { this._map = map; this._container = document.createElement('div'); this._container.className = 'maplibregl-ctrl'; this._container.textContent = 'Hello, world'; return this._container; } onRemove() { this._container.parentNode.removeChild(this._container); this._map = undefined; } } // Control implemented as ES5 prototypical class function HelloWorldControl() { } HelloWorldControl.prototype.onAdd = function(map) { this._map = map; this._container = document.createElement('div'); this._container.className = 'maplibregl-ctrl'; this._container.textContent = 'Hello, world'; return this._container; }; HelloWorldControl.prototype.onRemove = function () { this._container.parentNode.removeChild(this._container); this._map = undefined; }; ``` ### Methods # Coordinates Source: https://docs.maptiler.com/sdk-js/api/geography/ Coordinates General utilities and types that relate to working with and manipulating geographic information or geometries. LngLat src/geo/lng_lat.ts A LngLat object represents a given longitude and latitude coordinate, measured in degrees. These coordinates are based on the WGS84 (EPSG:4326) standard . SDK JS uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match the GeoJSON specification . Note that any SDK JS method that accepts a LngLat object as an argument or option can also accept an Array of two numbers and will perform an implicit conversion. This flexible type is documented as LngLatLike . Example Parameters lng ( number ) Longitude, measured in degrees. lat ( number ) Latitude, measured in degrees. Static Members convert (input) Converts an array of two numbers or an object with lng and lat or lon and lat properties to a LngLat object. If a LngLat object is passed in, the function returns it unchanged. Parameters input ( LngLatLike ) An array of two numbers or object to convert, or a LngLat object to return. Returns LngLat : A new LngLat object, if a conversion occurred, or the original LngLat object. Example Methods distanceTo (lngLat) Returns the approximate distance between a pair of coordinates in meters Uses the Haversine Formula (from R.W. Sinnott, "Virtues of the Haversine", Sky and Telescope, vol. 68, no. 2, 1984, p. 159) Parameters lngLat ( LngLat ) coordinates to compute the distance to Returns number : Distance in meters between the two coordinates. Example toArray () Returns the coordinates represented as an array of two numbers. Returns Array < number > : The coordinates represeted as an array of longitude and latitude. Example toString () Returns the coordinates represent as a string. Returns string : The coordinates represented as a string of the format 'LngLat(lng, lat)' . Example wrap () Returns a new LngLat object whose longitude is wrapped to the range (-180, 180). Returns LngLat : The wrapped LngLat object. Example Related examples Get coordinates of the mouse pointer Display a popup Create a timeline animation Point src/Point.ts A Point two numbers representing x and y screen coordinates in pixels. Example Parameters x ( number ) Longitude, measured in degrees. y ( number ) Latitude, measured in degrees. Static Members convert (a | p) Construct a point from an array if necessary, otherwise if the input is already a Point, or an unknown type, return it unchanged. Parameters a ( Array[number] ) An array of two numbers p ( Point ) the point to return Returns Point : The new constructed point, or passed-through value.. Example Methods add (p) Add this point's x & y coordinates to another point, yielding a new point. Parameters p ( Point ) the other point Returns Point : The new point. Example angle () Get the angle from the 0, 0 coordinate to this point, in radians coordinates. Returns number : The angle in radians. Example angleTo (p) Get the angle from this point to another point, in radians Parameters p ( Point ) the other point Returns number : The angle in radians. Example angleWith (p) Get the angle between this point and another point, in radians Parameters p ( Point ) the other point Returns number : The angle in radians. Example angleWithSep (x, y) Find the angle of the two vectors, solving the formula for the cross product a x b = |a||b|sin(θ) for θ. Parameters x ( number ) the x-coordinate y ( number ) the y-coordinate Returns number : The angle in radians. Example clone () Clone this point, returning a new point that can be modified without affecting the old one. Returns Point : The new point. Example dist (p) Calculate the distance from this point to another point. Parameters p ( Point ) the other point Returns number : The distance. Example distSqr (p) Calculate the distance from this point to another point, without the square root step. Useful if you're comparing relative distances. Parameters p ( Point ) the other point Returns number : The distance. Example div (k) Divide this point's x & y coordinates by a factor, yielding a new point. Parameters k ( number ) the factor Returns Point : The new point. Example divByPoint (p) Divide this point's x & y coordinates by point, yielding a new point. Parameters p ( Point ) the other point Returns Point : The new point. Example equals (p) Judge whether this point is equal to another point, returning true or false. Parameters p ( Point ) the other point Returns boolean : Whether the points are equal. Example mag () Return the magnitude of this point: this is the Euclidean distance from the 0, 0 coordinate to this point's x and y coordinates. Returns number : The magnitude. Example matMult (m) Multiply this point by a 4x1 transformation matrix. Parameters m ( Matrix2 ) Transformation matrix Returns Point : The new point. Example mult (k) Multiply this point's x & y coordinates by a factor, yielding a new point. Parameters k ( number ) the factor Returns Point : The new point. Example multByPoint (p) Multiply this point's x & y coordinates by point, yielding a new point. Parameters p ( Point ) the other point Returns Point : The new point. Example perp () Compute a perpendicular point, where the new y coordinate is the old x coordinate and the new x coordinate is the old y coordinate multiplied by -1. Returns Point : The perpendicular point. Example rotate (a) Rotate this point around the 0, 0 origin by an angle a, given in radians. Parameters a ( number ) angle to rotate around, in radians Returns Point : The new point. Example rotateAround (a, p) Rotate this point around p point by an angle a, given in radians. Parameters a ( number ) angle to rotate around, in radians p ( Point ) Point to rotate around Returns Point : The new point. Example round () Return a version of this point with the x & y coordinates rounded to integers. Returns Point : The new rounded point. Example sub (p) Subtract this point's x & y coordinates to from point, yielding a new point. Parameters p ( Point ) the other point Returns Point : The new point. Example unit () Calculate this point but as a unit vector from 0, 0, meaning that the distance from the resulting point to the 0, 0 coordinate will be equal to 1 and the angle from the resulting point to the 0, 0 coordinate will be the same as before. Returns Point : The unit vector point. Example LngLatBounds src/geo/lng_lat_bounds.ts A LngLatBounds object represents a geographical bounding box, defined by its southwest and northeast points in longitude and latitude. If no arguments are provided to the constructor, a null bounding box is created. Note that any GL method that accepts a LngLatBounds object as an argument or option can also accept an Array of two LngLatLike constructs and will perform an implicit conversion. This flexible type is documented as LngLatBoundsLike . Example Parameters sw ( LngLatLike ? ) The southwest corner of the bounding box. ne ( LngLatLike ? ) The northeast corner of the bounding box. Static Members convert (input) Converts an array to a LngLatBounds object. If a LngLatBounds object is passed in, the function returns it unchanged. Internally, the function calls LngLat#convert to convert arrays to LngLat values. Parameters input ( LngLatBoundsLike ) An array of two coordinates to convert, or a LngLatBounds object to return. Returns LngLatBounds : A new LngLatBounds object, if a conversion occurred, or the original LngLatBounds object. Example fromLngLat (center, radius) Returns a LngLatBounds from the coordinates extended by a given radius . The returned LngLatBounds completely contains the radius . Parameters center ( LngLat ) (default undefined ) Center coordinates of the new bounds. radius ( number ) (default 0 ) Distance in meters from the coordinates to extend the bounds. Returns LngLatBounds : A new LngLatBounds object representing the coordinates extended by the radius . Example Methods contains (lnglat) Check if the point is within the bounding box. Parameters lnglat ( LngLatLike ) geographic point to check against. Returns boolean : True if the point is within the bounding box. Example extend (obj) Extend the bounds to include a given LngLatLike or LngLatBoundsLike. Parameters obj ( ( LngLatLike | LngLatBoundsLike ) ) object to extend to Returns LngLatBounds : this getCenter () Returns the geographical coordinate equidistant from the bounding box's corners. Returns LngLat : The bounding box's center. Example getEast () Returns the east edge of the bounding box. Returns number : The east edge of the bounding box. getNorth () Returns the north edge of the bounding box. Returns number : The north edge of the bounding box. getNorthEast () Returns the northeast corner of the bounding box. Returns LngLat : The northeast corner of the bounding box. getNorthWest () Returns the northwest corner of the bounding box. Returns LngLat : The northwest corner of the bounding box. getSouth () Returns the south edge of the bounding box. Returns number : The south edge of the bounding box. getSouthEast () Returns the southeast corner of the bounding box. Returns LngLat : The southeast corner of the bounding box. getSouthWest () Returns the southwest corner of the bounding box. Returns LngLat : The southwest corner of the bounding box. getWest () Returns the west edge of the bounding box. Returns number : The west edge of the bounding box. isEmpty () Check if the bounding box is an empty/ null -type box. Returns boolean : True if bounds have been defined, otherwise false. setNorthEast (ne) Set the northeast corner of the bounding box Parameters ne ( LngLatLike ) a LngLatLike object describing the northeast corner of the bounding box. Returns LngLatBounds : this setSouthWest (sw) Set the southwest corner of the bounding box Parameters sw ( LngLatLike ) a LngLatLike object describing the southwest corner of the bounding box. Returns LngLatBounds : this toArray () Returns the bounding box represented as an array. Returns Array < Array < number >> : The bounding box represented as an array, consisting of the southwest and northeast coordinates of the bounding represented as arrays of numbers. Example toString () Return the bounding box represented as a string. Returns string : The bounding box represents as a string of the format 'LngLatBounds(LngLat(lng, lat), LngLat(lng, lat))' . Example LngLatLike src/geo/lng_lat.ts A LngLat object, an array of two numbers representing longitude and latitude, or an object with lng and lat or lon and lat properties. Example PointLike src/ui/camera.ts A Point or an array of two numbers representing x and y screen coordinates in pixels. Example LngLatBoundsLike src/geo/lng_lat_bounds.ts A LngLatBounds object, an array of LngLatLike objects in [sw, ne] order, or an array of numbers in [west, south, east, north] order. Example MercatorCoordinate src/geo/mercator_coordinate.ts A MercatorCoordinate object represents a projected three dimensional position. MercatorCoordinate uses the web mercator projection ( EPSG:3857 ) with slightly different units: the size of 1 unit is the width of the projected world instead of the "mercator meter" the origin of the coordinate space is at the north-west corner instead of the middle For example, MercatorCoordinate(0, 0, 0) is the north-west corner of the mercator world and MercatorCoordinate(1, 1, 0) is the south-east corner. If you are familiar with vector tiles it may be helpful to think of the coordinate space as the 0/0/0 tile with an extent of 1 . The z dimension of MercatorCoordinate is conformal. A cube in the mercator coordinate space would be rendered as a cube. Example Parameters x ( number ) The x component of the position. y ( number ) The y component of the position. z ( number ) (default 0 ) The z component of the position. Static Members fromLngLat (lngLatLike, altitude) Project a LngLat to a MercatorCoordinate . Parameters lngLatLike ( LngLatLike ) The location to project. altitude ( number ) (default 0 ) The altitude in meters of the position. Returns MercatorCoordinate : The projected mercator coordinate. Example Methods meterInMercatorCoordinateUnits () Returns the distance of 1 meter in MercatorCoordinate units at this latitude. For coordinates in real world units using meters, this naturally provides the scale to transform into MercatorCoordinate s. Returns number : Distance of 1 meter in MercatorCoordinate units. toAltitude () Returns the altitude in meters of the coordinate. Returns number : The altitude in meters. Example toLngLat () Returns the LngLat for the coordinate. Returns LngLat : The LngLat object. Example Related examples Add a custom style layer EdgeInsets src/geo/edge_insets.ts An EdgeInset object represents screen space padding applied to the edges of the viewport. This shifts the apprent center or the vanishing point of the map. This is useful for adding floating UI elements on top of the map and having the vanishing point shift as UI elements resize. Parameters top ( number ) (default 0 ) bottom ( number ) (default 0 ) left ( number ) (default 0 ) right ( number ) (default 0 ) Static Members getCenter (width, height) Utility method that computes the new apprent center or vanishing point after applying insets. This is in pixels and with the top left being (0.0) and +y being downwards. Parameters width ( number ) the width height ( number ) the height Returns Point : the point interpolate (start, target, t) Interpolates the inset in-place. This maintains the current inset value for any inset not present in target . Parameters start ( ( PaddingOptions | EdgeInsets ) ) interpolation start target ( PaddingOptions ) interpolation target t ( number ) interpolation step/weight Returns EdgeInsets : the insets toJSON () Returns the current state as json, useful when you want to have a read-only representation of the inset. Returns PaddingOptions : state as json # Events Source: https://docs.maptiler.com/sdk-js/api/events/ Events The different types of events that SDK JS can raise. You can also find additional event documentation for: Map , Marker , Popup , and GeolocationControl . Evented src/util/evented.ts Methods mixed in to other classes for event capabilities. Methods MapMouseEvent src/ui/events.ts MapMouseEvent is the event type for mouse-related map events. Extends Event . Example Methods lngLat The geographic location on the map of the mouse cursor. originalEvent The DOM event which caused the map event. point The pixel coordinates of the mouse cursor, relative to the map and measured from the top left corner. preventDefault () Prevents subsequent default processing of the event by the map. Calling this method will prevent the following default map behaviors: On mousedown events, the behavior of DragPanHandler On mousedown events, the behavior of DragRotateHandler On mousedown events, the behavior of BoxZoomHandler On dblclick events, the behavior of DoubleClickZoomHandler target The Map object that fired the event. type The event type (one of Map.event:mousedown , Map.event:mouseup , Map.event:click , Map.event:dblclick , Map.event:mousemove , Map.event:mouseover , Map.event:mouseenter , Map.event:mouseleave , Map.event:mouseout , Map.event:contextmenu ). MapTouchEvent src/ui/events.ts MapTouchEvent is the event type for touch-related map events. Extends Event . Methods lngLat The geographic location on the map of the center of the touch event points. lngLats The geographical locations on the map corresponding to a touch event's touches property. originalEvent The DOM event which caused the map event. point The pixel coordinates of the center of the touch event points, relative to the map and measured from the top left corner. points The array of pixel coordinates corresponding to a touch event's touches property. preventDefault () Prevents subsequent default processing of the event by the map. Calling this method will prevent the following default map behaviors: On touchstart events, the behavior of DragPanHandler On touchstart events, the behavior of TouchZoomRotateHandler target The Map object that fired the event. type The event type. MapLibreZoomEvent src/ui/events.ts A MapLibreZoomEvent is the event type for the boxzoom-related map events emitted by the BoxZoomHandler . Properties originalEvent ( MouseEvent ) : The DOM event that triggered the boxzoom event. Can be a MouseEvent or KeyboardEvent type ( string ) : The type of boxzoom event. One of boxzoomstart , boxzoomend or boxzoomcancel target ( Map ) : The Map instance that triggerred the event MapDataEvent src/ui/events.ts A MapDataEvent object is emitted with the Map.event:data and Map.event:dataloading events. Possible values for dataType s are: 'source' : The non-tile data associated with any source 'style' : The style used by the map Example Properties type ( string ) : The event type. dataType ( string ) : The type of data that has changed. One of 'source' , 'style' . isSourceLoaded ( boolean ? ) : True if the event has a dataType of source and the source has no outstanding network requests. source ( Object ? ) : The style spec representation of the source if the event has a dataType of source . sourceDataType ( string ? ) : Included if the event has a dataType of source and the event signals that internal data has been received or changed. Possible values are metadata , content and visibility . tile ( Object ? ) : The tile being loaded or changed, if the event has a dataType of source and the event is related to loading of a tile. coord ( Coordinates ? ) : The coordinate of the tile if the event has a dataType of source and the event is related to loading of a tile. MapWheelEvent src/ui/events.ts MapWheelEvent is the event type for the wheel map event. Extends Object . Methods originalEvent The DOM event which caused the map event. preventDefault () Prevents subsequent default processing of the event by the map. Calling this method will prevent the the behavior of ScrollZoomHandler . target The Map object that fired the event. type The event type. MapProjectionEvent src/ui/events.ts Supporting type to add validation to another style related type. Type declaration newProjection? ProjectionSpecification Specifies the name of the new projection. Additionally includes 'globe-mercator' to describe globe that has internally switched to mercator. # User interaction handlers Source: https://docs.maptiler.com/sdk-js/api/handlers/ User interaction handlers Items related to the ways in which the map responds to user input. BoxZoomHandler src/ui/handler/box_zoom.ts The BoxZoomHandler allows the user to zoom the map to fit within a bounding box. The bounding box is defined by clicking and holding shift while dragging the cursor. Methods disable () Disables the "box zoom" interaction. Example enable () Enables the "box zoom" interaction. Example isActive () Returns a Boolean indicating whether the "box zoom" interaction is active, i.e. currently being used. Returns boolean : true if the "box zoom" interaction is active. isEnabled () Returns a Boolean indicating whether the "box zoom" interaction is enabled. Returns boolean : true if the "box zoom" interaction is enabled. CooperativeGesturesHandler src/ui/handler/cooperative_gestures.ts A CooperativeGesturesHandler is a control that adds cooperative gesture info when user tries to zoom in/out. When the CooperativeGestureHandler blocks a gesture, it will emit a cooperativegestureprevented event. Example Properties _bypassKey This is the key ( "ctrlKey" | "metaKey" ) that will allow to bypass the cooperative gesture protection. Methods isActive () This is used to indicate if the handler is currently active or not. In case a handler is active, it will block other handlers from getting the relevant events. There is an allow list of handlers that can be active at the same time, which is configured when adding a handler. Returns boolean : true if the cooperative gestures interaction is enabled. reset () Can be called by the manager at any time and must reset everything to it's original state. ScrollZoomHandler src/ui/handler/scroll_zoom.ts The ScrollZoomHandler allows the user to zoom the map by scrolling. Methods disable () Disables the "scroll to zoom" interaction. Example enable (options?) Enables the "scroll to zoom" interaction. Parameters options ( Object ? ) Options object. options.around string ? If "center" is passed, map will zoom around center of map Example isEnabled () Returns a Boolean indicating whether the "scroll to zoom" interaction is enabled. Returns boolean : true if the "scroll to zoom" interaction is enabled. setWheelZoomRate (wheelZoomRate) Set the zoom rate of a mouse wheel Parameters wheelZoomRate ( number ) (default 1/450 ) The rate used to scale mouse wheel movement to a zoom value. Example setZoomRate (zoomRate) Set the zoom rate of a trackpad Parameters zoomRate ( number ) (default 1/100 ) The rate used to scale trackpad movement to a zoom value. Example DragPanHandler src/ui/handler/shim/drag_pan.ts The DragPanHandler allows the user to pan the map by clicking and dragging the cursor. Methods disable () Disables the "drag to pan" interaction. Example enable (options?) Enables the "drag to pan" interaction. Parameters options ( Object ? ) Options object options.linearity number default: 0 factor used to scale the drag velocity options.easing Function default: bezier(0,0,0.3,1) easing function applled to map.panTo when applying the drag. options.maxSpeed number default: 1400 the maximum value of the drag velocity. options.deceleration number default: 2500 the rate at which the speed reduces after the pan ends. Example isActive () Returns a Boolean indicating whether the "drag to pan" interaction is active, i.e. currently being used. Returns boolean : true if the "drag to pan" interaction is active. isEnabled () Returns a Boolean indicating whether the "drag to pan" interaction is enabled. Returns boolean : true if the "drag to pan" interaction is enabled. DragRotateHandler src/ui/handler/shim/drag_rotate.ts The DragRotateHandler allows the user to rotate the map by clicking and dragging the cursor while holding the right mouse button or ctrl key. Methods disable () Disables the "drag to rotate" interaction. Example enable () Enables the "drag to rotate" interaction. Example isActive () Returns a Boolean indicating whether the "drag to rotate" interaction is active, i.e. currently being used. Returns boolean : true if the "drag to rotate" interaction is active. isEnabled () Returns a Boolean indicating whether the "drag to rotate" interaction is enabled. Returns boolean : true if the "drag to rotate" interaction is enabled. KeyboardHandler src/ui/handler/keyboard.ts The KeyboardHandler allows the user to zoom, rotate, and pan the map using the following keyboard shortcuts: = / + : Increase the zoom level by 1. Shift-= / Shift-+ : Increase the zoom level by 2. - : Decrease the zoom level by 1. Shift-- : Decrease the zoom level by 2. Arrow keys: Pan by 100 pixels. Shift+⇢ : Increase the rotation by 15 degrees. Shift+⇠ : Decrease the rotation by 15 degrees. Shift+⇡ : Increase the pitch by 10 degrees. Shift+⇣ : Decrease the pitch by 10 degrees. Methods disable () Disables the "keyboard rotate and zoom" interaction. Example disableRotation () Disables the "keyboard pan/rotate" interaction, leaving the "keyboard zoom" interaction enabled. Example enable () Enables the "keyboard rotate and zoom" interaction. Example enableRotation () Enables the "keyboard pan/rotate" interaction. Example isActive () Returns true if the handler is enabled and has detected the start of a zoom/rotate gesture. Returns boolean : true if the handler is enabled and has detected the start of a zoom/rotate gesture. isEnabled () Returns a Boolean indicating whether the "keyboard rotate and zoom" interaction is enabled. Returns boolean : true if the "keyboard rotate and zoom" interaction is enabled. DoubleClickZoomHandler src/ui/handler/shim/dblclick_zoom.ts The DoubleClickZoomHandler allows the user to zoom the map at a point by double clicking or double tapping. Methods disable () Disables the "double click to zoom" interaction. Example enable () Enables the "double click to zoom" interaction. Example isActive () Returns a Boolean indicating whether the "double click to zoom" interaction is active, i.e. currently being used. Returns boolean : true if the "double click to zoom" interaction is active. isEnabled () Returns a Boolean indicating whether the "double click to zoom" interaction is enabled. Returns boolean : true if the "double click to zoom" interaction is enabled. TwoFingersTouchPitchHandler src/ui/handler/two_fingers_touch.ts The TwoFingersTouchPitchHandler allows the user to pitch the map by dragging up and down with two fingers. Extends TwoFingersTouchHandler . Methods disable Disables the "drag to pitch" interaction. Example enable (options?) Enables the "drag to pitch" interaction. Parameters options ( Object ? ) Options object. options.around string ? If "center" is passed, map will zoom around the center Example isActive Returns a Boolean indicating whether the "drag to pitch" interaction is active, i.e. currently being used. Returns boolean : true if the "drag to pitch" interaction is active. isEnabled Returns a Boolean indicating whether the "drag to pitch" interaction is enabled. Returns boolean : true if the "drag to pitch" interaction is enabled. TwoFingersTouchRotateHandler src/ui/handler/two_fingers_touch.ts The TwoFingersTouchRotateHandler allows the user to rotate with two fingers. Extends TwoFingersTouchHandler . Methods disable Disables the "drag to rotate" interaction. Example enable (options?) Enables the "drag to pitch" interaction. Parameters options ( Object ? ) Options object. options.around string ? If "center" is passed, map will zoom around the center Example isActive Returns a Boolean indicating whether the "drag to pitch" interaction is active, i.e. currently being used. Returns boolean : true if the "drag to pitch" interaction is active. isEnabled Returns a Boolean indicating whether the "drag to pitch" interaction is enabled. Returns boolean : true if the "drag to pitch" interaction is enabled. TwoFingersTouchZoomHandler src/ui/handler/shim/two_fingers_touch.ts The TwoFingersTouchZoomHandler allows the user to zoom the map two fingers. Methods disable () Disables the "pinch to rotate and zoom" interaction. Example enable (options?) Enables the "drag to zoom" interaction. Parameters options ( Object ? ) Options object. options.around string ? If "center" is passed, map will zoom around the center Example isActive () Returns true if the handler is enabled and has detected the start of a zoom/rotate gesture. Returns boolean : //eslint-disable-line isEnabled () Returns a Boolean indicating whether the "pinch to rotate and zoom" interaction is enabled. Returns boolean : true if the "pinch to rotate and zoom" interaction is enabled. TwoFingersTouchZoomRotateHandler src/ui/handler/shim/two_fingers_touch.ts The TwoFingersTouchZoomRotateHandler allows the user to zoom and rotate the map by pinching on a touchscreen. They can zoom with one finger by double tapping and dragging. On the second tap, hold the finger down and drag up or down to zoom in or out. Methods disable () Disables the "pinch to rotate and zoom" interaction. Example disableRotation () Disables the "pinch to rotate" interaction, leaving the "pinch to zoom" interaction enabled. Example enable (options?) Enables the "pinch to rotate and zoom" interaction. Parameters options ( Object ? ) Options object. options.around string ? If "center" is passed, map will zoom around the center Example enableRotation () Enables the "pinch to rotate" interaction. Example isActive () Returns true if the handler is enabled and has detected the start of a zoom/rotate gesture. Returns boolean : //eslint-disable-line isEnabled () Returns a Boolean indicating whether the "pinch to rotate and zoom" interaction is enabled. Returns boolean : true if the "pinch to rotate and zoom" interaction is enabled. # Languages Source: https://docs.maptiler.com/sdk-js/api/languages/ The MapTiler SDK JS has a built-in list of compatible languages, which can be used as shorthand for the [ISO language codes](https://en.wikipedia.org/wiki/ISO_639-1) used to define the language of the map labels. The language generally depends on the map's style. The MapTiler SDK JS also provides seamless support for **right-to-left languages**. Arabic, Hebrew, and other right-to-left languages are fully supported by default. No extra plugins are needed. Check out the [complete list of supported languages](https://github.com/maptiler/maptiler-client-js/blob/main/src/language.ts). In addition to the built-in ISO languages, there are these special cases for supported languages: - `Language.AUTO`: uses the default language of the browser - `Language.LATIN`: uses the default fallback language in the Latin charset - `Language.LOCAL`: uses the local language for each country - `Language.NON_LATIN`: uses the default fallback language in the non-Latin charset - `Language.STYLE`: uses the language defined by the style > [!WARNING] > `Language.STYLE` is the default state. Once you switch the language from `STYLE`, you **cannot switch it back**. - `Language.STYLE_LOCK`: keep the language from the style and prevent any further updates > [!WARNING] > `Language.STYLE_LOCK` should **only** be used in the **constructor**. - `Language.VISITOR`: uses the preferred language from the user settings and the "default name". This mode is useful when a user needs to access both local names and English names, for example, when traveling abroad where signs are likely to be available only in the local language. - `Language.VISITOR_ENGLISH`: uses English and the "default name". This mode is useful when a user needs to access both local names and English names, for example, when traveling abroad where signs are likely to be available only in the local language. > [!INFO] > The "default name" is equivalent to OSM's `{name}`, which is either the most globally recognized name or the local name. ## Related examples - [How to change the default map labels language](/sdk-js/examples/language-map/) - [How to change the map labels language based on visitor's location](/sdk-js/examples/ip-map-language/) - [Change a map's language](/sdk-js/examples/language-switch/) - [Display and style rich text labels](/sdk-js/examples/display-and-style-rich-text-labels/) # Color Ramp Source: https://docs.maptiler.com/sdk-js/api/color-ramp/ Color Ramp src/ColorRamp.ts A color ramp is a color gradient defined in a specific interval, for instance in [0, 1], and for any value within this interval will retrieve a color. They are defined by at least a color at each bound and usualy additional colors within the range. Color ramps are super useful to represent numerical data in a visual way: the temperature, the population density, the average commute time, etc. Example To use an already existing color ramp and access some of its values: Creating a new one consists in defining all the colors for each color stops . The values can be in the range of interest and do not have to be in [0, 1]. For example, let's recreate a Viridis color ramp but with a range going from 0 to 100: When defining a new ramp, the colors can be a RGB array ( [number, number, number] ) or a RGBA array ( [number, number, number, number] ). View more Color Ramp examples Parameters options? (ColorRampOptions) Options to provide to the constructor ( ColorRampOptions ) Properties options.min ( number )? The value the colorramp starts options.max ( number )? The value the colorramp ends options.stops ( Array < ColorStop >)? Some color stops to copy from Methods clone () Clone the color ramp. Returns ColorRamp : The cloned color ramp Example getBounds () Get the colorramp starts and end values. Returns Object : The color ramp min and max values Example getCanvasStrip (options?) Get the colorramp starts and end values. Parameters options? ( Object ) : The options object. options.horizontal boolean? default: true options.size number? default: 512 options.smooth boolean? default: true Returns HTMLCanvasElement : The color ramp canvas Example getColor (value, options?) Get the color for a given value. Parameters value ( number ) : value from color options? ( Object ) : The options object. options.smooth boolean? default: true Returns RgbaColor : The color for the given value Example getColorHex (value, options?) Get the color as an hexadecimal string for a given value. Parameters value ( number ) : value from color options? ( Object ) : The options object. options.smooth boolean? default: true options.withAlpha boolean? default: false Returns HexColor : The color for the given value Example getColorRelative (value, options?) Get the color of the color ramp at a relative position in [0, 1] Parameters value ( number ) : value from color options? ( Object ) : The options object. options.smooth boolean? default: true Returns RgbaColor : The color for the given value Example getRawColorStops () Get color ramp color stops array. Returns Array : ColorStop Example reverse (options?) Reverse the color ramp. Parameters options? ( Object ) : The options object. options.clone boolean? default: true Clone the reverse color ramp Returns ColorRamp : The reversed color ramp Example scale (min, max, options?) Scale the color ramp min and max values. Parameters min ( number ) : Minimum color ramp value max ( number ) : Maximum color ramp value options? ( Object ) : The options object. options.clone boolean? default: true Clone the scaled color ramp Returns ColorRamp : The scaled color ramp Example setStops (stops, options?) Change the color ramp stops values and colors Parameters stops ( Array <ColorStop>) : New color stops options? ( Object ) : The options object. options.clone boolean? default: true Clone the color ramp Returns ColorRamp : The color ramp with the new stops Example fromArrayDefinition (cr) Static Converts a array-definition color ramp definition into a usable ColorRamp instance. Note: units are not converted and may need to to be converted beforehand (eg. kelvin to centigrade) Parameters cr ( Array <ArrayColorRampStop>) : A color ramp as per array definition Returns ColorRamp : The new color ramp Example resample (method, samples) Apply a non-linear ressampling. This will create a new instance of ColorRamp with the same bounds. Check out the non-linear color ramps section to see how to apply the resampling to a point layer visualization. Parameters method ( "ease-in-square" | "ease-out-square" | "ease-in-sqrt" | "ease-out-sqrt" | "ease-in-exp" | "ease-out-exp" ) : Ressampling method samples ( number ) : number of steps. Default: 15 Returns ColorRamp : The new color ramp Example transparentStart () Makes a clone of this color ramp that is fully transparant at the begining of their range. Returns ColorRamp : The new color ramp Example hasTransparentStart () Check if this color ramp has a transparent start. Returns Boolean : color ramp has a transparent start Example Non-linear color ramps In this section we will see how to use the resample function of a color ramp to improve the visualization of data from a point layer. We are using a large dataset containing all the public schools in the US. We are using the PORTLAND color ramp: For the purpose of visualising the number of students, we are going to scale the PORTLAND color ramp on the range 300 to 4000 as most schools will contains more than 300 students and less than 4000. Linear We used the following color ramp definition: Here is how the data looks like over a New York City: It's not entirely bad, but only the very large schools stand out and it's quite difficult, without looking at the numbers, to differentiate all the blue dots just from their color variations. Generally speaking in data visualisation, small variations matter towards the lower bound and large variations matter towards the upper bound. For this particular dataset, we would like a schools with 300 students to show differently from a school with 500 (IOW, a small difference of 200 in the lower bound), but we would like a school with 3800 students to look roughly the same as one with 4000 students (IOW, a small difference on the upper bound). And this is where non linear rescaling or color ramps comes into play! Non-linear: ease-out square-root Easing-out is a way to say that something accelerates a lot at the beginning of a given interval and slows down towards the end, while still increasing all the way (aka. monotonically increasing). To perform the nonlinear rescaling of color ramps, MapTiler SDK performs some intermediate range changes so that only the range [0, 1] is actually relevant to observe (but then rescaled to its original range). Here is how the square root function looks like, naturally being of the ease-out kind: To obtain a PORTLAND color ramp scaled with the square root method, we can do: This results in the following version of PORTLAND : As we can see if we compare with its linear version, this resampled color ramp is slightly left-skewed and shows much faster variations towards the beginning of the range. That's exactly what we want to leverage to better visualise the differences between schools with fewer number of students. Here is how the same data looks like now: It's no longer about blue dots everywhere! We can now fairly easily differentiate a school with 400 students than one with 800. Non-linear going too far: ease-out exponential Some functions have a much steeper slope than the square root function and would emphasise the differences even more on the lower bound, maybe a bit too much, at the expense of clarity for the rest of the range. For very specific usages, the SDK features an exponential resampling. Here is how its function looks like on [0, 1] range: As we can see, starting from x = 0.5 there is very little variation left. Here is how to create the corresponding PORTLAND color ramp: The color ramp created looks very left-skewed: And the map visualisation: The South Bronx (north of Manhattan) contains many smaller schools that now look like they no longer have this blue color representative of the lower bound from the Portland color ramp. This is basically means we crossed a line in terms of resampling function and that our color ramp is no longer suitable for our purpose. Of course, knowing that the granularity of the color ramp on the second half is very poor, we can change its range, maybe double it to [300, 8000] : And we would still obtain a decent visualisation: But then, the process is backward and means the data range is adapted based on the capabilities and limitations of the color ramp. This adds an unnecessary overhead. > [!IDEA] > For this visualization we recommend using **Non-linear: ease-out square-root** `.resample("ease-out-sqrt)`. Builtin color ramps The SDK includes many built-in ready to use color ramps as well as extra logic to manipulate them and create new ones, here is the full list: Types and Interfaces ColorStop { value: number, // The "value" at which this ColorStop should be applied. color: string // GB[A] - Array of 3-4 numbers. 0-255 per channel. } # Config Source: https://docs.maptiler.com/sdk-js/api/config/ Config src/config.ts The config object represents the SDK global settings. It exposes properties and options that make it easier to define some values that the SDK will use globally, such as the API key, the map units, etc. Extends Evented . Example Properties apiKey string default: "" Gets and sets the MapTiler API key . Emits the apiKey event when updated. caching boolean default: true Starting from v2, MapTiler SDK introduced the caching of tiles and fonts served by MapTiler, which can represent a large chunk of the data being fetched when browsing a map. This caching leverages modern browsers caching API so it's well-managed and there is no risk of bloating! When we update MapTiler Planet or our official styles , the caching logic will detect it and automatically invalidate older versions of the tiles that were previously cached. Caching greatly improves the performance at load time and positively impact the user experience, for this reason, it is enabled by default . If for debugging purposes or a for a very specific use-case caching needs to be disabled, then it possible. session boolean default: true Setting on whether of not the SDK runs with a session logic. A "session" is started at the initialization of the SDK and finished when the browser page is being refreshed. When session is enabled, the extra URL param mtsid is added to queries on the MapTiler API. This allows MapTiler to enable "session based billing" . units Unit default: metric Gets and sets the map units. When updated, it emits the unit event that is caught inside of the map instances. Example: to update the scale control primaryLanguage LanguageString default: Language.AUTO Sets the map primary language, use when a Map instance is created. (default: the language of the web browser is used) fetch FetchFunction Gets and sets a the custom fetch function to replace the default one. If the fetch() function exists (browser or Node >= 18) then it will be resolved automatically. A custom fetch() function can be provided for early Node versions (Node telemetry boolean default: true The telemetry is very valuable to the team at MapTiler because it shares information about where to add the extra effort. It also helps spotting some incompatibility issues that may arise between the SDK and a specific version of a module. It consists in sending metrics about usage of the following features: SDK version [string] API key [string] MapTiler sesion ID (if opted-in) [string] if tile caching is enabled [boolean] if language specified at initialization [boolean] if terrain is activated at initialization [boolean] if globe projection is activated at initialization [boolean] In addition, each official module will be added to a list, alongside its version number. Telemetry is enabled by default but can be opted-out by setting to false . # ImageViewer Source: https://docs.maptiler.com/sdk-js/api/image-viewer/ ImageViewer src/ImageViewer/ImageViewer.ts MapTiler's ImageViewer component allows you to display tiled, non-georeferenced images but interact with them in almost the same way you would if you were displaying map. These can be handy for zoomable non-georeferenced, geographically "inaccurate" maps such as hotel maps, golf courses, theme parks etc. Think pixels instead of lattitudes and longtidues. You create a ImageViewer by specifying a container and other options. Then SDK JS initializes the viewer on the page and returns your ImageViewer object. Extends Evented . Example Parameters options (ImageViewerConstructorOptions) Options to provide to the ImageViewer constructor ( ImageViewerConstructorOptions ) Properties options.apiKey string ? Define the MapTiler API key to be used. This is equivalent to setting config.apiKey and will overwrite it. options.container ( HTMLElement | string ) The HTML element in which SDK JS will render the viewer, or the element's string id . options.imageUUID string The unique UUID of the image object you are displaying. options.center [number, number]? default: the center of the image The initial centerpoint in pixels of the viewer. options.zoom number ? default: 0 The initial zoom level of the viewer. options.bearing number ? default: 0 The initial bearing (rotation) of the viewer, measured in degrees counter-clockwise from north. options.debug boolean ? default: false Whether to show tiles debug information. options.fitToBoundsControl boolean ? default: true Whether to show a control to fit the image to the viewport. options.navigationControl boolean ? default: true Whether to show a navigation control. options.maxZoom number ? The maximum zoom level of the viewer. options.minZoom number ? The minimum zoom level of the viewer. Methods ImageViewer provides a subset of methods for interaction with the map. A major caveat is that the ImageViewer component works in pixels and not in LngLat. Thus, when using methods such as setCenter or flyTo the pixel values provided refer to the absolute pixel position on the image, not screen pixel position. Imagine your image is 10,000px x 10,000px, if regardless if your zoom is 2 or 4, calling .setCenter(500,500) will always position the viewer over the same part of the image. fitImageBounds (bounds) Set the bounds of the image. Parameters bounds ([[number, number],[number, number]]) The bounds of the image. The bounds are defined by topLeft and bottomRight corner. Returns ImageViewer : this fitImageToViewport (options?) Fits the image to the viewport. Parameters options (object?) Options describing the destination. options.ease boolean ? Whether to ease to the viewport bounds. Default false Returns void Example flyTo (options, eventData?) Fly to a given center. Parameters options ( ImageViewerFlyToOptions ) Options describing the destination. options.center [number, number] The given center. eventData ( MapDataEvent? ) The event data. Returns ImageViewer : this Example getBearing () Get the bearing of the ImageViewer in degrees. Returns number : The viewer's current bearing. getCanvas () Get the canvas of the internal SDK instance. Returns HTMLCanvasElement : The canvas of the internal SDK instance. getCenter () Get the center of the ImageViewer in pixels. Returns [number, number] : The center of the ImageViewer. Example getImageBounds () Get the visible bounds of the image in the viewport in imagePixels. [topLeft, bottomRight] Returns [[number, number], [number, number]] : The visible bounds of the image. Example getImageMetadata () Get the image metadata. Returns ImageMetadata : The image metadata . Example getZoom () Returns the viewer's current zoom level. Returns number : The viewer's current zoom level. Example jumpTo (options, eventData?) Jump to a given center. Parameters options ( ImageViewerJumpToOptions ) Options describing the destination. options.center [number, number] The given center. eventData ( MapDataEvent? ) The event data. Returns ImageViewer : this Example onReadyAsync () Waits for the ImageViewer to be ready. Returns Promise<void> Example panBy (delta, options?, eventData?) Pan by a given delta in pixels. Parameters delta ( PointLike ) The delta to pan by. options ( ImageViewerEaseToOptions? ) Options object for the pan. eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns ImageViewer : this panTo (center, options?, eventData?) Pan to a given center in pixels. Parameters center ( [number, number] ) The location to pan the map to. options ( ImageViewerEaseToOptions? ) The options for the pan. eventData ( any? ) Additional properties to be added to event objects of events triggered by this method. Returns ImageViewer : this Example pointIsWithinImageBounds (px) Check if a given point is within the bounds of the image. Parameters px ( [number, number] ) The point to be evaluated. Returns boolean Example remove () Destroys the ImageViewer, removes the map instance and all event listeners. Useful for cleanup. Returns void setBearing (bearing) Set the bearing of the ImageViewer in degrees.. Parameters bearing ( number ) The desired bearing. Returns ImageViewer : this Example setCenter (center) Set the center of the ImageViewer in pixels. Parameters center ([number, number]) The centerpoint to set. Returns ImageViewer : this Example setZoom (zoom) Sets the viewer's zoom level. Parameters zoom ( number ) The zoom level to set. Returns ImageViewer : this Example on (type, listener) Adds a listener for events of a specified type. Parameters type ( string ) The event type to listen for. listener ( Function ) The function to be called when the event is fired . The listener function is called with the data object passed to fire, extended with target and type properties. Returns Subscription Example off (type, listener) Removes a previously registered event listener. Parameters type ( string ) The event type to remove listeners for. listener ( Function ) The function previously installed as a listener. Returns ImageViewer : this once (type, listener?) Adds a listener that will be called only once to a specified event type. The listener will be called first time the event fires after the listener is registered. Parameters type ( string ) The event type to listen for. listener ( Function ?) The function to be called when the event is fired the first time. Returns ImageViewer | Promise<any> : this or a promise if a listener is not provided Events In a similar manner, a subset of map events are fired by the image viewer. All UI interaction events that would normally include a LngLat in the event data instead receive an imageX and imageY field, representing an absolute pixel position of the image. This is same for flyTo , jumpTo , panTo etc. A full list of supported events can be found in the exported type declaration ImageViewerEventTypes imageviewerinit Called only once after the viewer is initialized. Example imageviewerready Called only once after the viewer is ready. Example imagevieweriniterror Fired when an error occurs. Properties data ( {error: {message: string }} ) Related examples Display a tiled, non-georeferenced image Add markers to a non-georeferenced image # MaptilerAnimation Source: https://docs.maptiler.com/sdk-js/api/maptiler-animation/ MaptilerAnimation src/MaptilerAnimation/MaptilerAnimation.ts MapTiler's MaptilerAnimation is a utility class for smoothly animating between keyframes using custom easing and playback control. It supports event-based hooks for frame updates and completion, and works well within rendering loops or UI transitions. Example Related examples MaptilerAnimation with 3D Module Animations and Animated Routes # API Client Source: https://docs.maptiler.com/sdk-js/api/api-client/ API Client Our map SDK is not only about maps! The SDK also wraps API calls to MapTiler API services in a series of handy functions. The SDK uses the API Client JS library under the hood and exposes its functions so that they can be used directly from the SDK. Example Functions These are the services wrapper functions that are built-in: Geocoding Geolocation Coordinates Data Static maps Elevation Math Languages You can use any of the functions documented in the Client JS library. Check out the examples in the library's documentation. To use these functions in the SDK, all you have to do is change maptilerClient by maptilersdk Examples # Properties and options Source: https://docs.maptiler.com/sdk-js/api/properties/ Properties and options SDK JS's global properties and options that you can access while initializing your map or accessing information about its status. addProtocol src/source/protocol_crud.ts Adds a custom load resource function that will be called when using a URL that starts with a custom url schema. This will happen in the main thread, and workers might call it if they don't know how to handle the protocol. The example below will be triggered for custom:// urls defined in the sources list in the style definitions. The function passed will receive the request parameters and should return with the resulting resource, for example a pbf vector tile, non-compressed, represented as ArrayBuffer. Example Parameters customProtocol ( string ) the protocol to hook, for example 'custom' loadFn ( AddProtocolAction ) the function to use when trying to fetch a tile specified by the customProtocol addSourceType src/source/source.ts Adds a custom source type, making it available for use with Map.addSource. Parameters name ( string ) The name of the source type; source definition objects use this name in the {type: ...} field. SourceType ( SourceClass ) clearPrewarmedResources src/util/global_worker_pool.ts Clears up resources that have previously been created by maptilersdk.prewarm() . Note that this is typically not necessary. You should only call this function if you expect the user of your app to not return to a Map view at any point in your application. Example getMaxParallelImageRequests src/index.ts Gets the maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default. Example Returns number : Number of parallel requests currently configured. getRTLTextPluginStatus src/index.ts Gets the map's RTL text plugin status. The status can be unavailable (i.e. not requested or removed), loading , loaded or error . If the status is loaded and the plugin is requested again, an error will be thrown. Example getVersion src/index.ts Returns the package version of the library. Example getWorkerCount src/index.ts Gets the number of web workers instantiated on a page with GL JS maps. By default, workerCount is 1 except for Safari browser where it is set to half the number of CPU cores (capped at 3). Make sure to set this property before creating any map instances for it to have effect. Example Returns number : Number of workers currently configured. getWorkerUrl src/index.ts Gets the worker url Returns string : The worker url. getWebGLSupportError src/index.ts Detect WebGL compatibility Returns string | null : Return null if there is no error (WebGL is supported), or returns a string with the error message if WebGL2 is not supported. importScriptInWorkers src/index.ts Allows loading javascript code in the worker thread. Note that since this is using some very internal classes and flows it is considered experimental and can break at any point. It can be useful for the following examples: Using self.addProtocol in the worker thread - note that you might need to also register the protocol on the main thread. Using self.registerWorkerSource(workerSource: WorkerSource) to register a worker source, which sould come with addSourceType usually Using self.actor.registerMessageHandler to override some internal worker operations Example Parameters workerUrl ( string ) The worker url e.g. a url of a javascript file to load in the worker Returns Promise<void[]> prewarm src/util/global_worker_pool.ts Initializes resources like WebWorkers that can be shared across maps to lower load times in some situations. maptilersdk.workerUrl and maptilersdk.workerCount , if being used, must be set before prewarm() is called to have an effect. By default, the lifecycle of these resources is managed automatically, and they are lazily initialized when a Map is first created. By invoking prewarm() , these resources will be created ahead of time, and will not be cleared when the last Map is removed from the page. This allows them to be re-used by new Map instances that are created later. They can be manually cleared by calling maptilersdk.clearPrewarmedResources() . This is only necessary if your web page remains active but stops using maps altogether. This is primarily useful when using GL-JS maps in a single page app, wherein a user would navigate between various views that can cause Map instances to constantly be created and destroyed. Example removeProtocol src/source/protocol_crud.ts Removes a previously added protocol Example Parameters customProtocol ( string ) the custom protocol to remove registration for setMaxParallelImageRequests src/index.ts Sets the maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default. Example Parameters numRequests ( number ) The maximum number of images to load in parallel. setRTLTextPlugin src/index.ts Sets the map's RTL text plugin . Necessary for supporting the Arabic and Hebrew languages, which are written right-to-left. Example Parameters pluginURL ( string ) URL pointing to the MapLibre RTL text plugin source. callback ( Function ) Called with an error argument if there is an error. lazy ( boolean ) If set to true , maplibregl will defer loading the plugin until rtl text is encountered, rtl text will then be rendered only after the plugin finishes loading. setWorkerCount src/index.ts Sets the number of web workers instantiated on a page with GL JS maps. By default, workerCount is 1 except for Safari browser where it is set to half the number of CPU cores (capped at 3). Make sure to set this property before creating any map instances for it to have effect. Example Parameters count ( number ) The number of workers. setWorkerUrl src/index.ts Sets the worker url Parameters value ( string ) The worker url. clearStorage src/index.ts Clears browser storage used by this library. Using this method flushes the SDK JS tile cache that is managed by this library. Tiles may still be cached by the browser in some cases. This API is supported on browsers where the Cache API is supported and enabled. This includes all major browsers when pages are served over https:// , except Internet Explorer and Edge Mobile. When called in unsupported browsers or environments (private or incognito mode), the callback will be called with an error argument. Example Parameters callback ( Function ) Called with an error argument if there is an error. AnimationOptions src/ui/camera.ts Options common to map movement methods that involve animation, such as Map#panBy and Map#easeTo , controlling the duration and easing function of the animation. All properties are optional. Properties duration ( number ) : The animation's duration, measured in milliseconds. easing ( Function ) : A function taking a time in the range 0..1 and returning a number where 0 is the initial state and 1 is the final state. Default is a bezier-curve function with control points (0.25, 0.1) and (0.25, 1). Example: offset ( PointLike ) : of the target center relative to real map container center at the end of animation. animate ( boolean ) : If false , no animation will occur. essential ( boolean ) : If true , then the animation is considered essential and will not be affected by prefers-reduced-motion . CameraOptions src/ui/camera.ts Options common to Map#jumpTo , Map#easeTo , and Map#flyTo , controlling the desired location, zoom, bearing, and pitch of the camera. All properties are optional, and when a property is omitted, the current camera value for that property will remain unchanged. Example Properties center ( LngLatLike ) : The desired center. zoom ( number ) : The desired zoom level. bearing ( number ) : The desired bearing in degrees. The bearing is the compass direction that is "up". For example, bearing: 90 orients the map so that east is up. pitch ( number ) : The desired pitch in degrees. The pitch is the angle towards the horizon measured in degrees with a range between 0 and 60 degrees. For example, pitch: 0 provides the appearance of looking straight down at the map, while pitch: 60 tilts the user's perspective towards the horizon. Increasing the pitch value is often used to display 3D objects. around ( LngLatLike ) : If zoom is specified, around determines the point around which the zoom is centered. padding ( PaddingOptions ) : Dimensions in pixels applied on each side of the viewport for shifting the vanishing point. Related examples Set pitch and bearing Jump to a series of locations Fly to a location Display buildings in 3D PaddingOptions src/geo/edge_insets.ts Options for setting padding on calls to methods such as Map#fitBounds , Map#fitScreenCoordinates , and Map#setPadding . Adjust these options to set the amount of padding in pixels added to the edges of the canvas. Set a uniform padding on all edges or individual values for each edge. All properties of this object must be non-negative integers. Example Properties top ( number ) bottom ( number ) right ( number ) left ( number ) Static Members bottom Properties bottom ( number ) : Padding in pixels from the bottom of the map canvas. left Properties right ( number ) : Padding in pixels from the right of the map canvas. right Properties left ( number ) : Padding in pixels from the left of the map canvas. top Properties top ( number ) : Padding in pixels from the top of the map canvas. Related examples Fit to the bounds of a LineString Fit a map to a bounding box RequestParameters src/util/ajax.ts A RequestParameters object to be returned from Map.options.transformRequest callbacks. Example Properties url ( string ) : The URL to be requested. headers ( Object ) : The headers to be sent with the request. method ( string ) : Request method 'GET' | 'POST' | 'PUT' . body ( string ) : Request body. type ( string ) : Response body type to be returned 'string' | 'json' | 'arrayBuffer' . credentials ( string ) : 'same-origin'|'include' Use 'include' to send cookies with cross-origin requests. collectResourceTiming ( boolean ) : If true, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events. StyleImageInterface src/style/style_image.ts Interface for dynamically generated style images. This is a specification for implementers to model: it is not an exported method or class. Images implementing this interface can be redrawn for every frame. They can be used to animate icons and patterns or make them respond to user input. Style images can implement a StyleImageInterface#render method. The method is called every frame and can be used to update the image. Example Methods data Properties data ( ( Uint8Array | Uint8ClampedArray ) ) height Properties height ( number ) onAdd (map) Optional method called when the layer has been added to the Map with Map#addImage . Parameters map ( Map ) The Map this custom layer was just added to. onRemove () Optional method called when the icon is removed from the map with Map#removeImage . This gives the image a chance to clean up resources and event listeners. render () This method is called once before every frame where the icon will be used. The method can optionally update the image's data member with a new image. If the method updates the image it must return true to commit the change. If the method returns false or nothing the image is assumed to not have changed. If updates are infrequent it maybe easier to use Map#updateImage to update the image instead of implementing this method. Returns boolean : true if this method updated the image. false if the image was not changed. width Properties width ( number ) Related examples Add an animated icon to the map. CustomLayerInterface src/style/style_layer/custom_style_layer.ts Interface for custom style layers. This is a specification for implementers to model: it is not an exported method or class. Custom layers allow a user to render directly into the map's GL context using the map's camera. These layers can be added between any regular layers using Map#addLayer . Custom layers must have a unique id and must have the type of "custom" . They must implement render and may implement prerender , onAdd and onRemove . They can trigger rendering using Map#triggerRepaint and they should appropriately handle Map.event:webglcontextlost and Map.event:webglcontextrestored . The renderingMode property controls whether the layer is treated as a "2d" or "3d" map layer. Use: "renderingMode": "3d" to use the depth buffer and share it with other layers "renderingMode": "2d" to add a layer with no depth. If you need to use the depth buffer for a "2d" layer you must use an offscreen framebuffer and CustomLayerInterface#prerender Example Methods id Properties id ( string ) : A unique layer id. onAdd (map, gl) Optional method called when the layer has been added to the Map with Map#addLayer . This gives the layer a chance to initialize gl resources and register event listeners. Parameters map ( Map ) The Map this custom layer was just added to. gl ( WebGLRenderingContext ) The gl context for the map. onRemove (map, gl) Optional method called when the layer has been removed from the Map with Map#removeLayer . This gives the layer a chance to clean up gl resources and event listeners. Parameters map ( Map ) The Map this custom layer was just added to. gl ( WebGLRenderingContext ) The gl context for the map. prerender (gl, matrix) Optional method called during a render frame to allow a layer to prepare resources or render into a texture. The layer cannot make any assumptions about the current GL state and must bind a framebuffer before rendering. Parameters gl ( WebGLRenderingContext ) The map's gl context. matrix ( mat4 ) The map's camera matrix. It projects spherical mercator coordinates to gl coordinates. The mercator coordinate [0, 0] represents the top left corner of the mercator world and [1, 1] represents the bottom right corner. When the renderingMode is "3d" , the z coordinate is conformal. A box with identical x, y, and z lengths in mercator units would be rendered as a cube. MercatorCoordinate .fromLngLat can be used to project a LngLat to a mercator coordinate. render (gl, matrix) Called during a render frame allowing the layer to draw into the GL context. The layer can assume blending and depth state is set to allow the layer to properly blend and clip other layers. The layer cannot make any other assumptions about the current GL state. If the layer needs to render to a texture, it should implement the prerender method to do this and only use the render method for drawing directly into the main framebuffer. The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA) . This expects colors to be provided in premultiplied alpha form where the r , g and b values are already multiplied by the a value. If you are unable to provide colors in premultiplied form you may want to change the blend function to gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA) . Parameters gl ( WebGLRenderingContext ) The map's gl context. matrix ( Array < number > ) The map's camera matrix. It projects spherical mercator coordinates to gl coordinates. The spherical mercator coordinate [0, 0] represents the top left corner of the mercator world and [1, 1] represents the bottom right corner. When the renderingMode is "3d" , the z coordinate is conformal. A box with identical x, y, and z lengths in mercator units would be rendered as a cube. MercatorCoordinate .fromLngLat can be used to project a LngLat to a mercator coordinate. renderingMode Properties renderingMode ( string ) : Either "2d" or "3d" . Defaults to "2d" . type Properties type ( string ) : The layer's type. Must be "custom" . # Types Source: https://docs.maptiler.com/sdk-js/api/types/ Types CameraUpdateTransformFunction src/ui/camera.ts A callback hook that allows manipulating the camera and being notified about camera updates before they happen. Parameters next { bearing: number; center: LngLat; elevation: number; pitch: number; roll: number; zoom: number; } next.bearing number next.center LngLat next.elevation number next.pitch number next.roll number next.zoom number RequestTransformFunction src/util/request_manager.ts This function is used to tranform a request. It is used just before executing the relevant request. Parameters url string resourceType ? ResourceType ResourceType src/util/request_manager.ts A type of MapLibre resource. Enumeration members Glyphs Image Source SpriteImage SpriteJSON Style Tile Unknown Subscription src/util/util.ts Allows to unsubscribe from events without the need to store the method reference. Methods unsubscribe() Unsubscribes from the event. Returns void StyleSetterOptions src/style/style.ts Supporting type to add validation to another style related type. Type declaration validate? boolean Whether to check if the filter conforms to the MapLibre Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function. CubemapLayerConstructorOptions src/custom-layers/CubemapLayer/types.ts Constructor options for the CubemapLayer. Usage Simple space You can enable a simple space background with a solid color: Predefined Presets Alternatively, you can provide a cubemap for a space backround using one of the following methods: space : Dark blue hsl(210, 100%, 4%) background and white stars (transparent background image). Space color changes the background color, stars always stay white. stars (default): Black background (image mask), space color changes the stars color, background always stays black. milkyway : Black half-transparent background with standard milkyway and stars. Space color changes the stars and milkyway color, background always stays black. milkyway-subtle : Black half-transparent background with subtle milkyway and less stars. Space color changes the stars and milkyway color, background always stays black. Black half-transparent background with standard milkyway and stars. Space color changes the stars and milkyway color, background always stays black. milkyway-bright : Black half-transparent background with bright milkyway and more stars. Space color changes the stars and milkyway color, background always stays black. Cubemap Images (Custom Skybox) Load your custom cubemap images: Cubemap Path with image format This fetches all images from a path, this assumes all files are named px, nx, py, ny, pz, nz and suffixed with the appropriate extension specified in format . Set the space background dynamically You can also set the space dynamically after the map loads: Cubemap face images must be square and have a height / width of a power of 2 512px, 1024px if space.color or are not explicitly set in the call to setSpace , then the previous value will remain for this field. To override the default, set the required field to null . RadialGradientLayerConstructorOptions src/custom-layers/RadialGradientLayer/types.ts Options for constructing a RadialGradientLaye. Usage Simple halo You can enable a simple halo by setting it to true : Radial gradient For more customization, you can define a radial gradient with scale and stops: Set the halo dynamically You can also set the halo dynamically after the map loads: MaptilerCustomControlCallback src/controls/MaptilerCustomControl.ts A callback hook used by a MaptilerCustomControl . Parameters map SDKMap element HTMLElement event Event ImageMetadata src/ImageViewer/ImageViewer.ts The metadata of the image. This is the shape of the response from the API. And used to convert px to lnglat and vice versa.. Type declaration attribution string description string height number id string maxzoom number minzoom number tileSize number width number # SDK JS Modules Source: https://docs.maptiler.com/sdk-js/modules/

SDK JS Modules

Geocoding Control

TypescriptLogoJavaScriptLogo

Graphical component for the Geocoding control in your map application (MapTiler SDK, Leaflet, MapLibre, and more).

Read documentation
Geocoding control example

Weather JS module

TypescriptLogoJavaScriptLogo

The Weather JS module for MapTiler SDK contains a set of weather-specific tiled layers to put into your map, just like any layer! Visualize it at 60 frames per second animation.

Read documentation
Weather JS Module

Augmented reality (AR) Control

TypescriptLogoJavaScriptLogo

Add a button on your MapTiler SDK's Map to create a 3D model of the viewport, including 3D terrain and any layer you have put on top.

Read documentation
AR Control for MapTiler SDK JS

Elevation Profile Control

TypescriptLogoJavaScriptLogo

Elevation profile control for MapTiler SDK is an easy way to show the elevation profile of any GeoJSON trace, with elevation data fueled by MapTiler.

Read documentation
Elevation profile control for MapTiler SDK

Marker Layout

TypescriptLogoJavaScriptLogo

Create non-colliding marker overlays on top of MapTiler SDK. Fed by a vector layer from a tileset or from a GeoJSON source.

Read documentation
Marker layout for MapTiler SDK JS

3D objects/models

TypescriptLogoJavaScriptLogo

Add 3D objects to your basemap with plenty of customizations from glTF/glb files.

Read documentation
3D objects for MapTiler SDK
# 3D objects on MapTiler maps Source: https://docs.maptiler.com/sdk-js/modules/3d/ With the [MapTiler SDK](/sdk-js/) 3D JS module, you can add 3D objects to your basemap with plenty of customizations from **glTF/glb files**. These can be meshes, groups of meshes, point clouds, or a mix of all these. ## Get started Check out the [Add a 3D model on a map example](/sdk-js/examples/3d-js-get-started/). ## API reference The [reference](/sdk-js/modules/3d/api/) documents every object and method available. Each section describes classes or objects as well as their **properties, parameters, methods**, and associated **events**. Many sections also include inline code examples and related resources. The **main class** in the MapTiler 3D JS module is the [**Layer3D class**](/sdk-js/modules/3d/api/classes/Layer3D/)

COLLADA duck One texture Credit: © 2006, Sony. SCEA Shared Source License, Version 1.0 ↩

# 3D objects Source: https://docs.maptiler.com/sdk-js/modules/3d/api/ 3D objects Enumerations AltitudeReference SourceOrientation Classes Layer3D Interfaces Item3D Type Aliases AddMeshFromURLOptions AnimationLoopOptions AnimationMode CloneMeshOptions GenericObject3DOptions Item3DEventTypes Item3DMeshUIStateName Item3DMeshUIStateProperties Item3DMeshUIStates Item3DTransform Layer3DOptions MapTiler3DModuleConfig MeshOptions PointLightOptions Variables AnimationLoopOptionsMap config Functions getTransformationMatrix On This Page Enumerations Altitude Reference Source Orientation Classes Layer3 D Interfaces Item3 D Type Aliases Add Mesh From URL Options Animation Loop Options Animation Mode Clone Mesh Options Generic Object3 D Options Item3 D Event Types Item3 D Mesh UI State Name Item3 D Mesh UI State Properties Item3 D Mesh UI States Item3 D Transform Layer3 D Options Map Tiler3 D Module Config Mesh Options Point Light Options Variables Animation Loop Options Map config Functions get Transformation Matrix 3D objects Altitude Reference Source Orientation Layer3 D Item3 D Add Mesh From U R L Options Animation Loop Options Animation Mode Clone Mesh Options Generic Object3 D Options Item3 D Event Types Item3 D Mesh U I State Name Item3 D Mesh U I State Properties Item3 D Mesh U I States Item3 D Transform Layer3 D Options Map Tiler3 D Module Config Mesh Options Point Light Options Animation Loop Options Map config get Transformation Matrix # MapTiler 3D objects examples Source: https://docs.maptiler.com/sdk-js/modules/3d/examples/ _No overview content available._ # Augmented reality (AR) Control for MapTiler SDK JS Source: https://docs.maptiler.com/sdk-js/modules/ar/

Augmented reality (AR) Control for MapTiler SDK JS

This Augmented reality (AR) control adds a button on your [MapTiler SDK's](/sdk-js/) map to create a 3D model of the viewport, including 3D terrain and any layer you have put on top. The **Enable AR** button will appear if your device is compatible with **WebXR** or **Apple Quick Look**. Then, you can position and interact with the 3D model in your own space. ## Get started Check out the [Getting started with AR maps: Display an AR control on your maps example](/sdk-js/examples/ar-control/). ## API reference This [reference](/sdk-js/modules/ar/api/) documents every object and method available. Each section describes classes or objects as well as their **properties, parameters, methods**, and associated **events**. Many sections also include inline code examples and related resources. The **main class** in the MapTiler 3D JS module is the [**MaptilerARControl class**](/sdk-js/modules/ar/api/classes/MaptilerARControl/) # AR Control Source: https://docs.maptiler.com/sdk-js/modules/ar/api/ AR Control Classes MaptilerARControl Type Aliases MaptilerARControlOptions Variables HAS_INTERSECTION_OBSERVER HAS_RESIZE_OBSERVER HAS_WEBXR_DEVICE_API HAS_WEBXR_HIT_TEST_API IS_ANDROID IS_AR_QUICKLOOK_CANDIDATE IS_CHROMEOS IS_FIREFOX IS_IOS IS_IOS_CHROME IS_IOS_SAFARI IS_MOBILE IS_OCULUS IS_SAFARI IS_SCENEVIEWER_CANDIDATE IS_WEBXR_AR_CANDIDATE IS_WKWEBVIEW Functions mapTextureDataToCanvas On This Page Classes Maptiler AR Control Type Aliases Maptiler AR Control Options Variables HAS_ INTERSECTION_ OBSERVER HAS_ RESIZE_ OBSERVER HAS_ WEBXR_ DEVICE_ API HAS_ WEBXR_ HIT_ TEST_ API IS_ ANDROID IS_ AR_ QUICKLOOK_ CANDIDATE IS_ CHROMEOS IS_ FIREFOX IS_ IOS IS_ IOS_ CHROME IS_ IOS_ SAFARI IS_ MOBILE IS_ OCULUS IS_ SAFARI IS_ SCENEVIEWER_ CANDIDATE IS_ WEBXR_ AR_ CANDIDATE IS_ WKWEBVIEW Functions map Texture Data To Canvas AR Control Maptiler A R Control Maptiler A R Control Options H A S_ I N T E R S E C T I O N_ O B S E R V E R H A S_ R E S I Z E_ O B S E R V E R H A S_ W E B X R_ D E V I C E_ A P I H A S_ W E B X R_ H I T_ T E S T_ A P I I S_ A N D R O I D I S_ A R_ Q U I C K L O O K_ C A N D I D A T E I S_ C H R O M E O S I S_ F I R E F O X I S_ I O S I S_ I O S_ C H R O M E I S_ I O S_ S A F A R I I S_ M O B I L E I S_ O C U L U S I S_ S A F A R I I S_ S C E N E V I E W E R_ C A N D I D A T E I S_ W E B X R_ A R_ C A N D I D A T E I S_ W K W E B V I E W map Texture Data To Canvas # MapTiler Augmented reality (AR) Control Examples Source: https://docs.maptiler.com/sdk-js/modules/ar/examples/ _No overview content available._ # Elevation profile control Source: https://docs.maptiler.com/sdk-js/modules/elevation-profile/ The elevation profile control module for [MapTiler SDK](/sdk-js/) provides an easy way to visualize the [elevation](/guides/location-services/elevation/) of any GeoJSON trace; whether it's a `LineString` or a `MultiLineString`, this trace can be in a `Feature` or `FeatureCollection`. If multiple features are eligible in the provided dataset, the features will be concatenated and displayed together as a unique route. The module uses the [Elevation API Client JS](/client-js/#%EF%B8%8F-elevation). The elevation profile control is customizable in many ways and supports **metric** and **imperial** units. ## Get started Check out the [Get started with Elevation profile control example](/sdk-js/examples/elevation-profile-control-simple/). ## API reference This [reference](/sdk-js/modules/elevation-profile/api/) documents every object and method available. Each section describes classes or objects as well as their **properties, parameters, methods**, and associated **events**. Many sections also include inline code examples and related resources. ## Computing elevation Sometimes, the route data passed to the method `.setData()` will contain only longitude and latitude information but no elevation. In that case, the control will automatically fetch and compute the elevation data before displaying the profile. Under the hood, the MapTiler Client library performs this operation using elevation data from MapTiler. --- # Elevation Profile Control Source: https://docs.maptiler.com/sdk-js/modules/elevation-profile/api/ Elevation Profile Control Classes ElevationProfile ElevationProfileControl Type Aliases CallbackData ElevationProfileControlOptions ElevationProfileOptions On This Page Classes Elevation Profile Elevation Profile Control Type Aliases Callback Data Elevation Profile Control Options Elevation Profile Options Elevation Profile Control Elevation Profile Elevation Profile Control Callback Data Elevation Profile Control Options Elevation Profile Options # MapTiler Elevation Profile Control Examples Source: https://docs.maptiler.com/sdk-js/modules/elevation-profile/examples/ _No overview content available._ # Geocoding control (place search box) Source: https://docs.maptiler.com/sdk-js/modules/geocoding/ The geocoding control implements a complete [**place search**](/guides/location-services/geocoding-search/) in your map or other frontend application. This page explains how to implement it with [MapTiler SDK JS](/sdk-js/). ## Get started For the most basic integration, see the code example [Add place search to map](/sdk-js/examples/geocoder-component/). If you're using a JS framework like React or Svelte, get tailored instructions in these tutorials: - [React component](/react/sdk-js/geocoding-control/) - [Svelte component](/svelte/sdk-js/geocoding-control/) You can also go to [GitHub]("https://github.com/maptiler/maptiler-geocoding-control) or [npm](https://www.npmjs.com/package/@maptiler/geocoding-control) for integration details. ## Configure search To customize the geocoding control behavior for your needs, see these examples: - [Limit results by country](/sdk-js/examples/geocoding-filter-country/) - [Limit results by a bounding box](/sdk-js/examples/geocoding-filter-bbox/) - [Draw a custom search area](/sdk-js/examples/geocoding-filter-draw-bbox/) - [Prioritize nearby results](/sdk-js/examples/geocoding-filter-proximity/) - [Search specific place types](/sdk-js/examples/geocoding-filter-types/) - [Set search language](/sdk-js/examples/geocoding-language/) The search control has many more powerful config options, including autocomplete and typing predictions or highlighting search results on the map. Check out the [geocoding control API reference](/sdk-js/modules/geocoding/api/api-reference/#geocoding-parameters) to see all options. ## Advanced topics The geocoding control can be used as an **ES Module** (ESM) or **UMD** (Universal Module Definition). ### UMD global variables When importing scripts from CDN using ` # Search and Geocoding control Source: https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/ Search and Geocoding control Namespaces MaptilerGeocoderEvent Classes MaptilerGeocodeClearIconElement MaptilerGeocodeFailIconElement MaptilerGeocodeLoadingIconElement MaptilerGeocoderElement MaptilerGeocodeReverseGeocodingIconElement MaptilerGeocodeSearchIconElement Type Aliases BBox EnableReverse Feature FeatureCollection FeaturesClearEvent FeaturesHideEvent FeaturesListedEvent FeaturesShowEvent FlyToFeatures MaptilerGeocoderEvent MaptilerGeocoderEventName MaptilerGeocoderEventNameMap MaptilerGeocoderOptions PickedResultStyle PickEvent PlaceType Position ProximityRule QueryChangeEvent QueryClearEvent RequestEvent ResponseEvent ReverseToggleEvent SelectEvent ShowPlaceType TypeRule Worldview On This Page Namespaces Maptiler Geocoder Event Classes Maptiler Geocode Clear Icon Element Maptiler Geocode Fail Icon Element Maptiler Geocode Loading Icon Element Maptiler Geocoder Element Maptiler Geocode Reverse Geocoding Icon Element Maptiler Geocode Search Icon Element Type Aliases B Box Enable Reverse Feature Feature Collection Features Clear Event Features Hide Event Features Listed Event Features Show Event Fly To Features Maptiler Geocoder Event Maptiler Geocoder Event Name Maptiler Geocoder Event Name Map Maptiler Geocoder Options Picked Result Style Pick Event Place Type Position Proximity Rule Query Change Event Query Clear Event Request Event Response Event Reverse Toggle Event Select Event Show Place Type Type Rule Worldview Search and Geocoding control Maptiler Geocoder Event Features Clear Event Features Hide Event Features Listed Event Features Show Event Pick Event Query Change Event Query Clear Event Request Event Response Event Reverse Toggle Event Select Event Maptiler Geocode Clear Icon Element Maptiler Geocode Fail Icon Element Maptiler Geocode Loading Icon Element Maptiler Geocoder Element Maptiler Geocode Reverse Geocoding Icon Element Maptiler Geocode Search Icon Element B Box Enable Reverse Feature Feature Collection Features Clear Event Features Hide Event Features Listed Event Features Show Event Fly To Features Maptiler Geocoder Event Maptiler Geocoder Event Name Maptiler Geocoder Event Name Map Maptiler Geocoder Options Picked Result Style Pick Event Place Type Position Proximity Rule Query Change Event Query Clear Event Request Event Response Event Reverse Toggle Event Select Event Show Place Type Type Rule Worldview # MapTiler Geocoding Examples Source: https://docs.maptiler.com/sdk-js/modules/geocoding/examples/ _No overview content available._ # Geocoding control migration guide Source: https://docs.maptiler.com/sdk-js/modules/geocoding/api/migration/ **Version 3** of the Geocoding control **removes** the dependency on **Svelte**, so it's no longer required to have Svelte installed to use it. It also introduces a new integration approach: the control no longer uses the previous map controller. Instead, each map library **provides its own standalone, self-contained control**, which you use in the same way as any other control from that library. Version 3 also **includes a standalone geocoder component** implemented as a **standard Web Component**, which you can integrate with any frontend framework or library using its usual integration method. This page explains how to migrate from version 2 to version 3 of the Geocoding control. ## Imports and entrypoints ### Root entrypoint The package now **includes a root entry point**: `@maptiler/geocoding-control`. Importing this entry point without specifying any symbol registers a Web Component named `maptiler-geocoder`. ```js import "@maptiler/geocoding-control"; ``` ```html ``` Use this component as a standalone geocoder in any environment as a custom solution. If you use a map library, import the entry point for that specific library instead. See [MapTiler SDK entrypoint](#maptiler-sdk-entrypoint), ```js import "@maptiler/geocoding-control"; import { type MaptilerGeocoderOptions, type MaptilerGeocoderEvent } from "@maptiler/geocoding-control"; ``` #### Importing from CDN The name of the UMD file has changed from `vanilla.umd.js` to `index.umd.js` ```html ``` ### MapTiler SDK entrypoint The entry point remains `@maptiler/geocoding-control/maptilersdk`. This entry point no longer exports a function for creating a map controller. Instead, import `GeocodingControl` and add it to the map instance like any other map control. ```js import { GeocodingControl, type GeocodingControlOptions, type GeocodingControlEvent } from "@maptiler/geocoding-control/maptilersdk"; map.addControl(new GeocodingControl()); ``` #### Importing from CDN The name of the global UMD variable has changed from `maptilersdkMaptilerGeocoder` to `maptilerGeocoder`
### MapLibre GL entrypoint The entry point remains `@maptiler/geocoding-control/maplibregl`. This entry point no longer exports a function for creating a map controller. Instead, import `GeocodingControl` and add it to the map instance like any other map control. ```js import { GeocodingControl, type GeocodingControlOptions, type GeocodingControlEvent } from "@maptiler/geocoding-control/maplibregl"; map.addControl(new GeocodingControl()); ``` #### Importing from CDN The name of the global UMD variable has changed from `maplibreglMaptilerGeocoder` to `maptilerGeocoder`
### Leaflet entrypoint The entry point remains `@maptiler/geocoding-control/leaflet`. This entry point no longer exports a function for creating a map controller. Instead, import `GeocodingControl` and add it to the map instance like any other map control. ```js import { GeocodingControl, type GeocodingControlOptions, type GeocodingControlEvent } from "@maptiler/geocoding-control/leaflet"; map.addControl(new GeocodingControl()); ``` #### Importing from CDN The name of the global UMD variable has changed from `leafletMaptilerGeocoder` to `maptilerGeocoder`
### OpenLayers entrypoint The entry point remains `@maptiler/geocoding-control/openlayers`. This entry point no longer exports a function for creating a map controller. Instead, import `GeocodingControl` and add it to the map instance like any other map control. ```js import { GeocodingControl, type GeocodingControlOptions, type GeocodingControlEvent } from "@maptiler/geocoding-control/openlayers"; map.addControl(new GeocodingControl()); ``` #### Importing from CDN The name of the global UMD variable has changed from `openlayersMaptilerGeocoder` to `maptilerGeocoder`
### Common types entrypoint The entry point `@maptiler/geocoding-control/types` **no longer exists**. Import common types shared across modules from the root entry point `@maptiler/geocoding-control` or from any library entry point, such as `@maptiler/geocoding-control/maptilersdk`. Types that belong to a specific map control, such as `GeocodingControlOptions`, are available only from the entry point of that library. Each library can define slightly different types depending on its features and requirements. ```js import type { Feature, Position } from "@maptiler/geocoding-control"; import type { Feature, Position } from "@maptiler/geocoding-control/maptilersdk"; ``` ### Svelte entrypoints Svelte entrypoints **no longer exist**. The Geocoding control doesn't use Svelte anymore. To use the control in Svelte with a map library, treat it the same way you treat any other map control. ```js import { GeocodingControl } from "@maptiler/geocoding-control/maptilersdk"; ... ... let geocoderControl; ... ... geocoderControl = new GeocodingControl(); geocoderControl.on("select", (data) => { console.log("select", data); }); map.addControl(geocoderControl); ``` To use a standalone geocoder, treat it the same way you treat any other webcomponent. #### Geocoding control version 2 ⚠️ deprecated ```js import GeocodingControl from "@maptiler/geocoding-control/svelte/GeocodingControl.svelte"; import { createMapLibreGlMapController } from "@maptiler/geocoding-control/maplibregl"; ... ... let mapController; ... ... mapController = createMapLibreGlMapController(map, maptilersdk); ``` ```html
``` ### React entrypoint React entrypoint **no longer exists**. To use the control in React with a map library, use it the same way as any other map control. ```js import { GeocodingControl } from "@maptiler/geocoding-control/maptilersdk"; ... ... const control = useRef(null); ... ... control.current = new GeocodingControl(); control.current.on("select", (data) => { log("select", data); }); map.current.addControl(control.current); ``` To use a standalone geocoder, treat it the same way you treat any other webcomponent. A common approach uses `useRef`. #### Geocoding control version 2 ⚠️ deprecated ```js import { GeocodingControl } from "@maptiler/geocoding-control/react"; import { createMapLibreGlMapController } from "@maptiler/geocoding-control/maplibregl-controller"; ... ... const [mapController, setMapController] = useState(); ... ... setMapController(createMapLibreGlMapController(map.current, maptilersdk)); ``` ```html
{mapController && }
``` ### Vanilla entrypoint Vanilla entrypoint **no longer exists**. See the [root entrypoint](#root-entrypoint) for using standalone geocoder in Vanilla JavaScript and without any map library. See the library entrypoints for using the geocoding control in Vanilla JavaScript together with a map library. ### Style entrypoint Style entrypoint **no longer exists**. The package bundles all required styles inside the Web Component, so you don't need to import any CSS. Future releases may introduce additional customization and styling options. #### Importing from CDN The geocoder component **no longer provides a CSS** and doesn't require loading it.
## Events Version 3 renames several events and modifies some behaviors. ### New events - `featuresclear` The control fires this event when it clears features. For map controls, it fires after the control removes features from the map. - `featuresshow` The control fires this event when it shows the dropdown with search results. - `featureshide` The control fires this event when it hides the dropdown with search results. - `request` The control fires this event before sending a request. It complements the existing `response` event. - `queryclear` The control fires this event when the user clears the input field. - `focusin` The control fires this event when the input gains focus. - `focusout` The control fires this event when the input loses focus. - `markerclick` The control fires this event when the user clicks a marker on the map. - `markermouseenter` The control fires this event when the user moves the cursor over a marker on the map. - `markermouseleave` The control fires this event when the user moves the cursor away from a marker on the map. > Note: Marker events are available only for map controls. ### Modified events - `featureslisted` The control fires this event when it loads search results. For map controls, it fires after the control renders features on the map. It no longer fires when the control removes features; use `featuresclear` instead. - `pick` The control can fire this event twice when rendering full geometry. The first event contains simplified geometry, and the second contains full geometry. - `querychange` The control fires this event when the user changes the input. It no longer fires when the user clears the input; use `queryclear` instead. ### Deleted events - `featuresmarked` no longer exists. Use `featureslisted` instead. - `optionsvisibilitychange` no longer exists. Use `featuresshow` and `featureshide` instead. The following events remain unchanged: `response`, `select`, and `reversetoggle`. Event types now use `CustomEvent` for the Web Component and the corresponding event type from each map library for map controls. As a result, the event type differs slightly depending on the control variant. You can import events individually. Example: `ResponseEvent`. You can also import all events through the `GeocodingControlEvent` namespace. Example: `GeocodingControlEvent.ResponseEvent`. `GeocodingControlEvent` also represents the union type of all event types. ## Options - `adjustUrlQuery(sp: URLSearchParams)` has replaced with `adjustUrl(url: URL)`. The control exposes the full `URL` object for modification after it prepares the request and before it sends it. - `session` is now available in the MapTiler SDK control. It behaves the same as the `session` configuration option in the MapTiler SDK. # MapTiler Marker Layout for MapTiler SDK Source: https://docs.maptiler.com/sdk-js/modules/marker-layout/ The Marker Layout is a helper to create non-colliding marker overlays on top of [MapTiler SDK](/sdk-js/). Fed by a vector layer from a tileset or a GeoJSON source, it can be tuned with plenty of options. Thanks to its non-opinionated and logic-only approach, it lets you bind any kind of rendering you wish for your markers: vanilla HTML `div`, React components, floating canvas, animated SVGs or Lotties [^1], etc. as it computes the position and size of the markers but lets you handle the rendering part. In MapLibre you can create markers with a custom image and even represent them with some HTML (text, SVGs, Lotties, etc). The problem is that there is no collision detection and having too many markers on the map makes it difficult to understand at all scales. Using a symbol layer you can detect collisions and only show some elements (the most relevant ones, etc) but the possibility of creating markers using html is limited. Using the Marker Layout helper you have the best of both worlds; create your markers with HTML, Lotties (animated images), text, etc and thanks to the collision detection create a map that is understandable and usable at all scales. ## Get started Check out the [How to create non-colliding marker overlays example](/sdk-js/examples/marker-layout-basic/). In this get started we will create a Marker Layout to display the information from the city and town label layers. ## API reference This [reference](./api/) documents every object and method available. Each section describes classes or objects as well as their **properties, parameters, methods**, and associated **events**. Many sections also include inline code examples and related resources. ## Some concepts The Marker Layout... - computes screen-space bounding box logic - can be provided the desired marker size and relative anchor point - is fed with one or multiple vector layer - can only use *point* features - create non-overlapping bounding boxes - can filter and sort features based on vector feature properties - sorting can be done with a function, so that rank can come from an external source - can group multiple vector features into each marker - when updated will retrieve three lists of markers relative to the previous state: the new, the removed and the moved markers - does not enforce how the actual visual markers (eg. div) should be created, cached, pooled, reused or deleted [^1]: **Lottie** is a file format for vector graphics animation. They can be scaled without pixelation or loss of quality, just like an SVG file. It is intended as a lighter alternative to animated GIFs and APNG files for use in the web and mobile and desktop applications. Read more about [Lottie file format](https://en.wikipedia.org/wiki/Lottie_(file_format)). # Marker layout Source: https://docs.maptiler.com/sdk-js/modules/marker-layout/api/ Marker layout Classes MarkerLayout Type Aliases AbstractMarker FeatureGroup MarkerAnchor MarkerLayoutOptions MarkerMap MarkerStatus On This Page Classes Marker Layout Type Aliases Abstract Marker Feature Group Marker Anchor Marker Layout Options Marker Map Marker Status Marker layout Marker Layout Abstract Marker Feature Group Marker Anchor Marker Layout Options Marker Map Marker Status # MapTiler Marker Layout Examples Source: https://docs.maptiler.com/sdk-js/modules/marker-layout/examples/ _No overview content available._ # Weather JS module Source: https://docs.maptiler.com/sdk-js/modules/weather/ The **MapTiler Weather JS module** contains a set of weather-specific tiled layers to put into your map, just like any layer! You can read more about the benefits of this module on the [MapTiler Weather](https://www.maptiler.com/weather/) page. Use the [MapTiler SDK JS](https://docs.maptiler.com/sdk-js) to visualize the interactive weather layers available in [MapTiler](https://www.maptiler.com/cloud/) at 60 frames per second animation! Check out some of the [module's features](#weather-js-module-features). With MapTiler Weather JS Module, you have access to comprehensive weather data and advanced visualization tools that empower you to make informed decisions based on real-time conditions. > [!IDEA] > If you're new to weather visualization, go to [How to make weather maps](/guides/maps-apis/weather/how-to-make-weather-maps/) for a short intro including where to get weather data. ## Get started Check out the [Weather wind layer example](/sdk-js/examples/weather-wind/). In this example we will add the wind layer to the map and create a time slider bar to control the layer time animation. ## Objects and methods Each section describes classes or objects as well as their **properties, parameters, methods**, and associated **events**. Many sections also include inline code examples and related resources.
## Weather JS module features * 4-day forecast * global coverage * hourly precision * fresh data every few hours (generaly ~6 h) * animated * highly customizable * plenty of built-in color ramps * easy to setup with nice default settings * pick weather values for any lon/lat (and mouse move) * included in your FREE MapTiler plan! ![NpmLogo](/assets/img/npm.svg)[Install the npm package](https://www.npmjs.com/package/@maptiler/weather) # How to make weather maps Source: https://docs.maptiler.com/guides/maps-apis/weather/how-to-make-weather-maps/ This page explains the data sources, tools, and licensing needed to make a dynamic weather map using MapTiler. The MapTiler Weather tools can be used to animate your own weather data or can leverage data from our weather industry partners. The licensing of MapTiler Weather tools is conditioned on the use of MapTiler base maps in your applications unless a custom agreement is reached. ## Where to get weather data There are many sources of weather data, ranging from national/regional weather models like those produced by the Deutscher Wetterdienst to global models like GFS from NOAA or ECMWF. There are also high\-quality weather models created by commercial providers, including our data partner MeteoMatics. Weather models range from completely open\-source to commercial, so it is important to carefully read the terms of use before selecting the appropriate model for your application. ## How to process weather data The typical data format of weather models is NetCDF or GRIB2 format, which is quite a difficult format to work with, especially in raw form. MapTiler offers solutions for processing this data into the necessary format, with our data processing pipelines or with tools like MapTiler Engine. 👉 [How to process data in NetCDF and GRIB2 formats](/guides/maps-apis/weather/how-to-process-data-in-netcdf-and-grib2-formats/) Some weather model providers, including MeteoMatics, also sell weather data preprocessed into tile format so that the data can be ingested by the MapTiler Weather library. The weather tilesets are required to be encoded into RGB format, meaning that up to three variables can be encoded into each tileset (for example the wave height, wave direction, and wave period). The MapTiler Weather rendering library ingests data in tile format. The library is designed to be compiled directly into your own application, according to the documentation included in the GitHub repository. The library then ingests a single time series of tilesets, or multiple time series of tilesets, which are interpolated to display smooth animations of weather data over time and space. ## How to build a weather app One key benefit of the MapTiler Weather library is that it can be easily combined with [MapTiler basemaps](https://www.maptiler.com/maps/) to give users the dynamic modern map experience they are accustomed to, including panning, zooming, and tilting. We have a series of map styles that are optimized for the weather industry, including a Light, Dark, and Gray Satellite style. These can be used as a backdrop on which to show your weather data and provide geographic contexts such as country borders, hillshades, and labels. To get started, go to 👉 [MapTiler Weather SDK JS module](/sdk-js/modules/weather/). For inspiration, see [examples of weather visualization and animation](/sdk-js/examples/?q=weather) built with the SDK module. ## Useful links - [MapTiler Weather demo](https://www.maptiler.com/tools/weather/) - [MapTiler Weather solution & success stories](https://www.maptiler.com/industry/weather/) - [How to process NetCDF and GRIB2 weather data](/guides/maps-apis/weather/how-to-process-data-in-netcdf-and-grib2-formats/) - [MapTiler Weather SDK JS module](/sdk-js/modules/weather/) - [MapTiler Weather API](/cloud/api/weather/) - [Examples of weather visualization and animation](/sdk-js/examples/?q=weather) # Layers methods Source: https://docs.maptiler.com/sdk-js/modules/weather/api/methods/ These methods are available for all layers. For layer-specific methods, refer to the layer documentation. # Layers events Source: https://docs.maptiler.com/sdk-js/modules/weather/api/events/ These evetns are available for all layers. For layer-specific events, refer to the layer documentation. To add a calback function to a layer event, do the following:
> [!NOTE] > Note that most layer methods can only be called after the event sourceReady has been emmited. # Precipitation layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/precipitation/ The PrecipitationLayer shows the atmospheric precipitation in millimeter per hour (**mm/h**). Forecast for precipitation of all sorts (rain, snow, hail, sleet) in amount per hour. ![Precipitation layer](./precipitation.png)

Example

Parameters

options (PrecipitationLayerOptions)?
Options to provide to the Layer constructor (PrecipitationLayerOptions)

Properties

options.id
string
default: "MapTiler Precipitation"
 ID of the layer
options.colorramp
ColorRamp
default: ColorRamp.builtin.PRECIPITATION
 Colormap to use. Maximum range possible spans from 0 mm/h to 50 mm/h. Default spans from 0 mm/h to 50 mm/h
options.opacity
number
default: 1
 Opacity of the layer in [0, 1]
options.smooth
boolean
default: true
 Whether or not the colorramp must be smooth

Methods

Check out the [Layers method reference](../methods/)

Events

Check out the [Layers events reference](../events/) # Pressure layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/pressure/ The PressureLayer shows the atmospheric pressure in millibar (**mbar**) or hectopascal (**hPa**). Forecast for air pressure at mean sea level. ![Pressure layer](./pressure.png)

Example

Parameters

options (PressureLayerOptions)?
Options to provide to the Layer constructor (PressureLayerOptions)

Properties

options.id
string
default: "MapTiler Pressure"
 ID of the layer
options.colorramp
ColorRamp
default: ColorRamp.builtin.PRESSURE_2
 Colormap to use. Maximum range possible spans from 900 hPa to 1080 hPa. Default spans from 900 hPa to 1080 hPa
options.opacity
number
default: 1
 Opacity of the layer in [0, 1]
options.smooth
boolean
default: true
 Whether or not the colorramp must be smooth

Methods

Check out the [Layers method reference](../methods/)

Events

Check out the [Layers events reference](../events/) # Radar layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/radar/ The RadarLayer shows the atmospheric radar reflectivity in radar reflectivity factor (**dBZ**). Forecast for maximum composite radar reflectivity value. ![Radar layer](./radar.png)

Example

Parameters

options (RadarLayerOptions)?
Options to provide to the Layer constructor (RadarLayerOptions)

Properties

options.id
string
default: "MapTiler Radar"
 ID of the layer
options.colorramp
ColorRamp
default: ColorRamp.builtin.RADAR
Colormap to use. Maximum range possible spans from -20 dBZ to 80 dBZ. Default spans from 0 dBZ to 75 dBZ
Note: the built-in color ramp ColorRamp.builtin.RADAR_CLOUD was specificaly designed by our team to represent cloud coverage, and may be more intuitive for generalistic weather forecast usecases. Give it a try!
options.opacity
number
default: 1
 Opacity of the layer in [0, 1]
options.smooth
boolean
default: true
 Whether or not the colorramp must be smooth

Methods

Check out the [Layers method reference](../methods/)

Events

Check out the [Layers events reference](../events/) # Temperature layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/temperature/ The TemperatureLayer shows the atmospheric temperature in centigrade (**degree Celcius (°C)**). Forecast for temperatures at 2 m above ground. ![Temperature layer](./temperature.png)

Example

Parameters

options (TemperatureLayerOptions)?
Options to provide to the Layer constructor (TemperatureLayerOptions)

Properties

options.id
string
default: "MapTiler Temperature"
 ID of the layer
options.colorramp
ColorRamp
default: ColorRamp.builtin.TEMPERATURE_2
 Colormap to use. Maximum range possible spans from -127°C to 128°C. Default spans from -70.15°C to 46.85°C
options.opacity
number
default: 1
 Opacity of the layer in [0, 1]
options.smooth
boolean
default: true
 Whether or not the colorramp must be smooth

Methods

Check out the [Layers method reference](../methods/)

Events

Check out the [Layers events reference](../events/) # Wind layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/wind/ The WindLayer shows the atmospheric wind speed in meter per second (**m/s**). Forecast for speed and direction at an altitude of 10 m above ground. The WindLayer contains both a background to which is applied a color ramp and a set of moving particles, for this reason, the constructor WindLayer has more options that then other weather layers. ![Wind layer](./wind.png)

Example

Parameters

options (WindLayerOptions)?
Options to provide to the Layer constructor (WindLayerOptions)

Properties

options.id
string
default: "MapTiler Wind"
 ID of the layer
options.colorramp
ColorRamp
default: ColorRamp.builtin.VIRIDIS
 Colormap to use. Maximum range possible spans from 0 m/s to 75 m/s. Default spans from 0 m/s to 40 m/s
options.opacity
number
default: 1
 Opacity of the layer in [0, 1]
options.smooth
boolean
default: true
 Whether or not the colorramp must be smooth
options.color
RgbaColor
default: [255, 255, 255, 192]
 Color of the particle. RGBA 0-255.
options.fastColor
RgbaColor
default: same as color
 Color of the particle when moving "fast". RGBA 0-255.
options.density
number
default: 2
 Number of particles visible per 1000 px^2
options.fadeFactor
number
default: 0.1
 How much the particles fade over time
options.fastSpeed
number
 What is considered "fast" (in px/sec) for coloring purposes. Only makes sense when fastColor is used
options.maxAmount
number
default: 128
 Quantity of particles to be created. Has to be a power of 2 and at least 4. The actual exact number will be particles * particles.
Try to keep this value as low as possible to optimize performance.
The number of actually visible particles is determined by density.
options.pixelRatio
number
default: 2 for normal displays and 1 for HiDPI displays
 Use more pixels to make particles more smooth (especially when tilted)
options.refreshInterval
number
default: 800
 Time interval (in milliseconds) how often the particles are refreshed to avoid degradation. Random 1/16 of the particles is always randomly reset
options.size
number
default: 1.5
 Size of the particle
options.speed
number
default: 0.001
 Speed factor of the particles
options.fastIsLarger
boolean
default: false
 If this is true, the particles gets slighly larger as they become faster.

Methods

Check out the [Layers method reference](../methods/)

Events

Check out the [Layers events reference](../events/) # Pressure isolines layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/pressure-isolines/ The `PressureIsolineLayer` shows the atmospheric pressure isolines in millibar (**mbar**) or hectopascal (**hPa**). Forecast for air pressure at mean sea level. ![Pressure isolines layer](./isoline.png)

Example

Extends: [Isolines layer](../isolines/)

Parameters

options (PressureIsolineLayerOptions)?
Options to provide to the Layer constructor (PressureIsolinesLayerOptions)

Properties

options.id
string
default: "MapTiler Isoline Pressure"
 ID of the layer
options.colorramp
ColorRamp
default: ColorRamp.builtin.PRESSURE_4
 Colormap to use. Maximum range possible spans from 900 hPa to 1080 hPa. Default spans from 900 hPa to 1080 hPa
options.opacity
number
default: 1
 Opacity of the layer in [0, 1]
options.smooth
boolean
default: true
 Whether or not the colorramp must be smooth
options.lineThickness
number
default: 1.0
 Thickness of the isoline line
options.lineColor
Color [R, G, B, A]
default: [0, 0, 0, 40]
 Color of the isoline lines
options.lineColorTen
Color [R, G, B, A]
default: [0, 0, 0, 120]
 Line color for pressure that are multiples of 10 (980, 990, 1000, etc.)
options.renderBlurRadius
number
default: 4
 Integer > 0. Blurring is needed to ensure smoothly curved lines. Is used in every animation frame to get best result, but higher values can make animation slower.
options.stepForZoomLevels
Array<ZoomLevelStep>
default: [ { zoom: 0, step: 4 }, { zoom: 3, step: 2 }, { zoom: 5, step: 1 } ]
 Lines densities for zoom levels.

Methods

Check out the [Isolines layer methods](../isolines/#methods) and the [Layers method reference](../methods/)

Events

Check out the [Layers events reference](../events/) # Wind arrow layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/wind-arrow/ The `WindArrowLayer` shows the wind speed in meter per second (**m/s**). Forecast for speed and direction at an altitude of 10 m above ground. The WindArrowLayer contains both a background to which is applied a color ramp and a set of moving arrow-shaped particles, for this reason, the constructor WindArrowLayer has more options that then other weather layers. ![Wind arrow layer](./arrow-wind.png)

Example

Extends: [Arrow layer](../arrow/)

Parameters

options (WindArrowLayerOptions)?
Options to provide to the Layer constructor (WindArrowLayerOptions)

Properties

options.id
string
default: "MapTiler Arrow Wind"
 ID of the layer
options.colorramp
ColorRamp
default: ColorRamp.builtin.VIRIDIS
 Colormap to use. Maximum range possible spans from 0 m/s to 75 m/s. Default spans from 0 m/s to 40 m/s
options.opacity
number
default: 0.8
 Opacity of the layer in [0, 1]
options.smooth
boolean
default: true
 Whether or not the colorramp must be smooth
options.color
RgbaColor
default: [255, 255, 255, 192]
 Color of the arrows when slow. RGBA 0-255.
options.fastColor
RgbaColor
default: [255, 255, 255, 192]
 Color of the arrows when moving "fast". RGBA 0-255.
options.density
number
default: 2
 Number of arrows visible per 1000 px^2
options.fadeFactor
number
default: 0.1
 How much the particles fade over time
options.fastSpeed
number
default: 0.8
 What is considered "fast" (in px/sec) for coloring purposes. Only makes sense when fastColor is used
options.maxAmount
number
default: 128
 Quantity of arrows to be created. Has to be a power of 2 and at least 4. The actual exact number will be arrows * arrows.
Try to keep this value as low as possible to optimize performance.
The number of actually visible arrows is determined by density.
options.pixelRatio
number
default: 2 for normal displays and 1 for HiDPI displays
 Use more pixels to make particles more smooth (especially when tilted)
options.refreshInterval
number
default: 800
 Time interval (in milliseconds) how often the arrows are refreshed to avoid degradation. Random 1/4 of the arrows is always randomly reset
options.rttTimestep
number
default: 200
 Timestep between arrows render - shorter value means smoother direction change, but can lead to errors in speed computation (current speed is derived from movement on screen) which cause size and color glitches.
options.size
number
default: 18
 Size of the arrows
options.speed
number
default: 0.001
 Speed factor of the arrows
options.worldSpaceConstant
boolean
default: false
 The world space constant (when true) means the speed of the arrows is compensated with the zoom level so that they travel the same real world distance per unit of time. When false, the arrows travel the same distance in screen space, so that regardless the zoom level, they will travel a constant number of pixels per unit of time.

Methods

Check out the [Layers method reference](../methods/)

Events

Check out the [Layers events reference](../events/) # Color ramp Source: https://docs.maptiler.com/sdk-js/modules/weather/api/color-ramp/

Color ramp

Many integrated color ramps prepared by our cartographers are ready to use.

Example

To manually create a new color ramp that can be used with any of the weather layers, you must provide a color stop definition as follows:

Note that all the values of the color stops are in the actual unit of the layer (In the example °C) and the colors are in [R, G, B, A].

Parameters

options? (ColorRampOptions)
Options to provide to the constructor (ColorRampOptions)

Properties

options.min
(number)?
The value the colorramp starts
options.max
(number)?
The value the colorramp ends
options.stops
(Array<ColorStop>)?
Some color stops to copy from

Methods

Builtin color ramps

There are many builtin color ramps that are ready to be used. since most of them are defined in the interval [0, 1], they need to be scaled acording to their intended usage. Let's see how to do this:

Color blindness

Because some forms of color blindness can affect up to 8% of the population, we thought it was fair that our library includes some perceptually uniform color ramps that are more color blind friendly. The description from TypeScript auto completion will let you know about this information, otherwise, look for the ramps based on one of the following:
  • Mako
  • Turbo
  • Rocket
  • Cividis

See all the builtin color ramps:

# Types and interfaces Source: https://docs.maptiler.com/sdk-js/modules/weather/api/types/ Types of interfaces used in the constructors, options and functions of the different layers of the weather library.

ColorStop

Properties

options.value
number
 The "value" at which this ColorStop should be applied.
options.color
RgbaColor
 RGB[A] - Array of 3-4 numbers. 0-255 per channel.

DecodedChannelValue

Properties

options.decodeChannels
string
 Channel to use as a source of data "r" | "g" | "b" | "a".
options.min
number
 Real world value corresponding to the lower bound of the [0, 255] range.
options.max
number
 Real world value corresponding to the upper bound of the [0, 255] range.
options.arrowMinSize
number
 Minimal size of arrow.

DecoderOptions

Properties

options.channel
string
 Channel to be used to read the value from - "r" | "g" | "b". If more letters are present ("rg"), each channel is decoded separately and then the vector length is calculated.
options.min
number
 Minimum value encoded in each channel. (Value of 0 in the raster = this value.).
options.max
number
 Maximum value encoded in each channel.

MultiChannelDecoderOptions

Properties

options.polynomialCoefDegree2
number
 In the polynomial f(x) = ax^2 + bx + c. polynomialCoefDegree2 is "a".
options.polynomialCoefDegree1
number
 In the polynomial f(x) = ax^2 + bx + c. polynomialCoefDegree1 is "b".
options.polynomialConstant
number
 In the polynomial f(x) = ax^2 + bx + c. polynomialConstant is "c".

StopsPerCategoryType

The color stops as to be used by MultiChannelGradientColoringFragment

Properties

options.category
number | "all"
 A category. Categories are the values stored in the alpha channel (in [0, 255]). If the category value is "all" then the color stops will apply to all categories and if there are other StopsPerCategory for specific category number, they will be ignored.
options.stops
Array< ColorStop>
 The color stops are defining the colormap to be used.

ZoomLevelStep

Properties

options.step
number
 Integer > 0, specifies lines step on related zoom level.
options.zoom
number
 Related step starts to show on this zoom level and higher until next definition.
# Intesity or TileLayer layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/intensity/ The TileLayer consists of multiple timeframes, every frame is a tile pyramid in a different moment in time. The individual frames are smoothly animated. Decoding of the data and their visual representation is configurable.

Example

Constructor

Parameters

Methods

Check out the [Layers method reference](../methods/) # ColoringFragment Source: https://docs.maptiler.com/sdk-js/modules/weather/api/coloring-fragments/ Functions to generate coloring from the pixel values. Describes how to read the data value from the input files and transform the values to colors.

GradientColoringFragment

Use color gradient to generate coloring from the pixel values.

Example

Constructor

Parameters

OpacityColoringFragment

Use a single color, only change opacity based on the decoded value.

Example

Constructor

Parameters

MultiChannelGradientColoringFragment

Interpret image channels in the context of a multi channel gradient coloring fragment.

Example

Constructor

Parameters

# Particle layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/particles/ Extended version of [Intensity layer](../intensity/), which does particle-based animation on top the data. The standard raster visualization of Intensity layer can be used simultanously over the same data.

Constructor

Extends: [Intesity layer](../intensity/)

Parameters

Methods

Check out the [Layers method reference](../methods/) # Arrow layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/arrow/ The ArrowLayer contains both a background to which is applied a color ramp and a set of moving arrow-shaped particles, for this reason, the constructor ArrowLayer has more options that then other weather layers.

Constructor

Extends: [Intesity layer](../intensity/)

Parameters

Methods

Check out the [Layers method reference](../methods/) # Isolines layer Source: https://docs.maptiler.com/sdk-js/modules/weather/api/isolines/ An instance of IsolineLayer is maint to be used to display isoline, for example of atmospheric pressure. At the moment, this is working best with a tilesets containing a single level `0/0/0`.

Constructor

Extends: [Intesity layer](../intensity/)

Parameters

Methods

Check out the [Layers method reference](../methods/) # Mobile SDKs Source: https://docs.maptiler.com/guides/getting-started/mobile/ Our tools for building mobile apps include SDKs, sample apps, and tutorials, listed below. If you're new to mobile development, you may want to read [How to build mobile apps with SDKs](/guides/maps-apis/maps-platform/how-to-build-mobile-apps-with-maps-using-sdk/) first to see what options you have. - [Sample mobile PWA app](/sdk-js/examples/mobile-pwa/) - [Getting started with **React Native**](/react-native/) - [Getting started with **Flutter**](/flutter/) ## Android SDK - [MapTiler SDK Kotlin](/mobile-sdk/android/) - [Get started](/mobile-sdk/android/examples/get-started/) - [GitHub](https://github.com/maptiler/maptiler-sdk-kotlin) - [Examples](/mobile-sdk/android/examples/) ## iOS SDK - [MapTiler SDK iOS](/mobile-sdk/ios/) - [Get started](/mobile-sdk/ios/examples/get-started/) - [GitHub](https://github.com/maptiler/maptiler-sdk-swift) - [Examples](/mobile-sdk/ios/examples/) # How to build mobile map apps with SDKs Source: https://docs.maptiler.com/guides/maps-apis/maps-platform/how-to-build-mobile-apps-with-maps-using-sdk/ You can create a mobile map application using one of the available SDKs, or you can build a PWA with JavaScript and HTML. We explain the options on this page. ## Native mobile apps Using mobile SDK to create a native mobile app is mostly the best choice. The code is translated into native code and has lower hardware requirements. There are SDKs for both [**Android**](/mobile-sdk/android/) and [**iOS**](/mobile-sdk/ios/). The maps are encoded in the widely used and openly documented vector tile format. This means the tiles are compatible with all software tools implementing this format specification. MapTiler uses the open [**GL Style**](/gl-style-specification/) for defining the map design. The open-source [**MapTiler SDK for iOS**](/mobile-sdk/ios/) and [**MapTiler SDK for Android**](/mobile-sdk/android/) provides the most natural way how to display the tiles and styles in a mobile app natively. There are other open-source SDKs for native mobile apps like MapLibre Native. ## Sample app for Android and iOS There is a [**sample app**](https://openmaptiles.org/mobile) for iOS and Android, which demonstrates the capabilities of mobile SDK and its’ performance. You can download it for free from [App Store](https://itunes.apple.com/us/app/osm2vectortiles/id1089255502) or [get the source code](https://openmaptiles.com/mobile-app/) for further development of their own app. These apps show the vector map tiles displayed from a custom tile server, so you can choose [MapTiler](https://www.maptiler.com/cloud/) service, [MapTiler Server](https://www.maptiler.com/server/) or implement your own. Map tiles can be also bundled with the mobile app or users can download a tileset for a region of their choice. The SDK is able to display the tiles directly from MBTiles and is running in an offline environment. ## Progressive web applications (PWA) An alternative way for the development of multiplatform mobile apps is the use of the existing [JavaScript web viewers](/sdk-js/examples/mobile-pwa/) while using HTML, CSS, and JavaScript and packaging the web applications into a mobile application (PWA) with a framework like [Apache Cordova](https://cordova.apache.org/) or [Ionic Capacitor](https://capacitorjs.com/docs/). Modern mobile phones support WebGL and maps are acceptably performant, however native apps are still faster and ensure better compatibility with various devices. Check out the [**How to create a mobile app (PWA) with MapTiler SDK JS**](/sdk-js/examples/mobile-pwa/) example. While developing the mobile apps in JavaScript users can also use native components such as the Cordova app React Native. You can also develop your applications using [React Native](/react-native/) or [Flutter](/flutter/). ## Desktop and embedded apps For the development of native desktop applications and software for hardware appliances with embedded mapping systems powered by Linux, one can use the open\-source [MapLibre Native](https://maplibre.org/maplibre-native/docs/book/platforms/linux/index.html). It also has the ability to load the vector tiles from MapTiler, or the OpenMapTiles project and run completely offline. # How to create a mobile app (PWA) with MapTiler SDK JS Source: https://docs.maptiler.com/sdk-js/examples/mobile-pwa/ This example shows how to use MapTiler SDK to create a native mobile app that can be pushed to the Apple App Store and Google Play.
With this project as a starter (or any Capacitor app) and with a single codebase, you can create: * A web app hosted online, which people visit with a regular web browser. * A PWA that people can turn into a semi-app (under certain conditions: Android, EU-iPhone, etc.). * A Capacitor-powered native web app wrapped to be distributed on Apple AppStore and Google Play. > [!NOTE] > PWAs or [Progressive Web Apps](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) are web apps hosted online, like any website, but they are shipped with a few extra settings in a manifest file. We are not going to cover this here, but it's worth mentioning that your web app does **not** need to comply to the PWA set of rules to be wrapped inside a native mobile app with Capacitor. Those are two very different things, both with their pros and cons. > ## Get started For this project, we started from the [ViteJS Vanilla TypeScript sample project](https://vite.dev/guide/#trying-vite-online) and then followed the [Ionic Capacitor instructions](https://capacitorjs.com/docs/getting-started#add-capacitor-to-your-web-app) to give our project mobile superpowers. To make things easier for you, we have created the [maptiler-mini-mobile-app](https://github.com/maptiler/maptiler-mini-mobile-app) repository where we have already configured all the dependencies, configuration files, styles, etc. Here's how to set it up: 1. Clone the [maptiler-mini-mobile-app](https://github.com/maptiler/maptiler-mini-mobile-app) repo. 2. To install project dependencies, run `npx npm install`. 3. Rename `.env.sample` to `.env` and replace the value of `YOUR_MAPTILER_CLOUD_API_KEY` with your actual [MapTiler API key](https://cloud.maptiler.com/account/keys/). 4. Modify the file `capacitor.config.ts`: Update the app name, logo, bundleID, etc. For more info, refer to the [Capacitor configuration](https://capacitorjs.com/docs/config) docs. 5. In terminal, run `npx npm run build` && `npx cap sync`. ### Modify the source The project itself reuses the structure of the ViteJS boilerplate, meaning the project source is located in the `src/` directory and can be ran in a regular web browser: * In dev/watch mode: `npm run dev` * To build a production bundle: `npm run build` After building the project for production, you can run it locally with `npm run preview`. ### Update the mobile app Both mobile projects (XCode workspace and Android Studio Workspace) need to be updated after the web project has been built for production. To do so, run: `npm run sync` Back in XCode or Android Studio, you may see a popup asking if you want to refresh the project based on the updates. Select "yes" (or "Read from disk" in XCode). Then build the projects in XCode or Android Studio again and you should see your latest changes. #### Customize the iOS project First, run your project directly on iOS with the command `npx cap run ios` or open the iOS project with `npm run open-xcode`. You can then tune a few things. Select the target iOS version: ![Select the iOS target version](./img/pwa-iOS-target-version.png) If you plan to distribute your app, set up **signing** by associating it to a **Team**: ![iOS app signing & capabilities](./img/pwa-signing-app.png) To change the icon of your app, go to menu App > App > Assets and drag and drop a non-transparent image in the icon frame: ![Change the iOS app icon](./img/pwa-change-app-icon.png) ## What's in this project? ### Mobile-friendly geolocation The geolocation control originally available in MapTiler SDK is web-specific, and even though it will work when encapsulated into a mobile app, using it will trigger two user-agreement panel: one at the web-view level, and the next at system level. A more elegant way is to use `@capacitor/geolocation`, an official plugin that uses geolocation directly from the system. We had to modify the settings of the native projects (both Android and iOS) to grant the app the permission to use geolocation. You can read more about this on [the plugins's page](https://capacitorjs.com/docs/apis/geolocation). To make it simpler to integrate, we have created a SDK-friendly control that you can find in `src/universalgeolocatecontrol.ts`. Note that **this also works in a regular web page** as the plugin provides a complete fallback. ### Safe insets The safe insets are the margins that need to be put so that the content you display on screen does not step on the system display, such as the status bar on top or the bottom menu on iOS. They are defined as CSS environment variables that you can directly leverage in your styling. For instance, MapTiler SDK and MapLibre stylesheet define some classes that apply to the controls called `.maplibregl-ctrl-yyy-xxx`. Our mobile app can define more properties to these classes to prevent the visual elements to clash with the system display. You can see the classes with the insets in the file `src/style.css`. Example of a class using safe insets for controls positioned in the top-right corner of the map: ``` css .maplibregl-ctrl-top-right { top: env(safe-area-inset-top); } ``` The app's viewport must also have the following attributes in the `index.html`: ``` html ``` Here is the result: | ❌ **Without safe insets** | ✅ **With safe insets** | |:-----------:|:-----------:| | ![Map applicaction controls without safe insets](./img/map-with-no-insets.png) | ![Map applicaction controls with safe insets](./img/map-with-safe-insets.png) | > [!NOTE] > **Note**: The *safe insets* values will be `0` in a web browser, so it will not impact your layout to include them in all cases. > Filter site pages by: 1. IDs defined in page.related_examples 2. Group must be 'Examples' or 'Tutorials' 3. Category must match the current page category
Dynamic path construction: 1. Remove the ID and 'examples/' from the URL to get the base path 2. Append the assets folder structure This handles deep paths like /mobile-sdk/android/examples/helper/ -> /mobile-sdk/android/assets/...

Dynamic badge based on the group type

# MapTiler SDK Kotlin Source: https://docs.maptiler.com/mobile-sdk/android/ The MapTiler SDK Kotlin is a native SDK written in Kotlin, designed to work with the well-established MapTiler Cloud service, which provides all the data required to fuel a complete mobile mapping experience: vector tiles, GeoJSON, map interaction, custom styles, data visualization and more. ## 📦 Installation MapTiler Kotlin SDK is a Kotlin library and can be added as a dependency in your Gradle file (**Maven Central**): - Make sure you have mavenCentral() added to your repositores inside your build.gradle - Add the library as dependency in your module build.gradle file. ```kotlin dependencies { implementation("com.maptiler:maptiler-sdk-kotlin:1.3.0") } ``` Or, use Version Catalog instead, add following to the libs.versions.toml: ```kotlin maptilerSdkKotlin = "1.3.0" maptiler-sdk-kotlin = { module = "com.maptiler:maptiler-sdk-kotlin", version.ref = "maptilerSdkKotlin" } ``` Then add following implementation in your build.gradle: ```kotlin implementation(libs.maptiler.sdk.kotlin) ``` For latest version visit https://central.sonatype.com/artifact/com.maptiler/maptiler-sdk-kotlin. ## 🚀 Basic Usage Make sure to set your MapTiler Cloud API key first: ```kotlin MTConfig.apiKey = "YOUR_API_KEY" ``` ### Jetpack Compose Instantiate controller (with or without delegate) and the map view: ```kotlin import com.maptiler.maptilersdk.map.MTMapOptions import com.maptiler.maptilersdk.map.MTMapView import com.maptiler.maptilersdk.map.MTMapViewController import com.maptiler.maptilersdk.map.style.MTMapReferenceStyle val controller = MTMapViewController(context) MTMapView( MTMapReferenceStyle.STREETS, MTMapOptions(), controller, modifier = Modifier .fillMaxSize(), ) ``` ### XML Add MTMapViewClassic to your layout XML: ```xml ``` Instantiate the MTMapViewClassic: ```kotlin import com.maptiler.maptilersdk.map.MTMapOptions import com.maptiler.maptilersdk.map.MTMapViewClassic import com.maptiler.maptilersdk.map.MTMapViewController import com.maptiler.maptilersdk.map.style.MTMapReferenceStyle private lateinit var mapView: MTMapViewClassic override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) MTConfig.apiKey = "YOUR_API_KEY" val controller = MTMapViewController(baseContext) enableEdgeToEdge() setContentView(R.layout.main_activity_layout) mapView = findViewById(R.id.classicMapView) mapView.initialize(MTMapReferenceStyle.SATELLITE, MTMapOptions(), controller) } ``` For a detailed functionality overview, refer to the API reference documentation. ## 📘 API Reference For detailed guides, API reference, and advanced examples, visit our comprehensive documentation: [API documentation](https://docs.maptiler.com/mobile-sdk/android/api/) ### Sources and Layers Sources and layers can be added to the map view style object as soon as the map is initialized. Setting the style after adding layers resets them to default, so make sure the style has finished loading first. ```kotlin val sourceURL = URL("https://api.maptiler.com/tiles/v3-openmaptiles/tiles.json?key=$YOUR_API_KEY") val source = MTVectorTileSource("openmapsource", sourceURL) controller.style?.addSource(source) ``` ```kotlin try { val layer = MTFillLayer("fillLayer", "openmapsource") layer.color = Color.Blue.toArgb() layer.outlineColor = Color.Cyan.toArgb() layer.sourceLayer = "aeroway" controller.style?.addLayer(layer) } catch (error: MTStyleError) { Log.e("MTStyleError", "Layer already exists.") } ``` ### Markers and Popups ```kotlin val lngLat = LngLat(43.2352, 19.4567) val marker = MTMarker(lngLat, Color.Blue.toArgb()) controller.style?.addMarker(marker) ``` ```kotlin val lngLat = LngLat(43.2352, 19.4567) val popup = MTTextPopup(lngLat, "My Text") controller.style?.addTextPopup(popup) ``` ### Events Optionally wrap the map controller in a class to observe the map events and use the wrapper class controller for map manipulation. ```kotlin class MapController( private val context: Context, ) : MTMapViewDelegate { val controller: MTMapViewController = MTMapViewController(context).apply { delegate = this@MapController } override fun onMapViewInitialized() { Log.i("Init", "Map View Initialized.") } override fun onEventTriggered( event: MTEvent, data: MTData?, ) { Log.i("Event", "Map View Event Triggered: $event.") } } ``` ### Custom Annotations Render your own UI as map annotations. Note: Custom annotations rely on camera events. They work out of the box with the default `CAMERA_ONLY` event level (provides `ON_MOVE` and `ON_ZOOM`). If you override `eventLevel`, ensure it is `CAMERA_ONLY` or `ALL`. Compose — overlay on top of MTMapView ```kotlin Box(Modifier.fillMaxSize()) { MTMapView(MTMapReferenceStyle.STREETS, MTMapOptions(), controller, Modifier.fillMaxSize()) MTCustomAnnotationView( controller = controller, coordinates = LngLat(16.6, 49.2), modifier = Modifier, ) { // Your composable content here (e.g., a Card or Icon) } } ``` XML (Classic) — add a view above MTMapViewClassic ```kotlin // Create with desired size in pixels and initial coordinates val customView = MTCustomAnnotationViewClassic( context = this, widthPx = 120, heightPx = 48, initialCoordinates = LngLat(16.6, 49.2), ) // Attach above the WebView and start updates customView.addTo(mapView /* MTMapViewClassic */, controller) // Update position later customView.setCoordinates(LngLat(16.7, 49.25), controller) // Remove when no longer needed customView.remove() ``` ## ⚙️ Performance, Events, and Throttling To balance responsiveness and performance, the event level and throttling are configurable via `MTMapOptions`: - Event levels: - `ESSENTIAL`: Lifecycle and taps only (ready, load, moveend, resize). No per-frame camera updates. - `CAMERA_ONLY` (default): Essentials plus `move` and `zoom` camera events. Ideal for custom annotations. - `ALL`: Everything, including high-frequency touch/render events. Use with care on low-end devices. - `OFF`: Minimal wiring (internal lifecycle only). - Throttle: `highFrequencyEventThrottleMs` applies to `CAMERA_ONLY` and `ALL` to limit update rate during gestures. Default is `150` ms. Set to `0–32` for smoother overlays, or increase for balanced performance. Examples: ```kotlin // Smooth camera tracking for overlays val options = MTMapOptions( eventLevel = MTEventLevel.CAMERA_ONLY, highFrequencyEventThrottleMs = 16, ) // Leanest pipeline with lifecycle only val lean = MTMapOptions(eventLevel = MTEventLevel.ESSENTIAL) ``` You can also apply preset helpers: ```kotlin // Start from your options and apply lean performance defaults (keeps essentials; camera events can be opted-in) val opts = MTMapOptions(center = LngLat(16.6, 49.2), zoom = 10.0) val leanOpts = opts.withLeanPerformanceDefaults() // Or go for high fidelity performance settings val hiFi = MTMapOptions().withHighFidelityDefaults() ``` ### Space The space option customizes the globe’s background, simulating deep space or skybox effects. - Prerequisite: use globe projection. Set `projection = MTProjectionType.GLOBE` in `MTMapOptions`. Usage — solid color background ```kotlin val controller = MTMapViewController(context) val options = MTMapOptions( projection = MTProjectionType.GLOBE, space = MTSpaceOption.Config( MTSpace( color = Color(0xFF111122).toArgb(), ), ), ) MTMapView( MTMapReferenceStyle.STREETS, options, controller, modifier = Modifier.fillMaxSize(), ) ``` Presets — predefined cubemaps - `SPACE`: Dark blue background; stars stay white. Space color changes background color. - `STARS` (default): Black background; space color changes stars color. - `MILKYWAY`: Black half‑transparent background with standard milky way and stars; space color tints stars and milky way. - `MILKYWAY_SUBTLE`: Subtle milky way, fewer stars; space color tints stars and milky way. - `MILKYWAY_BRIGHT`: Bright milky way, more stars; space color tints stars and milky way. - `MILKYWAY_COLORED`: Full image with natural colors; space color has no effect. ```kotlin val options = MTMapOptions( projection = MTProjectionType.GLOBE, space = MTSpaceOption.Config(MTSpace(preset = MTSpacePreset.SPACE)), ) ``` Custom cubemap — provide all faces ```kotlin val faces = MTSpaceFaces( pX = "https://example.com/space/px.png", nX = "https://example.com/space/nx.png", pY = "https://example.com/space/py.png", nY = "https://example.com/space/ny.png", pZ = "https://example.com/space/pz.png", nZ = "https://example.com/space/nz.png", ) val options = MTMapOptions( projection = MTProjectionType.GLOBE, space = MTSpaceOption.Config(MTSpace(faces = faces)), ) ``` Cubemap by path — files named px, nx, py, ny, pz, nz with the given format ```kotlin val path = MTSpacePath( baseUrl = "https://example.com/spacebox/transparent", format = "png", // defaults to PNG if omitted ) val options = MTMapOptions( projection = MTProjectionType.GLOBE, space = MTSpaceOption.Config(MTSpace(path = path)), ) ``` Dynamic updates — change space at runtime ```kotlin // Call after the map is initialized (e.g., in MTMapViewDelegate.onMapViewInitialized) controller.style?.setSpace( MTSpace( color = Color.Red.toArgb(), path = MTSpacePath(baseUrl = "https://example.com/spacebox/transparent"), ), ) ``` Note: When calling `setSpace`, any field not explicitly provided (e.g., color, faces, path, or preset) keeps its previous value. ### Halo The halo option adds a gradient-based atmospheric glow around the globe, simulating the visual effect of Earth's atmosphere when viewed from space. - Prerequisite: use globe projection. Set `projection = MTProjectionType.GLOBE` in `MTMapOptions`. Enable during map initialization ```kotlin val options = MTMapOptions( projection = MTProjectionType.GLOBE, halo = MTHaloOption.Enabled, ) ``` Custom gradient — scale and stops ```kotlin val options = MTMapOptions(center = null, zoom = null, projection = MTProjectionType.GLOBE).apply { setHalo( MTHalo( scale = 1.5, // Controls the halo size stops = listOf( MTHaloStop(position = 0.2, color = "#00000000"), MTHaloStop(position = 0.2, color = "#FF0000"), MTHaloStop(position = 0.4, color = "#FF0000"), MTHaloStop(position = 0.4, color = "#00000000"), MTHaloStop(position = 0.6, color = "#00000000"), MTHaloStop(position = 0.6, color = "#FF0000"), MTHaloStop(position = 0.8, color = "#FF0000"), MTHaloStop(position = 0.8, color = "#00000000"), MTHaloStop(position = 1.0, color = "#00000000"), ), ), ) } ``` Dynamic updates — change halo at runtime ```kotlin // Call after the map is initialized (e.g., in MTMapViewDelegate.onMapViewInitialized) controller.style?.setHalo( MTHalo( scale = 2.0, stops = listOf( MTHaloStop(position = 0.0, color = "#87CEFA"), MTHaloStop(position = 0.5, color = "#0000FABF"), MTHaloStop(position = 0.75, color = "#FF000000"), ), ), ) ``` Disable animations — halo and space ```kotlin // Call after initialization controller.style?.disableHaloAnimations() controller.style?.disableSpaceAnimations() ``` # MapTilerSDK Source: https://docs.maptiler.com/mobile-sdk/android/api/ MapTilerSDK Map Tiler SDK com. maptiler. maptilersdk MTConfig MTUnit IMPERIAL METRIC NAUTICAL com. maptiler. maptilersdk. annotations MTAnchor CENTER TOP BOTTOM LEFT RIGHT TOP_ LEFT TOP_ RIGHT BOTTOM_ LEFT BOTTOM_ RIGHT MTAnnotation MTCustom Annotation View() MTCustom Annotation View Classic MTMarker MTPitch Alignment MAP VIEWPORT AUTO MTRotation Alignment MAP VIEWPORT AUTO MTText Popup com. maptiler. maptilersdk. bridge MTError Bridge Not Loaded Exception Error Invalid Result Type Missing Parent Unknown Unsupported Return Type MTException com. maptiler. maptilersdk. colorramp MTArray Color Ramp Stop MTBuiltin Color Ramp NULL GRAY JET HSV HOT SPRING SUMMER AUTOMN WINTER BONE COPPER GREYS YIGNBU GREENS YIORRD BLUERED RDBU PICNIC RAINBOW PORTLAND BLACKBODY EARTH ELECTRIC VIRIDIS INFERNO MAGMA PLASMA WARM COOL RAINBOW_ SOFT BATHYMETRY CDOM CHLOROPHYLL DENSITY FREESURFACE_ BLUE FREESURFACE_ RED OXYGEN PAR PHASE SALINITY TEMPERATURE TURBIDITY VELOCITY_ BLUE VELOCITY_ GREEN CUBEHELIX CIVIDIS TURBO ROCKET MAKO MTColor Ramp Companion MTColor Ramp Bounds MTColor Ramp Canvas Options MTColor Ramp Clone Options MTColor Ramp Collection MTColor Ramp Get Color Options MTColor Ramp Options MTColor Ramp Resampling Method EASE_ IN_ SQUARE EASE_ OUT_ SQUARE EASE_ IN_ SQRT EASE_ OUT_ SQRT EASE_ IN_ EXP EASE_ OUT_ EXP MTColor Stop com. maptiler. maptilersdk. events Event Processor Event Processor Delegate MTEvent ON_ BOX_ ZOOM_ CANCEL ON_ BOX_ ZOOM_ END ON_ BOX_ ZOOM_ START ON_ TAP ON_ COOPERATIVE_ GESTURE_ PREVENTED ON_ DATA_ UPDATE ON_ DATA_ UPDATE_ ABORT ON_ DATA_ UPDATE_ START ON_ DOUBLE_ TAP ON_ DRAG ON_ POPUP_ OPEN ON_ POPUP_ CLOSE ON_ DRAG_ END ON_ DRAG_ START ON_ MARKER_ DRAG ON_ MARKER_ DRAG_ END ON_ MARKER_ DRAG_ START ON_ IDLE ON_ LOAD ON_ LOAD_ WITH_ TERRAIN ON_ MOVE ON_ MOVE_ END ON_ MOVE_ START ON_ PITCH_ UPDATE ON_ PITCH_ UPDATE_ END ON_ PITCH_ UPDATE_ START ON_ PROJECTION_ MODIFY ON_ READY ON_ REMOVE ON_ RENDER ON_ RESIZE ON_ ROTATE ON_ ROTATE_ END ON_ ROTATE_ START ON_ SOURCE_ UPDATE ON_ SOURCE_ UPDATE_ ABORT ON_ SOURCE_ UPDATE_ START ON_ STYLE_ UPDATE ON_ STYLE_ UPDATE_ START ON_ STYLE_ IMAGE_ MISSING ON_ TERRAIN_ CHANGE ON_ TERRAIN_ ANIMATION_ START ON_ TERRAIN_ ANIMATION_ STOP ON_ TOUCH_ CANCEL ON_ TOUCH_ END ON_ TOUCH_ MOVE ON_ TOUCH_ START ON_ ZOOM ON_ ZOOM_ END ON_ ZOOM_ START com. maptiler. maptilersdk. helpers Json Config MTBenchmark MTColor Value Companion MTColor Value As String Serializer MTDash Array Option Numbers String Value MTDash Array Option Serializer MTHeatmap Layer Helper MTHeatmap Layer Options MTHelper Property Value MTNumber Or Property Values Number Property Map MTNumber Or Property Values Serializer MTNumber Or Zoom Number Values Number Ramp MTNumber Or Zoom Number Values Serializer MTOutline Position CENTER INSIDE OUTSIDE MTPerformance Presets MTPitch Limit Helper MTPoint Layer Helper MTPoint Layer Options MTPolygon Layer Helper MTPolygon Layer Options MTPolyline Layer Helper MTPolyline Layer Options MTProperty Values MTRadius Option Number Property Zoom MTRadius Option Serializer MTString Or Zoom String Values Color Hex Companion Ramp String Value MTString Or Zoom String Values Serializer MTZoom Number Value MTZoom Number Values MTZoom String Value MTZoom String Values to Hex String() with Balanced Performance Defaults() with High Fidelity Defaults() with Lean Performance Defaults() com. maptiler. maptilersdk. location MTLocation Error Permission Denied MTLocation Manager MTLocation Manager Delegate com. maptiler. maptilersdk. logging MTLog MTLoggable MTLogger MTLog Level Debug Info None MTLog Type INFO WARNING ERROR CRITICAL_ ERROR EVENT OSLogger com. maptiler. maptilersdk. map Lng Lat MTMap Camera Helper Companion MTMap Options MTMap View() MTMap View Classic MTMap View Content Delegate MTMap View Controller MTMap View Delegate com. maptiler. maptilersdk. map. gestures MTDouble Tap Zoom In Gesture Companion MTDrag Pan Gesture Companion MTGesture MTGesture Service Companion MTGesture Type DOUBLE_ TAP_ ZOOM_ IN DRAG_ PAN TWO_ FINGERS_ DRAG_ PITCH PINCH_ ROTATE_ AND_ ZOOM MTPinch Rotate And Zoom Gesture Companion MTTwo Fingers Drag Pitch Gesture Companion com. maptiler. maptilersdk. map. options MTAnimation Options MTCamera Options MTDrag Pan Options MTEvent Level ESSENTIAL CAMERA_ ONLY ALL OFF MTFit Bounds Options MTFly To Options MTHalo MTHalo Option Config Enabled MTHalo Option Serializer MTHalo Stop MTPadding Options MTSky Companion MTSpace MTSpace Faces MTSpace Option Config Enabled MTSpace Option Serializer MTSpace Path MTSpace Preset SPACE STARS MILKYWAY MILKYWAY_ SUBTLE MILKYWAY_ BRIGHT MILKYWAY_ COLORED com. maptiler. maptilersdk. map. style MTMap Reference Style AQUARELLE BACKDROP BASIC BRIGHT Companion CUSTOM DATAVIZ LANDSCAPE OCEAN OPENSTREETMAP OUTDOOR SATELLITE STREETS TONER TOPO WINTER MTMap Style Variant DEFAULT_ VARIANT DARK LIGHT PASTEL NIGHT SHINY TOPOGRAPHIQUE LITE LINES BACKGROUND VIVID MTStyle MTStyle Error Layer Already Exists Layer Not Found Source Already Exists Source Not Found MTTerrain Specification MTTile Scheme XYZ TMS set Circle Color Step() set Circle Color Step Await() set Circle Radius Step() set Circle Radius Step Await() set Text Allow Overlap() set Text Allow Overlap Await() set Text Field Token() set Text Field Token Await() set Text Size() set Text Size Await() com. maptiler. maptilersdk. map. style. dsl MTExpression MTFeature Key POINT_ COUNT CLUSTER_ ID MTFilter MTText Token POINT_ COUNT_ ABBREVIATED Property Value Arr Bool Color Companion Num Raw Js Str Style Value Bool Color Expression Number Str com. maptiler. maptilersdk. map. style. image MTAdd Image Options com. maptiler. maptilersdk. map. style. layer MTLayer MTLayer Type FILL LINE SYMBOL RASTER CIRCLE FILL_ EXTRUSION HEATMAP HILLSHADE BACKGROUND MTLayer Visibility Companion VISIBLE NONE com. maptiler. maptilersdk. map. style. layer. background MTBackground Layer com. maptiler. maptilersdk. map. style. layer. circle color Const() color Expr() MTCircle Layer MTCircle Pitch Alignment VIEWPORT MAP MTCircle Pitch Scale VIEWPORT MAP MTCircle Translate Anchor MAP VIEWPORT radius Const() radius Expr() com. maptiler. maptilersdk. map. style. layer. fill Color As Hex Serializer MTFill Layer MTFill Translate Anchor MAP VIEWPORT com. maptiler. maptilersdk. map. style. layer. fillextrusion MTFill Extrusion Layer MTFill Extrusion Translate Anchor MAP VIEWPORT com. maptiler. maptilersdk. map. style. layer. heatmap color Const() color Expr() intensity Const() intensity Expr() MTHeatmap Layer opacity Const() opacity Expr() radius Const() radius Expr() weight Const() weight Expr() com. maptiler. maptilersdk. map. style. layer. hillshade MTHillshade Illumination Anchor MAP VIEWPORT MTHillshade Layer com. maptiler. maptilersdk. map. style. layer. line MTLine Cap BUTT ROUND SQUARE MTLine Join BEVEL ROUND MITER MTLine Layer MTLine Translate Anchor MAP VIEWPORT com. maptiler. maptilersdk. map. style. layer. raster MTRaster Layer MTRaster Resampling LINEAR NEAREST com. maptiler. maptilersdk. map. style. layer. symbol MTSymbol Layer MTText Anchor Companion CENTER LEFT RIGHT TOP BOTTOM TOP_ LEFT TOP_ RIGHT BOTTOM_ LEFT BOTTOM_ RIGHT text Allow Overlap() text Anchor() text Color Const() text Color Expr() text Field() text Font() text Size() com. maptiler. maptilersdk. map. style. source MTGeo JSONSource Companion MTImage Source MTRaster DEMEncoding TERRARIUM MAPBOX MTRaster DEMSource MTRaster Tile Source MTSource MTSource Type VECTOR RASTER RASTER_ DEM GEOJSON IMAGE VIDEO MTTile Source MTVector Tile Source MTVideo Source URLAs String Serializer com. maptiler. maptilersdk. map. types MTBounds MTCountry Language ALBANIAN AMHARIC ARABIC ARMENIAN AZERBAIJANI BASQUE BELARUSIAN BENGALI BOSNIAN BRETON BULGARIAN CATALAN CHINESE TRADITIONAL_ CHINESE SIMPLIFIED_ CHINESE CORSICAN CROATIAN CZECH DANISH DUTCH ENGLISH ESPERANTO ESTONIAN FINNISH FRENCH FRISIAN GALICIAN GEORGIAN GERMAN GREEK HEBREW HINDI HUNGARIAN ICELANDIC INDONESIAN IRISH ITALIAN JAPANESE JAPANESE_ HIRAGANA JAPANESE_ LATIN JAPANESE_ KANA KANNADA KAZAKH KOREAN KOREAN_ LATIN KURDISH CLASSICAL_ LATIN LATVIAN LITHUANIAN LUXEMBOURGISH MACEDONIAN MALAY MALTESE MARATHI MONGOLIAN NEPALI NORWEGIAN OCCITAN PERSIAN POLISH PORTUGUESE PUNJABI WESTERN_ PUNJABI ROMANIAN ROMANSH RUSSIAN SARDINIAN SCOTTISH_ GAELIC SERBIAN_ CYRILLIC SERBIAN_ LATIN SLOVAK SLOVENE SPANISH SWAHILI SWEDISH TAGALOG TAMIL TELUGU THAI TURKISH UKRAINIAN URDU VIETNAMESE WELSH MTData MTLanguage Country Special MTLanguage Serializer MTMap Corner TOP_ LEFT TOP_ RIGHT BOTTOM_ LEFT BOTTOM_ RIGHT MTPoint MTProjection Type MERCATOR GLOBE MTSource Data MTSpecial Language AUTO INTERNATIONAL LATIN LOCAL NON_ LATIN STYLE VISITOR VISITOR_ ENGLISH com. maptiler. maptilersdk. map. workers. navigable MTNavigable com. maptiler. maptilersdk. map. workers. stylable MTStylable com. maptiler. maptilersdk. map. workers. zoomable MTZoomable MapTilerSDK Packages com.maptiler.maptilersdk androidJvm com.maptiler.maptilersdk.annotations androidJvm com.maptiler.maptilersdk.bridge androidJvm com.maptiler.maptilersdk.colorramp androidJvm com.maptiler.maptilersdk.events androidJvm com.maptiler.maptilersdk.helpers androidJvm com.maptiler.maptilersdk.location androidJvm com.maptiler.maptilersdk.logging androidJvm com.maptiler.maptilersdk.map androidJvm com.maptiler.maptilersdk.map.gestures androidJvm com.maptiler.maptilersdk.map.options androidJvm com.maptiler.maptilersdk.map.style androidJvm com.maptiler.maptilersdk.map.style.dsl androidJvm com.maptiler.maptilersdk.map.style.image androidJvm com.maptiler.maptilersdk.map.style.layer androidJvm com.maptiler.maptilersdk.map.style.layer.background androidJvm com.maptiler.maptilersdk.map.style.layer.circle androidJvm com.maptiler.maptilersdk.map.style.layer.fill androidJvm com.maptiler.maptilersdk.map.style.layer.fillextrusion androidJvm com.maptiler.maptilersdk.map.style.layer.heatmap androidJvm com.maptiler.maptilersdk.map.style.layer.hillshade androidJvm com.maptiler.maptilersdk.map.style.layer.line androidJvm com.maptiler.maptilersdk.map.style.layer.raster androidJvm com.maptiler.maptilersdk.map.style.layer.symbol androidJvm com.maptiler.maptilersdk.map.style.source androidJvm com.maptiler.maptilersdk.map.types androidJvm com.maptiler.maptilersdk.map.workers.navigable androidJvm com.maptiler.maptilersdk.map.workers.stylable androidJvm com.maptiler.maptilersdk.map.workers.zoomable androidJvm # MapTiler SDK Kotlin Examples Source: https://docs.maptiler.com/mobile-sdk/android/examples/ _No overview content available._ # MapTiler SDK Swift Source: https://docs.maptiler.com/mobile-sdk/ios/ The MapTiler SDK Swift is a native SDK written in Swift, designed to work with the well-established MapTiler Cloud service, which provides all the data required to fuel a complete mobile mapping experience: vector tiles, geojson, map interaction, custom styles, data visualization and more. ## 📦 Installation MapTiler Swift SDK is a Swift Package and can be added as dependency through **Swift Package Manager**. - File -> Add Package Dependencies - Add https://github.com/maptiler/maptiler-sdk-swift.git ## 🚀 Basic Usage Make sure to set your MapTiler Cloud API key first. (i.e. in AppDelegate): ```swift Task { await MTConfig.shared.setAPIKey("YOUR_API_KEY") } ``` ### UIKit ```swift import MapTilerSDK let coordinates = CLLocationCoordinate2D(latitude: 47.137765, longitude: 8.581651) let options = MTMapOptions(center: coordinates, zoom: 2.0, bearing: 1.0, pitch: 20.0) var mapView = MTMapView(frame: view.frame, options: options, referenceStyle: .streets) mapView.delegate = self view.addSubview(mapView) ``` If you are using auto layout, you can call the helper function for anchors pinning. This ensures correct orientation updates. ```swift mapView.pinToSuperviewEdges() ``` ### SwiftUI ```swift import MapTilerSDK @State private var mapView = MTMapView(options: MTMapOptions(zoom: 2.0)) var body: some View { MTMapViewContainer(map: mapView) {} .referenceStyle(.streets) } ``` For detailed functionality overview refer to the API Reference documentation or build local docs in Xcode: Product -> Build Documentation. ## 📘 API Reference For detailed guides, API reference, and advanced examples, visit our comprehensive documentation: [API documentation](https://docs.maptiler.com/mobile-sdk/ios/) ### Sources and Layers Sources and layers can be added to the map view style object as soon as map is initialized. Setting the style after adding layers resets them to default, so make sure style is finished loading first. #### UIKit ```swift guard let style = mapView.style else { return } if let contoursTilesURL = URL(string: "https://api.maptiler.com/tiles/contours-v2/tiles.json?key=YOUR_API_KEY") { let contoursDataSource = MTVectorTileSource(identifier: "contoursSource", url: contoursTilesURL) style.addSource(contoursDataSource) let contoursLayer = MTLineLayer(identifier: "contoursLayer", sourceIdentifier: contoursDataSource.identifier, sourceLayer: "contour_ft") contoursLayer.color = .brown contoursLayer.width = 2.0 style.addLayer(contoursLayer) } ``` #### SwiftUI ```swift @State private var mapView = MTMapView(options: MTMapOptions(zoom: 2.0)) var body: some View { MTMapViewContainer(map: mapView) { MTVectorTileSource(identifier: "countoursSource", url: URL(string: "https://api.maptiler.com/tiles/contours-v2/tiles.json?key=YOUR_API_KEY")) MTLineLayer(identifier: "contoursLayer", sourceIdentifier: "countoursSource", sourceLayer: "contour_ft") .color(.brown) .width(2.0) } } ``` ### Markers and Popups Markers and popups (Text, Custom Annotation) can be used for highlighting points of interest on the map. #### UIKit ```swift let coordinates = CLLocationCoordinate2D(latitude: 47.137765, longitude: 8.581651) let popup = MTTextPopup(coordinates: coordinates, text: "MapTiler", offset: 20.0) let marker = MTMarker(coordinates: coordinates, popup: popup) marker.draggable = true mapView.addMarker(marker) ``` #### SwiftUI ```swift @State private var mapView = MTMapView(options: MTMapOptions(zoom: 2.0)) let coordinates = CLLocationCoordinate2D(latitude: 47.137765, longitude: 8.581651) var body: some View { MTMapViewContainer(map: mapView) { let popup = MTTextPopup(coordinates: coordinates, text: "MapTiler", offset: 20.0) MTMarker(coordinates: coordinates, draggable: true, popup: popup) } } ``` Alternatively add content on custom actions: ```swift @State private var mapView = MTMapView(options: MTMapOptions(zoom: 2.0)) let coordinates = CLLocationCoordinate2D(latitude: 47.137765, longitude: 8.581651) var body: some View { MTMapViewContainer(map: mapView) { } .didInitialize { let marker = MTMarker(coordinates: coordinates) Task { await mapView.addMarker(marker) } } Button("Add Popup") { Task { let popup = MTTextPopup(coordinates: coordinates, text: "MapTiler", offset: 20.0) await mapView.addTextPopup(popup) } } } ``` For additional examples refer to the Examples directory. ### Custom Annotations In addition to `MTMarker` and `MTTextPopup`, you can use `MTCustomAnnotationView` class to make your own annotations and add them to the map. You can subclass to create custom UI it or use it as is for simple designs. ```swift let customSize = CGSize(width: 200.0, height: 80.0) let coordinates = CLLocationCoordinate2D(latitude: 47.137765, longitude: 8.581651) let offset = MTPoint(x: 0, y: -80) let myCustomView = MTCustomAnnotationView(size: customSize, coordinates: coordinates, offset: offset) myCustomView.backgroundColor = .blue myCustomView.addTo(mapView) ``` ### Space The space option customizes the globe’s background, simulating deep space or skybox effects. - Prerequisite: use globe projection. Set `projection: .globe` in `MTMapOptions`. Usage — solid color background ```swift import MapTilerSDK // UIKit let options = MTMapOptions( projection: .globe, space: .config( MTSpace( color: MTColor(color: UIColor(hex: "#111122")!.cgColor) ) ) ) let mapView = MTMapView(frame: view.bounds, options: options, referenceStyle: .streets) // SwiftUI @State private var mapView = MTMapView( options: MTMapOptions( projection: .globe, space: .config(MTSpace(color: MTColor(color: UIColor(hex: "#111122")!.cgColor))) ) ) ``` Presets — predefined cubemaps - `space`: Dark blue background; stars stay white. Space color changes background color. - `stars` (default): Black background; space color changes stars color. - `milkyway`: Black half‑transparent background with standard milky way and stars; space color tints stars and milky way. - `milkyway-subtle`: Subtle milky way, fewer stars; space color tints stars and milky way. - `milkyway-bright`: Bright milky way, more stars; space color tints stars and milky way. - `milkyway-colored`: Full image with natural colors; space color has no effect. ```swift // Use a preset let options = MTMapOptions( projection: .globe, space: .config(MTSpace(preset: .space)) ) ``` Custom cubemap — provide all faces ```swift let faces = MTSpaceFaces( pX: URL(string: "https://example.com/space/px.png")!, nX: URL(string: "https://example.com/space/nx.png")!, pY: URL(string: "https://example.com/space/py.png")!, nY: URL(string: "https://example.com/space/ny.png")!, pZ: URL(string: "https://example.com/space/pz.png")!, nZ: URL(string: "https://example.com/space/nz.png")! ) let options = MTMapOptions( projection: .globe, space: .config(MTSpace(faces: faces)) ) ``` Cubemap by path — files named px, nx, py, ny, pz, nz with the given format ```swift let path = MTSpacePath( baseUrl: URL(string: "https://example.com/spacebox/transparent")!, format: "png" // defaults to PNG if omitted ) let options = MTMapOptions( projection: .globe, space: .config(MTSpace(path: path)) ) ``` Dynamic updates — change space at runtime ```swift mapView.didInitialize = { Task { await mapView.setSpace( .config( MTSpace( color: MTColor(color: UIColor.red.cgColor), path: MTSpacePath(baseUrl: URL(string: "https://example.com/spacebox/transparent")!) ) ) ) } } ``` Note: When calling `setSpace`, any field not explicitly provided (e.g., `color`, `faces`, `path`, or `preset`) keeps its previous value. ### Halo The halo option adds a gradient-based atmospheric glow around the globe, simulating the visual effect of Earth's atmosphere when viewed from space. - Prerequisite: use globe projection. Set `projection: .globe` in `MTMapOptions`. Usage — enable simple halo ```swift import MapTilerSDK // UIKit let options = MTMapOptions( projection: .globe, halo: .enabled(true) ) let mapView = MTMapView(frame: view.bounds, options: options, referenceStyle: .outdoor) // SwiftUI @State private var mapView = MTMapView( options: MTMapOptions( projection: .globe, halo: .enabled(true) ) ) ``` Custom gradient — scale and stops ```swift let options = MTMapOptions( projection: .globe, halo: .config( MTHalo( scale: 1.5, // Controls the halo size stops: [ MTHaloStop(position: 0.2, color: MTColor(hex: "#00000000")), MTHaloStop(position: 0.2, color: MTColor(hex: "#FF0000")), MTHaloStop(position: 0.4, color: MTColor(hex: "#FF0000")), MTHaloStop(position: 0.4, color: MTColor(hex: "#00000000")), MTHaloStop(position: 0.6, color: MTColor(hex: "#00000000")), MTHaloStop(position: 0.6, color: MTColor(hex: "#FF0000")), MTHaloStop(position: 0.8, color: MTColor(hex: "#FF0000")), MTHaloStop(position: 0.8, color: MTColor(hex: "#00000000")), MTHaloStop(position: 1.0, color: MTColor(hex: "#00000000")) ] ) ) ) ``` Dynamic updates — change halo at runtime ```swift mapView.didInitialize = { Task { await mapView.setHalo( .config( MTHalo( scale: 2.0, stops: [ MTHaloStop(position: 0.0, color: MTColor(hex: "#87CEFA")), MTHaloStop(position: 0.5, color: MTColor(hex: "#0000FABF")), MTHaloStop(position: 0.75, color: MTColor(hex: "#FF000000")) ] ) ) ) } } ``` Disable animations — halo and space ```swift mapView.didInitialize = { Task { await mapView.disableHaloAnimations() await mapView.disableSpaceAnimations() } } ``` # MapTiler SDK Swift API Reference Source: https://docs.maptiler.com/mobile-sdk/ios/api/ Actors MTConfig Classes MTBackgroundLayer MTBenchmark MTCircleLayer MTColorRamp MTCustomAnnotationView MTFillExtrusionLayer MTFillLayer MTGeoJSONSource MTGestureService MTHeatmapLayer MTHeatmapLayerHelper MTHillshadeLayer MTImageSource MTLineLayer MTLocationManager MTLogger MTMapCameraHelper MTMapView MTMarker MTPointLayerHelper MTPolygonLayerHelper MTPolylineLayerHelper MTRasterDEMSource MTRasterLayer MTRasterTileSource MTStyle MTSymbolLayer MTTextPopup MTVectorTileSource MTVideoSource Enumerations MTAnchor MTCirclePaintProperty MTCirclePitchAlignment MTCirclePitchScale MTCircleTranslateAnchor MTColorRampPreset MTColorRampResampleMethod MTCountryLanguage MTDashArrayValue MTEasing MTError MTEvent MTEventLevel MTExpression MTFeatureKey MTFillExtrusionTranslateAnchor MTFillTranslateAnchor MTFilter MTFitBoundsPadding MTGestureType MTHaloOption MTHillshadeIlluminationAnchor MTLanguage MTLayerType MTLayerVisibility MTLightAnchor MTLineCap MTLineJoin MTLineTranslateAnchor MTLocationError MTLogLevel MTLogType MTMapCorner MTMapReferenceStyle MTMapStyleVariant MTMarkerPitchAlignment MTMarkerRotationAlignment MTNumberOrPropertyValues MTNumberOrZoomNumberValues MTPerformancePresets MTProjectionType MTPropertyValue MTRadiusOption MTRasterDEMEncoding MTRasterResampling MTSkyColorValue MTSkyExpression MTSkyNumberValue MTSourceType MTSpaceOption MTSpacePreset MTSpecialLanguage MTStringOrZoomStringValues MTStyleError MTStyleValue MTSymbolLayoutProperty MTSymbolPaintProperty MTTextAnchor MTTextToken MTTileScheme MTUnit Extensions CLLocationCoordinate2D UIColor Protocols MTAnnotation MTControllable MTGesture MTLayer MTLocationManagerDelegate MTLoggable MTMapViewContent MTMapViewDelegate MTNavigable MTRendering MTSource MTStylable MTTileSource MTVectorLayerHelper MTZoomable Structures MTAnimationOptions MTBounds MTCameraOptions MTColor MTColorRampArrayStop MTColorRampBounds MTColorRampCanvasStripOptions MTColorRampOptions MTColorRampStop MTColorValue MTData MTDoubleTapZoomInGesture MTDragPanGesture MTDragPanOptions MTException MTFitBoundsOptions MTFlyToOptions MTHalo MTHaloStop MTHeatmapLayerOptions MTHelperPropertyValue MTLight MTLog MTMapContentBuilder MTMapOptions MTMapViewContainer MTPaddingOptions MTPinchRotateAndZoomGesture MTPoint MTPointLayerOptions MTPolygonLayerOptions MTPolylineLayerOptions MTRGBAColor MTSky MTSourceData MTSpace MTSpaceFaces MTSpacePath MTStyleImageOptions – Stretch – Content MTStyleSetterOptions MTTwoFingersDragPitchGesture MTZoomNumberValue MTZoomStringValue Type Aliases MTPropertyValues MTZoomNumberValues MTZoomStringValues MapTiler SDK Swift API Reference Actors The following actors are available globally. MTConfig Object representing the SDK global settings. Exposes properties and options such as API Key and caching preferences. See more Declaration Swift public actor MTConfig Classes The following classes are available globally. MTCustomAnnotationView Subclassable view for adding custom annotations to the map. See more Declaration Swift @MainActor open class MTCustomAnnotationView : UIView , @preconcurrency MTAnnotation extension MTCustomAnnotationView : @preconcurrency MTMapViewContent MTMarker Annotation element that can be added to the map. See more Declaration Swift public class MTMarker : MTAnnotation , MTMapViewContent , @unchecked Sendable MTTextPopup Basic text popup. Can be attached to MTMarker or standalone. See more Declaration Swift public class MTTextPopup : MTAnnotation , MTMapViewContent , @unchecked Sendable MTBenchmark Basic benchmarking class. See more Declaration Swift @MainActor public final class MTBenchmark : MTMapViewDelegate MTMapView Object representing the map on the screen. Exposes methods and properties that enable changes to the map, and fires events that can be interacted with. See more Declaration Swift @MainActor open class MTMapView : UIView , Sendable extension MTMapView : MTControllable extension MTMapView : MTNavigable extension MTMapView : MTRendering extension MTMapView : MTStylable extension MTMapView : MTZoomable extension MTMapView : MTLocationManagerDelegate MTHeatmapLayerHelper Helper for creating a heatmap visualization layer from data and styling options. See more Declaration Swift public final class MTHeatmapLayerHelper : MTVectorLayerHelper , @unchecked Sendable MTPointLayerHelper Helper for creating a point visualization layer from data and styling options. Uses the current style to create the underlying source and layers. See more Declaration Swift public final class MTPointLayerHelper : MTVectorLayerHelper , @unchecked Sendable MTPolygonLayerHelper Helper for creating a polygon (fill) visualization layer from data and styling options. See more Declaration Swift public final class MTPolygonLayerHelper : MTVectorLayerHelper , @unchecked Sendable MTPolylineLayerHelper Helper for creating a polyline (line) visualization layer from data and styling options. See more Declaration Swift public final class MTPolylineLayerHelper : MTVectorLayerHelper , @unchecked Sendable MTLogger Logger class used for SDK logs. See more Declaration Swift public class MTLogger MTLocationManager Class responsible for location updates. See more Declaration Swift public class MTLocationManager : NSObject , @preconcurrency CLLocationManagerDelegate MTGestureService Service responsible for gesture handling and state. See more Declaration Swift @MainActor public class MTGestureService MTMapCameraHelper Sets combination of center, bearing and pitch, as well as roll and elevation. See more Declaration Swift public class MTMapCameraHelper MTStyle The proxy object for the current map style. Set of convenience methods for style, sources and layers manipulation. MTStyle is nil until map loading is complete. Since it is loaded asynchronously it should be manipulated only after MTEvent.didLoad triggers. See more Declaration Swift @MainActor public class MTStyle MTBackgroundLayer The background style layer covers the entire map. Use a background style layer to configure a color or pattern to show below all other map content. If the background layer is transparent or omitted from the style, any part of the map view that does not show another style layer is transparent. See more Declaration Swift public class MTBackgroundLayer : MTLayer , @unchecked Sendable , Codable MTCircleLayer The circle style layer renders one or more filled circles on the map. See more Declaration Swift public class MTCircleLayer : MTLayer , @unchecked Sendable , Codable extension MTCircleLayer : Equatable MTFillLayer The fill style layer that renders one or more filled (and optionally stroked) polygons on a map. See more Declaration Swift public class MTFillLayer : MTLayer , @unchecked Sendable , Codable extension MTFillLayer : Equatable MTFillExtrusionLayer A fill-extrusion style layer renders one or more filled (and optionally stroked) extruded (3D) polygons on a map. See more Declaration Swift public class MTFillExtrusionLayer : MTLayer , @unchecked Sendable , Codable extension MTFillExtrusionLayer : Equatable MTHeatmapLayer A heatmap style layer renders a range of colors to represent the density of points in an area. See more Declaration Swift public class MTHeatmapLayer : MTLayer , @unchecked Sendable , Codable extension MTHeatmapLayer : Equatable MTHillshadeLayer A hillshade style layer renders digital elevation model (DEM) data on the client-side. Supports Terrain RGB and Mapzen Terrarium tiles via a raster-dem source. See more Declaration Swift public class MTHillshadeLayer : MTLayer , @unchecked Sendable , Codable MTLineLayer The line style layer that renders one or more stroked polylines on the map. See more Declaration Swift public class MTLineLayer : MTLayer , @unchecked Sendable , Codable MTRasterLayer The raster style layer renders raster map textures such as imagery. See more Declaration Swift public class MTRasterLayer : MTLayer , @unchecked Sendable , Codable MTSymbolLayer The symbol style that layer renders icon and text labels at points or along lines on a map. See more Declaration Swift public class MTSymbolLayer : MTLayer , @unchecked Sendable , Codable extension MTSymbolLayer : Equatable MTGeoJSONSource A geojson source. See more Declaration Swift public class MTGeoJSONSource : MTSource , @unchecked Sendable , Codable MTImageSource An image source. The url value contains the image location. The coordinates array contains [longitude, latitude] pairs for the image corners listed in clockwise order: top left, top right, bottom right, bottom left. See more Declaration Swift public class MTImageSource : MTSource , @unchecked Sendable MTRasterDEMSource A raster DEM source. Only supports Terrain RGB. See more Declaration Swift public class MTRasterDEMSource : MTTileSource , @unchecked Sendable MTRasterTileSource A raster tile source. For raster tiles hosted by MapTiler, the “url” value should be of the form https://api.maptiler.com/tiles/[tilesetid]/tiles.json?key= See more Declaration Swift public class MTRasterTileSource : MTTileSource , @unchecked Sendable MTVectorTileSource Undocumented See more Declaration Swift public class MTVectorTileSource : MTTileSource , @unchecked Sendable MTVideoSource A video source. The urls value is an array. For each URL in the array, a video element source will be created. The coordinates array contains [longitude, latitude] pairs for the video corners listed in clockwise order: top left, top right, bottom right, bottom left. See more Declaration Swift public class MTVideoSource : MTSource , @unchecked Sendable MTColorRamp Swift wrapper over the MapTiler SDK ColorRamp class. See more Declaration Swift @MainActor public final class MTColorRamp : @unchecked Sendable Enumerations The following enumerations are available globally. MTAnchor Anchor positions for marker placement. See more Declaration Swift public enum MTAnchor : String , Sendable , Codable MTMarkerRotationAlignment Alignment for marker rotation relative to map or viewport. See more Declaration Swift public enum MTMarkerRotationAlignment : String , Sendable , Codable MTMarkerPitchAlignment Alignment for marker pitch relative to map or viewport. See more Declaration Swift public enum MTMarkerPitchAlignment : String , Sendable , Codable MTError Represents all the errors that can occur in the MapTiler SDK. All methods within the SDK throw MTError. See more Declaration Swift public enum MTError : Error MTLogLevel SDK log level. See more Declaration Swift public enum MTLogLevel : Sendable , Equatable MTLogType Type of log messages in the SDK. See more Declaration Swift public enum MTLogType : Sendable MTEvent Events triggered by the SDK See more Declaration Swift public enum MTEvent : String MTLanguage Language of the map labels. See more Declaration Swift public enum MTLanguage : Sendable , Codable MTSpecialLanguage Custom language options. See more Declaration Swift public enum MTSpecialLanguage : String , Sendable , Codable MTCountryLanguage Languages available for MTMapView object. See more Declaration Swift public enum MTCountryLanguage : String , Sendable , Codable , CaseIterable MTLocationError Enum representing MTLocationManager errors. See more Declaration Swift public enum MTLocationError : Error MTUnit Units of measurement used in MTMapView object. See more Declaration Swift public enum MTUnit : String , Sendable MTGestureType Gesture types available in the SDK. See more Declaration Swift @MainActor public enum MTGestureType MTEventLevel Controls which map events are forwarded from the map object. essential: Low-frequency lifecycle events only (ready, load, moveend, etc.) plus taps. cameraOnly: Forwards only camera events (move, zoom) in addition to minimal lifecycle. all: Default. Forwards all events including high-frequency move/zoom/touch/render (use with caution on low-end devices). off: Minimal wiring to keep internal lifecycle (ready/load) functioning; all other events are suppressed. See more Declaration Swift public enum MTEventLevel : String , Codable , Sendable MTPerformancePresets Performance-oriented presets for MapTiler Swift SDK. See more Declaration Swift public enum MTPerformancePresets MTFitBoundsPadding Padding values accepted by MTFitBoundsOptions . See more Declaration Swift public enum MTFitBoundsPadding : Sendable , Codable , Equatable MTExpression Helper to construct common style expressions without raw strings. See more Declaration Swift public enum MTExpression MTFeatureKey Commonly-used feature keys See more Declaration Swift public enum MTFeatureKey : String , Sendable MTFilter Helper to construct common filter expressions without raw strings. See more Declaration Swift public enum MTFilter MTCirclePaintProperty Typed keys for circle paint properties. See more Declaration Swift public enum MTCirclePaintProperty : String , Sendable MTSymbolLayoutProperty Typed keys for symbol layout properties. See more Declaration Swift public enum MTSymbolLayoutProperty : String , Sendable MTSymbolPaintProperty Typed keys for symbol paint properties. See more Declaration Swift public enum MTSymbolPaintProperty : String , Sendable MTCirclePitchAlignment Orientation of the circle when map is pitched. See more Declaration Swift public enum MTCirclePitchAlignment : String MTCirclePitchScale Controls the scaling behavior of the circle when the map is pitched. See more Declaration Swift public enum MTCirclePitchScale : String MTCircleTranslateAnchor Controls the frame of reference for circle translate. See more Declaration Swift public enum MTCircleTranslateAnchor : String MTFillTranslateAnchor Enum controlling the frame of reference for fill translate. See more Declaration Swift public enum MTFillTranslateAnchor : String MTFillExtrusionTranslateAnchor Controls the frame of reference for fill-extrusion translate. See more Declaration Swift public enum MTFillExtrusionTranslateAnchor : String MTHillshadeIlluminationAnchor Direction of light source when map is rotated. See more Declaration Swift public enum MTHillshadeIlluminationAnchor : String MTLineCap The display of line endings. See more Declaration Swift public enum MTLineCap : String MTLineJoin The display of lines when joining. See more Declaration Swift public enum MTLineJoin : String MTLineTranslateAnchor Controls the frame of reference for line translate. See more Declaration Swift public enum MTLineTranslateAnchor : String MTLayerType Types of layers. See more Declaration Swift public enum MTLayerType : String , Codable MTLayerVisibility Enum representing the visibility of the layer. See more Declaration Swift public enum MTLayerVisibility : String MTRasterResampling Resampling/interpolation method to use for overscaling. See more Declaration Swift public enum MTRasterResampling : String , Codable , Sendable MTMapReferenceStyle Defines purpose and guidelines on what information is displayed. See more Declaration Swift public enum MTMapReferenceStyle : Identifiable , Hashable , Sendable MTMapStyleVariant Variants of the reference styles. See more Declaration Swift public enum MTMapStyleVariant : String , Sendable , CaseIterable , Identifiable MTPropertyValue A typed value container See more Declaration Swift public enum MTPropertyValue : Sendable MTStyleError Represents the exceptions raised by the MTStyle object. See more Declaration Swift public enum MTStyleError : Error MTStyleValue A unified style value that may be a constant or an expression. See more Declaration Swift public enum MTStyleValue : Sendable MTTileScheme A scheme used for tiles. See more Declaration Swift public enum MTTileScheme : String MTRasterDEMEncoding Encoding used by the Raster DEM source. See more Declaration Swift public enum MTRasterDEMEncoding : String , Sendable MTSourceType Types of sources. Sources state which data the map should display. See more Declaration Swift public enum MTSourceType : String , Codable MTTextAnchor Symbol text anchor positions. See more Declaration Swift public enum MTTextAnchor : String , Sendable MTTextToken Common text field tokens See more Declaration Swift public enum MTTextToken : String , Sendable MTEasing Representing the control of the change rate of the animation. See more Declaration Swift public enum MTEasing : String , Sendable , Codable MTHaloOption Option that can enable default halo or configure it. See more Declaration Swift public enum MTHaloOption : Sendable , Codable MTLightAnchor Sets whether extruded geometries are lit relative to the map or viewport. See more Declaration Swift public enum MTLightAnchor : String , Sendable , Codable MTMapCorner Represents corners of the map. See more Declaration Swift public enum MTMapCorner : String , Sendable , Codable MTProjectionType Type of projection the map uses. See more Declaration Swift public enum MTProjectionType : String , Sendable , Codable MTSpacePreset Predefined cubemap presets for space backgrounds. See more Declaration Swift public enum MTSpacePreset : String , Sendable , Codable , CaseIterable MTSpaceOption Option that can enable default space or configure it. See more Declaration Swift public enum MTSpaceOption : Sendable , Codable MTColorRampResampleMethod Resampling methods supported by MapTiler SDK. See more Declaration Swift public enum MTColorRampResampleMethod : String , Sendable , Codable , CaseIterable MTColorRampPreset Built-in presets shipped with the SDK. See more Declaration Swift public enum MTColorRampPreset : String , Sendable , Codable , CaseIterable Union helper types for encoding mixed-value options MTNumberOrZoomNumberValues Either a numeric value or zoom-ramped numeric values. See more Declaration Swift public enum MTNumberOrZoomNumberValues : Codable , Sendable MTStringOrZoomStringValues Either a string value or zoom-ramped string values. See more Declaration Swift public enum MTStringOrZoomStringValues : Codable , Sendable MTNumberOrPropertyValues Either a numeric value or property-mapped numeric values. See more Declaration Swift public enum MTNumberOrPropertyValues : Codable , Sendable MTRadiusOption Heatmap radius can be a number, zoom-ramped numbers, or property-mapped numbers. See more Declaration Swift public enum MTRadiusOption : Codable , Sendable Line-specific helper values MTDashArrayValue Represents a dash pattern that can be provided as an array of numbers or as a string pattern composed of underscores and spaces (e.g. “___ _ ”). See more Declaration Swift public enum MTDashArrayValue : Codable , Sendable MTSkyExpression Expression element used to build MapTiler style expressions for sky values. See more Declaration Swift public enum MTSkyExpression : Sendable , Codable , Equatable MTSkyColorValue Represents a color or expression for the sky configuration. See more Declaration Swift public enum MTSkyColorValue : Sendable , Codable , Equatable MTSkyNumberValue Represents a numeric value or expression for the sky configuration. See more Declaration Swift public enum MTSkyNumberValue : Sendable , Codable , Equatable Extensions The following extensions are available globally. UIColor See more Declaration Swift extension UIColor CLLocationCoordinate2D See more Declaration Swift extension CLLocationCoordinate2D : @retroactive Equatable extension CLLocationCoordinate2D : Codable Protocols The following protocols are available globally. MTAnnotation Protocol requirements for all annotation objects. See more Declaration Swift public protocol MTAnnotation : Sendable MTVectorLayerHelper Base protocol adopted by vector layer helpers to share defaults and common option normalization logic. See more Declaration Swift public protocol MTVectorLayerHelper : AnyObject MTLoggable Protocol requirement for all Logger objects. See more Declaration Swift public protocol MTLoggable : Sendable MTLocationManagerDelegate Protocol requirements for location manager. See more Declaration Swift @MainActor public protocol MTLocationManagerDelegate : AnyObject MTControllable Defines methods for adding the map controls. See more Declaration Swift @MainActor public protocol MTControllable MTNavigable Defines methods for navigating the map. See more Declaration Swift @MainActor public protocol MTNavigable MTRendering Defines methods for adjusting rendering parameters. See more Declaration Swift @MainActor public protocol MTRendering MTStylable Defines methods for map styling methods. See more Declaration Swift @MainActor public protocol MTStylable MTZoomable Defines methods for manipulating zoom level. See more Declaration Swift @MainActor public protocol MTZoomable MTGesture Defines gestures behaviour. See more Declaration Swift @MainActor public protocol MTGesture MTMapViewContent Map view content requirements. See more Declaration Swift public protocol MTMapViewContent MTMapViewDelegate Delegate responsible for map event propagation See more Declaration Swift @MainActor public protocol MTMapViewDelegate : AnyObject MTLayer Protocol requirements for all types of Layers. See more Declaration Swift public protocol MTLayer : AnyObject , MTMapViewContent , Sendable MTSource Protocol requirements for all types of Sources. See more Declaration Swift public protocol MTSource : AnyObject , MTMapViewContent , Sendable MTTileSource Protocol requirements for all tile type sources. See more Declaration Swift public protocol MTTileSource : MTSource Structures The following structures are available globally. MTException Represents body of the MTError exception. See more Declaration Swift public struct MTException : Sendable MTColor Color wrapper. See more Declaration Swift public struct MTColor : Sendable , Codable , Equatable MTHeatmapLayerOptions Options for building a heatmap visualization layer through the helper. See more Declaration Swift public struct MTHeatmapLayerOptions : Codable , Sendable MTPointLayerOptions Options for building a point visualization layer through the helper. Mirrors the available configuration including common shape options. See more Declaration Swift public struct MTPointLayerOptions : Codable , Sendable MTPolygonLayerOptions Options for building a polygon (fill) visualization layer through the helper. See more Declaration Swift public struct MTPolygonLayerOptions : Codable , Sendable MTPolylineLayerOptions Options for building a polyline (line) visualization layer through the helper. See more Declaration Swift public struct MTPolylineLayerOptions : Codable , Sendable MTLog Log object used with MTLogger. See more Declaration Swift public struct MTLog MTDoubleTapZoomInGesture Handles zooming in the map with double tap. See more Declaration Swift @MainActor public struct MTDoubleTapZoomInGesture : MTGesture MTDragPanGesture Handles panning the map by dragging. See more Declaration Swift @MainActor public struct MTDragPanGesture : MTGesture MTPinchRotateAndZoomGesture Handles zoom and rotate by pinching with two fingers. See more Declaration Swift @MainActor public struct MTPinchRotateAndZoomGesture : MTGesture MTTwoFingersDragPitchGesture Handles changing the pitch by dragging with two fingers. See more Declaration Swift @MainActor public struct MTTwoFingersDragPitchGesture : MTGesture MTMapContentBuilder Map view content builder. See more Declaration Swift @resultBuilder public struct MTMapContentBuilder MTMapOptions Parameters of the map object. See more Declaration Swift public struct MTMapOptions : Sendable extension MTMapOptions : Codable MTMapViewContainer Declarative Map view for use in SwiftUI See more Declaration Swift @MainActor public struct MTMapViewContainer : View MTAnimationOptions Provides animation options for navigation functions. See more Declaration Swift public struct MTAnimationOptions : Sendable , Codable MTCameraOptions Options for controlling the desired location, zoom, bearing, and pitch of the camera. See more Declaration Swift public struct MTCameraOptions : Sendable extension MTCameraOptions : Codable MTDragPanOptions Options for drag and pan gesstures. See more Declaration Swift public struct MTDragPanOptions : Sendable , Codable MTFitBoundsOptions Options that configure how the map fits to a set of bounds. See more Declaration Swift public struct MTFitBoundsOptions : Sendable , Codable MTFlyToOptions Options describing the destination and animation of the flyTo transition. See more Declaration Swift public struct MTFlyToOptions : Sendable , Codable MTPaddingOptions Options for setting padding on calls to map methods. See more Declaration Swift public struct MTPaddingOptions : Sendable , Codable , Equatable MTStyleSetterOptions Supporting type to add validation to another style related type. See more Declaration Swift public struct MTStyleSetterOptions : Sendable , Codable MTStyleImageOptions Configuration that controls how an image is registered within the MapTiler style. See more Declaration Swift public struct MTStyleImageOptions : Codable , Equatable , Sendable MTBounds Represents rectangular geographic bounds defined by southwest and northeast corners. See more Declaration Swift public struct MTBounds : Sendable , Codable , Equatable MTData Object sent together with MTEvent. See more Declaration Swift public struct MTData : Codable MTHaloStop One stop in the halo radial gradient: position in [0,1] and color. See more Declaration Swift public struct MTHaloStop : Sendable , Codable MTHalo Configuration for the atmospheric glow (halo). See more Declaration Swift public struct MTHalo : Sendable , Codable MTLight A style’s light property provides a global light source for that style. See more Declaration Swift public struct MTLight : Sendable , Codable MTPoint Two numbers representing x and y screen coordinates in pixels. See more Declaration Swift public struct MTPoint : Codable , Sendable MTSourceData The style spec representation of the source if the event has a dataType of source . See more Declaration Swift public struct MTSourceData : Codable MTSpaceFaces Faces definition for a custom cubemap. See more Declaration Swift public struct MTSpaceFaces : Sendable , Codable MTSpacePath Path-based configuration for cubemap files. This fetches all images from a path, this assumes all files are named px, nx, py, ny, pz, nz and suffixed with the appropriate extension specified in format. See more Declaration Swift public struct MTSpacePath : Sendable , Codable MTSpace Configuration for the “space” background. See more Declaration Swift public struct MTSpace : Sendable , Codable MTRGBAColor RGBA color represented by 0…255 components. See more Declaration Swift public struct MTRGBAColor : Sendable , Codable MTColorRampStop A stop describing the value and color to apply. See more Declaration Swift public struct MTColorRampStop : Sendable , Codable MTColorRampBounds Bounds of a color ramp. See more Declaration Swift public struct MTColorRampBounds : Sendable , Codable MTColorRampOptions Options used when instantiating a color ramp. See more Declaration Swift public struct MTColorRampOptions : Sendable , Codable MTColorRampCanvasStripOptions Options for rendering the ramp to a canvas strip. See more Declaration Swift public struct MTColorRampCanvasStripOptions : Sendable , Codable MTColorRampArrayStop Array-based stop definition for fromArrayDefinition . See more Declaration Swift public struct MTColorRampArrayStop : Sendable , Codable MTZoomStringValue A single string value at a given zoom level. See more Declaration Swift public struct MTZoomStringValue : Codable , Sendable MTZoomNumberValue A single numeric value at a given zoom level. See more Declaration Swift public struct MTZoomNumberValue : Codable , Sendable MTHelperPropertyValue A single mapping from a property value to an associated numeric value. See more Declaration Swift public struct MTHelperPropertyValue : Codable , Sendable Colors MTColorValue Encodes a color to a hex string when converted to JSON. Accepts either a hex color string (e.g. “#RRGGBB”) or a UIColor. See more Declaration Swift public struct MTColorValue : Codable , Sendable MTSky Sky configuration used by map.setSky . See more Declaration Swift public struct MTSky : Sendable , Codable , Equatable # MapTiler SDK Swift Examples Source: https://docs.maptiler.com/mobile-sdk/ios/examples/ _No overview content available._ # Get started with React Native and MapLibre GL JS Source: https://docs.maptiler.com/react-native/
In this tutorial, you’ll learn how to display a map on a mobile device using React Native and MapLibre GL JS. Together, we will make a simple mobile fullscreen map application as an example of how to use MapTiler maps together with React Native and MapLibre GL JS for your native app. We have made this app using the [expo-dev-client](https://docs.expo.dev/development/getting-started/#installing--expo-dev-client--in-your-project) and the plugin [MapLibre React Native](https://maplibre.org/maplibre-react-native/). ## Installation and setting up 1. Clone the [Get started with React Native and MapLibre GL JS](https://github.com/maptiler/get-started-react-native-maplibre-gl-js) repo ```sh git clone https://github.com/maptiler/get-started-react-native-maplibre-gl-js.git my-react-map ``` 1. Navigate to the newly created project folder **my-react-map** ```sh cd my-react-map ``` 1. Install dependencies ```sh npm install ``` 1. Open the `App.js` file. Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it!
1. Build your project **Android** ```sh # Build your native Android project npx expo run:android ``` **iOS** ```sh # Build your native iOS project npx expo run:ios ``` > [!WARNING] > - `expo run:ios` requires Xcode (macOS only) installed on your computer. See the [setup guide](https://reactnative.dev/docs/environment-setup). > - `expo run:android` requires Android Studio and the Android SDK to be installed. See the [setup guide](https://reactnative.dev/docs/environment-setup). 1. You will find your app on your virtual device (Emulator) or physical device. ## Learn more - [Expo Development builds](https://docs.expo.dev/development/getting-started/#installing--expo-dev-client--in-your-project) - [Adding custom native code](https://docs.expo.dev/workflow/customizing/#generate-native-projects-with-prebuild) - [MapLibre React Native documentation](https://maplibre.org/maplibre-react-native/docs/setup/getting-started) # Get started with Flutter and MapTiler GL JS Source: https://docs.maptiler.com/flutter/ In this tutorial, you’ll learn how to display a map on a mobile device using Flutter and MapTiler GL JS. We will be using _webview_flutter_ to wrap the PWA app created with MapTiler GL JS and run it on a mobile device. > [!NOTE] > The advantage of using this approach (*webview_flutter* to wrap a PWA app) is that all [MapTiler SDK modules](/sdk-js/modules/) will work, this is especially useful if you want to include [weather layers](/sdk-js/modules/weather/) in your applications.
## Installation and setting up - Install and set up [Flutter](https://docs.flutter.dev/install) - (Optional) [VS Code Flutter extension](https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter) - Prepare the link to your web app built with [MapTiler GL JS](/sdk-js/). In our example we will be using [MapTiler demo app](https://maptiler.app/?map=). Each step can be done either via terminal or Visual Studio Code extension. We will cover both.
## Create new Flutter project
Open Visual Studio Code and open the command palette (with F1 or Ctrl+Shift+P or Shift+Cmd+P). Select the **Flutter: New Project** command, select a folder and name your app *my_map*.
```sh flutter create my_map ```
## Add Dependencies
Add the following to pubspec.yaml: ```yaml dependencies: flutter: sdk: flutter webview_flutter: ^4.12.0 ```
```sh flutter pub add webview_flutter ```
## Prepare the App Replace the content of main.dart with the following and make sure to replace url with your app url: ```dart import 'package:flutter/material.dart'; import 'package:webview_flutter/webview_flutter.dart'; // Import the web view void main() { runApp(const MainApp()); } // Add the WebView Widget class MainApp extends StatelessWidget { const MainApp({super.key}); @override Widget build(BuildContext context) { return MaterialApp( home: FullscreenWebView(), ); } } // Create Web View Widget class FullscreenWebView extends StatefulWidget { const FullscreenWebView({super.key}); @override FullscreenWebViewState createState() { return FullscreenWebViewState(); } } // Create Web View Wrapper class FullscreenWebViewState extends State { late final WebViewController _controller; final String url = "https://maptiler.app"; // Add your app url @override void initState() { super.initState(); _controller = WebViewController() ..setJavaScriptMode(JavaScriptMode.unrestricted) ..loadRequest(Uri.parse(url)); } @override Widget build(BuildContext context) { return Scaffold( body: WebViewWidget(controller: _controller), ); } } ``` ## Run the App > [!WARNING] > The application **must be run on a device that supports [webview_flutter](https://pub.dev/packages/webview_flutter)**. To list any available device emulators, run `flutter emulators` in a terminal. To run an emulator, run `flutter emulators --launch `.
Select device from the Flutter extension menu on the left side of the window. Press F5 or fn + F5 to run the app.
```sh cd my_map flutter run lib/main.dart ```
Congratulations!, you have displayed a map on a mobile device using Flutter and MapTiler GL JS. If you want to further customize the behavior, update your web app or _main.dart_ file. ## Weather showcase For weather showcase replace the [MapTiler demo app](https://maptiler.app/?map=) url with [Weather map demo](https://www.maptiler.com/tools/weather) url in main.dart and add SafeArea (bear in mind this is web page and not PWA):

Weather map in Flutter with MapTiler iOS SDK Weather map in Flutter with MapTiler in Android

## Learn more You can also develop your applications using [Flutter and MapLibre GL JS](/flutter/maplibre-gl-js/get-started/) using the `flutter-maplibre-gl` plugin. With this option, functionality is limited to the options available in [flutter-maplibre-gl](https://github.com/maplibre/flutter-maplibre-gl). MapTiler **SDK modules** and **weather layers** will **not work**. # How to display a map in Angular using MapTiler SDK JS Source: https://docs.maptiler.com/angular/ In this step-by-step tutorial, you’ll learn how to create an Angular component that leverages the power of MapTiler SDK JS mapping library to render maps. Together we will build a simple full-screen map application, serving as a practical example of how to seamlessly integrate MapTiler maps into your Angular app. By the end of this tutorial, you will be able to create a full-screen map with a marker placed at a specified location. With your newfound knowledge, you will be able to create visually stunning maps within your Angular projects. Take a look at the final output of this tutorial below: Display a map in Angular using MapTiler SDK JS ## Getting started *Minimal requirements for completing this tutorial.* * **Some experience with Angular** You don’t need a lot of experience using [Angular](https://angular.io/) for this tutorial, but you should be familiar with basic concepts and workflow. * **MapTiler API key.** Your MapTiler account access key is on your MapTiler [Cloud](https://cloud.maptiler.com/account/keys) account page or [Get the API key for FREE](https://cloud.maptiler.com/account/keys). * **MapTiler SDK JS.** JavaScript library for building web maps. In this tutorial, you will learn how to install it. * **Node.js and npm.** Necessary to run your Angular app locally. [Node.js](https://nodejs.org/en/) * **Angular CLI.** You need to have the [Angular CLI](https://angular.io/cli) installed. To install the Angular CLI, open a terminal window and run the following command: ``` bash npm install -g @angular/cli ``` ## Create an app In this step, we are going to learn how to create an Angular app. To create a new Angular project, run in your command-line: ``` bash ng new my-angular-map ``` The `ng new` command prompts you for information about features to include in the initial app. Accept the defaults by pressing the Enter or Return key. This installs the necessary Angular npm packages and other dependencies and creates a new workspace and a simple Welcome app, ready to run. For more information, follow [Create a workspace and initial application](https://angular.dev/tools/cli/setup-local#create-a-workspace-and-initial-application). Navigate to the newly created project folder `my-angular-map` ``` bash cd my-angular-map ``` Inside the newly created project folder, run `ng serve --open` to start your local environment. You will find your app running on the address `http://localhost:4200/`. Now you should see the app in your browser. ![Angular app](/angular/sdk-js/how-to-use-sdk-js/angular.png) ### Installation and setting up To install MapTiler SDK JS library, navigate to your project folder and run the command: ``` bash npm i @maptiler/sdk ``` Open the `tsconfig.json` file and add the `allowSyntheticDefaultImports: true` and `noImplicitAny: false` options to the `compilerOptions` list:
Also the `tsconfig.json` file and add the `strictTemplates: true` and `strictNullChecks: false` options to the `angularCompilerOptions` list:
Navigate to the `src` folder and replace all the contents of the `styles.css` file with the following lines: ``` css body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } code { font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace; } ``` Now navigate to the `src/app` folder and delete all the content of the `app.component.html` file Write the following lines in the `app.component.html` file ``` html
This is my map App
``` Now you should see “This is my map App“ in your browser. Open the `app.component.css` file and add these lines to center the content: ``` css .App { text-align: center; } ``` ### Create a navbar component In this step, we will create a simple heading navbar component. To create a new Angular component run in your command-line: ``` bash ng generate component navbar ``` Navigate to the newly created component folder `src/app/navbar` Remove all the content in the template file created by the Angular CLI (called `navbar.component.html`) and write the following lines: ``` html

This is my map App

``` Next, we are going to stylize our component to make a black navbar. Open the `navbar.component.css` file and write these lines: ``` css .heading { margin: 0; padding: 0px; background-color: black; color: white; } .heading > h1 { padding: 20px; margin: 0; } ``` The generator automatically added the `NavbarComponent` to the `AppModule` to make it available to other components in the application. Finally, to display the `NavbarComponent` as a child of the element of `AppComponent`, add the `` element to `app.component.html`. Replace the text *This is my map App* with ``. Your `app.component.html` file should look like this:
Now you should see the black navbar at the top of your browser. ![App navigation bar](/angular/sdk-js/how-to-use-sdk-js/navbar.png) ### Create a map component In this step, we will create a simple map component. To create the map component run in your command-line: ``` bash ng generate component map ``` Navigate to the newly created component folder `src/app/map` Remove all the content in the template file created by the Angular CLI (called `map.component.html`) and write the following lines:
Next, we are going to stylize our component to make a full-screen map. Open the `map.component.css` file and write these lines: ``` css .map-wrap { position: relative; width: 100%; height: calc(100vh - 77px); /* calculate height of the screen minus the heading */ } .map { position: absolute; width: 100%; height: 100%; } ``` We use `position: absolute` on the map itself and `position: relative` on the wrap around the map for more possibilities in future styling. Now we are going to modify the logic of our component to create a map using MapTiler SDK JS. Open the `map.component.ts` file and update the top of the file to import `ViewChild, ElementRef, AfterViewInit, OnDestroy` from `@angular/core`.
Add the `AfterViewInit, OnDestroy` lifecycle hooks to the `MapComponent`
Right after the @angular/core imports, import the necessary objects from MapTiler SDK JS include the MapTiler SDK CSS file
Create the map property where we are going to save the Map object. Write the following line just before the constructor function:
Add the reference to the element where the map will be displayed. On the line next to the map property, add these lines:
We use `@ViewChild` to get an instance of the native element `
` declared in the component template `map.component.html` Define the `ngOnInit` function to create the apiKey in the SDK `config` object, add these lines:
Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! Define the `ngAfterViewInit` function to create our map. After the `ngOnInit` function, add these lines:
1. The `container` option sets the DOM element in which the map will be rendered. We will assign the `ElementRef` (obtained thanks to the` @ViewChild`) expected by our component to an HTML element, which will act as a container. Keep in mind that it can only be used after the execution of the `ngAfterViewInit` hook. 1. The `style` option defines what style is the map going to use. 1. The `center` and `zoom` options set the starting position of the map. Define the `ngOnDestroy` function for cleanup that needs to occur when the instance is destroyed. After the `ngAfterViewInit` function write:
Your `map.component.ts` file should look like this:
### Render a map Finally, to display the `MapComponent` as a child of the element of `AppComponent`, add the `` element to `app.component.html`. Your `app.component.html` file should look like this:
With everything done up until now, you should be able to see your beautiful map in your browser. ![Full-screen map](/angular/sdk-js/how-to-use-sdk-js/map.png) ### Map marker Another basic thing to add to your map could be a [marker](/sdk-js/api/markers/#marker) of some location. Add the `Marker` next to the Map object import from MapTiler SDK in the `map.components.ts` file.
In the following line where we declare the navigation control, we add these lines:
We create a new marker using the `Marker` function. We added the color option to make it red, then set Lng/Lat of the marker using `.setLngLat()` function, and finally added it to the current map using `.addTo()` function. We are finished with our basic map objects, your `map.component.ts` file should look like this:
![Display MapTiler SDK JS map using Angular](/angular/sdk-js/how-to-use-sdk-js/final_map.png) Once the application is finished, you can export the project for production. ``` bash ng build ``` ## Conclusion Congratulations! You have finished your simple full-screen map app using Angular, showing Tokyo with a marker on Tokyo Imperial Palace. You can explore more about MapTiler SDK JS for your map in the [MapTiler SDK JS API reference](https://docs.maptiler.com/sdk-js). With MapTiler SDK JS, Angular developers can create stunning visualizations and data-driven maps that are responsive and efficient. It also provides support for advanced features like WebGL rendering, 3D maps, and animations. ## Useful links [MapTiler SDK JS API](https://docs.maptiler.com/sdk-js/) [NPM - MapTiler SDK JS](https://www.npmjs.com/package/@maptiler/sdk) [Angular - Getting started](https://angular.io/start) [MapTiler - Map Designer](https://www.maptiler.com/cloud/customize/) ## Learn more Check the more than [100 MapTiler SDK JS examples](/sdk-js/examples/) that we have prepared so that you can see the limitless possibilities of MapTiler SDK JS and unlock the full potential of your Angular applications. It offers easy terrain, built-in styles, language switching, geocoding, TypeScript power, optional IP geolocation, etc. ### Get started with Angular and MapLibre GL JS If you're looking to develop Angular applications with MapLibre GL JS, you have two options. First, you can make use of the ngx-maplibre-gl library, which provides an easy and convenient way to integrate MapLibre GL JS into your Angular projects. Alternatively, you can choose to develop your custom component from scratch. To get started, be sure to check out our tutorial titled [Get Started with Angular and MapLibre GL JS](/angular/maplibre-gl-js/get-started/). This tutorial will provide you with the necessary guidance and examples to kickstart your Angular and MapLibre GL JS development journey. # Angular Examples Source: https://docs.maptiler.com/angular/examples/ _No overview content available._ # React JS with MapTiler maps Source: https://docs.maptiler.com/react/ In this step-by-step tutorial, you’ll learn how to create a React JS component that leverages the power of MapTiler SDK JS mapping library to render maps. Together we will build a simple full-screen map application, serving as a practical example of how to seamlessly integrate MapTiler maps into your own React app. By the end of this tutorial, you will be able to create a full-screen map with a marker placed at a specified location. With your newfound knowledge, you will be able to create visually stunning maps within your React projects. Take a sneak peek at the final output of this tutorial below: ![Display MapTiler SDK JS map using React JS](/react/sdk-js/how-to-use-sdk-js/final_map.png) ## Getting started *Minimal requirements for completing this tutorial.* * **Basic React JS knowledge.** You don’t need a lot of experience using [React](https://reactjs.org/) for this tutorial, but you should be familiar with basic concepts and workflow. * **MapTiler API key.** Your MapTiler account access key is on your MapTiler [Cloud](https://cloud.maptiler.com/account/keys) account page or [Get API key for FREE](https://cloud.maptiler.com/account/keys). * **MapTiler SDK JS.** JavaScript library for building web maps. In this tutorial, you will learn how to install it. * **Node.js and npm.** Necessary to run your React app locally. [Node.js](https://nodejs.org/en/) ## Create an app In this step, we are going to learn how to create a React app. To create a new react project run in your command-line: ``` bash npm create vite my-react-map -- --template react ``` `create vite` will create a simple one-page application in React. For more information follow [Scaffolding Your First Vite Project](https://vitejs.dev/guide/#scaffolding-your-first-vite-project). Navigate to the newly created project folder `my-react-map` ``` bash cd my-react-map ``` Inside the newly created project, run `npm install` to install the dependencies. To start your local environment, run `npm run dev`. You will find your app running on the address `http://localhost:5173/`. Now you should see the app in your browser. ![Vite + React app](/react/sdk-js/how-to-use-sdk-js/vite.png) ### Installation and setting up To install MapTiler SDK JS library, navigate to your project folder and run the command: ``` bash npm i @maptiler/sdk ``` Navigate to the `src` folder and delete all the contents of the `index.css` file. Navigate to the `src` folder and replace all the contents of the `App.css` file with the following lines: ``` css body { margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } code { font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace; } ``` Replace all the contents of the `App.jsx` file with the following lines: ``` jsx import './App.css'; function App() { return (
This is my map App
); } export default App; ``` Now you should see “This is my map App“ in your browser. ### Create a navbar component In this step, we will create a simple heading navbar component. Create a new folder called `components` inside the `src` folder. Create a new file called `navbar.jsx` inside the `components` folder and write these lines: ``` jsx import React from 'react'; import './navbar.css'; export default function Navbar(){ return (

This is my map App

); } ``` Create a new file called `navbar.css` inside the `components` folder and write these lines: ``` css .heading { margin: 0; padding: 0px; background-color: black; color: white; text-align: center; } .heading > h1 { padding: 20px; margin: 0; } ``` Finally, to display the `Navbar` we need to import the Navbar component and add it to our main component `App.jsx`. Import the navbar component into `App.jsx` write the following line at the beginning of the file ``` jsx import Navbar from './components/navbar.jsx'; ``` Replace the text *This is my map App* with ``. Your `App.jsx` file should look like this:
Now you should see the black navbar at the top of your browser. ![App navigation bar](/react/sdk-js/how-to-use-sdk-js/navbar.png) ### Create a map component In this step, we will create a simple map component. Create a new file called `map.jsx` inside the `components` folder. First, we’ll import MapTiler SDK JS and the required React functions. Add these lines on top of `map.jsx` file.
Now we will create a function as our map component.
And set up your map's default state.
The state stores the map object, its container. Longitude, latitude, and zoom for the map will all change as your user interacts with the map. Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! In the next step, we will initialize the map in the `Map()` function.
This code will be right after the component is inserted into the DOM tree. We initialize the map using React effect hook and we also set up some basic options of the map: 1. The `container` option sets the DOM element in which will the map be rendered. We will assign the `ref` our component expects to an HTML element, which will act as a container, later in this tutorial. 1. The `style` option defines what style is the map going to use. 1. The `center` and `zoom` options set the starting position of the map. Now, we will add the `return` statement to your `Map()` function. Add the following code to your component above the closing curly brace of `Map()`:
The `ref={mapContainer}` specifies that App should be drawn to the HTML page in the `
` element. We are finished with our basic map component, your `map.jsx` file should look like this:
Now we will need simple styling to render the map correctly. Create a file named `map.css` in `components` folder for the map component style and write the following code to your `map.css` file: ``` css .map-wrap { position: relative; width: 100%; height: calc(100vh - 77px); /* calculate height of the screen minus the heading */ } .map { position: absolute; width: 100%; height: 100%; } ``` We use `position: absolute` on the map itself and `position: relative` on the wrap around the map for more possibilities in future styling. ### Render a map Now we will import the map component into your app, add the following line to the top of the `App.jsx`. ``` jsx import Map from './components/map.jsx'; ``` And then, add the imported `` component in your `App()` function. Your `App.jsx` file should then look like this:
With everything done up until now, you should be able see your beautiful map in your browser. ![Full-screen map](/react/sdk-js/how-to-use-sdk-js/map.png) ### Map marker Another basic thing to add to your map could be a [marker](/sdk-js/api/markers/#marker) of some location. In the next line where we declare the navigation control we add these lines:
We create a new marker using the `.marker` function. We added the color option to make it red, then set Lng/Lat of the marker using `.setLngLat()` function , and finally added it to the current map using `.addTo()` function. We are finished with our basic map objects, your `map.js` file should look like this:
![Display MapTiler SDK JS map using React JS](/react/sdk-js/how-to-use-sdk-js/final_map.png) ## What's next To enhance your map app, check out our **series on maps in React**. In the episodes, you'll learn how to add popups, a visualization switcher, geocoding control, 3D terrain, and a sidebar: 1. [Build a map app with Material UI](/react/sdk-js/get-started-material-ui/) 2. [Add points from GeoJSON](/react/sdk-js/geojson-points/) 3. [Create a heatmap](/react/sdk-js/heatmap/) 4. [Add popups and sidebar](/react/sdk-js/popup-sidebar/) 5. [Add place search (geocoding control) to a map](/react/sdk-js/geocoding-control/) 6. [Create a 3D terrain map with place search](/react/sdk-js/geocoding-control/) Also, you can check [more than 200 SDK JS examples](/sdk-js/examples/) to see the limitless possibilities of MapTiler SDK JS and unlock the full potential of your React applications. It offers easy terrain, built-in styles, language switching, geocoding, TypeScript power, optional IP geolocation, etc. ## Useful links - [MapTiler SDK JS API](https://docs.maptiler.com/sdk-js/) - [NPM - MapTiler SDK JS](https://www.npmjs.com/package/@maptiler/sdk) - [Vite - Getting Started](https://vitejs.dev/guide/) - [MapTiler - Map Designer](https://www.maptiler.com/cloud/customize/) Filter site pages by: 1. IDs defined in page.related_examples 2. Group must be 'Examples' or 'Tutorials' 3. Category must match the current page category
Dynamic path construction: 1. Remove the ID and 'examples/' from the URL to get the base path 2. Append the assets folder structure This handles deep paths like /mobile-sdk/android/examples/helper/ -> /mobile-sdk/android/assets/...

Dynamic badge based on the group type

# React JS Examples Source: https://docs.maptiler.com/react/examples/ _No overview content available._ # Svelte with MapTiler maps Source: https://docs.maptiler.com/svelte/ In this step-by-step tutorial, you’ll learn how to create a Svelte component that leverages the power of MapTiler SDK JS mapping library to render maps. Together we will build a simple full-screen map application, serving as a practical example of how to seamlessly integrate MapTiler maps into your own Svelte app. By the end of this tutorial, you will be able to create a full-screen map with a marker placed at a specified location. With your newfound knowledge, you will be able to create visually stunning maps within your Svelte projects. Take a look at the final output of this tutorial below: ![Display MapTiler SDK JS map using Svelte](/svelte/sdk-js/how-to-use-sdk-js/final_map.png) ## Getting started *Minimal requirements for completing this tutorial.* * **Basic Svelte knowledge.** You don’t need a lot of experience using [Svelte](https://svelte.dev/) for this tutorial, but you should be familiar with basic concepts and workflow. * **MapTiler API key.** Your MapTiler account access key is on your MapTiler [Cloud](https://cloud.maptiler.com/account/keys) account page or [Get API key for FREE](https://cloud.maptiler.com/account/keys). * **MapTiler SDK JS.** JavaScript library for building web maps. In this tutorial, you will learn how to install it. * **Node.js and npm.** Necessary to run your Svelte app locally. [Node.js](https://nodejs.org/en/) ## Create an app In this step, we are going to learn how to create a Svelte app. To create a new Svelte project run in your command-line: ``` bash npm create vite my-svelte-map -- --template svelte ``` `create vite` will create a simple one-page application in Svelte. For more information follow [Scaffolding Your First Vite Project](https://vitejs.dev/guide/#scaffolding-your-first-vite-project). Navigate to the newly created project folder `my-svelte-map` ``` bash cd my-svelte-map ``` Inside the newly created project, run `npm install` to install the dependencies. To start your local environment, run `npm run dev`. You will find your app running on the address `http://localhost:5173/`. Now you should see the app in your browser. ![Vite + Svelte app](/svelte/sdk-js/how-to-use-sdk-js/vite.png) ### Installation and setting up To install MapTiler SDK JS library, navigate to your project folder and run the command: ``` bash npm i @maptiler/sdk ``` Navigate to the `src` folder and replace all the contents of the `app.css` file with the following lines: ``` css body { margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } code { font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace; } ``` Delete all the content of the `App.svelte` file and write the following lines in the App.svelte file ``` html
This is my map App
``` Now you should see “This is my map App“ in your browser. ### Create a navbar component In this step, we will create a simple heading navbar component. Create a new folder called `components` inside the `src` folder. Create a new file called `Navbar.svelte` inside the `components` folder and write these lines: ``` html

This is my map App

``` Finally, to display the `Navbar` we need to import the Navbar component and add it to our main component `App.svelte`. Import the navbar component into `App.svelte` script block
Replace the text *This is my map App* with ``. Your `App.svelte` file should look like this:
Now you should see the black navbar at the top of your browser. ![App navigation bar](/svelte/sdk-js/how-to-use-sdk-js/navbar.png) ### Create a map component In this step, we will create a simple map component. Create a new file called `Map.svelte` inside the `components` folder and write these lines:
We use `position: absolute` on the map itself and `position: relative` on the wrap around the map for more possibilities in future styling. Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! 1. The `container` option sets the DOM element in which the map will be rendered. We will assign the `mapContainer` ref expected by our component to an HTML element, which will act as a container. Keep in mind that the reference to `mapContainer` can only be used after the execution of the `onMount` lifecycle function. 1. The `style` option defines what style is the map going to use. 1. The `center` and `zoom` options set the starting position of the map. 1. The `onDestroy` function does the cleanup that should occur when the instance is destroyed. ### Render a map Finally, to display the `Map` we need to import the Map component and add it to our main component `App.svelte`. Import the map component into `App.svelte` script block
Add the `` just below the Navbar in the template section. The template block should look like this
With everything done up until now, you should be able see your beautiful map in your browser. ![Full-screen map](/svelte/sdk-js/how-to-use-sdk-js/map.png) Your `App.svelte` file should look like this:
### Map marker Another basic thing to add to your map could be a [marker](https://docs.maptiler.com/sdk-js/api/markers/#marker) of some location. Add the `Marker` next to the Map object import from MapTiler SDK in the `Map.svelte` file.
In the next line where we declare the navigation control we add these lines:
We create a new marker using the `.marker` function. We added the color option to make it red, then set Lng/Lat of the marker using `.setLngLat()` function, and finally added it to the current map using `.addTo()` function. We are finished with our basic map objects, your `Map.svelte` file should look like this:
![Display MapTiler SDK JS map using Svelte JS](/svelte/sdk-js/how-to-use-sdk-js/final_map.png) Once the application is finished, you can export the project for production. ``` bash npm run build ``` ## Conclusion Congratulations! You have finished your simple full-screen map app using Svelte, showing Tokyo with a marker on Tokyo Imperial Palace. You can explore more about MapTiler SDK JS for your map in the [MapTiler SDK JS API reference](https://docs.maptiler.com/sdk-js). With MapTiler SDK JS, Svelte developers can create stunning visualizations and data-driven maps that are responsive and efficient. It also provides support for advanced features like WebGL rendering, 3D maps, and animations. ## Useful links [MapTiler SDK JS API](https://docs.maptiler.com/sdk-js/) [NPM - MapTiler SDK JS](https://www.npmjs.com/package/@maptiler/sdk) [Vite - Getting Started](https://vitejs.dev/guide/) [MapTiler - Map Designer](https://www.maptiler.com/cloud/customize/) ## Learn more Check the more than [100 MapTiler SDK JS examples](/sdk-js/examples/) that we have prepared so that you can see the limitless possibilities of MapTiler SDK JS and unlock the full potential of your Svelte applications. It offers easy terrain, built-in styles, language switching, geocoding, TypeScript power, optional IP geolocation, etc. ### Get started with Svelte and MapLibre GL JS If you're looking to develop Svelte applications with MapLibre GL JS, you have two options. First, you can make use of the svelte-maps library, which provides an easy and convenient way to integrate MapLibre GL JS into your Svelte projects. Alternatively, you can choose to develop your custom component from scratch. To get started, be sure to check out our tutorial titled [Get Started with Svelte and MapLibre GL JS](/svelte/maplibre-gl-js/get-started/). This tutorial will provide you with the necessary guidance and examples to kickstart your Svelte and MapLibre GL JS development journey. # Svelte Examples Source: https://docs.maptiler.com/svelte/examples/ _No overview content available._ # Get started with Vite and MapTiler SDK JS Source: https://docs.maptiler.com/vite/ In this step-by-step tutorial, you’ll learn how to add a map using MapTiler SDK JS to your TypeScript app. Together we will build a simple full-screen map application, serving as a practical example of how to seamlessly integrate MapTiler maps into your own Vite app. By the end of this tutorial, you will be able to create a full-screen map. With your newfound knowledge, you will be able to create visually stunning maps within your Vite projects. Take a look at the final output of this tutorial below: ## Getting started *Minimal requirements for completing this tutorial.* * **Basic Vite knowledge.** You don’t need a lot of experience using [Vite](https://vitejs.dev/) for this tutorial, but you should be familiar with basic concepts and workflow. * **MapTiler API key.** Your MapTiler account access key is on your MapTiler [Cloud](https://cloud.maptiler.com/account/keys) account page or [Get API key for FREE](https://cloud.maptiler.com/account/keys). * **MapTiler SDK JS.** JavaScript library for building web maps. In this tutorial, you will learn how to install it. * **Node.js and npm.** Necessary to run your Vite app locally. [Node.js](https://nodejs.org/en/) ## Create an app In this step, we are going to learn how to create a Vite app. To create a new Vite project, run in your command-line: ``` bash npm create vite@latest my-vite-map -- --template vanilla-ts ``` Navigate to the newly created project folder `my-vite-map` ``` bash cd my-vite-map ``` Inside the newly created project folder, run `npm install` to install the dependencies. To start your local environment, run `npm run dev`. You will find your app running on the address `http://localhost:5173/`. Now you should see the app in your browser. ![Vite + TypeScript app](/vite/sdk-js/vanilla-ts/vite.png) ### Installation and setting up To install MapTiler SDK JS library, navigate to your project folder and run the command: ``` bash npm i @maptiler/sdk ``` Change the `moduleResolution` from *`bundler`* to **`node`** in the `tsconfig.json` file. Navigate to the `src` folder and replace all the contents of the `style.css` file with the following lines: ``` css html, body { margin: 0; } #app { width: 100vw; height: 100vh; } ``` Replace all the contents of the `main.ts` file with the following lines: ``` ts import '@maptiler/sdk/dist/maptiler-sdk.css'; import './style.css'; import { config, Map } from '@maptiler/sdk'; function init() { const container = document.getElementById('app'); if (!container) throw new Error('There is no div with the id: "map" '); config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE'; const map = new Map({ container }); console.log('The map instance', map); } init(); ``` Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! With everything done up until now, you should be able to see your beautiful map in your browser. ![Display MapTiler SDK JS map using Vite](/vite/sdk-js/vanilla-ts/final_map.png) Once the application is finished, you can export the project for production. ``` bash npm run build ``` ## Conclusion Congratulations! You have finished your simple full-screen map app using Vite + TypeScript. You can explore more about MapTiler SDK JS for your map in the [MapTiler SDK JS API reference](https://docs.maptiler.com/sdk-js). With MapTiler SDK JS, Vite developers can create stunning visualizations and data-driven maps that are responsive and efficient. It also provides support for advanced features like WebGL rendering, 3D maps, and animations. ## Useful links [MapTiler SDK JS API](https://docs.maptiler.com/sdk-js/) [NPM - MapTiler SDK JS](https://www.npmjs.com/package/@maptiler/sdk) [Vite - Getting Started](https://vitejs.dev/guide/) [MapTiler - Map Designer](https://www.maptiler.com/cloud/customize/) ## Learn more Check the more than [100 MapTiler SDK JS examples](/sdk-js/examples/) that we have prepared so that you can see the limitless possibilities of MapTiler SDK JS and unlock the full potential of your Vite applications. It offers easy terrain, built-in styles, language switching, geocoding, TypeScript power, optional IP geolocation, etc. ### Building Interactive Maps in a React + Vite App If you're interested in developing React applications using the MapTiler SDK JS, we have the perfect tutorial for you: [React with MapTiler maps](/react/). This comprehensive step-by-step tutorial will provide you with the necessary guidance and examples to create a React component that leverages the power of MapTiler SDK JS mapping library to render maps. ### Make a simple interactive world map using Vite + Svelte If you are a developer who is interested in creating Svelte applications with MapTiler SDK JS, you might find the tutorial titled [Svelte with MapTiler maps](/svelte/) very helpful. This comprehensive tutorial provides step-by-step guidance and examples to help you create a Svelte component that utilizes the MapTiler SDK JS mapping library to render maps. ### Building a Map Application with Vue.js and Vite If you're looking to develop Vue.js applications with MapTiler SDK JS, check out our tutorial titled [Vue.js with MapTiler maps](/vuejs/). By following this step-by-step tutorial you'll gain a solid understanding of how to effectively utilize the MapTiler SDK JS in your Vue.js applications, with clear explanations and practical examples, you'll discover how to create a highly customizable Vue.js component that delivers visually appealing and interactive maps powered by the MapTiler SDK JS. # Vue.js with MapTiler maps Source: https://docs.maptiler.com/vuejs/ In this step-by-step tutorial, you’ll learn how to create a Vue.js component that leverages the power of MapTiler SDK JS mapping library to render maps. Together we will build a simple full-screen map application, serving as a practical example of how to seamlessly integrate MapTiler maps into your own Vue.js app. By the end of this tutorial, you will be able to create a full-screen map with a marker placed at a specified location. With your newfound knowledge, you will be able to create visually stunning maps within your Vue.js projects. Take a look at the final output of this tutorial below: ![Display MapTiler SDK JS map using Vue.js](/vuejs/sdk-js/how-to-use-sdk-js/final_map.png) ## Getting started *Minimal requirements for completing this tutorial.* * **Some experience with Vue.js** You don’t need a lot of experience using [Vue.js](https://vuejs.org/) for this tutorial, but you should be familiar with basic concepts and workflow. * **MapTiler API key.** Your MapTiler account access key is on your MapTiler [Cloud](https://cloud.maptiler.com/account/keys) account page or [Get API key for FREE](https://cloud.maptiler.com/account/keys). * **MapTiler SDK JS.** JavaScript library for building web maps. In this tutorial, you will learn how to install it. * **Node.js and npm.** Necessary to run your Vue.js app locally. [Node.js](https://nodejs.org/en/) ## Create an app In this step, we are going to learn how to create a Vue.js app. To create a new Vue.js project run in your command-line: ``` bash npm create vite my-vuejs-map -- --template vue ``` `create vite` will create a simple one-page application in Vue.js. For more information follow [Scaffolding Your First Vite Project](https://vitejs.dev/guide/#scaffolding-your-first-vite-project). Navigate to the newly created project folder `my-vuejs-map` ``` bash cd my-vuejs-map ``` Inside the newly created project, run `npm install` to install the dependencies. To start your local environment, run `npm run dev`. You will find your app running on the address `http://localhost:5173/`. Now you should see the app in your browser. ![Vite + Vue.js](/vuejs/sdk-js/how-to-use-sdk-js/vite.png) ### Installation and setting up To install MapTiler SDK JS library, navigate to your project folder and run the command: ``` bash npm i @maptiler/sdk ``` Navigate to the `src` folder and replace all the contents of the `styles.css` file with the following lines: ``` css body { margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } code { font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace; } ``` Replace all the contents of the `App.vue` file with the following lines: ``` html ``` Now you should see “This is my map App“ in your browser. Navigate to the `src/components` folder and delete de `HelloWorld.vue` file ### Create a navbar component In this step, we will create a simple heading navbar component. Create a new file called `Navbar.vue` inside the `components` folder and write these lines: ``` html ``` Finally, to display the `Navbar` we need to import the Navbar component and add it to our main component template section `App.vue`. Import the navbar component into `App.vue` script block
Replace the text *This is my map App* with ``. Your `App.vue` file should look like this:
Now you should see the black navbar at the top of your browser. ![App navigation bar](/vuejs/sdk-js/how-to-use-sdk-js/navbar.png) ### Create a map component In this step, we will create a simple map component. Create a new file called `Map.vue` inside the `components` folder and write these lines:
We use `position: absolute` on the map itself and `position: relative` on the wrap around the map for more possibilities in future styling. Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it! 1. The `container` option sets the DOM element in which the map will be rendered. We will assign the `mapContainer` ref expected by our component to an HTML element, which will act as a container. Keep in mind that the reference to `mapContainer` can only be used after the execution of the `onMounted` hook. 1. The `style` option defines what style is the map going to use. 1. The `center` and `zoom` options set the starting position of the map. 1. The `onUnmounted` function does the cleanup that should occur when the instance is destroyed. ### Render a map Finally, to display the `Map` we need to import the Map component and add it to our main component `App.vue`. Import the map component into `App.vue` script block
Add the `` just below the Navbar in the template section. The template block should look like this
With everything done up until now, you should be able to see your beautiful map in your browser. ![Full-screen map](/vuejs/sdk-js/how-to-use-sdk-js/map.png) Your `App.vue` file should look like this:
### Map marker Another basic thing to add to your map could be a [marker](https://docs.maptiler.com/sdk-js/api/markers/#marker) of some location. Add the `Marker` next to the Map object import from MapTiler SDK in the `Map.vue` file.
In the following line where we declare the map, we add these lines:
We create a new marker using the `.marker` function. We added the color option to make it red, then set Lng/Lat of the marker using `.setLngLat()` function, and finally added it to the current map using `.addTo()` function. We are finished with our basic map objects, your `Map.vue` file should look like this:
![Display MapTiler SDK JS map using Vue.js](/vuejs/sdk-js/how-to-use-sdk-js/final_map.png) Once the application is finished, you can export the project for production. ``` bash npm run build ``` ## Conclusion Congratulations! You have finished your simple full-screen map app using Vue.js, showing Tokyo with a marker on Tokyo Imperial Palace. You can explore more about MapTiler SDK JS for your map in the [MapTiler SDK JS API reference](https://docs.maptiler.com/sdk-js). With MapTiler SDK JS, Vue.js developers can create stunning visualizations and data-driven maps that are responsive and efficient. It also provides support for advanced features like WebGL rendering, 3D maps, and animations. ## Useful links [MapTiler SDK JS API](https://docs.maptiler.com/sdk-js/) [NPM - MapTiler SDK JS](https://www.npmjs.com/package/@maptiler/sdk) [Vite - Getting Started](https://vitejs.dev/guide/) [MapTiler - Map Designer](https://www.maptiler.com/cloud/customize/) ## Learn more Check the more than [100 MapTiler SDK JS examples](/sdk-js/examples/) that we have prepared so that you can see the limitless possibilities of MapTiler SDK JS and unlock the full potential of your Vue.js applications. It offers easy terrain, built-in styles, language switching, geocoding, TypeScript power, optional IP geolocation, etc. ### Get started with Vue.js and MapLibre GL JS If you're looking to develop Vue.js applications with MapLibre GL JS, you have two options. First, you can make use of the vue-maplibre-gl library, which provides an easy and convenient way to integrate MapLibre GL JS into your Vue.js projects. Alternatively, you can choose to develop your custom component from scratch. To get started, be sure to check out our tutorial titled [Get Started with Vue.js and MapLibre GL JS](/vuejs/maplibre-gl-js/get-started/). This tutorial will provide you with the necessary guidance and examples to kickstart your Vue.js and MapLibre GL JS development journey. # Vue.js Examples Source: https://docs.maptiler.com/vuejs/examples/ _No overview content available._ # Leaflet JS with MapTiler maps Source: https://docs.maptiler.com/leaflet/ [Leaflet](https://www.leafletjs.com) is a lightweight open-source library for online maps. It works efficiently across all major desktop and mobile platforms and can be extended with lots of [plugins](#maptiler-leaflet-plugins). You can use your MapTiler maps in Leaflet as vector tiles or the more traditional raster tiles. You can also add a geocoding control to your map with one line of code. ## Get started This is the way to use your MapTiler maps in Leaflet JS. Simply use the code below the map. ## Vector Tiles and Geocoding with MapTiler Leaflet plugins Leaflet is meant to be as lightweight as possible and focuses on a core set of features. An easy way to extend its functionality is to use plugins. * Check out the [**Use Leaflet JS with Vector Tiles**](/leaflet/examples/vector-tiles-in-leaflet-js/) example. * Check out the [**Leaflet geocoding control how to search places**](/leaflet/examples/geocoding-control/) example. ### Maptiler SDK layer (Vector Tiles layer) ![GitHubLogo](/assets/img/github.svg)[Leaflet Vector Tiles basemap plugin](https://github.com/maptiler/leaflet-maptilersdk) The [L.maptiler.maptilerLayer()](https://github.com/maptiler/leaflet-maptilersdk) plugin is how you display vector tiles in Leaflet JS. Using the **L.maptiler.maptilerLayer** you have: * All the power of [MapTiler SDK JS](/sdk-js/) to use vector tile layers (for data overlays) in your applications without any kind of limitation (show millions of geometries, choropleth maps, etc). * Multi-lingual vector tiles basemaps for Leaflet using the MapTiler SDK. * Use any of the many [professional looking basemaps](/sdk-js/api/map-styles/) created by MapTiler or use a map with your own custom basemap. * Easily change the language of your map without having to create a new basemap. * Locate the user and center the map accordingly.
### Geocoding control ![GitHubLogo](/assets/img/github.svg)[Leaflet geocoding control](https://github.com/maptiler/maptiler-geocoding-control#example-for-leaflet-using-module-bundler) The [L.control.maptilerGeocoding()](https://github.com/maptiler/maptiler-geocoding-control#example-for-leaflet-using-module-bundler) plugin for Leaflet utilizes [MapTiler Geocoding API](https://www.maptiler.com/cloud/geocoding/). With this control, users of your application can find any place on Earth (States, Cities, Streets, ...) down to the address level, restrict the search area to a specific country, highlight search results on the map, autocomplete words while typing, and much more.
## Learn more If you want to learn how to initialize a map and load the style see the [Learn the basics - How to use Leaflet JS](./examples/how-to-use-leaflet/) tutorial. Unlock your Leaflet mapping potential now! Look at the [Leaflet JS examples](/leaflet/examples/) we have prepared, from a quick start with Leaflet to advanced examples of how to load millions of points or use vector tiles with Leaflet JS. # Leaflet Examples Source: https://docs.maptiler.com/leaflet/examples/ _No overview content available._ # MapLibre GL JS with MapTiler maps Source: https://docs.maptiler.com/maplibre/ [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) is a open-source TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser. Great performance due to GPU-accelerated vector tile rendering. For a better developer experience and easier integration with MapTiler [maps](https://www.maptiler.com/maps/) and [API services](/cloud/api/), it is best to use the [MapTiler SDK JS](/sdk-js/). MapTiler SDK JS uses MapLibre as its main engine but extends it with more features. ## Get started This is the way to use your MapTiler maps in MapLibre GL JS. Simply use the code below the map. 







  

    
    
    
    
    
  


  

  

  




## Learn more

Check out the [How to migrate/switch from MapLibre to MapTiler](/sdk-js/examples/switch-from-maplibre/) tutorial.

Unlock your MapLibre mapping potential now! Look at the [MapLibre GL JS examples](/maplibre-gl-js/examples/) we have prepared.

Check out the more than 250 [MapTiler SDK examples](/sdk-js/examples/)

# MapLibre Examples

Source: https://docs.maptiler.com/maplibre/examples/

_No overview content available._

# OpenLayers JS with MapTiler maps

Source: https://docs.maptiler.com/openlayers/

[OpenLayers](https://openlayers.org) is a high-performance, full-featured web mapping library that displays maps from various sources and formats. If you need to develop a web application that interacts with most OGC standards, this is your tool, whether connecting to a WFS or reprojecting a raster.

You can use your MapTiler maps in OpenLayers as vector tiles or the more traditional raster tiles. You can also add a geocoding control to your map with one line of code.

## Get started

This is the easiest and fastest way to use your MapTiler maps in OpenLayers. Simply use the code below the map.





## Geocoding with MapTiler OpenLayers plugins
### Geocoding control


![GitHubLogo](/assets/img/github.svg)[OpenLayers geocoding control](https://github.com/maptiler/maptiler-geocoding-control#example-for-openlayers-using-module-bundler)

The [GeocodingControl()](https://github.com/maptiler/maptiler-geocoding-control#example-for-openlayers-using-module-bundler) plugin for OpenLayers utilizes [MapTiler Geocoding API](https://www.maptiler.com/cloud/geocoding/). With this control, users of your application can find any place on Earth (States, Cities, Streets, ...) down to the address level, restrict the search area to a specific country, highlight search results on the map, autocomplete words while typing, and much more.















Check out the [OpenLayers geocoding control how to search places](./examples/geocoding-control/) example.

## Learn more

If you want to learn how to initialize a map and load the style, see the [Learn the basics - How to use OpenLayers](./how-to-use-openlayers/) tutorial.

Unlock your OpenLayers mapping potential now! Look at the [OpenLayers JS examples](/openlayers/examples/) we have prepared, from a quick start with OpenLayers to advanced examples like using vector tiles with OpenLayers.

# OpenLayers Examples

Source: https://docs.maptiler.com/openlayers/examples/

_No overview content available._

# Deck.gl with MapTiler maps

Source: https://docs.maptiler.com/deck-gl/

[Deck.gl](https://deck.gl/) is a framework powered by WebGL for visual exploratory data analysis of large datasets.

Within Deck.gl, you have the option to incorporate MapTiler SDK either in interleaved mode (rendering directly into MapTiler SDK WebGL context) or reverse-controlled mode (renders deck.gl above the MapTiler SDK container and blocks any interaction to the base map).

Deck.gl is **not a map library**. Instead, it is a high-performance data visualization framework designed to works standalone without a base map. Deck.gl integrates with mapping libraries such as MapTiler SDK, MapLibre, etc.

## Get started

This is the easiest and fastest way to use your MapTiler maps in Deck.gl in interleaved mode. For reverse-controlled mode see: [How to use Vector Tiles in Deck.gl](./examples/get-started/)

Deck.gl allows a great diversification of visualizations. Like the one shown in the following example, where the `ArcLayer` is used to represent raised arc linking source and destination coordinate pair and `ScatterplotLayer` is used to show affected area. Simply use the code below the map.





  
  















  

    

  


  

  
  
  



Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it!



Filter site pages by:
1. IDs defined in page.related_examples
2. Group must be 'Examples' or 'Tutorials'
3. Category must match the current page category








  
  
  Dynamic path construction:
  1. Remove the ID and 'examples/' from the URL to get the base path
  2. Append the assets folder structure
  This handles deep paths like /mobile-sdk/android/examples/helper/ -> /mobile-sdk/android/assets/...
  
  
  

  

    
      
        
        
      
      


       Dynamic badge based on the group type 
      

      

        
      

    
  

  



# Deck.gl Examples

Source: https://docs.maptiler.com/deck-gl/examples/

_No overview content available._

# Cesium JS with MapTiler maps

Source: https://docs.maptiler.com/cesium/

[Cesium JS](https://cesium.com/platform/cesiumjs/) is an open-source JavaScript library for creating high-quality 3D globes and maps with the best possible performance, precision, visual quality, user-friendly interface, and ease of use.

You can use your MapTiler maps in Cesium as a [Terrain 3D quantized mesh](https://cloud.maptiler.com/tiles/terrain-quantized-mesh) format.

## Get started

This is the easiest and fastest way to use your MapTiler maps in Cesium JS. By using the code provided below the map, you can effortlessly generate a [3D map](https://www.maptiler.com/maps/3d/). 





## Learn more

To learn more about 3D terrain data modeling, read the [3D vector tiles with Cesium](/guides/self-hosting/self-hosted-maps/3d-vector-tiles-with-cesium) article.

Check out the [Photorealistic 3D terrain with aerial imagery using Cesium JS](/guides/map-tiling-hosting/data-hosting/photorealistic-3d-terrain-with-aerial-imagery-using-cesium-js) to know how to see an example of an outdoor map or how to display 3D terrain with aerial imagery from your server.



Filter site pages by:
1. IDs defined in page.related_examples
2. Group must be 'Examples' or 'Tutorials'
3. Category must match the current page category








  
  
  Dynamic path construction:
  1. Remove the ID and 'examples/' from the URL to get the base path
  2. Append the assets folder structure
  This handles deep paths like /mobile-sdk/android/examples/helper/ -> /mobile-sdk/android/assets/...
  
  
  

  

    
      
        
        
      
      


       Dynamic badge based on the group type 
      

      

        
      

    
  

  



# Unreal Engine with MapTiler real-world 3D content

Source: https://docs.maptiler.com/unreal/

This step-by-step tutorial will teach you how to use MapTiler maps in Unreal application. To do this, we will use the [Cesium plugin for Unreal](https://cesium.com/platform/cesium-for-unreal/), allowing us to create digital worlds from real-world content in 3D. Now, MapTiler basemaps can be easily used in the plugin, via [MapTiler](https://www.maptiler.com/cloud/) or [MapTiler Server](https://www.maptiler.com/server/) for on-premise and offline use-cases.

[**Unreal Engine**](https://www.unrealengine.com/)(UE) is a complete suite of game development, simulation, and other real-time application creation tools. It is built by developers for developers. Whatever your vision, bring it to life with this real-time 3D creation tool.



## Installation and setting up

1. Install Unreal Engine version 5.3. [Download Unreal Engine](https://www.unrealengine.com/en-US/download)

1. Install the Cesium for Unreal plugin. [Unreal marketplace Cesium plugin](https://www.unrealengine.com/marketplace/en-US/product/87b0d05800a545d49bf858ef3458c4f7)

## Create a new Unreal project

1. Open a new project in Unreal Engine. Launch Unreal Engine and create a new project. Select **Game** as the New Project Category and **Blank** as the Template. For a simple setup, uncheck **Starter Content**.

1. Turn on the Cesium plugin. Once the project is fully loaded, activate the Cesium for Unreal plugin. Open the Plugins window (Edit ➡ Plugins) and search for “Cesium” in the search bar at the top of the Plugins window. Make sure that the checkbox next to the plugin is checked. You may need to restart Unreal Engine after enabling the plugin.

   ![Unreal turn on the Cesium for Unreal plugin](/unreal/cesium/get-started/img/cesium-for-unreal-plugin.jpeg)

   > [!NOTE]
   > After restarting the Editor with the Cesium for Unreal plugin activated for the first time, you may see an error related to the **Water Body Collision profile**. Click the **Add entry to DefaultEngine.ini** link to fix it.

1. Create a new level (File ➡ New Level). When prompted, select "Empty Level" to make sure there are no objects in the level.

1. Disable the World Bounds Checks. This option is found in World Settings (Window ➡ World Settings), in the World ➡ Advanced category.

   ![Unreal disable the World Bounds Checks](/unreal/cesium/get-started/img/disable-world-bounds-checks.jpg)

   > [!NOTE]
   > With **Enable World Bounds Checks ON**, Unreal Engine will attempt to fly a Pawn that is far from the origin back toward the origin. In most Cesium applications, being far from the origin is completely normal, and this automatic behavior prevents the Pawn from going where the user wants it to go.

1. Open the **Cesium** panel by clicking Window ➡ Cesium.

1. Add some lighting so you'll be able to see the tilesets you add in later steps. Cesium for Unreal comes with a pre-made, globe-aware sun and atmosphere system called [CesiumSunSky](https://cesium.com/learn/unreal/unreal-geospatially-accurate-sun/).

   In the Quick Add Basic Actors section of the panel, find **Cesium SunSky** and click the button to add it to the level. You should see a sky-like gradient appear in the viewport.

   ![Unreal add Cesium SunSky](/unreal/cesium/get-started/img/add-cesium-sky.jpg)

1. Click the **Save the current level to disk** button in the top-left corner of the Editor, or press `Ctrl+S`. Give your level a name (for example MapTilerMap). You may also want to set your new level as the project's default map. This will make sure that your level will automatically open when you restart the project or package and run your application. In the Edit ➡ Project Settings window left sidebar, click on **Maps & Modes**, then look for the Default Maps section. Change both the **Editor Startup Map** and the **Game Default Map** to your new level.

   ![Unreal change default maps](/unreal/cesium/get-started/img/change-default-maps.jpg)

## Add global real-world 3D terrain to your level

1. Add a blank 3D Tiles tileset.

   ![Unreal add a blank 3D Tiles tileset](/unreal/cesium/get-started/img/add-blank-3d-tiles.jpg)

1. Change the source from Cesium Ion to '**From URL**'.

   ![Change Cesium tileset source to From URL](/unreal/cesium/get-started/img/cesium-3d-tiles-source-from-url.jpg)

1. Insert the MapTiler 3D terrain tileset URL in the URL field. The tiles contain real-world elevation data encoded into vector TIN polygons in format for the Cesium JavaScript library. The URL should be `https://api.maptiler.com/tiles/terrain-quantized-mesh-v2/tiles.json?key=YOUR_MAPTILER_API_KEY_HERE` (or just copy the URL from your 3D terrain in the [Maptiler Cloud](https://cloud.maptiler.com/tiles/terrain-quantized-mesh-v2/)). Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it!

   ![Copy the MapTiler terrain URL](/unreal/cesium/get-started/img/maptiler-terrain-cesium.jpg)

1. Add a new component in Cesium3DTileset. Add a new Web Map Tile Service Raster WMTS (`CesiumWebMapTileServiceRasterOverlay`).

   ![Unreal add new Cesium WMTS raster tile service](/unreal/cesium/get-started/img/cesium-wmts-raster-tile-service.jpg)

1. Get the URL of the (WMTS) Web map tile service of your MapTiler maps. Go to the [MapTiler maps](https://cloud.maptiler.com/maps/), and select one of the standard maps (high-quality basemaps like Planet, Ocean, High-Res Imagery) or your custom maps (Try the [MapTiler Map Designer](https://www.maptiler.com/cloud/customize/)). The URL should be `https://api.maptiler.com/maps/YOUR_MAP_ID_HERE/{TileMatrix}/{TileCol}/{TileRow}.jpg?key=YOUR_MAPTILER_API_KEY_HERE` or open the WMTS Capabilities.

   ![Open WMTS capabilities](/unreal/cesium/get-started/img/maptiler-wmts-capabilities.jpg)

   In the Capabilities XML look for the **ResourceURL** within Content ➡ Layer. And copy the URL value of the `template` attribute.

   ![WMTS capabilities ResourceURL](/unreal/cesium/get-started/img/maptiler-wmts-resource-url.jpg)

1. Configure the `CesiumWebMapTileServiceRasterOverlay`. Add the WMTS URL obtained in the previous step into the URL field and check the box for '**Use Web Mercator Projection**'.

   ![Unreal configure CesiumWebMapTileServiceRasterOverlay url and mercator](/unreal/cesium/get-started/img/cesium-wmts-service-url-mercator.jpg)

   > [!NOTE]
   > The process is replicable with MapTiler Server with [Download Terrain 3D - Cesium quantized mesh of the entire planet ](https://www.maptiler.com/on-prem-datasets/dataset/terrain-quantized-mesh/) and then for the overlay, any map that is on your [MapTiler Server](https://www.maptiler.com/server/).

## Set the initial view localization coordinates

1. Select the **CesiumGeoreference** actor in the **Outliner**. This actor determines where in the world your level is set. The level's current latitude, longitude, and height can be changed with this actor.

1. In the **Details** panel, look for the **Origin Latitude**, **Origin Longitude**, and **Origin Height** variables under the Cesium category. Change these variables to the coordinates of your favorite city or use these coordinates to travel to Lake Louise, Canada.

   ```
   Origin Latitude = 51.395879
   Origin Longitude = -116.261587
   Origin Height = 3000.0
   ```

   ![Unreal CesiumGeoreference change origin latitude and longitude](/unreal/cesium/get-started/img/cesium-georeference-change-origin-lat-lon.jpg)

1. Press the **Play** button, you'll notice that the default camera speed is very slow, and not adjustable. Given the scale that real-world data can be, you'll need a different Pawn to efficiently navigate the level during play.

1. Add a **Dynamic Pawn** using the Cesium panel.

   ![Unreal add a Cesium dynamic pawn](/unreal/cesium/get-started/img/add-dynamic-pawn.jpg)

   Cesium's **DynamicPawn** actor extends the built-in pawn class by making it globe-aware. The DynamicPawn also adds important movement functionality, such as the ability to adjust movement speed with the mouse wheel and the ability to fly between global locations along a curved path.

## Explore your level

1. You're ready to test out your level! Press the **Play** button at the top toolbar. Like the viewport controls, you can use the W, A, S, and D keyboard keys and the mouse to fly around. Use the mouse scroll wheel to change your speed.
   You've created your first project with Cesium for Unreal. Feel free to explore the world!

### Examples

![Real-world 3D MapTiler maps in Unreal](/unreal/cesium/get-started/img/maptiler-unreal-cesium.png)
[MapTiler High resolution Imagery map](https://cloud.maptiler.com/maps//)

![Real-world 3D globe MapTiler maps in Unreal](/unreal/cesium/get-started/img/maptiler-unreal-globe.png)
[MapTiler Global Satellite map](https://cloud.maptiler.com/maps//)

![Custom MapTiler old maps in Unreal](/unreal/cesium/get-started/img/maptiler-unreal-custom-old-maps.png)
[UK Great Britain, 1900s](https://cloud.maptiler.com/tiles/uk-osgb1888/)

![Real-world 3D MapTiler outdoor maps in Unreal](/unreal/cesium/get-started/img/maptiler-unreal-outdoor.png)
[MapTiler Outdoor map](https://cloud.maptiler.com/maps//)

![Real-world 3D MapTiler bathymetry maps in Unreal](/unreal/cesium/get-started/img/maptiler-unreal-bathymetry-map.png)
[MapTiler ocean seafloor and bathymetry map](https://cloud.maptiler.com/maps//)

## Summary

- MapTiler basemaps can be easily used in Unreal adding a WMTS map, via [MapTiler](https://www.maptiler.com/cloud/) or [MapTiler Server](https://www.maptiler.com/server/) for on-premise and offline use-cases.

- Create high-fidelity 3D geospatial visualization and simulation capabilities within the Unreal Engine environment using the [MapTiler 3D terrain](https://cloud.maptiler.com/tiles/terrain-quantized-mesh-v2/) service.

- Add your custom maps to Unreal. Whether they are: maps created with the [MapTiler Map Designer](https://www.maptiler.com/cloud/customize/), self-hosted maps & images for use in on-prem/local Cesium-based applications for Unreal or create your tiled service with [MapTiler Engine](https://www.maptiler.com/engine/).

## Learn more

Check out the [Cesium for Unreal tutorials](https://cesium.com/learn/unreal/)

# Unity with MapTiler real-world 3D content

Source: https://docs.maptiler.com/unity/

This step-by-step tutorial will teach you how to use MapTiler maps in your Unity application. To do this, we will use the [Cesium plugin for Unity](https://cesium.com/platform/cesium-for-unity/), allowing us to create digital worlds from real-world content in 3D. Now, MapTiler basemaps can be easily used in the plugin, via [MapTiler](https://www.maptiler.com/cloud/) or [MapTiler Server](https://www.maptiler.com/server/) for on-premise and offline use-cases.

[**Unity Engine**](https://unity.com/products/unity-engine) is a real-time 3D development engine, that provides tools to create and operate amazing games and other real-time interactive experiences and publish them to a wide range of devices. Unity's real-time 3D development engine allows artists, designers, and developers to collaborate to create incredible immersive and interactive experiences.



## Installation and setting up

1. Install Unity 2021.3.2f1 or later. [Download Unity](https://unity.com/download)

## Create a new Unity project

1. Create a new project from the Projects tab by clicking the New project button. A new window should open, allowing you to configure your project. This tutorial uses the **Universal 3D** (URP) template, but the High Definition 3D (HDRP) template will also work. Give your project a name and choose its file location. Then, press **Create project**. Your new project will open momentarily.

   ![Unity new URP project](/unity/cesium/get-started/img/unity-create-project.jpeg)

   > [!NOTE]
   > Cesium for Unity works with both the Universal 3D (URP) and High Definition 3D (HDRP). However, it does not support Unity’s built-in renderer. If you choose the empty 3D project as your template, the datasets loaded by Cesium will not render properly.

1. Once the project has fully loaded, open the Project Settings by going to Edit ➡ Project Settings... in the menu. Click the **Package Manager section** on the left. Add a new **Scoped Registry** with the following settings and click **Save**:
   - **Name**: Cesium
   - **URL**: https://unity.pkg.cesium.com
   - **Scope(s)**: com.cesium.unity

   ![Unity project settings](/unity/cesium/get-started/img/unity-project-settings.jpeg)

1. Close the project settings and then open the **Package Manager** by going to Window ➡ Package Manager in the menu. In the Package Manager, click on the **Packages** drop-down and select **My Registries**.

   ![Unity package manager](/unity/cesium/get-started/img/unity-package-manager.jpeg)

1. **Cesium for Unity** will appear in the package list. Click on it, and then click Install. Cesium for Unity and its dependencies will be downloaded and installed.

   ![Install Cesium for Unity](/unity/cesium/get-started/img/unity-install-cesium-package.jpeg)

## Add global real-world 3D terrain to your level

1. Open the Cesium window by selecting Cesium ➡ Cesium from the menu.

1. From the Cesium window, add a blank 3D Tiles tileset.

   ![Unity add a blank 3D Tiles tileset](/unity/cesium/get-started/img/unity-add-blank-3d-tiles.jpg)

1. Change the Tileset Source from Cesium Ion to '**From URL**'.

   ![Change Cesium tileset source to From URL](/unity/cesium/get-started/img/cesium-3d-tiles-source-from-url.jpg)

1. Insert the MapTiler 3D terrain tileset URL in the URL field. The tiles contain real-world elevation data encoded into vector TIN polygons in format for the Cesium JavaScript library. The URL should be `https://api.maptiler.com/tiles/terrain-quantized-mesh-v2/tiles.json?key=YOUR_MAPTILER_API_KEY_HERE` (or just copy the URL from your 3D terrain in the [Maptiler Cloud](https://cloud.maptiler.com/tiles/terrain-quantized-mesh-v2/)). Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [protect the key](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) before you publish it!

   ![Copy the MapTiler terrain URL](/unity/cesium/get-started/img/maptiler-terrain-cesium.jpg)

1. Take a look at the _Hierarchy_ window. The **CesiumGeoreference**, is created automatically the first time you add a 3D Tileset to the scene.

1. Add a new component inside the **CesiumGeoreference**. In the Inspector window click the Add component button. Add a new Web Map Tile Service Raster

   ![Unity add new Cesium WMTS raster tile service](/unity/cesium/get-started/img/cesium-wmts-raster-tile-service.jpg)

1. Get the URL of the (WMTS) Web map tile service of your MapTiler maps. Go to the [MapTiler maps](https://cloud.maptiler.com/maps/), and select one of the standard maps (high-quality basemaps like Planet, Ocean, High-Res Imagery) or your custom maps (Try the [MapTiler Map Designer](https://www.maptiler.com/cloud/customize/)). The URL should be `https://api.maptiler.com/maps/YOUR_MAP_ID_HERE/{TileMatrix}/{TileCol}/{TileRow}.jpg?key=YOUR_MAPTILER_API_KEY_HERE` or open the WMTS Capabilities.

   ![Open WMTS capabilities](/unity/cesium/get-started/img/maptiler-wmts-capabilities.jpg)

   In the Capabilities XML look for the **ResourceURL** within Content ➡ Layer. And copy the URL value of the `template` attribute.

   ![WMTS capabilities ResourceURL](/unity/cesium/get-started/img/maptiler-wmts-resource-url.jpg)

1. Configure the _Cesium Web Map Tile Service Raster Overlay_. Add the WMTS URL obtained in the previous step into the Base URL field and check the projection is Web Mercator.

   ![Unity configure CesiumWebMapTileServiceRasterOverlay url and mercator](/unity/cesium/get-started/img/cesium-wmts-service-url-mercator.jpg)

   > [!NOTE]
   > The process is replicable with MapTiler Server with [Download Terrain 3D - Cesium quantized mesh of the entire planet ](https://www.maptiler.com/on-prem-datasets/dataset/terrain-quantized-mesh/) and then for the overlay, any map that is on your [MapTiler Server](https://www.maptiler.com/server/).

## Set the initial view localization coordinates

1. Select the **CesiumGeoreference** in the **Hierarchy**.

1. In the **Inspector** panel, look for the **Latitude**, **Longitude**, and **Height** variables under the _Origin (Longitude Latitude Height)_ category. Change these variables to the coordinates of your favorite city or use these coordinates to travel to Lake Louise, Canada.

   ```
   Origin Latitude = 51.395879
   Origin Longitude = -116.261587
   Origin Height = 3000.0
   ```

   ![Unity CesiumGeoreference change origin latitude and longitude](/unity/cesium/get-started/img/cesium-georeference-change-origin-lat-lon.jpg)

   After entering these coordinates, the scene will have shifted to the new location.

1. Now that you have added global real-world content to your scene, let’s learn how to navigate it.

1. Add a **Dynamic Camera** using the Cesium panel.

   ![Unity add a Cesium dynamic camera](/unity/cesium/get-started/img/add-dynamic-camera.jpg)

   The Dynamic Camera can dynamically adjust its clipping planes so the globe is not clipped as it zooms out. It also offers easier navigation of the globe by allowing users to adjust their movement speed with the mouse wheel and providing the ability to fly between global locations along a curved path.

   The DynamicCamera should appear under the existing **CesiumGeoreference** in the Hierarchy window.

1. Disable the Main Camera by selecting it in the Hierarchy window and unchecking the box next to its name in the Inspector. The DynamicCamera will become the new main camera of the scene. You can also remove the Main Camera object from the scene entirely.

1. The DynamicCamera is a georeferenced object, it will maintain its position relative to its coordinates on the globe, and not the standard Unity world coordinates. This means that if the **CesiumGeoreference’s Origin** is changed to a different location, the _DynamicCamera_ will stay behind.

   If you'd like to move it to your new location, select it in the Hierarchy window and find its Transform in the Inspector. Change its Position’s X, Y, and Z coordinates to 0 to move it to the Unity origin. You can also right-click the three dots on the Transform component and select Reset from the drop-down menu.

## Explore your level

1. You're ready to test out your level! Press the **Play** button at the top toolbar. You can use the W, A, S, and D keyboard keys and the mouse to fly around. Use the Q and E keys to move the camera vertically to the globe. Use the mouse scroll wheel to change your speed.
   You've created your first project with Cesium for Unity. Feel free to explore the world!

### Examples

![Real-world 3D MapTiler maps in Unity](/unity/cesium/get-started/img/maptiler-unity-cesium.png)
[MapTiler High resolution Imagery map](https://cloud.maptiler.com/maps//)

![Real-world 3D globe MapTiler maps in  Unity](/unity/cesium/get-started/img/maptiler-unity-globe.png)
[MapTiler Global Satellite map](https://cloud.maptiler.com/maps//)

![Custom MapTiler old maps in Unity](/unity/cesium/get-started/img/maptiler-unity-custom-old-maps.png)
[UK Great Britain, 1900s](https://cloud.maptiler.com/tiles/uk-osgb1888/)

![Real-world 3D MapTiler winter maps in Unity](/unity/cesium/get-started/img/maptiler-unity-winter.png)
[MapTiler Outdoor Winter map](https://cloud.maptiler.com/maps//)

## Summary

- MapTiler basemaps can be easily used in Unity adding a WMTS map, via [MapTiler ](https://www.maptiler.com/cloud/) or [MapTiler Server](https://www.maptiler.com/server/) for on-premise and offline use-cases.

- Create high-fidelity 3D geospatial visualization and simulation capabilities within the Unity Engine using the [MapTiler 3D terrain](https://cloud.maptiler.com/tiles/terrain-quantized-mesh-v2/) service.

- Add your custom maps to Unity. Whether they are: maps created with the [MapTiler Map Designer](https://www.maptiler.com/cloud/customize/), self-hosted maps & images for use in on-prem/local Cesium-based applications for Unity or create your tiled service with [MapTiler Engine](https://www.maptiler.com/engine/).

## Learn more

Check out the [Cesium for Unity tutorials](https://cesium.com/learn/unity/)

# How maps work

Source: https://docs.maptiler.com/guides/how-maps-work/

This is an intro to digital maps. It’s for everyone and doesn’t require any previous knowledge. This page should provide enough information to help you understand the basics needed for building, customizing, and implementing maps.

## How a map gets displayed

In contrast to paper maps, a digital map is usually interactive, allowing you to zoom and pan (move around). However, a single map of the entire world would be too big and too slow to display. So how does it work? 

In short, the world is divided into small squares called **map tiles**, and your browser only loads tiles needed for the current view and zoom level. It's fast and you get an illusion of exploring a single large map.

**Learn more:** [Tiles à la Google Maps](/google-maps-coordinates-tile-bounds-projection/)




## What a map consists of

A map is essentially a combination of two things: **map data** (*what* is displayed on the map) and a **map style** (*how* it is displayed). The relation of these two components is crucial for understanding how to customize a map or add something to it.

### Map data

Map data is the information and material to build a map with. It comes in **datasets** of various types, and determines what you can see on the map. If a dataset contains information about countries (their names and location of borders), then the map can show countries. If a dataset contains information about the floors of water bodies, then the oceans on the map can have a shaded profile indicating depth rather than just flat blue color.

The most important type of dataset is a **tileset**. Each tileset holds a set of map tiles of the same type for a certain area. The tiles can be in either **vector** or **raster** format. At MapTiler, we keep a range of professionally maintained and regularly updated [global tilesets](https://cloud.maptiler.com/tiles/) which are the data backbone of [our maps](https://cloud.maptiler.com/maps/). You can purchase them for your on-prem maps, too. Also, you can create new tilesets from your own data and then combine them with our tilesets to create exactly the map you need.

The other basic dataset type is a **vector data (features)** file. It isn't tiled and contains individual map features in geometric shapes such as points and lines. Thanks to its simplicity, this format is ideal if you want to define your own custom features to show on the map.

**Learn more:** 

- [Vector features](/guides/map-tiling-hosting/data-processing/vector-feature/)
- [Raster and vector tiles compared](/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/)

### Map style

Map style is the cartographic design applied to the map data. If you're showing countries, how thick should the borders be and in what color? If you include country names, what font to use for the labels, and in which language to display them? What shade of blue and which level of transparency for the water areas? 

In practice, the map design is organized into **layers**. Each layer describes 1. what source to get the data from, 2. how to display it. For example, a map layer can pull cycling paths from the MapTiler [Outdoor](https://cloud.maptiler.com/tiles/outdoor/) tileset, and define that the paths will be styled in certain colors based on their difficulty. Definitions of all the layers then get consolidated into a single **map style** document (JSON) which represents your map.

> [!INFO]
> Note that the terms **map** and **map style** are often used interchangeably. For example, the [Streets](https://www.maptiler.com/maps/streets/) map is in fact a `streets.json` file (map style document) which describes how the map should look, so we can refer to it as "the Streets map" or "the Streets map *style*", depending on situation.

## Visual effects

Once you have a map with the desired design, you may want to add some special effects, for example an elaborate visualization of your data or fly-through animation. This requires adding code for the desired effect or functionality, which is usually the job of a developer. We cover everything related to that job in the [developer’s section](/guides/getting-started/developer/) of this documentation.

## What's next?

Now that you know the basic concepts and terminology of map building, you can go ahead and [start designing your map](/guides/getting-started/map-design/) or proceed to learn [how to add your own data to a map](/guides/map-data/add-your-data/). Happy mapping!

# Tiles à la Google Maps: Coordinates, Tile Bounds and Projection

Source: https://docs.maptiler.com/google-maps-coordinates-tile-bounds-projection/









  

    
Tiles à la Google maps

    
Coordinates, tile bounds, projection

    
Learn how zoomable maps works, why they're typically in Mercator projection, and what coordinate systems they can use.

  

  

    Pyramid
  







Explore map tiles in full screen




  

    
How a zoomable map works

  

  
People have been using coordinate systems and map projections to transform the shape of Earth into usable flat maps for centuries.

  
A map of the entire world is too big to be directly displayed on a computer. Therefore, there is a clever mechanism for quick browsing and zooming on maps: the map tiles.

  
The world is divided into small squares, each with a fixed geographic area and scale. This clever trick allows you to browse just a small part of the planet without loading the whole map, and you still get an illusion of exploring a single huge document.






  

    
Spherical Mercator

    
Map projection pioneered by Google, now standardized.

    
Google Maps was one of the first systems for displaying dynamic maps on the web. They chose a Spherical Mercator projection because it preserves shape and angles. The entire world looks like a square, making it easy to work with on a computer.

      
      
        spherical mercator graph
    
    
Almost every open source (like OpenStreetMap) and commercial Maps API provider (like MapTiler) are now using this projection and tiling profile. The tiles are therefore compatible with each other.
    

  






  

    
Coordinate systems for using global map tiles

  





  

    Map of Earth
  

  

    
Degrees Geodetic coordinates WGS84 (EPSG:4326)

    

        
Longitude and latitude coordinates are used by GPS devices for defining position on Earth using World Geodetic System defined in 1984 (WGS84).

        
WGS84 geodetic datum specifies lon/lat (lambda/phi) coordinates on defined ellipsoid shape with defined origin ([0,0] on a prime meridian).

    

  





  

    World displayed using mercator projection
  

  

    
Meters Projected coordinates Spherical Mercator (EPSG:3857)

    

        
Global projected coordinates in meters for the entire planet. Used for raster tile generation in GIS and WM(T)S services.

        
Simpler spherical calculations are used instead of ellipsoidal. Mercator map projection deforms size (Greenland vs. Africa) and never shows poles.

    

  





  

    Pyramid with explanation of resolution and zoom levels
  

  

    
 Pixels Screen coordinates XY pixels at zoom

    

        
Zoom-specific pixel coordinates for each level of the pyramid. Top level (zoom=0) has usually 256x256 pixels, next level 512x512, etc.

        
Devices calculate pixel coordinates at defined zoom level and determine visible viewport for an area which should be loaded from servers. 

    

  





  

    map tiles graph
  

  

    
Tiles Tile coordinates Tile Map Service (ZXY)

    

        
Coordinates of a tile in the pyramid. There is one tile on the top of the pyramid, then 4 tiles, 16 tiles, etc. All raster tiles have the same size, usually 256x256 or 512x512 pixels. Vector tiles work a bit differently.

        
Only relevant tiles are loaded and displayed for the area of interest (viewport). 

    

  




# Map resolution and zoom

Source: https://docs.maptiler.com/guides/how-maps-work/map-resolution/

Map **resolution** defines the level of detail visible on a map at a specific **zoom level**. MapTiler uses a tiling system based on the Spherical Mercator projection (EPSG:3857), where the world is divided into a [pyramid of tiles](/google-maps-coordinates-tile-bounds-projection/) across different zoom levels. As you increase the zoom level, the resolution also increases, providing more detail for a smaller geographic area.

## Zoom levels explained

As resolution is directly tied to zoom level, it's necessary to understand what are the zoom levels, what's visible on each, and also how they behave depending on data type:

* **Raster tiles**: Pre-rendered images with a fixed resolution per tile. If you zoom beyond the maximum available tile zoom, the map will appear pixelated as the device stretches the existing pixels.
* **Vector tiles**: Contain mathematical points and lines, making them resolution-independent. Labels and features remain sharp at any scale, though the *density of data* is managed by the zoom level to maintain readability and performance.

The table below lists the zoom levels with clickable examples for both types of data. 

| Zoom | View | What's visible | Raster map | Vector map |
| :--- | :--- | :--- | :--- | :--- |
| **0–3** | Global | Entire Earth, continents, and oceans. | Satellite 0-3 | Vector 0-3
| **4–5** | Continental | Large-scale geographical features and broad weather patterns. | Satellite 4-5 | Vector 4-5
| **6–9** | Regional | Extensive river systems, mountain ranges, and large metropolitan areas. | Satellite 6-9 | Vector 6-9
| **10–14** | City view | City layouts, major highways, and significant urban features. | Satellite 10-14 | Vector 10-14
| **15–16** | Streets | Neighborhood views where individual buildings become recognizable. | Satellite 15-16 | Vector 15-16
| **17–18** | Street blocks | Highly detailed views of street layouts, parking lots, and vehicles. | Satellite 17-18 | Vector 17-18
| **19–20** | Buildings | Building features, roof structures, and architectural details. | Satellite 19-20 | Vector 19-20
| **21+** | Details | Fine details such as street furniture. Typically only available for areas of particular interest. | Satellite 19-20 | Vector 19-20

**Note:** At zoom levels 15–16, aerial imagery typically replaces satellite imagery to provide higher clarity. Extreme zoom levels (21+) often use drone imagery.

## Resolution and tile size

The resolution (meters per pixel) is determined by the zoom level and tile size. While the industry historically used 256 px tiles, MapTiler uses 512 px tiles as the standard for both vector and raster data. 

- **256×256 px: legacy standard**
- **512×512 px: MapTiler standard**

A 512 px tile covers the same geographic area as four 256 px tiles, which means that MapTiler's zoom levels appear one level sharper than the legacy industry standard and work well also on hi-res displays like Retina.

## Resolution and scales {#table}

The values below represent the resolution at the equator for our **standard 512 px tiles**. Note that for the 512 px tiles, the resolution at a given zoom level is equivalent to the next zoom level in the 256 px standard. To explore map tiles at different resolutions and zoom levels, see our interactive demo.




  

    

      
      
      
    

  





  

    

      

      

        
          

            Zoom level
            Resolution (meters/pixel)
            Map scale at 96 DPI/PPI
            Map width and height (pixels)
          

        
        
      

    

  




# Map coordinate systems

Source: https://docs.maptiler.com/guides/how-maps-work/coordinate-systems/

A coordinate system is the first important thing that you face when making a map from scratch. A map without it is subjected to oblivion in the geospatial world as it cannot be located. Coordinate systems are what make ordinary data *geospatial*. Thanks to them, we can navigate through maps reliably and with great accuracy.

There is no coordinate system or projection that would preserve areas, angles, distances and directions of the Earth precisely. You always have to think about the purpose of your maps, scale, and type of data to choose the most fitting one.

## Flattening the Earth

We, of course, cannot replicate the Earth’s surface as it is on our maps. To transform it from a 3D to a 2D map layout, **map projections** are being used. These are mathematical algorithms within the coordinate systems. **Coordinate systems** define how to bind your map to the real locations on the Earth.

As the Earth is not flat, there will always be a distortion to some level when transforming it into the map. The important thing is what precision we need the most. Map projections can either preserve **areas, angles, distances, directions,** or **compensate** for all the distortions together.

Once we have the Earth's surface transformed into a map, coordinate systems ensure that we can navigate through it with a set of defined numbers – coordinates. When looking for a coordinate system, you may come across two terms – **geographic or projected coordinate systems**.

In the **geographic coordinate system**, the coordinates are related to an ellipsoid representing the Earth and are in the form of latitude and longitude. The most popular one is the World Geodetic System defined in 1984 (WGS84\) which is used by GPS devices.

![](./4410407957649_6717e57ccf.png)

The **projected coordinate system**, on the other hand, is flat, represented by two axes with coordinates in meters or other linear units. Web Mercator is the most commonly used one. Adopted by Google Maps in 2005, it quickly became a de\-facto standard for web mapping applications.

![](./4410407961361_557e055ab1.png)

## Web Mercator

Web Mercator, also known as **Google Web Mercator**, **Spherical Mercator**, **WGS 84 Web Mercator,** or **Pseudo\-Mercator**, is the coordinate system that you will see on MapTiler maps.

The original Mercator projection was mainly used for **navigation purposes** as it preserves angles and pictures loxodromes as straight lines. This helped the sailors to keep a steady course during their travels.

Web Mercator differs from the original Mercator projection in a far **easier computation,** which is done on a sphere instead of an ellipsoid. The entire world is **shaped like a square,** making it easy to work with on the web. The **north is always up** on the maps and it reduces the area distortion on large scales, making it **suited for seamless zooming** with interactive world maps.

Despite its popularity in the online mapping world, Web Mercator also has its drawbacks. It **distorts areas with distance from the equator**, making Greenland almost the same size as Africa. Poles are not present on the Web Mercator maps and Antarctica is infinite in size. Therefore, it is **not usable for polar areas** at all.

## Search or trasform coordinates

To look up a coordinate system or integrate transformation coordinates into your workflow, use the [Coordinates API](https://docs.maptiler.com/cloud/api/coordinates/). 

## Local coordinate systems

The coordinate system for MapTiler base maps is the **Web Mercator**. MapTiler, however, can host documents in other map projections too. This is useful for integrating with some sources of data and to conform to region\-specific expectations of how maps should look. 

Many countries have national standards for collecting geographic information that use local coordinate systems. Each system is then usually displayed in a specific map projection. The use of local coordinates and projections predates the modern era of GPS measurements in the global WGS84 coordinate system and the ubiquity of online maps. Cadastre maps, road maps, and building plans are examples of documents that are usually available only in local coordinates. People are also used to the way their country or region looks on a map in the local projection. The Mercator projection notoriously distorts regions close to the north and south poles, and even regions further away might look unnatural.

We offer hosting for both raster and vector tilesets in custom coordinate systems. The MBTiles format of tileset container files is specified to always be in web Mercator. To upload a tileset in any other coordinate system, you have to use the GeoPackage format. MapTiler Engine is capable of producing raster GeoPackage tilesets in any projection. However, note that it can only produce vector GeoPackage tilesets in web Mercator for now.

We store vector features in WGS84 and publish them in the GeoJSON format. Due to internal limitations, it is not possible to add datasets as sources to maps operating in local coordinate systems.

# What is map data

Source: https://docs.maptiler.com/guides/how-maps-work/map-data/

**Map data** is the building material for a map. If this sounds unclear, see the beginner intro [What a map consists of](/guides/getting-started/how-maps-work/#what-a-map-consists-of).

## Types of map data

Map data comes in **datasets** of various types. There are these key types: 

#### Tilesets

A tileset is a container with **map tiles**, which is map data cut into roughly square tiles and [organized into a pyramid](/google-maps-coordinates-tile-bounds-projection/) for fast and easy access. Map tiles inside a tileset can be in different formats: 

- **Raster tilesets** contain map tiles in regular image formats (PNG, JPG, WEBP...). Raster tiles are the traditional format used to store satellite and aerial imagery.

- **Vector tilesets** contain [vector features](/guides/map-tiling-hosting/data-processing/vector-feature/). These represent objects on a map as geometric shapes – points, lines, and polygons. Vector tiles are more modern, lightweight, and can be styled on the fly. See [Raster vs vector map tiles](/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/) to learn more.

#### Vector data files 

Vector data files contain [vector features](/guides/map-tiling-hosting/data-processing/vector-feature/), just like **vector tilesets**. The difference is that a vector data file is *not tiled*. It's a single file, usually in GeoJSON format. A vector data file needs to get tiled when it's too big to be accessed as one object.

#### Other types

The mentioned dataset types (raster tilesets, vector tilesets, vector data files) are the most common, but there are other types as well, for example **raster-DEM tilesets** that contain various additional values (like elevation) encoded as standard RGB colors, or **3D quantized polygon mesh** representing 3D terrain. 

Usually, these special formats are already embedded in ready-made maps and you won't need to work with them directly.

## How to use map data

To make your final map, you'll typically need:

1. A ready-made [MapTiler map](https://www.maptiler.com/maps/) as a base. All our maps contain up-to-date global map data of the right types, and you don't need to do anything special [to use them](/guides/getting-started/use-map/).

2. Your own **custom data** that you want to add to the map. See 👉 [how to add your own map data](/guides/getting-started/add-data/) to learn all about how to prepare and integrate it.

3. To build a specialized map, you may need to combine your selected MapTiler basemap with **additional MapTiler data**. See 👉 [Map data by MapTiler](/guides/map-data/maptiler-datasets/) to get more details about the individual tilesets we offer.

Both MapTiler data and your custom data can be also self-hosted. Check out [MapTiler Server](/guides/self-hosting/map-server/) if you're looking to host your map data on-prem.

# Vector features and data

Source: https://docs.maptiler.com/guides/how-maps-work/vector-feature/

Vector data is one of the most common types of map data. It consists of **vector features** which represent real-life objects as geometric shapes: **points, lines, and polygons**. That's different from [raster data](/guides/general/raster-vs-vector-map-tiles-what-is-the-difference-between-the-two-data-types/) which uses images and pixels. Overall, vector features are more lightweight, easier to create and style, and suitable for [adding your own map data](/guides/map-data/use-vector-data/). 

## Geometry

Vector features consist of two parts: **geometry** and **properties**. Geometry is the shape that represents an object:

- **Point** geometry (vertex) represents objects that occupy a single spot, for example lamps, traffic lights, single trees, or bus stops.
- **Line** geometries (edges) represent linear objects such as roads, highways, electric wires, and similar objects.
- **Polygons** are enclosed lines that represent areal objects like buildings, forests, crop fields, and so on.

Here's what raw, unstyled vector features look like:

![](./4410765110801_0c72cda405.png)

As you can see, the basic three geometries are sufficient to show pretty much anything on a map. Of course, sometimes you need to combine them to get the best representation of an object. For example, a river stream can use lines for the banks, and a polygon for the water body itself.

## Properties

Properties are attribute values that hold additional information about the object they represent. For example, for a road object (which is represented as line geometry) you can add properties such as road ID, owner, or last date of snow cleaning – whatever you need.

## Working with vector features

Every point, line, and polygon counts as one vector feature. So, if you have data with 5 points of interest (POI), 10 roads, and 5 buildings, it is in total 20 vector features. This is important to understand because the number of vector features affects how the vector data is stored and handled.

Vector data come in two formats, which you can both create with our tools: 

- As a **single file** (typically GeoJSON). You can create, edit, and export such file in our [**Vector data editor**](/guides/vector-data-editor/).

- As a **vector tileset**. In this case, vector features are split into multiple map tiles and stored in a container file, which is handy when a single file becomes too large. At MapTiler, we set specific [size limits](/guides/maps-apis/maps-platform/dataset-upload-formats-and-limits/) for vector features that you can upload as a single file – if your file is larger than these limits, you can tile it up using [**MapTiler Engine**](/guides/map-tiling-hosting/data-processing/).

# Raster vs vector tiles: the difference

Source: https://docs.maptiler.com/guides/how-maps-work/raster-vector-tiles/

This page explains the difference between raster and vector map tiles. You will learn about different MapTiler products that offer ready\-to\-use raster and vector tiles of the entire planet for your projects and applications. Also, you will find out how to create raster or vector map tiles from your own data with [MapTiler Engine](https://www.maptiler.com/engine/pricing/).

## Brief summary

- **Raster** map tiles are larger in size, less demanding on end\-users' hardware but more demanding on the server\-side performance.
 **Vector** map tiles are faster to load, and less demanding on the server\-side performance but more demanding on end\-users hardware.
- MapTiler uses both map data types. We provide [many standard tilesets](/guides/how-maps-work/maptiler-datasets/) with data for the whole world, as well as [tools](/guides/map-tiling-hosting/data-processing/) to create your own tilesets.

## Raster tiles

Web maps based on raster tiles technology are older but still widely used approach by many. In computer graphics, a raster graphic is a dot matrix data structure that represents a generally rectangular grid of pixels (points of color), viewable e.g. via a computer or mobile display. Raster images are stored in image files of varying formats.

Raster map tiles are essentially raster images. Zoomable raster maps consist of many raster map tiles (in the .png or .jpg format) placed next to each other, ordered in a pyramid scheme. This clever trick allows you to browse just a small part of the map without loading it whole while maintaining the feeling of exploring a single large document. Read more about zoomable maps and the [pyramid scheme](/google-maps-coordinates-tile-bounds-projection/).

![](./4411207924625_7a1e6e7036.png)

As raster tiles are images stitched together, they can be zoomed and panned but do not provide styling capabilities on the user’s end. Raster tiles have fixed styles, defined at the time they are created (rendered). Rendering raster imagery is CPU\- and memory\-consuming. One solution, used by many web map providers, is to render tiles in advance before serving them from a server. So every time a user opens the map, the pre\-rendered tiles are simply shown on the screen which means that the requirements for end\-users' hardware are much lower while the server\-side hardware requirements are higher.

On the other hand, raster tiles are large in size, so the loading time during panning and zooming on the map may be longer, depending on the network connection speed.

![](./4411207925009_0dec5100f1.png)

### Vector map tiles

Vector tiles were introduced later, they also deliver data that are divided into roughly squared tiles. But these tiles do not consist of raster images, they are made of mathematical interpretations of geometric features such as points, curves, or polygons. Vector tiles are rendered on the client’s side with a style, which is a small text file that defines how certain map elements look and how they are displayed (e.g., a road can be defined as a solid red line placed on top of all map elements). The style also says whether the map element should be rendered at all, and what font and language are to be used for rendering the labels. So vector tiles make it easy to change the map's look & feel on the fly with minimum resources.

Vector tiles are transferred over the internet in the form of a geographic data package, which usually consists of individual tiles in the .pbf format. The map client on the end user's device will use a rendering engine to create the map in the form of an image that can be displayed to the end user to view. That is why the vector tiles are more demanding on the client’s hardware.

Vector tiles are about 20–50% of the size of raster tiles so they take less time to transmit, requiring fewer resources for processing. Moreover, they offer a high\-resolution display on all zoom levels without increasing the file size of the tiles.

Vector tiles are supported by many JavaScript libraries and SDKs for the web and mobile, such as:

* [MapLibre Open Maps SDKs](https://maplibre.org/) (JavaScript, Android, iOS)
* [Leaflet](https://leafletjs.com/) (JavaScript)
* [OpenLayers](https://openlayers.org/) (JavaScript)
* [QGIS](https://qgis.org/), [ArcGIS](https://www.arcgis.com/), and other GIS software tools

![](./4411207925521_e590d8420e.png)

## Pros and cons

Both vector and raster map tiles have their advantages and disadvantages which impact what they are used for. Let’s take a look at the most important points:

### Vector tiles

#### Pros:

* Smaller size \- lower server space requirement
* Lower bandwidth consumption
* Faster loading time
* Smooth zooming experience
* Invisible zoom levels
* A high\-resolution display on all zoom levels without increasing the file size
* Easy and on\-the\-fly customization

#### Cons:

* Rendering on the end\-users device requires more powerful hardware

### Raster tiles

#### Pros:

* Rendering on the server \- lower requirements for end\-users hardware
* Suitable for some data types like satellite or aerial imagery

#### Cons:

* Larger size \- higher server space requirement
* Higher bandwidth consumption
* Slower loading time
* Step zooming (not smooth)
* Visible zoom levels
* Lower resolution on greater zoom levels

It is possible to mix raster with vector tiles and get the best out of both, e.g., a satellite map (raster tiles) with an overlay of streets with labels available in different languages (vector tiles). Check on the interactive map below.

## Create your own tiles 

To get started creating your own raster or vector tileset, simply [upload your files](/guides/map-data/upload-files/) into your MapTiler account and let us handle the processing, or check out [MapTiler Engine](/guides/map-tiling-hosting/data-processing/) if you prefer a powerful tool running on your own hardware.

# Generalization in maps

Source: https://docs.maptiler.com/guides/how-maps-work/generalization-in-maps/

Cartographic generalization, or map generalization, includes any changes in a map that are made when deriving a smaller\-scale map from the larger\-scale map or map data. It is a central part of cartographic design. Whether performed manually by a cartographer, or by a computer, or by a set of algorithms, generalization aims to abstract spatial information at a high level of detail into information that can be rendered on a map at a lower level of detail.

The cartographer can customize the content of their maps to create an appropriate and useful map that conveys spatial information while striking the right balance between the purpose of the map and the precise detail of the item being mapped. Well\-generated maps are those that highlight key map elements while representing the world as faithfully and recognizable as possible.

Cartographic generalization is a complex discipline that has been evolving for more than a hundred years with countless scientific publications and tons of research. This page gives just a brief introduction into the topic.

## Generalization operators

### Select

Selection is the process of simply removing entire geographic features from the map. There are two types of selection, which are combined in some models, and separated in others. There are 2 basic types of selection: feature selection, and layer selection.

### Simplify

Simplification is the removal of vertices in lines and area boundaries.

### Smooth

For line features (and area boundaries), Smoothing seems similar to simplification, and in the past, was sometimes combined with simplification. The difference is that smoothing is designed to make the overall shape of the line look simpler by removing small details; which may actually require more vertices than the original. Simplification tends to make a curved line look angular, while Smoothing tends to do the opposite.

### Merge

Merging involves combining neighboring features into a single feature of the same type, at scales where the distinction between them is not important.

### Aggregate

Aggregation is the merger of multiple features into a new composite feature, often of increased Dimension (usually points to areas). The new feature is of an ontological type different than the original individuals because it conceptualizes the group.

### Typify

Typify is a symbology operator that replaces a large set of similar features with a smaller number of representative symbols, resulting in a sparser, cleaner map. For example, an area with dozens of wind power plants might be symbolized with only 3 or 4 wind power plant symbols that do not represent actual wind power plant locations, just the general presence of wind power plants in the area.

### Collapse

This operator reduces the Dimension of a feature, such as the common practice of representing cities (2\-dimensional) as points (0\-dimensional), and roads (2\-dimensional) as lines (1\-dimensional).

### Reclassify

This operator primarily simplifies the attributes of the features, although a geometric simplification may also result. While Categorization is used for a wide variety of purposes, in this case, the task is to take a large range of values that is too complex to represent on the map of a given scale and reduce it to a few categories that are much simpler to represent, especially if geographic patterns result in large regions of the same category.

### Exaggerate

Exaggeration is the partial adjustment of geometry or symbology to make some aspect of a feature larger than it really is, in order to make them more visible, recognizable, or higher in the visual hierarchy. For example, a set of tight switchbacks in a road would run together on a small\-scale map, so the road is redrawn with the loops larger and further apart than in reality.

### Displace

Displacement can be employed when two objects are so close to each other that they would overlap at smaller scales, especially when the exaggerate operator has made the two objects larger than they really are.

### Enhance

This is the addition of symbols or other details on a smaller scale map to make a particular feature make more sense, especially when such understanding is important for the map's purpose.

## Generalization in MapTiler maps

Let's see an example of how some generalization rules influence the visibility of features in MapTiler maps. Let's say I use Maptiler basic map and I'm trying to get the minor roads in zoom level 7\+ to be visible at all zoom levels (even in those higher than 7, like 4, 5, or 6\). I have the min zoom level for "road\_network" set to 0, but it seems there are other factors determining when the minor roads appear within the style.JSON file. What are they? below are two pictures that demonstrate the visibility of the road network across different zoom levels.
  
Zoom level: 6,39

![1.png](./8785094762641_70664a0295.png)
  
Zoom level: 7,15

![2.png](./8785094779921_9673481b37.png)

### How to make the road network visible in higher zoom levels

MapTiler cartography team defined the default map styles (including the Baic) in a way that complies with the rules of cartographical generalization and that renders the maps easy to read and somehow pleasant to the eye. As a result of that, certain features are by default visible only at certain zoom levels, with little possibility of altering the visibility range (usually making the visibility range shorter).  
That is to avoid situations when e.g. a low\-level road network would suddenly appear in higher zoom levels and would cover most of the map surface, making the map hard to read.  
   
This is achieved by a set of rules in the style.json on one hand, and by uploading only a limited amount of tiles into the map repository on the other hand. Therefore, the road network cannot be made visible only by moving the sliders in the Advanced map editor, because the map tiles for that layer and for that zoom levels are simply not generated and uploaded to the map's repository.  
   
To make the road network visible (going a bit against the cartographical rules), you can generate a dataset that contains the map tiles with the road network in the required zoom levels (generate is with MapTiler Engine) and once the new tileset is ready, upload it to MapTiler. Follow these steps:

1. [Download MapTiler Engine](https://www.maptiler.com/engine/download)
2. [Generate a new set of vector tiles (road network)](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-vector-data)
3. [Add the generated dataset to your custom MapTiler map](/guides/maps-apis/maps-platform/dataset-upload-formats-and-limits)

# Map data by MapTiler

Source: https://docs.maptiler.com/guides/how-maps-work/maptiler-datasets/

All [map data](/guides/map-data/) provided by MapTiler comes in **tilesets**. We use them ourselves to build the selection of [ready-made maps](https://cloud.maptiler.com/maps/) for you, so you can simply [pick and use any of them](/guides/getting-started/use-map/) as-is.

In case you're building a specialized map, it can happen that none of our ready-made maps precisely match your needs. In that case, you can **enrich a ready-made map** with data from [additional tilesets](https://cloud.maptiler.com/tiles/) and combine them to get the exact result you want. Expert users can even build their own map style using our tilesets. For that purpose, you'll need advanced information available in this section.

👉 [See all our **vector tile schemas**](/schema/)

## Data updates

Each of our tilesets has a different update schedule. The main tilesets that contain a lot of changing details are updated every 2 weeks, others less frequently or ad hoc. To get the exact date of the last update, go to [page **Tiles**](https://cloud.maptiler.com/tiles/), click on the tileset you're interested in, and check the section **Tileset details**.

## Data for download

Most of our professional tilesets are also available for [self-hosting](/guides/self-hosting/map-server/). You can get a standard package for a specific country or the whole world, or select your own **custom extract** to get exactly the part you need. Check out the [on-prem datasets](https://www.maptiler.com/on-prem-datasets/planet/) to see what's available.

# MapTiler Planet v4

Source: https://docs.maptiler.com/schema/planet-v4/


MapTiler Planet v4 is the next generation of the global vector tileset, designed for both professional cartographers and map designers. It delivers an optimized schema hierarchy, higher detail across all zoom levels, and enhanced data consistency worldwide. It features points of interest, administrative areas, built-up regions with buildings, transportation networks, and water and natural features. The dataset is updated bi-weekly with rigorous quality control to ensure reliability and precision.



# MapTiler Buildings

Source: https://docs.maptiler.com/schema/buildings/

The MapTiler Buildings tileset provides additional building-related layers with enhanced detail (e.g. entrances, names, classification attributes). It is intended for use with MapTiler Planet v4, and together they offer rich building context for everyday mapping applications.

# MapTiler Cadastre

Source: https://docs.maptiler.com/schema/cadastre/

MapTiler Cadastre is a tileset containing real estate cadastre information. Design of tileset containing the most useful information (availability depends on country) like parcel, buildings and their numbers, land-use, or addresses. Tileset provides the most precise geometry (low scale mapping) with additional information for interconnecting with authorities. Nevertheless, this Tileset cannot be used for any legal action and in any legal case please contact the competent authority.

# MapTiler Cadastre dataset

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/maptiler-cadastre-dataset/

MapTiler Cadastral is a dataset containing **real estate cadastre information**. The dataset's design contains **the most useful information** (availability depends on country), such as **parcels**, **buildings,** and their **numbers**, **land use**, or **addresses**. The dataset provides **the most precise geometry** (large\-scale, detailed mapping) with additional information for **interconnecting with authorities**.

Nevertheless, this dataset **cannot be used for any legal action.** If you need data for a legal case, please contact the competent authority.

* *The tile service, WMTS, for static maps is at: [Map in MapTiler](https://cloud.maptiler.com/maps/cadastre/)*
* *A schema of the dataset is available here: [Cadastre schema](https://docs.maptiler.com/schema/cadastre/ "https://docs.maptiler.com/schema/countries/")*
* *An overview of the dataset is available here: [Cadastre map](https://www.maptiler.com/cadastre/)*
* *The launch news article is here: [Cadastral maps with vector tiles](https://www.maptiler.com/news/2022/05/cadastral-maps-with-vector-tiles/)*

Area of use
-----------

Dataset version 0\.2 covers 19 of the 26 Cantons of **Switzerland**. We are working on adding other countries; if you have any preferences, please let us know ([MapTiler Support](/support/requests/)).

Data updates
------------

Currently, the data are **updated** **monthly**. However, please always check the **Last modified** date in the Tileset details \- date of the last data export. Each canton has a different update cycle frequency and not all cantons provide their data as open\-data.

| Canton | Update cycle |
| --- | --- |
| AG \- Aargau | Weekly |
| AI \- Appenzell Innerrhoden | Daily |
| AR \- Appenzell Ausserrhoden | No open data |
| BE \- Berne | Custom |
| BL \- Basel\-Landschaft | Weekly |
| BS \- Basel\-Stadt | Unknown |
| FR \- Fribourg​ | Daily |
| GE \- Geneva | Monthly |
| GL \- Glarus | Custom |
| GR \- Grisons | Irregular |
| JU \- Jura | No open data |
| LU \- Lucerne | No open data |
| NE \- Neuchâtel | No open data |
| NW \- Nidwalden | No open data |
| OW \- Obwalden | No open data |
| SG \- St. Gallen | Custom |
| SH \- Schaffhausen | Daily |
| SO \- Solothurn | Weekly |
| SZ \- Schwyz | Weekly |
| TG \- Thurgau | Constantly |
| TI \- Ticino | Constantly |
| UR \- Uri | Weekly |
| VD \- Vaud | No open data |
| VS \- Valais | Data from 2021\-12\-08 |
| ZG \- Zug | Monthly |
| ZH \- Zürich | Weekly |

![](./15206978139281_3cf1662fb0.png)

There is the `updated` attribute for each feature in layers `building`, `landuse`, `parcel` and `survey_point` that describes from which data export the data originate.

Map Style
---------

There is available **ready\-to\-use** [**map style**](https://cloud.maptiler.com/maps/cadastre/) that you can modify, or implement into your map style.

The **[tileset](https://cloud.maptiler.com/tiles/cadastre/)** could be also used and styled as you wish. It could be implemented into e.g. Street style and boost your own map with cadastral data

How to add cadastre into your map
---------------------------------

* Open Streets style in **Advance Customize**
* Add Cadastral as a **new source**
* Add a new layer e.g. **“parcel”** as a **`line`** from data source **`Cadastre`** and source layer **`parcel`**
* Style your new **`parcel`** layers as usual (line layer)
* Add a new layer e.g. **“parcel\_name”** as a **`symbol`** from data source **`Cadastre`** and source layer **`parcel_name`**
* Style your new **`parcel_name`** layers as usual
    - the example is used filter **`rank=1`** to show just a parcel number  
    - in the text field is set to the value **`{number}`**.

![streets_cadastral_map_fullhd.png](./4417427852945_206d79cf4b.png)

Attribution
-----------

The Cadastral dataset requires only **(c) MapTiler** attribution with the link. There is a possibility to purchase attribution exemption or get data for self\-hosting. If you need it for your use case, please contact us.

Useful links
------------

[Maps, Tiles, Data: What are they and how do they differ?](/guides/map-tiling-hosting/data-hosting/maps-tiles-data-what-are-they-and-how-do-they-differ/)  
[How to create a map with your own style/design in MapTiler Edit Style](/guides/map-design/layer-styling)  
[Edit Style: Advanced customization of the map](/guides/map-design/layer-styling)  
[MapTiler Cadastre Schema](https://docs.maptiler.com/schema/cadastre/)

# MapTiler Contours

Source: https://docs.maptiler.com/schema/contours/

MapTiler Contours is a tileset that contains contour lines with height in both meters and feet and additional information for index line and glacier styling.

# Global Contours tileset

Source: https://docs.maptiler.com/guides/self-hosting/self-hosted-maps/global-contours-tileset/

The Global Contour lines tileset by MapTiler contains contour lines in both imperial (feet) and metric  (meters) system. This articles describes how to work with both of them.

![vrstevnice.png](./15105682273169_4e87199cee.png)

[Topo style \| Maps \| MapTiler](https://www.maptiler.com/maps/#style=topo&mode=2d&position=13.55/46.95406/10.90823)

## Technical parameters

Contour lines are generated between zoom levels 9 and 14 in the PBF vector format. The tileset contains two layers: ***\-deactivate*** and **_contour_ft_**. Each LineString segment contains attributes: 

- **_height_** \- representing elevation
- **_nth_line_** \- marking every 1st, 2nd, 5th and 10th line
- **_glacier_** \- indicating, whether the segment intersects with the glacier or not

The interval between contour lines is

- 10 meters
- 20 feet

See the [MapTiler Contours schema](https://docs.maptiler.com/schema/contours/) section for more technical details.

## How to change Meters to Feet in the map using style.json

In the style.json of your map, you have to change the source\-layer attribute from contour to cotour_ft:

**Using contours in meters**

```json
{
  "id": "contour",
  "type": "line",
  "source": "contours",
  "source-layer": "contour",
  "minzoom": 11,
  "paint": {
  "line-color": "hsl(36, 39%, 49%)",
  "line-width": 0.8
  },
  ...
}
```

**Using contours in feet**

```json
{
  "id": "contour",
  "type": "line",
  "source": "contours",
  "source-layer": "contour_ft",
  "minzoom": 11,
  "paint": {
  "line-color": "hsl(36, 39%, 49%)",
  "line-width": 0.8
  },
  ...
}
```

You can switch the unit system in the Advanced Style editor:

![image-20230424-123852.png](./15105775429521_c1f6b76b2c.png)

## Switch between meters and feet using MapTiler SDK

When switching the layer source, the layer must be removed and added back.

```js
const changeLayerSource = function (layer_id, source) {
  // get layer definition, remove layer, add layer
  const oldLayers = map.getStyle().layers;
  const layerIndex = oldLayers.findIndex((l) => l.id === layer_id);
  const contourDef = oldLayers[layerIndex];
  const before = oldLayers[layerIndex + 1] && oldLayers[layerIndex + 1].id;
  contourDef["source-layer"] = source;
  map.removeLayer(layer_id);
  map.addLayer(contourDef, before);
};
```

Example: [https://docs.maptiler.com/sdk\-js/examples/contour\-meter\-feet/](https://docs.maptiler.com/sdk-js/examples/contour-meter-feet/)

## Generalization

The geometry of the contour lines is generalized on zoom levels 9 to 11\. From zoom level 12 best line geometry is used. But not all contour lines are included in the data source on every zoom level. From zoom ZL9 to ZL14, contour lines are gradually added in increments of 500 and 10\.

## License conditions

With the use of this tileset, you must visibly credit these attributions:

[© MapTiler](https://www.maptiler.com/copyright/)

## Usage in MapTiler

The [Contours tileset](https://cloud.maptiler.com/tiles/contours/) is available for all users of the [MapTiler](https://cloud.maptiler.com/) platform in the [Tiles](https://cloud.maptiler.com/tiles/) section. Contour tileset is already part of pre\-defined map styles:

- [Outdoor](https://www.maptiler.com/maps/#style=&mode=2d&position=14.86/46.81031/10.26298)
- [Winter](https://www.maptiler.com/maps/#style=&mode=2d&position=14.86/46.81031/10.26298)
- [Topo](https://cloud.maptiler.com/maps//)

See the documentation article about the practical usage of the Contour tileset:

- [Improve terrain visualization in glacial regions](/guides/map-design/improve-terrain-visualization-in-glacial-regions)
- [Contours and mountain peaks in feet](/guides/map-design/contours-and-mountain-peaks-in-feet)

## Self\-hosting via MapTiler data

The tileset is also available for download for self\-hosted with [MapTiler Server](https://www.maptiler.com/server/) through the [MapTiler data](https://www.maptiler.com/on-prem-datasets/dataset/contours/) platform.

## Useful links

[MapTiler Contours schema](https://docs.maptiler.com/schema/contours/)

# MapTiler Countries

Source: https://docs.maptiler.com/schema/countries/

MapTiler Countries is a tileset that contains data about administrative divisions of a world based on countries and their territories. List of features and IDs Useful links with features for data joins. cdn.maptiler.com/data/countries/administrative-level-0.csv cdn.maptiler.com/data/countries/administrative-level-1.csv cdn.maptiler.com/data/countries/administrative-level-2.csv cdn.maptiler.com/data/countries/administrative-level-3.csv cdn.maptiler.com/data/countries/postal-level-0.csv cdn.maptiler.com/data/countries/postal-level-1-extra.csv cdn.maptiler.com/data/countries/postal-level-1.csv

# MapTiler Countries dataset

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/maptiler-countries-dataset/

**MapTiler Countries** is a dataset that primarily contains data about administrative divisions of the world based on countries and their territories. The dataset is designed to be used as an **interactive choropleth map** to make beautiful cartographic visualizations easily. If you are searching for the land polygon only, see the **MapTiler Land** dataset.

### Before you scroll down, please read these 2 articles:

[Schema documentation](https://docs.maptiler.com/schema/countries/)  
[The dataset in MapTiler](https://cloud.maptiler.com/tiles/countries/)  

![Screenshot_2023-04-24_at_12.14.59.png](./14785700884497_26d8d181c4.png)

Structure
---------

According to [the schema](https://docs.maptiler.com/schema/countries/), there are two main layers as polygons:

**administrative** \- contains levels of countries and their divisions

**postal** \- contains zip code areas \- now only available in the US

How to use and filter data for MapTiler Countries
-------------------------------------------------

1. Add the data source **countries** from MapTiler to your map in the MapTiler Editor.
2. Add a layer and name it in your language, for example, “US\_states”.
3. Now you can filter it by level.

The level represents divisions in the whole country. The level with the value 0 (as a number) is a country, and levels 1, 2, and 3 are divisions, subdivisions, and sub\-subdivisions of the countries. The dataset currently contains countries and divisions; along with subdivisions for Europe and the USA. If you need more subdivisions and sub\-subdivisions, please contact us.  
  
Example of style filtered to colored US states

``` json
...
{
  "id": "US_states",
  "type": "fill",
  "paint": {
    "fill-color": [
      "match",
      ["get", "name"],
      ["Nebraska", "Alaska", "Washington", "Nevada", "New Mexico", "Montana", "Minnesota", "Louisiana", "North Carolina", "Kentucky", "Massachusetts", "Delaware", "Michigan"],
      "#D5CD85",
      ["Oklahoma", "Florida", "Idaho", "Wisconsin", "Arizona", "Tennessee", "Pennsylvania", "New Hampshire", "Rhode Island"],
      "#D58785",
      ["New York", "California", "Wyoming", "Kansas", "Illinois", "Mississippi", "South Carolina", "West Virginia"],
      "#735F91",
      ["Texas", "Georgia", "Utah", "Missouri", "South Dakota", "Ohio", "Maryland", "Vermont"],
      "#567986",
      ["Colorado", "Oregon", "Alabama", "Indiana", "North Dakota", "Iowa", "Arkansas", "Virginia", "New Jersey", "Maine", "Connecticut"],
      "#69A86D",
      "rgba(0, 0, 0, 0.5)"
    ],
    "fill-outline-color": "rgba(125, 101, 101, 1)"
  },
  "filter": [
    "all",
    ["==", "level", 1],
    ["==", "level_0", "US"]
  ],
  "source": "countries",
  "source-layer": "administrative"
}
...
```

Attribution
-----------

The dataset requires only (c) MapTiler attribution with the link. There is a possibility to purchase attribution exemption or get data for self\-hosting. If you need it for your use case, please contact us.

Useful links
------------

[How to add own data to MapTiler Countries to make a choropleth map](/guides/maps-apis/maps-platform/join-maptiler-countries-with-your-own-custom-data-and-make-a-choropleth-map)  
[Choropleth map with GeoJSON](/guides/maps-apis/maps-platform/zoomable-choropleth-map-from-geojson-with-leaflet)

# MapTiler Grid

Source: https://docs.maptiler.com/schema/grid/

MapTiler Grid is a vector tileset providing global spatial reference layers, including international timezones, UTC offset boundaries, and a standardized WGS84 graticule.

# Hillshading

Source: https://docs.maptiler.com/schema-raster/hillshading/

Global shaded relief uses digital elevation models (DEMs) to generate shades based on light sources. It is generated up to medium resolution, where it can be replaced by [Terrain RGB](/schema-raster/terrain-rgb/) hillshading methods.

**[Inspect Hillshading](https://cloud.maptiler.com/tiles/hillshade/)**

## Dataset definition

- Dataset ID: hillshade
- Name: Hillshading
- Min zoom: 0
- Max zoom: 12
- Format: webp
- Latest version: 2.1
- Resolution: 30 m

# Hand drawn hillshading

Source: https://docs.maptiler.com/schema-raster/hand-drawn-hillshading/

Hand-drawn hillshading is a cartographic technique that enhances the visual representation of terrain using light, shadow, and artistic shading methods. One of the most influential figures in this field was Eduard Imhof, a Swiss cartographer known for his meticulous hand-drawn hillshades that created depth and realism in maps. His techniques emphasized natural landforms, improving readability and aesthetics.

Hand-drawn hillshading specifically focuses on subtle transitions, soft shadowing, and precise light positioning to maintain clarity and prevent over-exaggeration. It is generated up to medium resolution, where it can be replaced by [Terrain RGB](/schema-raster/terrain-rgb/) hillshading methods.

**[Inspect Hand drawn hillshading](https://cloud.maptiler.com/tiles/hand-drawn-hillshade/)**

## Maps with this tileset

- [Landscape](https://cloud.maptiler.com/maps/landscape-v4/)

## Dataset definition

- Dataset ID: hand-drawn-hillshade
- Name: Hand drawn hillshading
- Min zoom: 0
- Max zoom: 9
- Format: webp
- Latest version: 1
- Resolution: 30 m

## Related tutorials

- [Enhance terrain with hand-drawn hillshading](/guides/map-design/terrain/hand-drawn-hillshading/#use-hand-drawn-hillshading)

# MapTiler Land

Source: https://docs.maptiler.com/schema/land/

MapTiler Land is a tileset that contains vector polygons of land for advanced cartographic visualizations.

# MapTiler Landcover

Source: https://docs.maptiler.com/schema/landcover/

MapTiler Landcover is a tileset containing coverage of land reflected as polygons for whole world generalized for upper zooms. This tileset is included also in MapTiler Planet .

# MapTiler Landcover vector data tileset

Source: https://docs.maptiler.com/guides/self-hosting/self-hosted-maps/maptiler-landcover-vector-data-tileset/

This page describes the tileset called MapTiler Landcover. It is a vector dataset that contains various classes of land cover worldwide. This article provides an overview of these classes, and it presents the internal structure of the whole dataset. There is also a short mention of usage and attribution.

![](./16995653837201_3916a8989a.png)

Structure
---------

The structure of the MapTiler Landcover layer is very simple. There is only one layer in the dataset called `globallandcover` and in this layer, there is the `class` attribute, which contains information about the land cover class. The available values for the `class` attribute are:

* crop
* grass
* scrub
* tree
* forest
* snow

> [!INFO]
> The same data are available in the [MapTiler Planet tileset](https://docs.maptiler.com/schema/planet/#globallandcover) MapTiler team created a separate layer for more lightweight maps or applications, which need a different licensing model from the standard one. To find out more, visit the [MapTiler](https://cloud.maptiler.com/tiles/landcover/) (requires login). The Landcover dataset is also [available for download](https://www.maptiler.com/on-prem-datasets/dataset/landcover/) for local usage.

Usage examples
--------------

Here are a couple of examples of how the MapTiler Landcover layer can be used:

* Create maps that show various landcover classes in an area.
* Perform spatial analysis to understand the relationship between landcover and other factors, such as population density or economic development. This can be very useful, especially in combination with the [MapTiler Countries dataset](/guides/map-tiling-hosting/data-hosting/maptiler-countries-dataset).

Attribution
-----------

The MapTiler Landcover layer requires only (c) MapTiler attribution with the link. It is also possible to purchase attribution exemption or get data for self\-hosting. If you need it for your use case, please contact the sales team of MapTiler.

Conclusion
----------

The MapTiler Landcover layer is a valuable resource for anyone who needs to work with data about landcover. This dataset is easy to use, and it can be integrated with a variety of different applications. The dataset is also regularly updated, so you can be confident that you are using the latest data. In case you would need to use this dataset without any attribution (you want to hide the *OpenStreetMap Contributors* attribution), you can purchase a special license. Just [contact us here](mailto:sales@maptiler.com).

Useful links
------------

[MapTiler Landcover schema page](https://docs.maptiler.com/schema/landcover/)  
[MapTiler Landcover for download](https://www.maptiler.com/on-prem-datasets/dataset/landcover/)  
[MapTIler Landcover in MapTiler](https://cloud.maptiler.com/tiles/landcover/)  
[MapTiler Countries dataset](/guides/map-tiling-hosting/data-hosting/maptiler-countries-dataset)

# MapTiler Landform

Source: https://docs.maptiler.com/schema/landform/

MapTiler Landform is a tileset that contains prominent topographic features—such as mountain peaks, volcanoes, saddles, cliffs, and ridgelines. Features with elevations include values in both metres and feet.

# Land Gradient, Land Gradient Dark

Source: https://docs.maptiler.com/schema-raster/land-gradient/

Land Gradient raster dataset means a gradual fade or glow around the coast and blending seamlessly into the ocean. It is generated according to the data from the [Land dataset](/schema/land/). There is also the fading as you approach the poles.

**[Inspect Land Gradient](https://cloud.maptiler.com/tiles/land-gradient/)**

**[Inspect Land Gradient Dark](https://cloud.maptiler.com/tiles/land-gradient-dark/)**

## Maps with this tileset

- [Landscape](https://cloud.maptiler.com/maps/landscape-v4/)
- [Landscape Dark](https://cloud.maptiler.com/maps/landscape-v4-dark/)
- [Landscape Vivid](https://cloud.maptiler.com/maps/landscape-v4-vivid/)

## Dataset definition

- Dataset ID: land-gradient (land-gradient-dark)
- Name: Land Gradient (Land Gradient Dark)
- Min zoom: 0
- Max zoom: 4
- Format: webp

## Related tutorials

- [Enhance coastlines with Land Gradient](/guides/map-design/land-gradient/)

# MapTiler Ocean

Source: https://docs.maptiler.com/schema/ocean/

MapTiler Ocean is a tileset that contains contour lines with minimum depth in meters, adjacent polygons with minimum depth for world oceans and seas.

# Ocean RGB

Source: https://docs.maptiler.com/schema-raster/ocean-rgb/

Bathymetry is describing the underwater depth of ocean floors. This dataset represents the values encoded into RGB. The encoding process is the same as in the [RGB Terrain by MapTiler](/schema-raster/terrain-rgb/).

You can use this data to enrich your map styles with hill shade or colored slopes but you can also use it in applications - such as elevation profiles, planning etc.

**[Inspect Ocean RGB](https://cloud.maptiler.com/tiles/ocean-rgb/)**

## Maps with this tileset

- [Ocean](https://cloud.maptiler.com/maps/ocean-v4/)

## Dataset definition

- Dataset ID: ocean-rgb
- Name: Ocean RGB
- Min zoom: 0
- Max zoom: 7
- Format: webp
- Resolution: 300 m

## Related tutorials

- [How to use MapTiler Ocean](/guides/map-tiling-hosting/data-hosting/how-to-build-an-ocean-vector-bathymetry-map-with-maptiler/)

# Global RGB bathymetry tileset

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/global-rgb-bathymetry-tileset/

Bathymetry is describing the underwater depth of ocean floors. Together with the topographical data,  a global relief model can be created.

The encoding process is the same as in the [RGB Terrain by MapTiler](/guides/map-tiling-hosting/data-hosting/rgb-terrain-by-maptiler): the elevation is split into tiles and each tile has elevations encoded in a WebP image where each pixel color (red, green, blue) can be turned into elevation using a smart formula:

`elevation = -10000 + ((R * 256 * 256 + G * 256 + B) * 0.1)`
  
The format allows storing elevations very efficiently (3 bytes vs. 4 or 8 bytes in the case of floating\-point numbers) with sufficient precision.

![mceclip1.png](./11036986748817_a08301b758.png)
  
We are already using the dataset as a hillshade layer in the ***Ocean map:***

***![mceclip2.png](./11037201968529_3aa0fcc4aa.png)***

# MapTiler Outdoor

Source: https://docs.maptiler.com/schema/outdoor/

MapTiler Outdoor is a tileset containing general layers to maps for outdoor life like hiking, cycling, cross-country skiing, and other related activities.

# Satellite

Source: https://docs.maptiler.com/schema-raster/satellite/

Satellite images are from the year 2021, many countries have then high resolution aerial imagery over it. In fact, Satellite isn't a single tileset – it is a *virtual tileset* that behaves like a single object, but it pulls the image data from several different sources under the hood.

**[Inspect Satellite](https://cloud.maptiler.com/tiles/satellite-v2/)**

## Maps with this tileset

- [Satellite Plain](https://cloud.maptiler.com/maps/satellite-v4/)
- [Satellite Hybrid](https://cloud.maptiler.com/maps/hybrid-v4/)

## Dataset definition

- Dataset ID: satellite-v2
- Name: Satellite
- Min zoom: 0
- Max zoom: 22
- Format: jpg
- Resolution: 2 m globally, up to 7.5 cm in specific areas

## Related tutorials

- [Display a satellite map](/sdk-js/examples/satellite-map/) using MapTiler SDK JS
- [Create a virtual tileset](/guides/on-prem/server/virtual-tileset/) to blend satellite with other imagery
- [Raster styling](/guides/map-design/layer-styling/#raster-styling)

# Satellite maps

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/satellite-maps/

In this article we explain what satellite data is, its benefits, and how maps from these data are created. We also show you which satellite data we host, and how you can use these different layers in your project.

About satellite imagery
-----------------------

Sometimes even with the most accurate maps you can't describe/capture the level of detail in our real world or maybe you want to do some specific analysis of a particular area.

All of this is becoming available thanks to satellite imagery.

Today there are plenty of satellites that are orbiting the globe, that’s the main reason why the availability of satellite data is increasing. 

Each of these satellites captures the globe in different *spatial, temporal, and spectral resolutions;* some of them, like **MODIS,** capture the globe in spatial resolution of *100 m/px*, others like **Sentinel\-2**  to a couple of meters (*10 m/px*)  or even centimeters *41 cm/px* from **DigitalGlobe's** **GeoEye\-1**.

![](./file_0ea4807e17.png)

In the context of temporal resolution, there are satellites that **acquire the same spot under the same angle in a couple of days or even days**.

All of these satellites, capture images in a different wavelength, which brings different information about the surveyed area, all the acquired information from specific wavelengths are stored in separate bands.

For visual purposes, like creating beautiful satellite maps, normally bands from the visible spectrum would be used like the **blue, green, and red bands**.

![](./file_6385b5e7db.png)

Available datasets
==================

The creation of a beautiful satellite map, it's a bit of alchemy, it is necessary to process a large amount of data with a decent dose of algorithmic art. This is caused by **huge variability in the quality** of satellite images, e.g. there are parts in the world where it is almost impossible to find satellite images without any artifacts in them like clouds, snow, or shadows.

And that's why we in **[MapTiler](https://www.maptiler.com/satellite/)** do this tedious work for you and bring the best satellite maps to you in our **[MapTiler](https://www.maptiler.com/maps/#hybrid//vector/3/-84.98/44.16)** or thanks to our **[MapTiler Server](https://www.maptiler.com/server/)** you can host your satellite map on your own infrastructure by yourself. On our **[MapTiler](https://www.maptiler.com/data/)** page, you can find plenty of data sources, not just satellite data but also orthophoto, different maps, and so on.

MapTiler satellite maps
=======================

Are created from data that comes from satellite **Sentinel\-2** with spatial resolution ***10 m/px,***  for coverage see the official [Revisit and Coverage](https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi/revisit-coverage) of **Sentinel\-2** mission from the **European Space Agency (ESA)*.*** In our **Cloud,** you can find in overall **4 satellite maps**. Our main **[MapTiler](https://cloud.maptiler.com/tiles/satellite/)****[Satellite](https://cloud.maptiler.com/tiles/satellite/)** map is created from **Satellite Mediumres 2020** (zoom level 0\-13\) and aerial data (zoom level 14\-19\).

Then we have separate satellite map layers from different years **[Mediumres 2016](https://cloud.maptiler.com/tiles/satellite-mediumres/)** (zoom level 0\-13\)**, [Mediuemres 2018](https://cloud.maptiler.com/tiles/satellite-mediumres-2018/)** (zoom level 0\-13\)**,** and the latest one from **Mediumres 2020** (zoom level 0\-13\)**.** The quality of the maps goes in the same order, 2016 with the least quality to 2020 with the most detailed and highest map quality.

| **Product** | **Resolution** | **Accuisition years** | **Zoom level** | **Type** | **Link to product** |
| --- | --- | --- | --- | --- | --- |
| Satellite | 10 m/px \- 20 cm/px | 2020 | 0\-19 | raster |  |
| Satellite Mediumres 2021 | 10 m/px | 2020 and 2021 | 0\-13 | raster | to be released |
| Satellite Mediumres 2018 | 10 m/px | 2017 and 2018 | 0\-13 | raste | [https://cloud.maptiler.com/tiles/satellite\-mediumres\-2018/](https://cloud.maptiler.com/tiles/satellite-mediumres-2018/) |
| Satellite Mediumres 2016 | 10 m/px | 2016 | 0\-13 | raster | [https://cloud.maptiler.com/tiles/satellite\-mediumres/](https://cloud.maptiler.com/tiles/satellite-mediumres/) |

Satellite Medium res 2016
-------------------------

It has some qualitative issues (visible clouds) mainly in **America**, **Asia,** and areas around the **equator**. This was caused by the lower temporal resolution of **Sentinel\-2** around these areas until the year 2017 when **Sentinel\-2B** was launched, which then increased the total revisit time and brought the higher quality of improved **Satellite Mediures 2018**. Both **Satellite Mediumres 2016** and **Satellite Mediumres 2018** have visible strips almost in all locations. This is caused by different time periods from which the algorithm was selecting input files for the final map creation. But in the areas like **Europe, North Africa, Middle East,** and **Australia** **Satellite Mediumres 2016** is fairly looking.

![](./file_a68df4a85b.png)

Satellite Mediumres 2018
------------------------

Thanks to the higher revisit time of twin satellites **Sentinel\-2A** and **Sentinel\-2B**, areas that did not contain clouds increased. Mountain ranges with snow cover look more real, they don’t contain that many clouds as in **Mediumres 2016\.** Most of the coastlines and islands got significant improvement in quality. **Asia** and also **America** has fewer clouds on them, but strip visibility caused by different seasons is still significantly present. Finally, **improved color toning** brought a more realistic look to the satellite map. In **Mediumres 2018** you can spot a huge improvement in quality, but we think that it was still far from perfect.

![](./file_f5b7d59408.png)

Satellite Mediumres 2021
------------------------

We improved the algorithm in a way that the artifacts like **clouds**, **snow**, and **shadows** are visible only on a fraction of areas compared to **Satellite Mediumres 2018**, also these areas are those with the least significance. We managed to **eliminate the strip visibilities** that were visible on both **Mediumres 2016** and **Mediumres 2018**, also with the better algorithmic approach of selecting the input files we brought to you a more greeny\-looking satellite map. We have also added a new **NIR (B08\) band** to the final product, for analytic purposes. Finally, with the new\-looking color toning, you can enjoy an even more realistic feel of a satellite map.

![](./file_caf139ee2b.png)

New Mediumres 2021
------------------

Let's look at some astonishing places on earth that you can find in our new **Mediumres 2020\.**

![](./file_bd6ea2346f.png)

![](./file_db1636b503.png)

![](./file_a9df03b8f6.png)

![](./file_59779cd4ff.png)

![](./file_a1f2741a8b.png)

![](./file_36d1b6538f.png)

![](./file_b8021155e1.png)

![](./file_af961551b9.png)

![](./file_53748b8f3d.png)

But there is so much more to see. Find out more at the [MapTiler page](https://www.maptiler.com/data/).

Using MapTiler satellite maps
-----------------------------

You can find our satellite map on our **[MapTiler](https://www.maptiler.com/maps/#hybrid//vector/3/-84.98/44.16)** as **[MapTiler Satellite](https://cloud.maptiler.com/tiles/satellite/)**, currently, we are using **[Mediumres 2018](https://cloud.maptiler.com/tiles/satellite-mediumres-2018/)** as the source dataset**,** but in a very short period, we would be switching it to our new **Mediumres 2021** satellite map. You can try it for **[free](https://www.maptiler.com/cloud/)**.

But if there is any reason why the cloud solution is not the right choice for you, we provide you our **[MapTiler Server](https://www.maptiler.com/server/)** solution, so you can host your **[datasets](https://www.maptiler.com/data/)** by yourself.

For more info about satellite maps don’t hesitate to visit our **[MapTiler Satellite](https://www.maptiler.com/satellite/)** page.

Useful links
------------

[MapTiler Satellite Imagery](https://cloud.maptiler.com/tiles/satellite/)  
[Satellite Mediumres 2018](https://cloud.maptiler.com/tiles/satellite-mediumres-2018/)  
[MapTiler data](https://www.maptiler.com/data/)

# Satellite Medium Res distribution

Source: https://docs.maptiler.com/guides/self-hosting/self-hosted-maps/satellite-medium-res-distribution/

The Satellite Medium Res dataset is part of the MapTiler Satellite map. You can use it via API in [MapTiler](https://cloud.maptiler.com/tiles/satellite-v2/) or download it for self\-hosting as a MapTiler data package. This page shows how to set up a sample layer from MapTiler Satellite Medium Res, downloadable from the [MapTiler data Satellite Medium Res download page.](https://www.maptiler.com/on-prem-datasets/dataset/satellite-2021/)
  
To optimize the size of this package, we prepared it in a WebP format with transparency. This format allows us to compress the size to hundreds of gigabytes (from the original terabytes of raw data).

The Satellite Medium Res consists of two layers:
------------------------------------------

MapTiler Satellite Lowres  
- around 80 MB  
- overview of the world  
- this dataset is part of the free MapTiler Server starter pack downloadable from [MapTiler data](https://data.maptiler.com/server/).

![mceclip1.png](./4413759213841_655aa84eee.png)  

[MapTiler Satellite Mediumres 2021](https://www.maptiler.com/on-prem-datasets/dataset/satellite-2021/) 
- around 500GB 
- with detailed parts of the continental area.  

![mceclip0.png](./4413753277457_3c41c93ec8.png)  

To serve this data, we recommend using the [MapTiler Server, which is available for free](https://www.maptiler.com/server/download/).  

How to combine multiple layers using Virtual Tileset JSON
---------------------------------------------------------

1\. Download and unpack the MapTiler Server starter pack to your work directory from [MapTiler Data.](https://data.maptiler.com/server/)

2\. Download the Satellite Medium Res from [MapTiler data downloads section.](https://www.maptiler.com/on-prem-datasets/dataset/satellite-2021/)

3\. Move the downloaded file (maptiler\-satellite\-2021\-XXXX.mbtiles) to your working directory.

4\. Open the text file called "*maptiler\-satellite.json*" and update the virtual source with the following lines:

``` json
"virtual_sources": [  
  {  
    "url": "maptiler-satellite-lowres",  
    "bounds": [  
      -20037508.342789, -20037508.342789244, 20037123.912877,  
      20037508.342789244  
    ],  
    "minzoom": 0,  
    "maxzoom": 6,  
    "_name": "satellite-lowres-2021"  
  },  
  {  
    "url": "maptiler-satellite-2021",  
    "bounds": [  
      -20037508.342789244, -13149614.7081853, 20037508.342789244,  
      17689362.572804667  
    ],  
    "minzoom": 3,  
    "maxzoom": 13,  
    "_name": "satellite-mediumres-2021"  
  }  
],
```

5\. Launch MapTiler Server in this folder and open the administration.

6\. Go to the Tiles section and rename the **ID** of Satellite Mediumres 2021 to **maptiler\-satellite\-2021**.

7\. Now, you can see a seamless mosaic in Tiles as **maptiler\-satellite.json**.  
  
Check out the [Virtual Tileset JSON in MapTiler Server](/guides/self-hosting/map-server/virtual-tileset-json-for-seamless-blending-of-drone-aerial-and-satellite-imagery) article to learn more.

# Satellite Night

Source: https://docs.maptiler.com/schema-raster/satellite-night/

Night satellite images from 2016 are used in dark version of Satellite maps, in lower zoom levels only.

**[Inspect Satellite Night](https://cloud.maptiler.com/tiles/satellite-night/)**

## Maps with this tileset

- [Satellite Plain Dark](https://cloud.maptiler.com/maps/satellite-v4-dark/)
- [Satellite Hybrid Dark](https://cloud.maptiler.com/maps/hybrid-v4-dark/)

## Dataset definition

- Dataset ID: satellite-night
- Name: Satellite
- Min zoom: 0
- Max zoom: 6
- Format: webp
- Resolution: cca 450 m

## Related tutorials

- [Custom night satellite image in a goble with space background](/sdk-js/examples/halo-space-night/)
- [Raster styling](/guides/map-design/layer-styling/#raster-styling)

# Terrain RGB

Source: https://docs.maptiler.com/schema-raster/terrain-rgb/

The MapTiler Terrain RGB is a composite of high-resolution DEMs (Digital Elevation Models) with global coverage, curated and processed by our geodata team. Not only you can use this data to enrich your map styles with hill shade or colored slopes, but you can also use it in applications such as elevation profiles, microwave link planning, etc. The Terrain RGB covers the land, and [Ocean RGB](/schema-raster/ocean-rgb/) covers the ocean floor. 

As the data contains the encoded elevation values directly and it’s even possible to manipulate them on the fly, there are many areas of applications. We have prepared [Hillshading](/schema-raster/hillshading/) and [Hand drawn hillshading](/schema-raster/hand-drawn-hillshading/) to be used in our maps.

**[Inspect Terrain RGB](https://cloud.maptiler.com/tiles/terrain-rgb-v2/)**

## Maps with this tileset

- [Landscape](https://cloud.maptiler.com/maps/landscape-v4/)
- [Backdrop](https://cloud.maptiler.com/maps/backdrop-v4/)
- [Topo](https://cloud.maptiler.com/maps/topo-v4/)
- [Outdoor](https://cloud.maptiler.com/maps/outdoor-v4/)
- [Winter](https://cloud.maptiler.com/maps/winter-v4/)
- [Ocean](https://cloud.maptiler.com/maps/ocean-v4/)

## Dataset definition

- Dataset ID: terrain-rgb-v2
- Name: Terrain RGB
- Min zoom: 0
- Max zoom: 14
- Format: webp
- Resolution: 30 m globally, 5 m in specific areas
- Vertical Resolution: 6 m

## Related tutorials

- [Create a globe map with 3D terrain elevation](/sdk-js/examples/globe-terrain/)
- [Display a 3D terrain map](/sdk-js/examples/3d-map/)
- [Enable/disable map terrain](/sdk-js/examples/map-terrain/)
- [Add a 3D model on terrain with three.js](/sdk-js/examples/add-3d-model-terrain/)
- [Style terrain with color relief](/guides/map-design/terrain/color-relief/)

# Terrain RGB by MapTiler

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/rgb-terrain-by-maptiler/

The MapTiler [Terrain RGB](https://cloud.maptiler.com/tiles/terrain-rgb-v2/) is a composite of high-resolution DEMs (Digital Elevation Models) with global coverage, curated and processed by our geodata team. Not only you can use this data to enrich your map styles with hill shade or colored slopes, but you can also use it in applications \- such as elevation profiles, microwave link planning, etc. The MapTiler Terrain RGB covers the land, and [MapTiler Ocean RGB](https://cloud.maptiler.com/tiles/ocean/) covers the ocean floor. 

## How it works

MapTiler Terrain RGB tileset is available up to zoom level 14\. Elevation data provides height above the sea level in meters for every single place in the world, measured for regions of approximately 30x30 meters. The elevation model is split into tiles and each tile has elevations encoded into standard RGB image format where each pixel color (red, green, blue) can be calculated into elevation.

Splitting DEM into raster tiles has all the advantages of a tiled map. The main one is low traffic for web applications because the browser loads only the tiles in the current view with appropriate resolution, and only downloads additional data when the user zooms in or pans the map.

If you open any tile from the tileset in an image viewer, you would see something like this:

![](./file_c4a29b77aa.png)

Don’t be confused by the unusual look you will see at first glance: this is not yet a final product meant for direct viewing; it's a base for adaptation.

## Application

As the data contains the encoded elevation values directly and it's even possible to manipulate them on the fly, there are many areas of applications. We list the most common examples below, including interactive JavaScript tools.

### Hillshading

By adding the elevation data to your map, you can create a nice visual shaded relief. It's even possible to change the hill shading colors and light direction, which you can do in our visual map style editor [Map Designer](https://www.maptiler.com/cloud/customize/).

DEM hillshading is already used in our [Outdoor map](https://www.maptiler.com/maps/#style=outdoor&mode=2d&position=5.97/46.09/8.67), which is available for free under [MapTiler maps](https://cloud.maptiler.com/maps/). See our interactive [hillshading example](https://www.maptiler.com/tools/hillshading/#7/46.165/9.459).

[![](./file_57f29c4d15.png)](https://www.maptiler.com/tools/hillshading/#7/46.165/9.459)

MapTiler also provides the [Hillshading tileset](https://cloud.maptiler.com/tiles/hillshade/). However, you might want to use the RGB terrain tileset because it covers a bigger area of the Earth and allows you to customize the color of the hillshade. 

### Hypsometry

Hypsometry uses the measurement elevation and depth relative to mean sea level. The traditional color model used mostly for the relief model in geographical maps contains green color for lowlands, yellow for highlands, brown for mountains, and a different tone of blue for bathymetry. See our interactive [flood simulator](https://www.maptiler.com/tools/hypsometry/#8/46.16/9.46) as an application example.

![](./file_ce4d6cefd9.png)

### Terrain profiles

Terrain profiles have a wide range of applications. You can use them for trip planning, terrain analysis, microwave links planning, pipelines, and electric wires planning, etc. You can use MapTiler SDK JS to implement an [elevation profile control](/sdk-js/modules/elevation-profile/) like this:

![](./elevation-profile-control.png)

# Terrain 3D (Cesium quantized mesh)

Source: https://docs.maptiler.com/schema-raster/terrain-3d/

The tiles contain elevation data encoded into vector TIN polygons in format for the Cesium JavaScript library. The data source is using EGM96 datum.

Check out the [Cesium tutorial](/cesium/) showing how to create a map and display it on a web page using MapTiler data.

**[Inspect Terrain 3D](https://cloud.maptiler.com/tiles/terrain-quantized-mesh-v2/)**

## Dataset definition

- Dataset ID: terrain-quantized-mesh-v2
- Name: Terrain 3D - Cesium quantized mesh
- Min zoom: 0
- Max zoom: 15
- CRS: WGS 84 (EPSG:4326)
- Format: quantized-mesh-1.0

## Related tutorials

- [Cesium JS with MapTiler maps](/cesium/)
- [Unreal Engine with MapTiler real-world 3D content](/unreal/)
- [Unity with MapTiler real-world 3D content](/unity/)

# OpenMapTiles Planet

Source: https://docs.maptiler.com/schema/omt-planet/

OpenMapTiles Planet is a tileset containing general layers with topographic information based on OSM Data. It is built to use as a general context of a map for daily life or as a base of visualization for your data.

# OpenStreetMap vector data

Source: https://docs.maptiler.com/guides/self-hosting/self-hosted-maps/openstreetmap-vector-data/

Vector data served on MapTiler and MapTiler data comes mostly from OpenStreetMap (OSM, [www.openstreetmap.org](https://www.openstreetmap.org/)). OpenStreetMap is a collaborative project that aims to create freely available geographic data. 

The schema for the OpenStreetMap vector tiles can be found at .   
OpenMapTiles schema was created to serve as a base map and additional data can be rendered separately and added to the MapTiler service.

Missing or incorrect data
-------------------------

If you are missing any information in the maps or find anything wrong in the map, you can suggest an edit to the data in the OSM database editor: [https://learnosm.org/en/beginner/id\-editor/](https://learnosm.org/en/beginner/id-editor/).  
When the data is correct in OSM and incorrect in MapTiler, please contact MapTiler at [MapTiler Support](/support/requests/). The rule of thumb is that fixing the data in OSM will automatically fix the data in MapTiler.

Updates
-------

We regularly update our maps on MapTiler and in MapTiler data. OpenStreetMap vector tiles are updated weekly, with the refreshed tileset available Monday morning containing data from the previous week. 

Useful links
------------

[MapTiler Planet Schema](https://docs.maptiler.com/schema/planet/)

# MapTiler Planet Lite

Source: https://docs.maptiler.com/schema/planet-lite/

MapTiler Planet Lite is a tileset containing general layers containing topographic information for a copyright-free map of the entire world up to zoom 10.

# MapTiler Planet v3

Source: https://docs.maptiler.com/schema/planet/

MapTiler Planet v3 is a tileset containing general layers containing topographic information. It is built to use as a general context of a map for daily life or as a base of visualization for your data.

# Origin of the MapTiler Planet data

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-hosting/origin-of-the-maptiler-planet-data/

MapTiler Planet is compiled from many data sources. Using local data sources increases the quality of the whole dataset and brings the base maps to their best for our customers.

Natural Earth
-------------

Natural Earth is a public dataset at 1:10 m, 1:50 m, and 1:110 million scales. Due to its small scale, the detail and quality of these vector data are perfect for showing the entire planet up to zoom 6\. This dataset contains cultural vector data \- such as countries, administrative divisions, urban polygons, or water boundaries \- and physical vector data \- such as the ocean, rivers, lakes minor islands, or glaciated areas. We always use the latest version of Natural Earth, currently version 5 (2023\-12\-19\).

OpenStreetMap
-------------

[OpenStreetMap data](https://osm.org/) is the main data source of our maps. OSM is a collaborative project to create a free editable map of the world and offers street\-scale quality data with regular updates. Every day OSM data receive millions of updates from community contributors.

To avoid having low\-quality or even misleading edits and inconsistency in data, we collaborate with our partners and use additional tools and technologies on top of OSM to drive a higher level of detail, quality, and accuracy on the map. Our data from OSM are updated twice a month after they’ve been scanned for vandalism, topology errors, and inconsistency.  

![](./4410415506321_f57b6a56d3.gif)![](./4410415506961_5c04846ae8.gif)

Building footprints
-------------------

The building footprints are a joint product of [Microsoft Building Footprints](https://www.microsoft.com/en-us/maps/building-footprints), [Esri Community Maps Program](https://communitymaps.arcgis.com/) and [Google Open Buildings](https://sites.research.google/open-buildings/) dataset. They combine the positional accuracy of Microsoft’s footprint data creation and authoritative tags such as name and address provided by authoritative sources in collaboration with Esri. Google Open buildings use a deep learning model that was trained to determine the footprints of buildings from high resolution satellite imagery. This causes one of the biggest steps forward in our maps. Check out the difference between OpenMapTiles and MapTiler Planet in the US, Canada, Australia, parts of Central and South America, as well as parts of Africa and Asia. The building footprint is also updated on bi\-weekly basis.

![](./4410415507217_583bd05e72.gif)![](./4410415507729_fd2029af25.gif)

| **Country** | **MT Planet (2023\-11\-12\)** | **OMT Planet (2024\-01\-01\)** |
| --- | --- | --- |
| Argentina | 27 247 549 | 940 478 |
| Australia | 12 198 751 | 2 751 705 |
| Bolivia | 7 373 737 | 361 227 |
| Brazil | 116 340 933 | 9 100 222 |
| Canada | 13 268 539 | 6 352 601 |
| Chile | 10 211 127 | 674 900 |
| Ethiopia | 34 219 748 | 1 051 211 |
| India | 431 933 620 | 12 963 324 |
| Indonesia | 101 919 944 | 39 805 929 |
| Japan | 68 748 109 | 20 742 530 |
| Kenya | 25 617 907 | 5 883 408 |
| Malaysia | 9 104 932 | 1 051 688 |
| Mexico | 65 404 400 | 2 767 762 |
| Nigeria | 62 904 923 | 11 321 420 |
| Philippines | 29 978 166 | 10 342 332 |
| Saudi Arabia | 6 024 823 | 135 271 |
| Tanzania | 29 799 157 | 14 342 154 |
| Thailand | 44 741 203 | 984 362 |
| Uganda | 22 263 584 | 8 086 615 |
| USA | 152 005 530 | 62 577 466 |
| Vietnam | 46 494 678 | 853 076 |
| **Planet** | **2 411 240 973** | **590 279 161** |

GSI buildings
-------------

Thanks to our partnership with a Japanese company [Mierune](https://www.mierune.co.jp/aboutus), we got access to a dataset from The Geospatial Information Authority of Japan (GSI). This means that MapTiler users now can see building footprints even in the tiniest mountain village in Japan. GSI updates its data every three months.

![](./4410407980945_d5214bd11c.gif)

Global landcover
----------------

Global landcover is a derivated product from imagery made by ESA as a part of the ESA Climate Change Initiative and in particular its Land Cover project. ESA Landcover v1\.1 is processed and vectorized into a data source which we use in our MapTiler Planet for global landcover from zoom 0 to zoom 9\. Data have six classes: crop, forest, grass, scrub, snow, tree.

USGS landcover
--------------

For woodland in the USA, we use a data source produced by The United States Geological Survey (USGS). Land Cover \- Woodland is a dataset that gathers woodland datasets from each of the states with irregular updates according to USGS standards. The latest version is from June 2021\.

![](./4410407982865_637818e265.gif)

Canadian landcover
------------------

Canadian open data offer the Land Features dataset as part of the CanVec series. The land features of the CanVec series contain landscape features of Canada such as islands, shoreline delineation, wooded areas, saturated soil features, and landform features (esker, sand, etc.). These data are further processed and reclassified to fit in our [schema](https://docs.maptiler.com/schema/planet/). It results in a very detailed land cover, even in the most remote parts of Canada. The currently used dataset was published in March 2019\.

![](./4410407983249_233544eaab.gif)![](./4410415509777_3ed6757d6c.gif)

Glaciers
--------

For polygons of glaciers we use open data from the GLIMS project. GLIMS (Global Land Ice Measurements from Space) is an initiative designed to monitor the world's glaciers primarily using data from optical satellite instruments.

![Peek_2022-11-07_08-17.gif](./10446720022545_fbbdfde791.gif)

![Peek_2022-11-07_08-10.gif](./10446774238865_a8fe3d5ba0.gif)

Useful links
------------

[**MapTiler Planet Schema**](https://docs.maptiler.com/schema/planet/)

[Natural Earth Data](https://www.naturalearthdata.com/)  
[ArcGIS Community Maps](https://communitymaps.arcgis.com/)  
[Building Footprints](https://www.microsoft.com/en-us/maps/building-footprints)  
[Japan GSI](https://www.gsi.go.jp/ENGLISH/)  
[Open Street Map](https://www.openstreetmap.org)  
[GLIMS](https://www.glims.org/)

# Weather data

Source: https://docs.maptiler.com/schema-raster/weather/

MapTiler provides data for Weather visualizations.

For details, see the [Temperature layer](/sdk-js/modules/weather/api/temperature/) reference and check the [MapTiler Weather presentation](https://www.maptiler.com/weather/).

## Related tutorials

- [How to make weather maps](/guides/maps-apis/weather/how-to-make-weather-maps/)
- [Weather temperature layer](/sdk-js/examples/weather-temperature/)
- [Weather wind and temperature layer](/sdk-js/examples/weather-wind-temperature/)
- [Weather layer with a custom color blind ramp](/sdk-js/examples/weather-temperature-color-ramp/)
- [Weather layer switcher](/sdk-js/examples/weather-layer-switcher/)

# UK OS Open Zoomstack

Source: https://docs.maptiler.com/schema/uk-openzoomstack/

Ordnance Survey's OS Open Zoomstack is an open vector basemap showing coverage of Great Britain from a national level, right down to street detail.

# NL Cartiqo

Source: https://docs.maptiler.com/schema/nl-cartiqo/

Cartiqo is a Vector Tile product based on open source geo data of the Netherlands. It provides a full and detailed map of the Netherlands customizable to your own likes.

# CH Swisstopo LeichteBasiskarte

Source: https://docs.maptiler.com/schema/ch-swisstopo-lbm/

CH Swisstopo Leichte Basiskarte tileset is a tileset showcasing all SwissTopo layers.

# JP GSI

Source: https://docs.maptiler.com/schema/jp-gsi/

JP GSI is a tileset that contains vector tiles provided by the Geospatial Information Authority of Japan.

# France Cadastre

Source: https://docs.maptiler.com/schema/fr-cadastre/

France Cadastral is a tileset containing real estate cadastre information for France. Design of tileset containing the most useful information like parcel, buildings and their numbers, or addresses. Tileset provides the most precise geometry (low scale mapping) with additional information for interconnecting with authorities. Nevertheless, this Tileset cannot be used for any legal action and in any legal case please contact the competent authority.

# GL Style Specification

Source: https://docs.maptiler.com/gl-style-specification/

A GL style is a document that defines the visual appearance of a map: what data to draw, the order to draw it in, and how to style the data when drawing it. A style document is a [JSON](https://www.json.org/) object with specific root level and nested properties. This specification defines and describes these properties.

The intended audience of this specification includes:

- Advanced designers and cartographers who want to write styles by hand.
- Developers using style-related features of [MapTiler SDK JS](/sdk-js/) or the Mobile SDK for [iOS](/mobile-sdk/ios/) and [Android](/mobile-sdk/android/).
- Authors of software that generates or processes MapLibre styles.

## Style document structure

A GL style consists of a set of [root properties](root), some of which describe a single global property, and some of which contain nested properties. Some root properties, like [`version`](root/#version), [`name`](root/#name), and [`metadata`](root/#metadata), don't have any influence over the appearance or behavior of your map, but provide important descriptive information related to your map. Others, like [`layers`](layers) and [`sources`](sources), are critical and determine which map features will appear on your map and what they will look like. Some properties, like [`center`](root/#center), [`zoom`](root/#zoom), [`pitch`](root/#pitch), and [`bearing`](root/#bearing), provide the map renderer with a set of defaults to be used when initially displaying the map.

# Root

Source: https://docs.maptiler.com/gl-style-specification/root/

Root level properties of a GL style specify the map's layers, tile sources and other resources, and default values for the initial camera position when not specified elsewhere.

```json
{
    "version": 8,
    "name": "Streets",
    "sprite": "https://api.maptiler.com/maps//sprite",
    "glyphs": "https://api.maptiler.com/fonts/{fontstack}/{range}.pbf?key=",
    "sources": {...},
    "layers": [...]
}
```

## bearing

Optional [number](../types/#number). Units in degrees. Defaults to `0`.

Default bearing, in degrees. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up. This value will be used only if the map has not been positioned by other means (e.g. map options or user interaction).

```json
"bearing": 29
```

## center

Optional [array](../types/#array) of [numbers](../types/#number).

Default map center in longitude and latitude. The style center will be used only if the map has not been positioned by other means (e.g. map options or user interaction).

```json
"center": [
  -73.9749,
  40.7736
]
```

## glyphs

Optional [string](../types/#string).

A URL template for loading signed-distance-field glyph sets in PBF format. The URL must include `{fontstack}` and `{range}` tokens. This property is required if any layer uses the `text-field` layout property. The URL must be absolute, containing the [scheme, authority and path components](https://en.wikipedia.org/wiki/URL#Syntax).

```json
"glyphs": "https://api.maptiler.com/fonts/{fontstack}/{range}.pbf?key="
```

## layers

Required [array](../types/#array) of [layers](../layers).

Layers will be drawn in the order of this array.

```json
"layers": [
  {
    "id": "water",
    "source": "openmaptiles",
    "source-layer": "water",
    "type": "fill",
    "paint": {
      "fill-color": "#00ffff"
    }
  }
]
```

## light

Optional [light](../light).

The global light source.

```json
"light": {
  "anchor": "viewport",
  "color": "white",
  "intensity": 0.4
}
```

## sky

Optional [sky](../sky/).

The map's sky configuration.

> [!NOTE]
> This definition is still experimental and is under development in maplibre-gl-js.

```json
"sky": {
    "sky-color": "#199EF3",
    "sky-horizon-blend": 0.5,
    "horizon-color": "#ffffff",
    "horizon-fog-blend": 0.5,
    "fog-color": "#0000ff",
    "fog-ground-blend": 0.5,
    "atmosphere-blend": [
        "interpolate",
        ["linear"],
        ["zoom"],
        0,
        1,
        10,
        1,
        12,
        0
    ]
}
```

## metadata

Optional.

Arbitrary properties useful to track with the stylesheet, but do not influence rendering. Properties should be prefixed to avoid collisions, like 'openmaptiles:'.

## name

Optional [string](../types/#string).

A human-readable name for the style.

```json
"name": "Bright"
```

## pitch

Optional [number](../types/#number). Units in degrees. Defaults to `0`.

Default pitch, in degrees. Zero is perpendicular to the surface, for a look straight down at the map, while a greater value like 60 looks ahead towards the horizon. The style pitch will be used only if the map has not been positioned by other means (e.g. map options or user interaction).

```json
"pitch": 50
```

## sources

Required object with [source](../sources) values.

Data source specifications.

```json
"sources": {
    "openmaptiles": {
        "url": "https://api.maptiler.com/tiles/v3/tiles.json?key=",
        "type": "vector"
    }
}
```

## sprite

Optional [string](../types/#string).

A base URL for retrieving the sprite image and metadata. The extensions `.png`, `.json` and scale factor `@2x.png` will be automatically appended. This property is required if any layer uses the `background-pattern`, `fill-pattern`, `line-pattern`, `fill-extrusion-pattern`, or `icon-image` properties. The URL must be absolute, containing the [scheme, authority and path components](https://en.wikipedia.org/wiki/URL#Syntax).

```json
"sprite": "https://api.maptiler.com/maps//sprite"
```

## transition

Optional [transition](../transition).

A global transition definition to use as a default across properties, to be used for timing transitions between one value and the next when no property-specific transition is set. Collision-based symbol fading is controlled independently of the style's `transition` property.

```json
"transition": {
  "duration": 300,
  "delay": 0
}
```

## version

Required [enum](../types/#enum).

Style specification version number. Must be 8.

```json
"version": 8
```

## zoom

Optional [number](../types/#number).

Default zoom level. The style zoom will be used only if the map has not been positioned by other means (e.g. map options or user interaction).

```json
"zoom": 12.5
```

# Light

Source: https://docs.maptiler.com/gl-style-specification/light/

A style's `light` property provides a global light source for that style. Since this property is the light used to light extruded features, you will only see visible changes to your map style when modifying this property if you are using extrusions.

```json
"light": {
  "anchor": "viewport",
  "color": "white",
  "intensity": 0.4
}
```

## anchor

Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"viewport"`.

Whether extruded geometries are lit relative to the map or viewport.

`"map"`:

The position of the light source is aligned to the rotation of the map.

`"viewport"`:

The position of the light source is aligned to the rotation of the viewport.

```json
"anchor": "map"
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

## color

Optional [color](../types/#color). Defaults to `"#ffffff"`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Color tint for lighting extruded geometries.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

## intensity

Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `0.5`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Intensity of lighting (on a scale from 0 to 1). Higher numbers will present as more extreme contrast.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

## position

Optional [array](../types/#array) of [numbers](../types/#number). Defaults to `[1.15,210,30]`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Position of the light source relative to lit (extruded) geometries, in \[r radial coordinate, a azimuthal angle, p polar angle\] where r indicates the distance from the center of the base of an object to its light, a indicates the position of the light relative to 0° (0° when `light.anchor` is set to `viewport` corresponds to the top of the viewport, or 0° when `light.anchor` is set to `map` corresponds to due north, and degrees proceed clockwise), and p indicates the height of the light (from 0°, directly above, to 180°, directly below).

```json
"position": [
  1.5,
  90,
  80
]
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

# Sources

Source: https://docs.maptiler.com/gl-style-specification/sources/

Sources state which data the map should display. Specify the type of source with the `"type"` property, which must be one of `vector, raster, raster-dem, geojson, image, video.` Adding a source isn't enough to make data appear on the map because sources don't contain styling details like color or width. Layers refer to a source and give it a visual representation. This makes it possible to style the same source in different ways, like differentiating between types of roads in a highways layer.

Tiled sources (vector and raster) must specify their details according to the [TileJSON specification](https://github.com/mapbox/tilejson-spec). There are several ways to do so:

- By supplying TileJSON properties such as `"tiles"`, `"minzoom"`, and `"maxzoom"` directly in the source:

```json
"streets": {
    "type": "vector",
    "tiles": [
        "http://a.example.com/tiles/{z}/{x}/{y}.pbf",
        "http://b.example.com/tiles/{z}/{x}/{y}.pbf"
    ],
    "maxzoom": 14
}
```

- By providing a `"url"` to a TileJSON resource:

```json
"streets": {
    "type": "vector",
    "url": "http://api.example.com/tilejson.json"
}
```

- By providing a URL to a WMS server that supports EPSG:3857 (or EPSG:900913) as a source of tiled data. The server URL should contain a `"{bbox-epsg-3857}"` replacement token to supply the `bbox` parameter.

```json
"wms-imagery": {
    "type": "raster",
    "tiles": [
        "http://a.example.com/wms?bbox={bbox-epsg-3857}&format=image/png&service=WMS&version=1.1.1&request=GetMap&srs=EPSG:3857&width=256&height=256&layers=example"
    ],
    "tileSize": 256
}
```

## vector

A vector tile source. Tiles must be in [Vector Tile format](https://www.maptiler.com/news/2019/02/what-are-vector-tiles-and-why-you-should-care/). All geometric coordinates in vector tiles must be between `-1 * extent` and `(extent * 2) - 1` inclusive. All layers that use a vector source must specify a [`"source-layer"`](../layers/#source-layer) value. For vector tiles hosted by MapTiler, the `"url"` value should be of the form  `https://api.maptiler.com/tiles/{tilesetid}/tiles.json?key="`.

```json
"Streets": {
    "type": "vector",
    "url": "https://api.maptiler.com/tiles/v3/tiles.json?key="
}
```

### attribution

Optional [string](../types/#string)

Contains an attribution to be displayed when the map is shown to a user.

### bounds

Optional [array](../types/#array) of [numbers](../types/#number). Defaults to `[-180,-85.051129,180,85.051129]`.

An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: `[sw.lng, sw.lat, ne.lng, ne.lat]`. When this property is included in a source, no tiles outside of the given bounds are requested by MapTiler SDK JS.

### maxzoom

Optional [number](../types/#number). Defaults to `22`.

Maximum zoom level for which tiles are available, as in the TileJSON spec. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.

### minzoom

Optional [number](../types/#number). Defaults to `0`.

Minimum zoom level for which tiles are available, as in the TileJSON spec.

### promoteId

Optional [promoteId](../types/#promoteid).

A property to use as a feature id (for feature state). Either a property name, or an object of the form `{: }`. If specified as a string for a vector tile source, the same property is used across all its source layers.

### scheme

Optional [enum](../types/#enum). One of `"xyz"`, `"tms"`. Defaults to `"xyz"`.

Influences the y direction of the tile coordinates. The global-mercator (aka Spherical Mercator) profile is assumed.

`"xyz"`:

Slippy map tilenames scheme.

`"tms"`:

OSGeo spec scheme.

### tiles

Optional [array](../types/#array) of [strings](../types/#string).

An array of one or more tile source URLs, as in the TileJSON spec.

### url

Optional [string](../types/#string).

A URL to a TileJSON resource. Supported protocols are `http:`, `https:`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## raster

A raster tile source. For raster tiles hosted by MapTiler, the `"url"` value should be of the form `https://api.maptiler.com/tiles/[tilesetid]/tiles.json?key=`.

```json
"satellite": {
    "type": "raster",
    "url": "https://api.maptiler.com/tiles/satellite/tiles.json?key=",
    "tileSize": 256
}
```

### attribution

Optional [string](../types/#string).

Contains an attribution to be displayed when the map is shown to a user.

### bounds

Optional [array](../types/#array) of [numbers](../types/#number). Defaults to `[-180,-85.051129,180,85.051129]`.

An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: `[sw.lng, sw.lat, ne.lng, ne.lat]`. When this property is included in a source, no tiles outside of the given bounds are requested by MapTiler SDK JS.

### maxzoom

Optional [number](../types/#number). Defaults to `22`.

Maximum zoom level for which tiles are available, as in the TileJSON spec. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.

### minzoom

Optional [number](../types/#number). Defaults to `0`.

Minimum zoom level for which tiles are available, as in the TileJSON spec.

### scheme

Optional [enum](../types/#enum). One of `"xyz"`, `"tms"`. Defaults to `"xyz"`.

Influences the y direction of the tile coordinates. The global-mercator (aka Spherical Mercator) profile is assumed.

`"xyz"`:

Slippy map tilenames scheme.

`"tms"`:

OSGeo spec scheme.

### tileSize

Optional [number](../types/#number). Units in pixels. Defaults to `512`.

The minimum visual size to display tiles for this layer. Only configurable for raster layers.

### tiles

Optional [array](../types/#array) of [strings](../types/#string).

An array of one or more tile source URLs, as in the TileJSON spec.

### url

Optional [string](../types/#string).

A URL to a TileJSON resource. Supported protocols are `http:`, `https:`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## raster-dem

A raster DEM source. Only supports [Terrain RGB](/guides/map-tiling-hosting/data-hosting/rgb-terrain-by-maptiler)

```json
"terrain-rgb": {
    "type": "raster-dem",
    "url": "https://api.maptiler.com/tiles/terrain-rgb-v2/tiles.json?key="
}
```

### attribution

Optional [string](../types/#string).

Contains an attribution to be displayed when the map is shown to a user.

### bounds

Optional [array](../types/#array) of [numbers](../types/#number). Defaults to `[-180,-85.051129,180,85.051129]`.

An array containing the longitude and latitude of the southwest and northeast corners of the source's bounding box in the following order: `[sw.lng, sw.lat, ne.lng, ne.lat]`. When this property is included in a source, no tiles outside of the given bounds are requested by MapTiler SDK JS.

### encoding

Optional [enum](../types/#enum). One of `"terrarium"`, `"mapbox"`. Defaults to `"mapbox"`.

The encoding used by this source. Terrain RGB is used by default

`"terrarium"`:

Terrarium format PNG tiles. See [https://aws.amazon.com/es/public-datasets/terrain/](https://aws.amazon.com/es/public-datasets/terrain/) for more info.

`"mapbox"`:

Terrain RGB tiles. See [RGB Terrain by MapTiler](/guides/map-tiling-hosting/data-hosting/rgb-terrain-by-maptiler) for more info.

### maxzoom

Optional [number](../types/#number). Defaults to `22`.

Maximum zoom level for which tiles are available, as in the TileJSON spec. Data from tiles at the maxzoom are used when displaying the map at higher zoom levels.

### minzoom

Optional [number](../types/#number). Defaults to `0`.

Minimum zoom level for which tiles are available, as in the TileJSON spec.

### tileSize

Optional [number](../types/#number). Units in pixels. Defaults to `512`.

The minimum visual size to display tiles for this layer. Only configurable for raster layers.

### tiles

Optional [array](../types/#array) of [strings](../types/#string).

An array of one or more tile source URLs, as in the TileJSON spec.

### url

Optional [string](../types/#string).

A URL to a TileJSON resource. Supported protocols are `http:`, `https:`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | Not yet supported | Not yet supported | Not yet supported |

## geojson

A [GeoJSON](https://geojson.org/) source. Data must be provided via a `"data"` property, whose value can be a URL or inline GeoJSON.

```json
"geojson-marker": {
    "type": "geojson",
    "data": {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [16.62662018, 49.2125578]
        },
        "properties": {
            "title": "MapTiler",
            "marker-symbol": "monument"
        }
    }
}
```

This example of a GeoJSON source refers to an external GeoJSON document via its URL. The GeoJSON document must be on the same domain or accessible using [CORS](https://enable-cors.org/).

```json
"geojson-lines": {
    "type": "geojson",
    "data": "./lines.geojson"
}
```

### attribution

Optional [string](../types/#string).

Contains an attribution to be displayed when the map is shown to a user.

### buffer

Optional [number](../types/#number) between `0` and `512` inclusive. Defaults to `128`.

Size of the tile buffer on each side. A value of 0 produces no buffer. A value of 512 produces a buffer as wide as the tile itself. Larger values produce fewer rendering artifacts near tile edges and slower performance.

### cluster

Optional [boolean](../types/#boolean). Defaults to `false`.

If the data is a collection of point features, setting this to true clusters the points by radius into groups. Cluster groups become new `Point` features in the source with additional properties:

- `cluster` Is `true` if the point is a cluster
- `cluster_id` A unqiue id for the cluster to be used in conjunction with the cluster inspection methods
- `point_count` Number of original points grouped into this cluster
- `point_count_abbreviated` An abbreviated point count

### clusterMaxZoom

Optional [number](../types/#number).

Max zoom on which to cluster points if clustering is enabled. Defaults to one zoom less than maxzoom (so that last zoom features are not clustered).

### clusterProperties

Optional.

An object defining custom properties on the generated clusters if clustering is enabled, aggregating values from clustered points. Has the form `{"property_name": [operator, map_expression]}`. `operator` is any expression function that accepts at least 2 operands (e.g. `"+"` or `"max"`) — it accumulates the property value from clusters/points the cluster contains; `map_expression` produces the value of a single point.

Example: `{"sum": ["+", ["get", "scalerank"]]}`.

For more advanced use cases, in place of `operator`, you can use a custom reduce expression that references a special `["accumulated"]` value, e.g.: `{"sum": [["+", ["accumulated"], ["get", "sum"]], ["get", "scalerank"]]}`

### clusterRadius

Optional [number](../types/#number) greater than or equal to `0`. Defaults to `50`.

Radius of each cluster if clustering is enabled. A value of 512 indicates a radius equal to the width of a tile.

### data

Optional.

A URL to a GeoJSON file, or inline GeoJSON.

### generateId

Optional [boolean](../types/#boolean). Defaults to `false`.

Whether to generate ids for the geojson features. When enabled, the `feature.id` property will be auto assigned based on its index in the `features` array, over-writing any previous values.

### lineMetrics

Optional [boolean](../types/#boolean). Defaults to `false`.

Whether to calculate line distance metrics. This is required for line layers that specify `line-gradient` values.

### maxzoom

Optional [number](../types/#number). Defaults to `18`.

Maximum zoom level at which to create vector tiles (higher means greater detail at high zoom levels).

### promoteId

Optional [promoteId](../types/#promoteid).

A property to use as a feature id (for feature state). Either a property name, or an object of the form `{: }`.

### tolerance

Optional [number](../types/#number). Defaults to `0.375`.

Douglas-Peucker simplification tolerance (higher means simpler geometries and faster performance).

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| clustering | >= 0.14.0 | >= 4.2.0 | >= 3.4.0 | >= 0.3.0 |
| line distance metrics | >= 0.45.0 | >= 6.5.0 | >= 4.4.0 | >= 0.11.0 |

## image

An image source. The `"url"` value contains the image location.

The `"coordinates"` array contains `[longitude, latitude]` pairs for the image corners listed in clockwise order: top left, top right, bottom right, bottom left.

```json
"image": {
    "type": "image",
    "url": "https://docs.maptiler.com/sdk-js/raster-layer/img/aerial_wgs84.png",
    "coordinates": [
        [4.639663696289062, 50.900867668253724],
        [4.642066955566406, 50.900867668253724],
        [4.642066955566406, 50.89935199434383],
        [4.639663696289062, 50.89935199434383]
    ]
}
```

### coordinates

Required [array](../types/#array) of [array](../types/#array) of [numbers](../types/#number).

Corners of image specified in longitude, latitude pairs.

### url

Required [string](../types/#string).

URL that points to an image.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

## video

A video source. The `"urls"` value is an array. For each URL in the array, a video element [source](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source) will be created. To support the video across browsers, supply URLs in multiple formats.

The `"coordinates"` array contains `[longitude, latitude]` pairs for the video corners listed in clockwise order: top left, top right, bottom right, bottom left.

```json
"video": {
    "type": "video",
    "urls": [
        "https://static-assets.mapbox.com/mapbox-gl-js/drone.mp4",
        "https://static-assets.mapbox.com/mapbox-gl-js/drone.webm"
    ],
    "coordinates": [
        [-122.51596391201019, 37.56238816766053],
        [-122.51467645168304, 37.56410183312965],
        [-122.51309394836426, 37.563391708549425],
        [-122.51423120498657, 37.56161849366671]
    ]
}
```

### coordinates

Required [array](../types/#array) of [array](../types/#array) of [numbers](../types/#number).

Corners of video specified in longitude, latitude pairs.

### urls

Required [array](../types/#array) of [strings](../types/#string).

URLs to video content in order of preferred format.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | Not yet supported | Not yet supported | Not yet supported |

# Sprite

Source: https://docs.maptiler.com/gl-style-specification/sprite/

Loading a `sprite` can be done using the optional sprite property at the root level of a MapTiler style.

A style's `sprite` property supplies a template for loading small images to use in rendering `background-pattern`, `fill-pattern`, `line-pattern`,`fill-extrusion-pattern` and `icon-image` style properties.

## Usage

You need to pass an URL where the sprite can be loaded from.

```json
"sprite": "https://api.maptiler.com/maps//sprite"
```

This will load both an image by appending `.png` and the metadata about the sprite needed for loading by appending `.json`. For example:

- [https://api.maptiler.com/maps//sprite.png](https://api.maptiler.com/maps//sprite.png)
- [https://api.maptiler.com/maps//sprite.json](https://api.maptiler.com/maps//sprite.json)

Check out the details about the exact requirements on the format of these files is provided in the [Sprite Source Format](#sprite-source-format) section.

When a sprite is provided, you can refer to the images in the sprite in other parts of the style sheet. For example, when creating a symbol layer with the layout property `"icon-image": "museum"`. Or with the tokenized value `"icon-image": "{icon}"` and vector tile features with an `icon` property with the value `museum`.

### Multiple Sprite Sources

You can also supply an array of `{ id: ..., url: ... }` pairs to load multiple sprites:

```json
"sprite": [
  {
    id: 'outdoor',
    url: 'https://api.maptiler.com/maps//sprite'
  },
  {
    id: 'winter',
    url: 'https://api.maptiler.com/maps//sprite'
  },
  {
    id: 'default',
    url: 'https://api.maptiler.com/maps//sprite'
  }
]
```

As you can see, each sprite has an id. All images contained within a sprite also have an id. When using multiple sprites, you need to prefix the id of the image with the id of the sprite it is contained within, followed by a colon. For example, to reference the `campsite` image on the roadsigns sprite, you would need to use `outdoor:campsite`.

The sprite with id `default` is special in that you do not need to prefix the images contained within it. For example, to reference the image with id `airport` in the default sprite above, you can simply use `airport`.

> [!NOTE]
> Currently, the [Map Designer tool](https://cloud.maptiler.com/maps/editor?) doesn't support multiple sprites. To add multiple sprites to your map, JavaScript code is required.
> 
> ```js
> const style = map.getStyle();
> style.sprite = [
> {
> id: "outdoor",
> url: "https://api.maptiler.com/maps//sprite",
> },
> {
> id: "default",
> url: "https://api.maptiler.com/maps//sprite",
> },
> ];
> map.setStyle(style);
> ```
> 

## Sprite Source Format

A valid sprite source must supply two types of files:

- An **image file**, which is a PNG images containing the sprite data.

- An **index file**, which is a JSON document containing a description of each image contained in the sprite. The content of this file must be a JSON object whose keys form identifiers to be used as the values of the above style properties, and whose values are objects describing the dimensions (`width` and `height` properties) and pixel ratio (`pixelRatio`) of the image and its location within the sprite (`x` and `y`). For example, a sprite containing a single image might have the following index file contents:

```json
{
  "poi": {
    "width": 32,
    "height": 32,
    "x": 0,
    "y": 0,
    "pixelRatio": 1
  }
}
```

### Optional Properties

Apart from the required `width`, `height`, `x`, and `y` properties, the following optional properties are supported:

- `content`: An array of four numbers, with the first two specifying the left, top corner, and the last two specifying the right, bottom corner. If present, and if the icon uses [`icon-text-fit`](../layers/#icon-text-fit), the symbol's text will be fit inside the content box.
- `stretchX`: An array of two-element arrays, consisting of two numbers that represent the _from_ position and the _to_ position of areas that can be stretched.
- `stretchY`: Same as `stretchX`, but for the vertical dimension.
- `sdf`: If `true` then the image is handled as a signed-distance field (SDF) and its color can be set at runtime using the `icon-color` and `icon-halo-color` properties. Defaults to `false`.
- `textFitWidth`: TextFit enum of the value stretchOrShrink (or undefined), stretchOnly, proportional describing the behavior, horizontally, when scaling a sprite due to `'icon-text-fit': 'both'`.
- `textFitHeight`: Same as `textFitWidth` except vertically.

#### Stretch Properties

The following image gives a bit more information regarding the stretch properties:

```json
{
    "sheild": {
        "width": 25,
        "height": 30,
        "x": 0,
        "y": 0,
        "stretchX": [[5, 10], [15, 20]]
        "stretchY": [[5, 20]]
        "pixelRatio": 1
    }
}
```

The red highlighted part is where the stretch will occur over the Y axis and the blue highlight is for the X axis.

![Popup sprite stretch example](/gl-style-specification/assets/img/popup_debug.png)

#### Text Fit Properties

The properties `textFitWidth` and `textFitHeight` alter how a sprite's content rectangle maps to its contents when scaling a sprite. These properties are defined with the enum TextFit which may have the following values:

- `stretchOrShrink` (or omitted)
- `stretchOnly`
- `proportional`

The primary use cases of interest are:

1. Both properties are undefined or stretchOrShrink

   The content rectangle scales precisely to contain its contents.

1. textFitWidth = stretchOnly and textFitHeight = proportional

   The content rectangle scales to precisely contain the height of its contents but the width will not shrink smaller than the aspect ratio of the original content rectangle. This is primarily useful for shields that shouldn't become too narrow if their contents are narrow (like the number "1").

1. textFitWidth = proportional and textFitHeight = stretchOnly

   The content rectangle scales to precisely contain the width of its contents but the height will not shrink smaller than the aspect ratio of the original content rectangle. This may be useful scenarios like no. 2 except with vertically written scripts (using `"text-writing-mode": ["vertical"]`).

![Sprite texFit options example](/gl-style-specification/assets/img/textFit.png)

## High-DPI Devices

On high-DPI devices, `@2x` is appended to the URLs described above. For example, if you specified `"sprite": "https://example.com/sprite"`, renderers would load `https://example.com/sprite.json` and `https://example.com/sprite.png`, or `https://example.com/sprite@2x.json` and `https://example.com/sprite@2x.png`.

## Generating Sprites

There are tools that can generate sprites from SVG files, such as [spreet](https://github.com/flother/spreet) and [spritezero](https://www.npmjs.com/package/@elastic/spritezero).

MapTiler map styles have their own sprites prepared by our cartographers. You can change the Icon's **fill color**, **outline**, or **size** easily in the [Map Designer tool](https://cloud.maptiler.com/maps/editor?). If you want to use your icons instead of the prepared icon sets, you can uploading your icons.

# Glyphs

Source: https://docs.maptiler.com/gl-style-specification/glyphs/

A style's `glyphs` property provides a URL template for loading signed-distance-field glyph sets in PBF format.

```json
"glyphs": "https://api.maptiler.com/fonts/{fontstack}/{range}.pbf?key="
```

This URL template should include two tokens:

- `{fontstack}` When requesting glyphs, this token is replaced with a comma separated list of fonts from a font stack specified in the [`text-font`](../layers/#text-font) property of a symbol layer.
- `{range}` When requesting glyphs, this token is replaced with a range of 256 Unicode code points. For example, to load glyphs for the [Unicode Basic Latin and Basic Latin-1 Supplement blocks](https://en.wikipedia.org/wiki/Unicode_block), the range would be `0-255`. The actual ranges that are loaded are determined at runtime based on what text needs to be displayed.

# Transition

Source: https://docs.maptiler.com/gl-style-specification/transition/

A `transition` property controls timing for the interpolation between a transitionable style property's previous value and new value. A style's [root `transition`](../root/#transition) property provides global transition defaults for that style.

```json
"transition": {
  "duration": 300,
  "delay": 0
}
```

Any transitionable layer property, marked by , may also have its own *-transition property that defines specific transition timing for that layer property, overriding the global transition values.

```json
"fill-opacity-transition": {
  "duration": 300,
  "delay": 0
}
```

## delay

Optional [number](../types/#number) greater than or equal to `0`. Units in milliseconds. Defaults to `0`.

Length of time before a transition begins.

## duration

Optional [number](../types/#number) greater than or equal to `0`. Units in milliseconds. Defaults to `300`.

Time allotted for transitions to complete.

# Layers

Source: https://docs.maptiler.com/gl-style-specification/layers/

A style's `layers` property lists all the layers available in that style. The type of layer is specified by the `"type"` property, and must be one of `background, fill, line, symbol, raster, circle, fill-extrusion, heatmap, hillshade`.

Except for layers of the _background_ type, each layer needs to refer to a source. Layers take the data that they get from a source, optionally filter features, and then define how those features are styled.

```json
"layers": [
  {
    "id": "water",
    "source": "streets",
    "source-layer": "water",
    "type": "fill",
    "paint": {
      "fill-color": "#00ffff"
    }
  }
]
```

## filter

Optional [expression](../expressions).

A expression specifying conditions on source features. Only features that match the filter are displayed. Zoom expressions in filters are only evaluated at integer zoom levels. The `feature-state` expression is not supported in filter expressions.

## id

Required [string](../types/#string).

Unique layer name.

## layout

Optional [layout](#layout-property).

Layout properties for the layer.

## maxzoom

Optional [number](../types/#number) between `0` and `24` inclusive.

The maximum zoom level for the layer. At zoom levels equal to or greater than the maxzoom, the layer will be hidden.

## metadata

Optional.

Arbitrary properties useful to track with the layer, but do not influence rendering. Properties should be prefixed to avoid collisions, like 'openmaptiles:'.

## minzoom

Optional [number](../types/#number) between `0` and `24` inclusive.

The minimum zoom level for the layer. At zoom levels less than the minzoom, the layer will be hidden.

## paint

Optional [paint](#paint-property).

Default paint properties for this layer.

## source

Optional [string](../types/#string).

Name of a source description to be used for this layer. Required for all layer types except `background`.

## source-layer

Optional [string](../types/#string).

Layer to use from a vector tile source. Required for vector tile sources; prohibited for all other source types, including GeoJSON sources.

## type

Required [enum](../types/#enum). One of `"fill"`, `"line"`, `"symbol"`, `"circle"`, `"heatmap"`, `"fill-extrusion"`, `"raster"`, `"hillshade"`, `"background"`.

Rendering type of this layer.

`"fill"`:

A filled polygon with an optional stroked border.

`"line"`:

A stroked line.

`"symbol"`:

An icon or a text label.

`"circle"`:

A filled circle.

`"heatmap"`:

A heatmap.

`"fill-extrusion"`:

An extruded (3D) polygon.

`"raster"`:

Raster map textures such as satellite imagery.

`"hillshade"`:

Client-side hillshading visualization based on DEM data. Currently, the implementation only supports Terrain RGB and Mapzen Terrarium tiles.

`"background"`:

The background color or pattern of the map.







Layers have two sub-properties that determine how data from that layer is rendered: `layout` and `paint` properties.

_Layout properties_ appear in the layer's `"layout"` object. They are applied early in the rendering process and define how data for that layer is passed to the GPU. Changes to a layout property require an asynchronous "layout" step.

_Paint properties_ are applied later in the rendering process. Paint properties appear in the layer's `"paint"` object. Changes to a paint property are cheap and happen synchronously.

## [background](#background)

The `background` style layer covers the entire map. Use a background style layer to configure a color or pattern to show below all other map content. If the background layer is transparent or omitted from the style, any part of the map view that does not show another style layer is transparent.

![Vintage map style with a brown halftone background pattern.](img/layer-background-800.webp)

Use a custom SVG [`background-pattern`](#background-pattern) to achieve a textured vintage look.

### background-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. _Disabled by_ background-pattern. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The color with which the background will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### background-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity at which the background will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### background-pattern

[Paint](#paint-property) property. Optional [resolvedImage](../types/#resolvedimage). Transitionable.

Name of image in sprite to use for drawing an image background. For seamless patterns, image width and height must be a factor of two (2, 4, 8, ..., 512). Note that zoom-dependent expressions will be evaluated only at integer zoom levels.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | Not yet supported | Not yet supported | Not yet supported | Not yet supported |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## [fill](#fill)

A `fill` style layer renders one or more filled (and optionally stroked) polygons on a map. You can use a fill layer to configure the visual appearance of polygon or multipolygon features.

![Map of Rio de Janeiro with a purple polygon.](img/layer-fill-800.webp)

This [map of Rio de Janeiro](/sdk-js/examples/geojson-polygon/) uses the [`fill-opacity`](#fill-opacity) paint property to render a semi-transparent polygon.

### fill-antialias

[Paint](#paint-property) property. Optional [boolean](../types/#boolean). Defaults to `true`.

Whether or not the fill should be antialiased.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### fill-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. _Disabled by_ fill-pattern. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The color of the filled part of this layer. This color can be specified as `rgba` with an alpha component and the color's opacity will not affect the opacity of the 1px stroke, if it is used.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.19.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### fill-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity of the entire fill layer. In contrast to the `fill-color`, this value will also affect the 1px stroke around the fill, if the stroke is used.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.21.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### fill-outline-color

[Paint](#paint-property) property. Optional [color](../types/#color). _Disabled by_ fill-pattern. _Requires_ fill-antialias to be `true`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The outline color of the fill. Matches the value of `fill-color` if unspecified.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.19.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### fill-pattern

[Paint](#paint-property) property. Optional [resolvedImage](../types/#resolvedimage). Transitionable.

Name of image in sprite to use for drawing image fills. For seamless patterns, image width and height must be a factor of two (2, 4, 8, ..., 512). Note that zoom-dependent expressions will be evaluated only at integer zoom levels.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.49.0 | >= 6.5.0 | >= 4.4.0 | >= 0.11.0 |

### fill-sort-key

[Layout](#layout-property) property. Optional [number](../types/#number).

Sorts features in ascending order based on this value. Features with a higher sort key will appear above features with a lower sort key.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.2.0 | >= 9.1.0 | >= 5.8.0 | >= 0.15.0 |
| data-driven styling | >= 1.2.0 | >= 9.1.0 | >= 5.8.0 | >= 0.15.0 |

### fill-translate

[Paint](#paint-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in pixels. Defaults to `[0,0]`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The geometry's offset. Values are \[x, y\] where negatives indicate left and up, respectively.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### fill-translate-anchor

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"map"`. _Requires_ fill-translate.

Controls the frame of reference for `fill-translate`.

`"map"`:

The fill is translated relative to the map.

`"viewport"`:

The fill is translated relative to the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## [line](#line)

A `line` style layer renders one or more stroked polylines on the map. You can use a line layer to configure the visual appearance of polyline or multipolyline features.

![Outdoors style map with a red line showing a hiking path.](img/layer-line-800.webp)

This [hiking map through Grand Teton National Park](/sdk-js/examples/geojson-line/) uses the [`line-color`](#line-color) and [`line-width`](#line-width) paint properties to style the strong red line of the user's route.

### line-blur

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `0`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Blur applied to the line, in pixels.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### line-cap

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"butt"`, `"round"`, `"square"`. Defaults to `"butt"`.

The display of line endings.

`"butt"`:

A cap with a squared-off end which is drawn to the exact endpoint of the line.

`"round"`:

A cap with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.

`"square"`:

A cap with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### line-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. _Disabled by_ line-pattern. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The color with which the line will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.23.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### line-dasharray

[Paint](#paint-property) property. Optional [array](../types/#array) of [numbers](../types/#number) greater than or equal to `0`. Units in line widths. _Disabled by_ line-pattern. Transitionable.

Specifies the lengths of the alternating dashes and gaps that form the dash pattern. The lengths are later scaled by the line width. To convert a dash length to pixels, multiply the length by the current line width. Note that GeoJSON sources with `lineMetrics: true` specified won't render dashed lines to the expected scale. Also note that zoom-dependent expressions will be evaluated only at integer zoom levels.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | Not yet supported | Not yet supported | Not yet supported | Not yet supported |

### line-gap-width

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `0`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Draws a line casing outside of a line's actual path. Value indicates the width of the inner gap.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### line-gradient

[Paint](#paint-property) property. Optional [color](../types/#color). _Disabled by_ line-dasharray. _Disabled by_ line-pattern. _Requires_ source to be `"geojson"`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Defines a gradient with which to color a line feature. Can only be used with GeoJSON sources that specify `"lineMetrics": true`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.5.0 | >= 4.4.0 | >= 0.11.0 |
| data-driven styling | Not yet supported | Not yet supported | Not yet supported | Not yet supported |

### line-join

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"bevel"`, `"round"`, `"miter"`. Defaults to `"miter"`.

The display of lines when joining.

`"bevel"`:

A join with a squared-off end which is drawn beyond the endpoint of the line at a distance of one-half of the line's width.

`"round"`:

A join with a rounded end which is drawn beyond the endpoint of the line at a radius of one-half of the line's width and centered on the endpoint of the line.

`"miter"`:

A join with a sharp, angled corner which is drawn with the outer sides beyond the endpoint of the path until they meet.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.40.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

### line-miter-limit

[Layout](#layout-property) property. Optional [number](../types/#number). Defaults to `2`. _Requires_ line-join to be `"miter"`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Used to automatically convert miter joins to bevel joins for sharp angles.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### line-offset

[Paint](#paint-property) property. Optional [number](../types/#number). Units in pixels. Defaults to `0`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The line's offset. For linear features, a positive value offsets the line to the right, relative to the direction of the line, and a negative value to the left. For polygon features, a positive value results in an inset, and a negative value results in an outset.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.12.0 | >= 3.0.0 | >= 3.1.0 | >= 0.1.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### line-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity at which the line will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### line-pattern

[Paint](#paint-property) property. Optional [resolvedImage](../types/#resolvedimage). Transitionable.

Name of image in sprite to use for drawing image lines. For seamless patterns, image width must be a factor of two (2, 4, 8, ..., 512). Note that zoom-dependent expressions will be evaluated only at integer zoom levels.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.49.0 | >= 6.5.0 | >= 4.4.0 | >= 0.11.0 |

### line-round-limit

[Layout](#layout-property) property. Optional [number](../types/#number). Defaults to `1.05`. _Requires_ line-join to be `"round"`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Used to automatically convert round joins to miter joins for shallow angles.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### line-sort-key

[Layout](#layout-property) property. Optional [number](../types/#number).

Sorts features in ascending order based on this value. Features with a higher sort key will appear above features with a lower sort key.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.2.0 | >= 9.1.0 | >= 5.8.0 | >= 0.15.0 |
| data-driven styling | >= 1.2.0 | >= 9.1.0 | >= 5.8.0 | >= 0.15.0 |

### line-translate

[Paint](#paint-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in pixels. Defaults to `[0,0]`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The geometry's offset. Values are \[x, y\] where negatives indicate left and up, respectively.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### line-translate-anchor

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"map"`. _Requires_ line-translate.

Controls the frame of reference for `line-translate`.

`"map"`:

The line is translated relative to the map.

`"viewport"`:

The line is translated relative to the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### line-width

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `1`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Stroke thickness.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.39.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## [symbol](#symbol)

A `symbol` style layer renders icon and text labels at points or along lines on a map. You can use a symbol layer to configure the visual appearance of labels for features in vector tiles.

![Map with USA airports.](img/layer-symbol-800.webp)

This [map of Airports](/sdk-js/examples/geojson-point/) uses the [`icon-image`](#icon-image) layout property to use a custom image as an icon in a symbol layer.

### icon-allow-overlap

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`. _Requires_ icon-image.

If true, the icon will be visible even if it collides with other previously drawn symbols.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### icon-anchor

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"center"`, `"left"`, `"right"`, `"top"`, `"bottom"`, `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`. Defaults to `"center"`. _Requires_ icon-image.

Part of the icon placed closest to the anchor.

`"center"`:

The center of the icon is placed closest to the anchor.

`"left"`:

The left side of the icon is placed closest to the anchor.

`"right"`:

The right side of the icon is placed closest to the anchor.

`"top"`:

The top of the icon is placed closest to the anchor.

`"bottom"`:

The bottom of the icon is placed closest to the anchor.

`"top-left"`:

The top left corner of the icon is placed closest to the anchor.

`"top-right"`:

The top right corner of the icon is placed closest to the anchor.

`"bottom-left"`:

The bottom left corner of the icon is placed closest to the anchor.

`"bottom-right"`:

The bottom right corner of the icon is placed closest to the anchor.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.40.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |
| data-driven styling | >= 0.40.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

### icon-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. _Requires_ icon-image. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The color of the icon. This can only be used with sdf icons.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### icon-halo-blur

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `0`. _Requires_ icon-image. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Fade out the halo towards the outside.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### icon-halo-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"rgba(0, 0, 0, 0)"`. _Requires_ icon-image. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The color of the icon's halo. Icon halos can only be used with SDF icons.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### icon-halo-width

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `0`. _Requires_ icon-image. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Distance of halo to the icon outline.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### icon-ignore-placement

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`. _Requires_ icon-image.

If true, other symbols can be visible even if they collide with the icon.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### icon-image

[Layout](#layout-property) property. Optional [resolvedImage](../types/#resolvedimage).

Name of image in sprite to use for drawing an image background.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.35.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### icon-keep-upright

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`. _Requires_ icon-image. _Requires_ icon-rotation-alignment to be `"map"`. _Requires_ symbol-placement to be `"line"`, or `"line-center"`.

If true, the icon may be flipped to prevent it from being rendered upside-down.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### icon-offset

[Layout](#layout-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Defaults to `[0,0]`. _Requires_ icon-image. Supports [`interpolate`](../expressions/#interpolate)expressions.

Offset distance of icon from its anchor. Positive values indicate right and down, while negative values indicate left and up. Each component is multiplied by the value of `icon-size` to obtain the final offset in pixels. When combined with `icon-rotate` the offset will be as if the rotated direction was up.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### icon-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. _Requires_ icon-image. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity at which the icon will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### icon-optional

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`. _Requires_ icon-image. _Requires_ text-field.

If true, text will display without their corresponding icons when the icon collides with other symbols and the text does not.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### icon-padding

[Layout](#layout-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `2`. _Requires_ icon-image. Supports [`interpolate`](../expressions/#interpolate)expressions.

Size of the additional area around the icon bounding box used for detecting symbol collisions.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### icon-pitch-alignment

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`, `"auto"`. Defaults to `"auto"`. _Requires_ icon-image.

Orientation of icon when map is pitched.

`"map"`:

The icon is aligned to the plane of the map.

`"viewport"`:

The icon is aligned to the plane of the viewport.

`"auto"`:

Automatically matches the value of `icon-rotation-alignment`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.39.0 | >= 5.2.1 | >= 3.7.0 | >= 0.6.0 |

### icon-rotate

[Layout](#layout-property) property. Optional [number](../types/#number). Units in degrees. Defaults to `0`. _Requires_ icon-image. Supports [`interpolate`](../expressions/#interpolate)expressions.

Rotates the icon clockwise.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.21.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### icon-rotation-alignment

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`, `"auto"`. Defaults to `"auto"`. _Requires_ icon-image.

In combination with `symbol-placement`, determines the rotation behavior of icons.

`"map"`:

When `symbol-placement` is set to `point`, aligns icons east-west. When `symbol-placement` is set to `line` or `line-center`, aligns icon x-axes with the line.

`"viewport"`:

Produces icons whose x-axes are aligned with the x-axis of the viewport, regardless of the value of `symbol-placement`.

`"auto"`:

When `symbol-placement` is set to `point`, this is equivalent to `viewport`. When `symbol-placement` is set to `line` or `line-center`, this is equivalent to `map`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| auto value | >= 0.25.0 | >= 4.2.0 | >= 3.4.0 | >= 0.3.0 |

### icon-size

[Layout](#layout-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in factor of the original icon size. Defaults to `1`. _Requires_ icon-image. Supports [`interpolate`](../expressions/#interpolate)expressions.

Scales the original size of the icon by the provided factor. The new pixel size of the image will be the original pixel size multiplied by `icon-size`. 1 is the original size; 3 triples the size of the image.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.35.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### icon-text-fit

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"none"`, `"width"`, `"height"`, `"both"`. Defaults to `"none"`. _Requires_ icon-image. _Requires_ text-field.

Scales the icon to fit around the associated text.

`"none"`:

The icon is displayed at its intrinsic aspect ratio.

`"width"`:

The icon is scaled in the x-dimension to fit the width of the text.

`"height"`:

The icon is scaled in the y-dimension to fit the height of the text.

`"both"`:

The icon is scaled in both x- and y-dimensions.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.21.0 | >= 4.2.0 | >= 3.4.0 | >= 0.2.1 |
| stretchable icons | >= 1.6.0 | >= 9.2.0 | >= 5.8.0 | >= 0.15.0 |

### icon-text-fit-padding

[Layout](#layout-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in pixels. Defaults to `[0,0,0,0]`. _Requires_ icon-image. _Requires_ text-field. _Requires_ icon-text-fit to be `"both"`, or `"width"`, or `"height"`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Size of the additional area added to dimensions determined by `icon-text-fit`, in clockwise order: top, right, bottom, left.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.21.0 | >= 4.2.0 | >= 3.4.0 | >= 0.2.1 |

### icon-translate

[Paint](#paint-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in pixels. Defaults to `[0,0]`. _Requires_ icon-image. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Distance that the icon's anchor is moved from its original placement. Positive values indicate right and down, while negative values indicate left and up.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### icon-translate-anchor

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"map"`. _Requires_ icon-image. _Requires_ icon-translate.

Controls the frame of reference for `icon-translate`.

`"map"`:

Icons are translated relative to the map.

`"viewport"`:

Icons are translated relative to the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### symbol-avoid-edges

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`.

If true, the symbols will not cross tile edges to avoid mutual collisions. Recommended in layers that don't have enough padding in the vector tile to prevent collisions, or if it is a point symbol layer placed after a line symbol layer. When using a client that supports global collision detection, like MapLibre GL JS version 0.42.0 or greater, enabling this property is not needed to prevent clipped labels at tile boundaries.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### symbol-placement

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"point"`, `"line"`, `"line-center"`. Defaults to `"point"`.

Label placement relative to its geometry.

`"point"`:

The label is placed at the point where the geometry is located.

`"line"`:

The label is placed along the line of the geometry. Can only be used on `LineString` and `Polygon` geometries.

`"line-center"`:

The label is placed at the center of the line of the geometry. Can only be used on `LineString` and `Polygon` geometries. Note that a single feature in a vector tile may contain multiple line geometries.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| line-center value | >= 0.47.0 | >= 6.4.0 | >= 4.3.0 | >= 0.10.0 |

### symbol-sort-key

[Layout](#layout-property) property. Optional [number](../types/#number).

Sorts features in ascending order based on this value. Features with lower sort keys are drawn and placed first. When `icon-allow-overlap` or `text-allow-overlap` is `false`, features with a lower sort key will have priority during placement. When `icon-allow-overlap` or `text-allow-overlap` is set to `true`, features with a higher sort key will overlap over features with a lower sort key.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.53.0 | >= 7.4.0 | >= 4.11.0 | >= 0.14.0 |
| data-driven styling | >= 0.53.0 | >= 7.4.0 | >= 4.11.0 | >= 0.14.0 |

### symbol-spacing

[Layout](#layout-property) property. Optional [number](../types/#number) greater than or equal to `1`. Units in pixels. Defaults to `250`. _Requires_ symbol-placement to be `"line"`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Distance between two symbol anchors.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### symbol-z-order

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"auto"`, `"viewport-y"`, `"source"`. Defaults to `"auto"`.

Determines whether overlapping symbols in the same layer are rendered in the order that they appear in the data source or by their y-position relative to the viewport. To control the order and prioritization of symbols otherwise, use `symbol-sort-key`.

`"auto"`:

Sorts symbols by `symbol-sort-key` if set. Otherwise, sorts symbols by their y-position relative to the viewport if `icon-allow-overlap` or `text-allow-overlap` is set to `true` or `icon-ignore-placement` or `text-ignore-placement` is `false`.

`"viewport-y"`:

Sorts symbols by their y-position relative to the viewport if `icon-allow-overlap` or `text-allow-overlap` is set to `true` or `icon-ignore-placement` or `text-ignore-placement` is `false`.

`"source"`:

Sorts symbols by `symbol-sort-key` if set. Otherwise, no sorting is applied; symbols are rendered in the same order as the source data.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.49.0 | >= 6.6.0 | >= 4.5.0 | >= 0.12.0 |

### text-allow-overlap

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`. _Requires_ text-field.

If true, the text will be visible even if it collides with other previously drawn symbols.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-anchor

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"center"`, `"left"`, `"right"`, `"top"`, `"bottom"`, `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`. Defaults to `"center"`. _Requires_ text-field. _Disabled by_ text-variable-anchor.

Part of the text placed closest to the anchor.

`"center"`:

The center of the text is placed closest to the anchor.

`"left"`:

The left side of the text is placed closest to the anchor.

`"right"`:

The right side of the text is placed closest to the anchor.

`"top"`:

The top of the text is placed closest to the anchor.

`"bottom"`:

The bottom of the text is placed closest to the anchor.

`"top-left"`:

The top left corner of the text is placed closest to the anchor.

`"top-right"`:

The top right corner of the text is placed closest to the anchor.

`"bottom-left"`:

The bottom left corner of the text is placed closest to the anchor.

`"bottom-right"`:

The bottom right corner of the text is placed closest to the anchor.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.39.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

### text-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. _Requires_ text-field. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The color with which the text will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### text-field

[Layout](#layout-property) property. Optional [formatted](../types/#formatted). Defaults to `""`.

Value to use for a text label. If a plain `string` is provided, it will be treated as a `formatted` with default/inherited formatting options.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### text-font

[Layout](#layout-property) property. Optional [array](../types/#array) of [strings](../types/#string). Defaults to `["Open Sans Regular","Arial Unicode MS Regular"]`. _Requires_ text-field.

Font stack to use for displaying text.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### text-halo-blur

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `0`. _Requires_ text-field. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The halo's fadeout distance towards the outside.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### text-halo-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"rgba(0, 0, 0, 0)"`. _Requires_ text-field. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The color of the text's halo, which helps it stand out from backgrounds.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### text-halo-width

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `0`. _Requires_ text-field. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Distance of halo to the font outline. Max text halo width is 1/4 of the font-size.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### text-ignore-placement

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`. _Requires_ text-field.

If true, other symbols can be visible even if they collide with the text.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-justify

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"auto"`, `"left"`, `"center"`, `"right"`. Defaults to `"center"`. _Requires_ text-field.

Text justification options.

`"auto"`:

The text is aligned towards the anchor position.

`"left"`:

The text is aligned to the left.

`"center"`:

The text is centered.

`"right"`:

The text is aligned to the right.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.39.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |
| auto value | >= 0.54.0 | >= 7.4.0 | >= 4.10.0 | >= 0.14.0 |

### text-keep-upright

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `true`. _Requires_ text-field. _Requires_ text-rotation-alignment to be `"map"`. _Requires_ symbol-placement to be `"line"`, or `"line-center"`.

If true, the text may be flipped vertically to prevent it from being rendered upside-down.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-letter-spacing

[Layout](#layout-property) property. Optional [number](../types/#number). Units in ems. Defaults to `0`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions.

Text tracking amount.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.40.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

### text-line-height

[Layout](#layout-property) property. Optional [number](../types/#number). Units in ems. Defaults to `1.2`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions.

Text leading value for multi-line text.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-max-angle

[Layout](#layout-property) property. Optional [number](../types/#number). Units in degrees. Defaults to `45`. _Requires_ text-field. _Requires_ symbol-placement to be `"line"`, or `"line-center"`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Maximum angle change between adjacent characters.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-max-width

[Layout](#layout-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in ems. Defaults to `10`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions.

The maximum line width for text wrapping.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.40.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

### text-offset

[Layout](#layout-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in ems. Defaults to `[0,0]`. _Requires_ text-field. _Disabled by_ text-radial-offset. Supports [`interpolate`](../expressions/#interpolate)expressions.

Offset distance of text from its anchor. Positive values indicate right and down, while negative values indicate left and up. If used with text-variable-anchor, input values will be taken as absolute values. Offsets along the x- and y-axis will be applied automatically based on the anchor position.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.35.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### text-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. _Requires_ text-field. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity at which the text will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### text-optional

[Layout](#layout-property) property. Optional [boolean](../types/#boolean). Defaults to `false`. _Requires_ text-field. _Requires_ icon-image.

If true, icons will display without their corresponding text when the text collides with other symbols and the icon does not.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-padding

[Layout](#layout-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `2`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions.

Size of the additional area around the text bounding box used for detecting symbol collisions.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-pitch-alignment

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`, `"auto"`. Defaults to `"auto"`. _Requires_ text-field.

Orientation of text when map is pitched.

`"map"`:

The text is aligned to the plane of the map.

`"viewport"`:

The text is aligned to the plane of the viewport.

`"auto"`:

Automatically matches the value of `text-rotation-alignment`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.21.0 | >= 4.2.0 | >= 3.4.0 | >= 0.2.1 |
| auto value | >= 0.25.0 | >= 4.2.0 | >= 3.4.0 | >= 0.3.0 |

### text-radial-offset

[Layout](#layout-property) property. Optional [number](../types/#number). Units in ems. Defaults to `0`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions.

Radial offset of text, in the direction of the symbol's anchor. Useful in combination with `text-variable-anchor`, which defaults to using the two-dimensional `text-offset` if present.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.54.0 | >= 7.4.0 | >= 4.10.0 | >= 0.14.0 |
| data-driven styling | >= 0.54.0 | >= 7.4.0 | >= 4.10.0 | >= 0.14.0 |

### text-rotate

[Layout](#layout-property) property. Optional [number](../types/#number). Units in degrees. Defaults to `0`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions.

Rotates the text clockwise.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.35.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### text-rotation-alignment

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`, `"auto"`. Defaults to `"auto"`. _Requires_ text-field.

In combination with `symbol-placement`, determines the rotation behavior of the individual glyphs forming the text.

`"map"`:

When `symbol-placement` is set to `point`, aligns text east-west. When `symbol-placement` is set to `line` or `line-center`, aligns text x-axes with the line.

`"viewport"`:

Produces glyphs whose x-axes are aligned with the x-axis of the viewport, regardless of the value of `symbol-placement`.

`"auto"`:

When `symbol-placement` is set to `point`, this is equivalent to `viewport`. When `symbol-placement` is set to `line` or `line-center`, this is equivalent to `map`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| auto value | >= 0.25.0 | >= 4.2.1 | >= 3.4.0 | >= 0.3.0 |

### text-size

[Layout](#layout-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `16`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions.

Font size.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.35.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### text-transform

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"none"`, `"uppercase"`, `"lowercase"`. Defaults to `"none"`. _Requires_ text-field.

Specifies how to capitalize text, similar to the CSS `text-transform` property.

`"none"`:

The text is not altered.

`"uppercase"`:

Forces all letters to be displayed in uppercase.

`"lowercase"`:

Forces all letters to be displayed in lowercase.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.33.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### text-translate

[Paint](#paint-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in pixels. Defaults to `[0,0]`. _Requires_ text-field. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Distance that the text's anchor is moved from its original placement. Positive values indicate right and down, while negative values indicate left and up.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-translate-anchor

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"map"`. _Requires_ text-field. _Requires_ text-translate.

Controls the frame of reference for `text-translate`.

`"map"`:

The text is translated relative to the map.

`"viewport"`:

The text is translated relative to the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### text-variable-anchor

[Layout](#layout-property) property. Optional [array](../types/#array) of [enums](../types/#enum). One of `"center"`, `"left"`, `"right"`, `"top"`, `"bottom"`, `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`. _Requires_ text-field. _Requires_ symbol-placement to be `"point"`.

To increase the chance of placing high-priority labels on the map, you can provide an array of `text-anchor` locations: the renderer will attempt to place the label at each location, in order, before moving onto the next label. Use `text-justify: auto` to choose justification based on anchor position. To apply an offset, use the `text-radial-offset` or the two-dimensional `text-offset`.

`"center"`:

The center of the text is placed closest to the anchor.

`"left"`:

The left side of the text is placed closest to the anchor.

`"right"`:

The right side of the text is placed closest to the anchor.

`"top"`:

The top of the text is placed closest to the anchor.

`"bottom"`:

The bottom of the text is placed closest to the anchor.

`"top-left"`:

The top left corner of the text is placed closest to the anchor.

`"top-right"`:

The top right corner of the text is placed closest to the anchor.

`"bottom-left"`:

The bottom left corner of the text is placed closest to the anchor.

`"bottom-right"`:

The bottom right corner of the text is placed closest to the anchor.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.54.0 | >= 7.4.0 | >= 4.10.0 | >= 0.14.0 |

### text-writing-mode

[Layout](#layout-property) property. Optional [array](../types/#array) of [enums](../types/#enum). One of `"horizontal"`, `"vertical"`. _Requires_ text-field. _Requires_ symbol-placement to be `"point"`.

The property allows control over a symbol's orientation. Note that the property values act as a hint, so that a symbol whose language doesn’t support the provided orientation will be laid out in its natural orientation. Example: English point symbol will be rendered horizontally even if array value contains single 'vertical' enum value. The order of elements in an array define priority order for the placement of an orientation variant.

`"horizontal"`:

If a text's language supports horizontal writing mode, symbols with point placement would be laid out horizontally.

`"vertical"`:

If a text's language supports vertical writing mode, symbols with point placement would be laid out vertically.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.3.0 | >= 8.3.0 | >= 5.3.0 | >= 0.15.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## [raster](#raster)

A `raster` style layer renders raster tiles on a map. You can use a raster layer to configure the color parameters of raster tiles.

![Cementery aerial image.](img/layer-raster-800.webp)

This [cementery map](/sdk-js/examples/raster-layer/) use the `raster-opacity` paint property to show a raster image overlay to the map.

### raster-brightness-max

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Increase or reduce the brightness of the image. The value is the maximum brightness.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### raster-brightness-min

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `0`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Increase or reduce the brightness of the image. The value is the minimum brightness.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### raster-contrast

[Paint](#paint-property) property. Optional [number](../types/#number) between `-1` and `1` inclusive. Defaults to `0`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Increase or reduce the contrast of the image.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### raster-fade-duration

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in milliseconds. Defaults to `300`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Fade duration when a new tile is added.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### raster-hue-rotate

[Paint](#paint-property) property. Optional [number](../types/#number). Units in degrees. Defaults to `0`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Rotates hues around the color wheel.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### raster-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports [`interpolate`](../expressions/#interpolate) expressions. Transitionable.

The opacity at which the image will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### raster-resampling

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"linear"`, `"nearest"`. Defaults to `"linear"`.

The resampling/interpolation method to use for overscaling, also known as texture magnification filter

`"linear"`:

(Bi)linear filtering interpolates pixel values using the weighted average of the four closest original source pixels creating a smooth but blurry look when overscaled

`"nearest"`:

Nearest neighbor filtering interpolates pixel values using the nearest original source pixel creating a sharp but pixelated look when overscaled

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.47.0 | >= 6.3.0 | >= 4.2.0 | >= 0.9.0 |

### raster-saturation

[Paint](#paint-property) property. Optional [number](../types/#number) between `-1` and `1` inclusive. Defaults to `0`. Supports [`interpolate`](../expressions/#interpolate) expressions. Transitionable.

Increase or reduce the saturation of the image.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## [circle](#circle)

A `circle` style layer renders one or more filled circles on a map. You can use a circle layer to configure the visual appearance of point or point collection features in vector tiles. A circle layer renders circles whose radii are measured in screen units.

![Map with circles of different sizes and colors.](img/layer-circle-800.webp)

This [cluster map](/sdk-js/examples/cluster/) uses a circle layer with a GeoJSON data source and sets the source's [`cluster`](../sources/#geojson-cluster) property to `true` to visualize points as clusters.

### circle-blur

[Paint](#paint-property) property. Optional [number](../types/#number). Defaults to `0`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Amount to blur the circle. 1 blurs the circle such that only the centerpoint is full opacity.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.20.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### circle-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The fill color of the circle.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.18.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### circle-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity at which the circle will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.20.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### circle-pitch-alignment

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"viewport"`.

Orientation of circle when map is pitched.

`"map"`:

The circle is aligned to the plane of the map.

`"viewport"`:

The circle is aligned to the plane of the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.39.0 | >= 5.2.0 | >= 3.7.0 | >= 0.6.0 |

### circle-pitch-scale

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"map"`.

Controls the scaling behavior of the circle when the map is pitched.

`"map"`:

Circles are scaled according to their apparent distance to the camera.

`"viewport"`:

Circles are not scaled.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.21.0 | >= 4.2.0 | >= 3.4.0 | >= 0.2.1 |

### circle-radius

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `5`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Circle radius.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |
| data-driven styling | >= 0.18.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### circle-sort-key

[Layout](#layout-property) property. Optional [number](../types/#number).

Sorts features in ascending order based on this value. Features with a higher sort key will appear above features with a lower sort key.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.2.0 | >= 9.2.0 | >= 5.9.0 | >= 0.16.0 |
| data-driven styling | >= 1.2.0 | >= 9.2.0 | >= 5.9.0 | >= 0.16.0 |

### circle-stroke-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The stroke color of the circle.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### circle-stroke-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity of the circle's stroke.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### circle-stroke-width

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in pixels. Defaults to `0`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The width of the circle's stroke. Strokes are placed outside of the `circle-radius`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |
| data-driven styling | >= 0.29.0 | >= 5.0.0 | >= 3.5.0 | >= 0.4.0 |

### circle-translate

[Paint](#paint-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in pixels. Defaults to `[0,0]`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The geometry's offset. Values are \[x, y\] where negatives indicate left and up, respectively.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### circle-translate-anchor

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"map"`. _Requires_ circle-translate.

Controls the frame of reference for `circle-translate`.

`"map"`:

The circle is translated relative to the map.

`"viewport"`:

The circle is translated relative to the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.10.0 | >= 2.0.1 | >= 2.0.0 | >= 0.1.0 |

## [fill-extrusion](#fill-extrusion)

A `fill-extrusion` style layer renders one or more filled (and optionally stroked) extruded (3D) polygons on a map. You can use a fill-extrusion layer to configure the extrusion and visual appearance of polygon or multipolygon features.

![Map of Europe with countries extruded to various heights.](img/layer-fill-extrusion-800.webp)

This [map of Europe with countries extruded](/sdk-js/examples/fill-extrusion/) uses an external dataset to provide data-driven values for the [`fill-extrusion-height`](#fill-extrusion-height) paint property of various country polygons in a fill-extrusion layer.

### fill-extrusion-base

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in meters. Defaults to `0`. _Requires_ fill-extrusion-height. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The height with which to extrude the base of this layer. Must be less than or equal to `fill-extrusion-height`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |
| data-driven styling | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### fill-extrusion-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. _Disabled by_ fill-extrusion-pattern. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The base color of the extruded fill. The extrusion's surfaces will be shaded differently based on this color in combination with the root `light` settings. If this color is specified as `rgba` with an alpha component, the alpha component will be ignored; use `fill-extrusion-opacity` to set layer opacity.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |
| data-driven styling | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### fill-extrusion-height

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Units in meters. Defaults to `0`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The height with which to extrude this layer.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |
| data-driven styling | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### fill-extrusion-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The opacity of the entire fill extrusion layer. This is rendered on a per-layer, not per-feature, basis, and data-driven styling is not available.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### fill-extrusion-pattern

[Paint](#paint-property) property. Optional [resolvedImage](../types/#resolvedimage). Transitionable.

Name of image in sprite to use for drawing images on extruded fills. For seamless patterns, image width and height must be a factor of two (2, 4, 8, ..., 512). Note that zoom-dependent expressions will be evaluated only at integer zoom levels.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |
| data-driven styling | >= 0.49.0 | >= 6.5.0 | >= 4.4.0 | >= 0.11.0 |

### fill-extrusion-translate

[Paint](#paint-property) property. Optional [array](../types/#array) of [numbers](../types/#number). Units in pixels. Defaults to `[0,0]`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The geometry's offset. Values are \[x, y\] where negatives indicate left and up (on the flat plane), respectively.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### fill-extrusion-translate-anchor

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"map"`. _Requires_ fill-extrusion-translate.

Controls the frame of reference for `fill-extrusion-translate`.

`"map"`:

The fill extrusion is translated relative to the map.

`"viewport"`:

The fill extrusion is translated relative to the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

### fill-extrusion-vertical-gradient

[Paint](#paint-property) property. Optional [boolean](../types/#boolean). Defaults to `true`.

Whether to apply a vertical gradient to the sides of a fill-extrusion layer. If true, sides will be shaded slightly darker farther down.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.50.0 | Not yet supported | >= 4.7.0 | >= 0.13.0 |
| data-driven styling | >= 0.49.0 | >= 6.5.0 | >= 4.4.0 | >= 0.11.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.27.0 | >= 5.1.0 | >= 3.6.0 | >= 0.5.0 |

## [heatmap](#heatmap)

A `heatmap` style layer renders a range of colors to represent the density of points in an area.

![Dark map with a heatmap layer glowing red inside and white outside.](img/layer-heatmap-800.webp)

This [visualization of earthquake data](/sdk-js/examples/heatmap-layer/) uses a heatmap layer with carefully defined [paint](#paint-property) properties to highlight areas where earthquake frequency is high and many points are clustered closely together.

### heatmap-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `["interpolate",["linear"],["heatmap-density"],0,"rgba(0, 0, 255, 0)",0.1,"royalblue",0.3,"cyan",0.5,"lime",0.7,"yellow",1,"red"]`. Supports [`interpolate`](../expressions/#interpolate)expressions.

Defines the color of each pixel based on its density value in a heatmap. Should be an expression that uses `["heatmap-density"]` as input.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| data-driven styling | Not yet supported | Not yet supported | Not yet supported | Not yet supported |

### heatmap-intensity

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Defaults to `1`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Similar to `heatmap-weight` but controls the intensity of the heatmap globally. Primarily used for adjusting the heatmap based on zoom level.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### heatmap-opacity

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `1`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The global opacity at which the heatmap layer will be drawn.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### heatmap-radius

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `1`. Units in pixels. Defaults to `30`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Radius of influence of one heatmap point in pixels. Increasing the value makes the heatmap smoother, but less detailed.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| data-driven styling | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### heatmap-weight

[Paint](#paint-property) property. Optional [number](../types/#number) greater than or equal to `0`. Defaults to `1`. Supports _[`feature-state`](../expressions/#feature-state)_ and [`interpolate`](../expressions/#interpolate)expressions.

A measure of how much an individual point contributes to the heatmap. A value of 10 would be equivalent to having 10 points of weight 1 in the same spot. Especially useful when combined with clustering.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| data-driven styling | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [hillshade](#hillshade)

A `hillshade` style layer renders digital elevation model (DEM) data on the client-side. The implementation only supports Terrain RGB and Mapzen Terrarium tiles.

![Map of Mount Shasta rising up with striking texture and shading.](img/layer-hillshade-800.webp)

This [map of Mount Shasta](/sdk-js/examples/hillshade/) uses a high value for the [`hillshade-exaggeration`](#hillshade-exaggeration) paint property to apply an intense shading effect. Values of hillshading can be [adjusted dynamically](/sdk-js/examples/dynamic-hillshade/) and simulate movement of the sun.

### hillshade-accent-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The shading color used to accentuate rugged terrain like sharp cliffs and gorges.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### hillshade-exaggeration

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `1` inclusive. Defaults to `0.5`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

Intensity of the hillshade

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### hillshade-highlight-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#FFFFFF"`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The shading color of areas that faces towards the light source.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### hillshade-illumination-anchor

[Paint](#paint-property) property. Optional [enum](../types/#enum). One of `"map"`, `"viewport"`. Defaults to `"viewport"`.

Direction of light source when map is rotated.

`"map"`:

The hillshade illumination is relative to the north direction.

`"viewport"`:

The hillshade illumination is relative to the top of the viewport.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### hillshade-illumination-direction

[Paint](#paint-property) property. Optional [number](../types/#number) between `0` and `359` inclusive. Defaults to `335`. Supports [`interpolate`](../expressions/#interpolate)expressions.

The direction of the light source used to generate the hillshading with 0 as the top of the viewport if `hillshade-illumination-anchor` is set to `viewport` and due north if `hillshade-illumination-anchor` is set to `map`.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### hillshade-shadow-color

[Paint](#paint-property) property. Optional [color](../types/#color). Defaults to `"#000000"`. Supports [`interpolate`](../expressions/#interpolate)expressions. Transitionable.

The shading color of areas that face away from the light source.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

### visibility

[Layout](#layout-property) property. Optional [enum](../types/#enum). One of `"visible"`, `"none"`. Defaults to `"visible"`.

Whether this layer is displayed.

`"visible"`:

The layer is shown.

`"none"`:

The layer is not shown.

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.43.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

# Projection

Source: https://docs.maptiler.com/gl-style-specification/projection/

The projection configuration

```json
projection: {
  "type": [
    "interpolate",
    ["linear"],
    ["zoom"],
    10,
    "vertical-perspective",
    12,
    "mercator"
  ]
}
```

## type

Optional [ProjectionDefinition](../types/#ProjectionDefinition). Defaults to `mercator`. Supports [interpolate](../expressions/#interpolate) expressions.

The projection definition type. Can be specified as a string, a transition state, or an expression.

# Sky

Source: https://docs.maptiler.com/gl-style-specification/sky/

The map's sky configuration.

> [!NOTE]
> This definition is still experimental and is under development in maplibre-gl-js.

```json
"sky": {
    "sky-color": "#199EF3",
    "sky-horizon-blend": 0.5,
    "horizon-color": "#ffffff",
    "horizon-fog-blend": 0.5,
    "fog-color": "#0000ff",
    "fog-ground-blend": 0.5,
    "atmosphere-blend": [
        "interpolate",
        ["linear"],
        ["zoom"],
        0,
        1,
        10,
        1,
        12,
        0
    ]
}
```

## sky-color

Optional [color](../types/#color). Defaults to `#88C6FC`. Supports [interpolate](../expressions/#interpolate) expressions. Transitionable.

The base color at the horizon.

## horizon-color

Optional [color](../types/#color). Defaults to `#ffffff`. Supports [interpolate](../expressions/#interpolate) expressions. Transitionable.

The base color at the horizon.

## fog-color

Optional [color](../types/#color). Defaults to `#ffffff`. Supports [interpolate](../expressions/#interpolate) expressions. Transitionable.

The base color for the fog. Requires 3D terrain.

## fog-ground-blend

Optional [number](../types/#number) in range [0, 1]. Defaults to `0.5`. Supports [interpolate](../expressions/#interpolate) expressions. Transitionable.

How to blend the fog over the 3D terrain. Where 0 is the map center and 1 is the horizon.

## horizon-fog-blend

Optional [number](../types/#number) in range [0, 1]. Defaults to `0.8`. Supports [interpolate](../expressions/#interpolate) expressions. Transitionable.

How to blend the fog color and the horizon color. Where 0 is using the horizon color only and 1 is using the fog color only.

## sky-horizon-blend

Optional [number](../types/#number) in range [0, 1]. Defaults to `0.8`. Supports [interpolate](../expressions/#interpolate) expressions. Transitionable.

How to blend the the sky color and the horizon color. Where 1 is blending the color at the middle of the sky and 0 is not blending at all and using the sky color only.

## atmosphere-blend

Optional [number](../types/#number) in range [0, 1]. Defaults to `0.8`. Supports [interpolate](../expressions/#interpolate) expressions. Transitionable.

How to blend the atmosphere. Where 1 is visible atmosphere and 0 is hidden. It is best to interpolate this expression when using globe projection.

# Types

Source: https://docs.maptiler.com/gl-style-specification/types/

A GL style contains values of various types, most commonly as values for the style properties of a layer.

## Color

The `color` type is a color in the [sRGB color space](https://en.wikipedia.org/wiki/SRGB). Colors are JSON strings in a variety of permitted formats: HTML-style hex values, RGB, RGBA, HSL, and HSLA. Predefined HTML colors names, like `yellow` and `blue`, are also permitted.

```json
{
    "line-color": "#ff0",
    "line-color": "#ffff00",
    "line-color": "rgb(255, 255, 0)",
    "line-color": "rgba(255, 255, 0, 1)",
    "line-color": "hsl(100, 50%, 50%)",
    "line-color": "hsla(100, 50%, 50%, 1)",
    "line-color": "yellow"
}
```

Especially of note is the support for HSL, which can be [easier to reason about than RGB](https://mothereffinghsl.com/).

## Formatted

The `formatted` type is a string broken into sections annotated with separate formatting options.

```json
{
    "text-field": ["format",
        "foo", { "font-scale": 1.2 },
        "bar", { "font-scale": 0.8 }
    ]
}
```

## ResolvedImage

The `resolvedImage` type is an image (e.g., an icon or pattern) which is used in a layer. An input to the `image` expression operator is checked against the current map style to see if it is available to be rendered or not, and the result is returned in the `resolvedImage` type. This approach allows developers to define a series of images which the map can fall back to if previous images are not found, which cannot be achieved by providing, for example, `icon-image` with a plain string (because multiple strings cannot be supplied to `icon-image` and multiple images cannot be defined in a string).

```json
{
    "icon-image": ["coalesce", ["image", "myImage"], ["image", "fallbackImage"]]
}
```

## String

A string is text. In GL styles, strings are in quotes.

```json
{
    "source": "mySource"
}
```

## Boolean

Boolean means yes or no, so it accepts the values `true` or `false`.

```json
{
    "fill-enabled": true
}
```

## Number

A number value, often an integer or floating point (decimal number). Written without quotes.

```json
{
    "text-size": 24
}
```

## Array

Arrays are comma-separated lists of one or more numbers in a specific order. For example, they're used in line dash arrays, in which the numbers specify intervals of line, break, and line again. If an array is used as an argument in an expression, the array must be wrapped in a `literal` expression.

```json
{
    "line-dasharray": [2, 4]
}

{
    "circle-color": ["in", 1, ["literal", [1, 2, 3]]]
}
```

## Enum

An Enum is a special data type that enables for a variable to be a set of predefined constants. The variable must be equal to one of the values that have been predefined for it. 

```json
{
    "scheme": "tms"
}

{
    "encoding": "terrarium"
}
```

Look at the allowed values in the attribute definition. Ex. [raster-dem encoding](../sources/#encoding)

## PromoteId

A property to use as a feature id (for feature state). Either a property name, or an object of the form `{: }`. If specified as a string for a vector tile source, the same property is used across all its source layers.


## ProjectionDefinition

The `projection` is used to configure which projection to use for the map.

There are currently two projections implemented.

* `mercator` - [Web Mercator projection](https://en.wikipedia.org/wiki/Web_Mercator_projection)
* `vertical-perspective` - [Vertical Perspective projection](https://en.wikipedia.org/wiki/General_Perspective_projection)

And the following [presets](#use-a-projection-preset)

The `projection` output sent to the renderer is always of the shape:

`[from, to, transition]: [string, string, number]`

* `from` is the projection of lower zoom level
* `to` is the projection of higher zoom level
* `transition` is the interpolation value, going from 0 to 1, with 0 being in the `from` projection, and 1 being in the `to` projection.

In case `from` and `to` are equal, the `transition` will have no effect.

### Step between projection at discrete zoom levels

Use a `camera expression`, to discretely `step` between projections at certain zoom levels.

```json
type: ["step", ["zoom"],
    "vertical-perspective",
    11, "mercator"
]


output at zoom 10.9: "vertical-perspective"
output at zoom 11.0: "vertical-perspective"
output at zoom 11.1: "mercator"
```

### Animate between different projections based on zoom level

Use a `camera expression`, to animate between projections based on zoom, using `interpolate` function. The example below will yield an adaptive globe that interpolates from `vertical-perspective` to `mercator` between zoom 10 and 12.

```json
type: ["interpolate", ["linear"], ["zoom"],
    10,"vertical-perspective",
    12,"mercator"
]


output at zoom 9.9:  "vertical-perspective"
output at zoom 11:   ["vertical-perspective", "mercator", 0.5]
output at zoom 12:   ["vertical-perspective", "mercator", 1]
output at zoom 12.1: "mercator"
```

### Provide a `projection`

```json
type: ["vertical-perspective", "mercator", 0.7]
```

### Use a projection preset

There are also additional presets that yield commonly used expressions:

| Preset | Full value                                  | Description                                                                                                  |
|--------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| globe  | `["interpolate", ["linear"], ["zoom"], 10, "vertical-perspective", 12, "mercator"]` | Adaptive globe: interpolates from vertical-perspective to mercator projection between zoom levels 10 and 12. |

# Expressions

Source: https://docs.maptiler.com/gl-style-specification/expressions/

The value for any [layout property](../layers/#layout-property), [paint property](../layers/#paint-property), or [filter](../layers/#filter) may be specified as an _expression_. An expression defines a formula for computing the value of the property using the _operators_ described below. The set of expression operators provided by MapTiler SDK JS includes:

- Mathematical operators for performing arithmetic and other operations on numeric values
- Logical operators for manipulating boolean values and making conditional decisions
- String operators for manipulating strings
- Data operators, providing access to the properties of source features
- Camera operators, providing access to the parameters defining the current map view

Expressions are represented as JSON arrays. The first element of an expression array is a string naming the expression operator, e.g. [`"*"`](#*) or [`"case"`](#case). Elements that follow (if any) are the _arguments_ to the expression. Each argument is either a literal value (a string, number, boolean, or `null`), or another expression array.

```json
[expression_name, argument_0, argument_1, ...]
```

## [Data expressions](#data-expressions)

A _data expression_ is any expression that access feature data -- that is, any expression that uses one of the data operators: [`get`](#get), [`has`](#has), [`id`](#id), [`geometry-type`](#geometry-type), [`properties`](#properties), or [`feature-state`](#feature-state). Data expressions allow a feature's properties or state to determine its appearance. They can be used to differentiate features within the same layer and to create data visualizations.

```json
{
    "circle-color": [
        "rgb",
        // red is higher when feature.properties.temperature is higher
        ["get", "temperature"],
        // green is always zero
        0,
        // blue is higher when feature.properties.temperature is lower
        ["-", 100, ["get", "temperature"]]
    ]
}
```

This example uses the [`get`](#get) operator to get the `temperature` value of each feature. That value is used to compute arguments to the [`rgb`](#rgb) operator, defining a color in terms of its red, green, and blue components.

Data expressions are allowed as the value of the [`filter`](../layers/#filter) property, and as values for most paint and layout properties. However, some paint and layout properties do not yet support data expressions. The level of support is indicated by the "data-driven styling" row of the "SDK Support" table for each property. Data expressions with the [`feature-state`](#feature-state) operator are allowed only on paint properties.

## [Camera expressions](#camera-expressions)

A _camera expression_ is any expression that uses the [`zoom`](#zoom) operator. Such expressions allow the appearance of a layer to change with the map's zoom level. Camera expressions can be used to create the appearance of depth and to control data density.

```json
{
    "circle-radius": [
        "interpolate", ["linear"], ["zoom"],
        // zoom is 5 (or less) -> circle radius will be 1px
        5, 1,
        // zoom is 10 (or greater) -> circle radius will be 5px
        10, 5
    ]
}
```

This example uses the [`interpolate`](#interpolate) operator to define a linear relationship between zoom level and circle size using a set of input-output pairs. In this case, the expression indicates that the circle radius should be 1 pixel when the zoom level is 5 or below, and 5 pixels when the zoom is 10 or above. Between the two zoom levels, the circle radius will be linearly interpolated between 1 and 5 pixels

Camera expressions are allowed anywhere an expression may be used. When a camera expression used as the value of a layout or paint property, it must be in one of the following forms:

```json
[ "interpolate", interpolation, ["zoom"], ... ]
```

Or:

```json
[ "step", ["zoom"], ... ]
```

Or:

```json
[
    "let",
    ... variable bindings...,
    [ "interpolate", interpolation, ["zoom"], ... ]
]
```

Or:

```json
[
    "let",
    ... variable bindings...,
    [ "step", ["zoom"], ... ]
]
```

That is, in layout or paint properties, `["zoom"]` may appear only as the input to an outer [`interpolate`](../expressions/#interpolate) or [`step`](../expressions/#step) expression, or such an expression within a [`let`]../expressions/index.md/#let) expression.

There is an important difference between layout and paint properties in the timing of camera expression evaluation. Paint property camera expressions are re-evaluated whenever the zoom level changes, even fractionally. For example, a paint property camera expression will be re-evaluated continuously as the map moves between zoom levels 4.1 and 4.6. A _layout property_ camera expression is evaluated only at integer zoom levels. It will _not_ be re-evaluated as the zoom changes from 4.1 to 4.6 -- only if it goes above 5 or below 4.

## [Composition](#composition)

A single expression may use a mix of data operators, camera operators, and other operators. Such composite expressions allows a layer's appearance to be determined by a combination of the zoom level _and_ individual feature properties.

```json
{
    "circle-radius": [
        "interpolate", ["linear"], ["zoom"],
        // when zoom is 0, set each feature's circle radius to the value of its "rating" property
        0, ["get", "rating"],
        // when zoom is 10, set each feature's circle radius to four times the value of its "rating" property
        10, ["*", 4, ["get", "rating"]]
    ]
}
```

An expression that uses both data and camera operators is considered both a data expression and a camera expression, and must adhere to the restrictions described above for both.

## [Type system](#type-system)

The input arguments to expressions, and their result values, use the same set of [types](#types) as the rest of the style specification: boolean, string, number, color, and arrays of these types. Furthermore, expressions are _type safe_: each use of an expression has a known result type and required argument types, and the SDKs verify that the result type of an expression is appropriate for the context in which it is used. For example, the result type of an expression in the [`filter`](../layers/#filter) property must be [boolean](#boolean), and the arguments to the [`+`](#+) operator must be [numbers](#number).

When working with feature data, the type of a feature property value is typically not known ahead of time by the SDK. To preserve type safety, when evaluating a data expression, the SDK will check that the property value is appropriate for the context. For example, if you use the expression `["get", "feature-color"]` for the [`circle-color`](../layers/#circle-color) property, the SDK will verify that the `feature-color` value of each feature is a string identifying a valid [color](#color). If this check fails, an error will be indicated in an SDK-specific way (typically a log message), and the default value for the property will be used instead.

In most cases, this verification will occur automatically wherever it is needed. However, in certain situations, the SDK may be unable to automatically determine the expected result type of a data expression from surrounding context. For example, it is not clear whether the expression `["<", ["get", "a"], ["get", "b"]]` is attempting to compare strings or numbers. In situations like this, you can use one of the _type assertion_ expression operators to indicate the expected type of a data expression: `["<", ["number", ["get", "a"]], ["number", ["get", "b"]]]`. A type assertion checks that the feature data matches the expected type of the data expression. If this check fails, it produces an error and causes the whole expression to fall back to the default value for the property being defined. The assertion operators are [`array`](#array), [`boolean`](#boolean), [`number`](#number), and [`string`](#string).

Expressions perform only one kind of implicit type conversion: a data expression used in a context where a [color](#color) is expected will convert a string representation of a color to a color value. In all other cases, if you want to convert between types, you must use one of the _type conversion_ expression operators: [`to-boolean`](#to-boolean), [`to-number`](#to-number), [`to-string`](#to-string), or [`to-color`](#to-color). For example, if you have a feature property that stores numeric values in string format, and you want to use those values as numbers rather than strings, you can use an expression such as `["to-number", ["get", "property-name"]]`.

If an expression accepts an array argument and the user supplies an array literal, that array _must_ be wrapped in a `literal` expression (see the examples below). When GL-JS encounters an array in a style-spec property value, it will assume that the array is an expression and try to parse it; the library has no way to distinguish between an expression which failed validation and an array literal unless the developer makes this distinction explicit with the `literal` operator. The `literal` operator is not necessary if the array is returned from a sub-expression, e.g. `["in", 1, ["get", "myArrayProp"]]`.

```json
// will throw an error
{
    "circle-color": ["in", 1, [1, 2, 3]]
}

// will work as expected
{
    "circle-color": ["in", 1, ["literal", [1, 2, 3]]]
}
```

# [Expression reference](#expression-reference)

## [Types](#types)

The expressions in this section are for testing for and converting between different data types like strings, numbers, and boolean values.

Often, such tests and conversions are unnecessary, but they may be necessary in some expressions where the type of a certain sub-expression is ambiguous. They can also be useful in cases where your feature data has inconsistent types; for example, you could use `to-number` to make sure that values like `"1.5"` (instead of `1.5`) are treated as numeric values.

## array

Asserts that the input is an array (optionally with a specific item type and length). If, when the input expression is evaluated, it is not of the asserted type, then this assertion will cause the whole expression to be aborted.

### Syntax

```javascript
["array", value]: array
```

```javascript
["array", type: "string" | "number" | "boolean", value]: array
```

```javascript
["array",
    type: "string" | "number" | "boolean",
    N: number (literal),
    value
]: array
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.1 | >= 4.0.0 | >= 0.7.0 |

## boolean

Asserts that the input value is a boolean. If multiple values are provided, each one is evaluated in order until a boolean is obtained. If none of the inputs are booleans, the expression is an error.

### Syntax

```javascript
["boolean", value]: boolean
```

```javascript
["boolean", value, fallback: value, fallback: value, ...]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## collator

Returns a `collator` for use in locale-dependent comparison operations. The `case-sensitive` and `diacritic-sensitive` options default to `false`. The `locale` argument specifies the IETF language tag of the locale to use. If none is provided, the default locale is used. If the requested locale is not available, the `collator` will use a system-defined fallback locale. Use `resolved-locale` to test the results of locale fallback behavior.

### Syntax

```javascript
["collator",
    { "case-sensitive": boolean, "diacritic-sensitive": boolean, "locale": string }
]: collator
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## format

Returns a `formatted` string for displaying mixed-format text in the `text-field` property. The input may contain a string literal or expression, including an [`'image'`](#image) expression. Strings may be followed by a style override object that supports the following properties:

- `"text-font"`: Overrides the font stack specified by the root layout property.
- `"text-color"`: Overrides the color specified by the root paint property.
- `"font-scale"`: Applies a scaling factor on `text-size` as specified by the root layout property.

### Syntax

```javascript
["format",
    input_1: string | image, options_1: { "font-scale": number, "text-font": array, "text-color": color },
    ...,
    input_n: string | image, options_n: { "font-scale": number, "text-font": array, "text-color": color }
]: formatted
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.48.0 | >= 6.7.0 | >= 4.6.0 | >= 0.12.0 |
| text-font | >= 0.48.0 | >= 6.7.0 | >= 4.6.0 | >= 0.12.0 |
| font-scale | >= 0.48.0 | >= 6.7.0 | >= 4.6.0 | >= 0.12.0 |
| text-color | >= 1.3.0 | >= 7.3.0 | >= 4.10.0 | >= 0.14.0 |
| image | >= 1.6.0 | >= 8.6.0 | >= 5.7.0 | >= 0.15.0 |

## image

Returns an `image` type for use in `icon-image`, `*-pattern` entries and as a section in the `format` expression. If set, the `image` argument will check that the requested image exists in the style and will return either the resolved image name or `null`, depending on whether or not the image is currently in the style. This validation process is synchronous and requires the image to have been added to the style before requesting it in the `image` argument.

### Syntax

```javascript
["image", value]: image
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.4.0 | >= 8.6.0 | >= 5.7.0 | >= 0.15.0 |

## literal

Provides a literal array or object value.

### Syntax

```javascript
["literal", [...] (JSON array literal)]: array
```

```javascript
["literal", {...} (JSON object literal)]: object
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## number

Asserts that the input value is a number. If multiple values are provided, each one is evaluated in order until a number is obtained. If none of the inputs are numbers, the expression is an error.

### Syntax

```javascript
["number", value]: number
```

```javascript
["number", value, fallback: value, fallback: value, ...]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## number-format

Converts the input number into a string representation using the providing formatting rules. If set, the `locale` argument specifies the locale to use, as a BCP 47 language tag. If set, the `currency` argument specifies an ISO 4217 code to use for currency-style formatting. If set, the `min-fraction-digits` and `max-fraction-digits` arguments specify the minimum and maximum number of fractional digits to include.

### Syntax

```javascript
["number-format",
    input: number,
    options: { "locale": string, "currency": string, "min-fraction-digits": number, "max-fraction-digits": number }
]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.54.0 | Not yet supported | Not yet supported | Not yet supported |

## object

Asserts that the input value is an object. If multiple values are provided, each one is evaluated in order until an object is obtained. If none of the inputs are objects, the expression is an error.

### Syntax

```javascript
["object", value]: object
```

```javascript
["object", value, fallback: value, fallback: value, ...]: object
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## string

Asserts that the input value is a string. If multiple values are provided, each one is evaluated in order until a string is obtained. If none of the inputs are strings, the expression is an error.

### Syntax

```javascript
["string", value]: string
```

```javascript
["string", value, fallback: value, fallback: value, ...]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## to-boolean

Converts the input value to a boolean. The result is `false` when then input is an empty string, 0, `false`, `null`, or `NaN`; otherwise it is `true`.

### Syntax

```javascript
["to-boolean", value]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |


## to-color

Converts the input value to a color. If multiple values are provided, each one is evaluated in order until the first successful conversion is obtained. If none of the inputs can be converted, the expression is an error.

### Syntax

```javascript
["to-color", value, fallback: value, fallback: value, ...]: color
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## to-number

Converts the input value to a number, if possible. If the input is `null` or `false`, the result is 0. If the input is `true`, the result is 1. If the input is a string, it is converted to a number as specified by the ["ToNumber Applied to the String Type" algorithm](https://tc39.github.io/ecma262/#sec-tonumber-applied-to-the-string-type) of the ECMAScript Language Specification. If multiple values are provided, each one is evaluated in order until the first successful conversion is obtained. If none of the inputs can be converted, the expression is an error.

### Syntax

```javascript
["to-number", value, fallback: value, fallback: value, ...]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## to-string

Converts the input value to a string. If the input is `null`, the result is `""`. If the input is a boolean, the result is `"true"` or `"false"`. If the input is a number, it is converted to a string as specified by the ["NumberToString" algorithm](https://tc39.github.io/ecma262/#sec-tostring-applied-to-the-number-type) of the ECMAScript Language Specification. If the input is a color, it is converted to a string of the form `"rgba(r,g,b,a)"`, where `r`, `g`, and `b` are numerals ranging from 0 to 255, and `a` ranges from 0 to 1. Otherwise, the input is converted to a string in the format specified by the [`JSON.stringify`](https://tc39.github.io/ecma262/#sec-json.stringify) function of the ECMAScript Language Specification.

### Syntax

```javascript
["to-string", value]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## typeof

Returns a string describing the type of the given value.

### Syntax

```javascript
["typeof", value]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [Feature data](#feature-data)

## accumulated

Gets the value of a cluster property accumulated so far. Can only be used in the `clusterProperties` option of a clustered GeoJSON source.

### Syntax

```javascript
["accumulated"]: value
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.53.0 | Not yet supported | Not yet supported | Not yet supported |

## feature-state

Retrieves a property value from the current feature's state. Returns null if the requested property is not present on the feature's state. A feature's state is not part of the GeoJSON or vector tile data, and must be set programmatically on each feature. Features are identified by their `id` attribute, which must be an integer or a string that can be cast to an integer. Note that \["feature-state"\] can only be used with paint properties that support data-driven styling.

### Syntax

```javascript
["feature-state", string]: value
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.46.0 | Not yet supported | Not yet supported | Not yet supported |

## geometry-type

Gets the feature's geometry type: `Point`, `MultiPoint`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`.

### Syntax

```javascript
["geometry-type"]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## id

Gets the feature's id, if it has one.

### Syntax

```javascript
["id"]: value
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |


## line-progress

Gets the progress along a gradient line. Can only be used in the `line-gradient` property.

### Syntax

```javascript
["line-progress"]: number
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.5.0 | >= 4.6.0 | >= 0.12.0 |

## properties

Gets the feature properties object. Note that in some cases, it may be more efficient to use \["get", "property\_name"\] directly.

### Syntax

```javascript
["properties"]: object
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [Lookup](#lookup)

## at

Retrieves an item from an array.

### Syntax

```javascript
["at", number, array]: ItemType
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |


## get

Retrieves a property value from the current feature's properties, or from another object if a second argument is provided. Returns null if the requested property is missing.

### Syntax

```javascript
["get", string]: value
```

```javascript
["get", string, object]: value
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## has

Tests for the presence of an property value in the current feature's properties, or from another object if a second argument is provided.

### Syntax

```javascript
["has", string]: boolean
```

```javascript
["has", string, object]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## in

Determines whether an item exists in an array or a substring exists in a string.

### Syntax

```javascript
["in",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string)
]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.6.0 | >= 9.1.0 | >= 5.8.0 | >= 0.15.0 |

## index-of

Returns the first position at which an item can be found in an array or a substring can be found in a string, or `-1` if the input cannot be found. Accepts an optional index from where to begin the search.

### Syntax

```javascript
["index-of",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string)
]: number
```

```javascript
["index-of",
    keyword: InputType (boolean, string, or number),
    input: InputType (array or string),
    index: number
]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.10.0 | Not yet supported | Not yet supported | Not yet supported |

## length

Gets the length of an array or string.

### Syntax

```javascript
["length", string | array | value]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## slice

Returns an item from an array or a substring from a string from a specified start index, or between a start index and an end index if set. The return value is inclusive of the start index but not of the end index.

### Syntax

```javascript
["slice",
    input: InputType (array or string),
    index: number
]: OutputType (ItemType or string)
```

```javascript
["slice",
    input: InputType (array or string),
    index: number,
    index: number
]: OutputType (ItemType or string)
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.10.0 | Not yet supported | Not yet supported | Not yet supported |

## [Decision](#decision)

The expressions in this section can be used to add conditional logic to your styles. For example, the [`'case'`](#case) expression provides "if/then/else" logic, and [`'match'`](#match) allows you to map specific values of an input expression to different output expressions.

## !

Logical negation. Returns `true` if the input is `false`, and `false` if the input is `true`.

### Syntax

```javascript
["!", boolean]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## !=

Returns `true` if the input values are not equal, `false` otherwise. The comparison is strictly typed: values of different runtime types are always considered unequal. Cases where the types are known to be different at parse time are considered invalid and will produce a parse error. Accepts an optional `collator` argument to control locale-dependent string comparisons.

### Syntax

```javascript
["!=", value, value]: boolean
```

```javascript
["!=", value, value, collator]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| collator | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## <

Returns `true` if the first input is strictly less than the second, `false` otherwise. The arguments are required to be either both strings or both numbers; if during evaluation they are not, expression evaluation produces an error. Cases where this constraint is known not to hold at parse time are considered in valid and will produce a parse error. Accepts an optional `collator` argument to control locale-dependent string comparisons.

### Syntax

```javascript
["<", value, value]: boolean
```

```javascript
["<", value, value, collator]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| collator | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## <=

Returns `true` if the first input is less than or equal to the second, `false` otherwise. The arguments are required to be either both strings or both numbers; if during evaluation they are not, expression evaluation produces an error. Cases where this constraint is known not to hold at parse time are considered in valid and will produce a parse error. Accepts an optional `collator` argument to control locale-dependent string comparisons.

### Syntax

```javascript
["<=", value, value]: boolean
```

```javascript
["<=", value, value, collator]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| collator | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## \==

Returns `true` if the input values are equal, `false` otherwise. The comparison is strictly typed: values of different runtime types are always considered unequal. Cases where the types are known to be different at parse time are considered invalid and will produce a parse error. Accepts an optional `collator` argument to control locale-dependent string comparisons.

### Syntax

```javascript
["==", value, value]: boolean
```

```javascript
["==", value, value, collator]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| collator | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## \>

Returns `true` if the first input is strictly greater than the second, `false` otherwise. The arguments are required to be either both strings or both numbers; if during evaluation they are not, expression evaluation produces an error. Cases where this constraint is known not to hold at parse time are considered in valid and will produce a parse error. Accepts an optional `collator` argument to control locale-dependent string comparisons.

### Syntax

```javascript
[">", value, value]: boolean
```

```javascript
[">", value, value, collator]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| collator | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## \>=

Returns `true` if the first input is greater than or equal to the second, `false` otherwise. The arguments are required to be either both strings or both numbers; if during evaluation they are not, expression evaluation produces an error. Cases where this constraint is known not to hold at parse time are considered in valid and will produce a parse error. Accepts an optional `collator` argument to control locale-dependent string comparisons.

### Syntax

```javascript
[">=", value, value]: boolean
```

```javascript
[">=", value, value, collator]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |
| collator | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## all

Returns `true` if all the inputs are `true`, `false` otherwise. The inputs are evaluated in order, and evaluation is short-circuiting: once an input expression evaluates to `false`, the result is `false` and no further input expressions are evaluated.

### Syntax

```javascript
["all", boolean, boolean]: boolean
```

```javascript
["all", boolean, boolean, ...]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## any

Returns `true` if any of the inputs are `true`, `false` otherwise. The inputs are evaluated in order, and evaluation is short-circuiting: once an input expression evaluates to `true`, the result is `true` and no further input expressions are evaluated.

### Syntax

```javascript
["any", boolean, boolean]: boolean
```

```javascript
["any", boolean, boolean, ...]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## case

Selects the first output whose corresponding test condition evaluates to true, or the fallback value otherwise.

### Syntax

```javascript
["case",
    condition: boolean, output: OutputType,
    condition: boolean, output: OutputType,
    ...,
    fallback: OutputType
]: OutputType
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## coalesce

Evaluates each expression in turn until the first non-null value is obtained, and returns that value.

### Syntax

```javascript
["coalesce", OutputType, OutputType, ...]: OutputType
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## match

Selects the output whose label value matches the input value, or the fallback value if no match is found. The input can be any expression (e.g. `["get", "building_type"]`). Each label must be either:

- a single literal value; or
- an array of literal values, whose values must be all strings or all numbers (e.g. `[100, 101]` or `["c", "b"]`). The input matches if any of the values in the array matches, similar to the `"in"` operator. Each label must be unique. If the input type does not match the type of the labels, the result will be the fallback value.

### Syntax

```javascript
["match",
    input: InputType (number or string),
    label: InputType | [InputType, InputType, ...], output: OutputType,
    label: InputType | [InputType, InputType, ...], output: OutputType,
    ...,
    fallback: OutputType
]: OutputType
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## within

Returns `true` if the evaluated feature is fully contained inside a boundary of the input geometry, `false` otherwise. The input value can be a valid GeoJSON of type `Polygon`, `MultiPolygon`, `Feature`, or `FeatureCollection`. Supported features for evaluation:

- `Point`: Returns `false` if a point is on the boundary or falls outside the boundary.
- `LineString`: Returns `false` if any part of a line falls outside the boundary, the line intersects the boundary, or a line's endpoint is on the boundary.

### Syntax

```javascript
["within", object]: boolean
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 1.9.0 | >= 9.1.0 | >= 5.8.0 | >= 0.15.0 |

## [Ramps, scales, curves](#ramps-scales-curves)

## interpolate

Produces continuous, smooth results by interpolating between pairs of input and output values ("stops"). The `input` may be any numeric expression (e.g., `["get", "population"]`). Stop inputs must be numeric literals in strictly ascending order. The output type must be `number`, `array`, or `color`.

Interpolation types:

- `["linear"]`: Interpolates linearly between the pair of stops just less than and just greater than the input.
- `["exponential", base]`: Interpolates exponentially between the stops just less than and just greater than the input. `base` controls the rate at which the output increases: higher values make the output increase more towards the high end of the range. With values close to 1 the output increases linearly.
- `["cubic-bezier", x1, y1, x2, y2]`: Interpolates using the cubic bezier curve defined by the given control points.

### Syntax

```javascript
["interpolate",
    interpolation: ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2],
    input: number,
    stop_input_1: number, stop_output_1: OutputType,
    stop_input_n: number, stop_output_n: OutputType, ...
]: OutputType (number, array, or Color)
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.42.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## interpolate-hcl

Produces continuous, smooth results by interpolating between pairs of input and output values ("stops"). Works like `interpolate`, but the output type must be `color`, and the interpolation is performed in the Hue-Chroma-Luminance color space.

### Syntax

```javascript
["interpolate-hcl",
    interpolation: ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2],
    input: number,
    stop_input_1: number, stop_output_1: Color,
    stop_input_n: number, stop_output_n: Color, ...
]: Color
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.49.0 | Not yet supported | Not yet supported | Not yet supported |

## interpolate-lab

Produces continuous, smooth results by interpolating between pairs of input and output values ("stops"). Works like `interpolate`, but the output type must be `color`, and the interpolation is performed in the CIELAB color space.

### Syntax

```javascript
["interpolate-lab",
    interpolation: ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2 ],
    input: number,
    stop_input_1: number, stop_output_1: Color,
    stop_input_n: number, stop_output_n: Color, ...
]: Color
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.49.0 | Not yet supported | Not yet supported | Not yet supported |

## step

Produces discrete, stepped results by evaluating a piecewise-constant function defined by pairs of input and output values ("stops"). The `input` may be any numeric expression (e.g., `["get", "population"]`). Stop inputs must be numeric literals in strictly ascending order. Returns the output value of the stop just less than the input, or the first output if the input is less than the first stop.

### Syntax

```javascript
["step",
    input: number,
    stop_output_0: OutputType,
    stop_input_1: number, stop_output_1: OutputType,
    stop_input_n: number, stop_output_n: OutputType, ...
]: OutputType
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.42.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [Variable binding](#variable-binding)

## let

Binds expressions to named variables, which can then be referenced in the result expression using \["var", "variable\_name"\].

### Syntax

```javascript
["let",
    string (alphanumeric literal), any, string (alphanumeric literal), any, ...,
    OutputType
]: OutputType
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## var

References variable bound using "let".

### Syntax

```javascript
["var", previously bound variable name]: the type of the bound expression
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [String](#string)

## concat

Returns a `string` consisting of the concatenation of the inputs. Each input is converted to a string as if by `to-string`.

### Syntax

```javascript
["concat", value, value, ...]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## downcase

Returns the input string converted to lowercase. Follows the Unicode Default Case Conversion algorithm and the locale-insensitive case mappings in the Unicode Character Database.

### Syntax

```javascript
["downcase", string]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## is-supported-script

Returns `true` if the input string is expected to render legibly. Returns `false` if the input string contains sections that cannot be rendered without potential loss of meaning (e.g. Indic scripts that require complex text shaping, or right-to-left scripts if the the `MapLibre-gl-rtl-text` plugin is not in use in MapLibre GL JS).

### Syntax

```javascript
["is-supported-script", string]: boolean
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.6.1 | Not yet supported | Not yet supported |

## resolved-locale

Returns the IETF language tag of the locale being used by the provided `collator`. This can be used to determine the default system locale, or to determine if a requested locale was successfully loaded.

### Syntax

```javascript
["resolved-locale", collator]: string
```
| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.5.0 | >= 4.2.0 | >= 0.9.0 |

## upcase

Returns the input string converted to uppercase. Follows the Unicode Default Case Conversion algorithm and the locale-insensitive case mappings in the Unicode Character Database.

### Syntax

```javascript
["upcase", string]: string
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [Color](#color)

## rgb

Creates a color value from red, green, and blue components, which must range between 0 and 255, and an alpha component of 1. If any component is out of range, the expression is an error.

### Syntax

```javascript
["rgb", number, number, number]: color
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## rgba

Creates a color value from red, green, blue components, which must range between 0 and 255, and an alpha component which must range between 0 and 1. If any component is out of range, the expression is an error.

### Syntax

```javascript
["rgba", number, number, number, number]: color
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## to-rgba

Returns a four-element array containing the input color's red, green, blue, and alpha components, in that order.

### Syntax

```javascript
["to-rgba", color]: array
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [Math](#math)

## \-

For two inputs, returns the result of subtracting the second input from the first. For a single input, returns the result of subtracting it from 0.

### Syntax

```javascript
["-", number, number]: number
```

```javascript
["-", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.1 | >= 4.0.0 | >= 0.7.0 |

## \*

Returns the product of the inputs.
### Syntax

```javascript
["*", number, number, ...]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## /

Returns the result of floating point division of the first input by the second.

### Syntax

```javascript
["/", number, number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## %

Returns the remainder after integer division of the first input by the second.

### Syntax

```javascript
["%", number, number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |


## ^

Returns the result of raising the first input to the power specified by the second.

### Syntax

```javascript
["^", number, number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## +
### Syntax

```javascript
["+", number, number, ...]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## abs

Returns the absolute value of the input.

### Syntax

```javascript
["abs", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## acos

Returns the arccosine of the input.

### Syntax

```javascript
["acos", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## asin

Returns the arcsine of the input.

### Syntax

```javascript
["asin", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## atan

Returns the arctangent of the input.

### Syntax

```javascript
["atan", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## ceil

Returns the smallest integer that is greater than or equal to the input.

### Syntax

```javascript
["ceil", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## cos

Returns the cosine of the input.

### Syntax

```javascript
["cos", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |


## distance

Returns the shortest distance in meters between the evaluated feature and the input geometry. The input value can be a valid GeoJSON of type `Point`, `MultiPoint`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`, `Feature`, or `FeatureCollection`. Distance values returned may vary in precision due to loss in precision from encoding geometries, particularly below zoom level 13.

### Syntax

```javascript
["distance", object]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | Not yet supported | >= 9.2.0 | >= 5.9.0 | >= 0.16.0 |

## e

Returns the mathematical constant e.

### Syntax

```javascript
["e"]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## floor

Returns the largest integer that is less than or equal to the input.

### Syntax

```javascript
["floor", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.45.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## ln

Returns the natural logarithm of the input.

### Syntax

```javascript
["ln", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## ln2

Returns mathematical constant ln(2).

### Syntax

```javascript
["ln2"]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## log10

Returns the base-ten logarithm of the input.

### Syntax

```javascript
["log10", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## log2

Returns the base-two logarithm of the input.

### Syntax

```javascript
["log2", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## max

Returns the maximum value of the inputs.

### Syntax

```javascript
["max", number, number, ...]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## min

Returns the minimum value of the inputs.

### Syntax

```javascript
["min", number, number, ...]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## pi

Returns the mathematical constant pi.

### Syntax

```javascript
["pi"]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## round

Rounds the input to the nearest integer. Halfway values are rounded away from zero. For example, `["round", -1.5]` evaluates to -2.

### Syntax

```javascript
["round", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## sin

Returns the sine of the input.

### Syntax

```javascript
["sin", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## sqrt

Returns the square root of the input.

### Syntax

```javascript
["sqrt", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.42.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## tan

Returns the tangent of the input.

### Syntax

```javascript
["tan", number]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [Zoom](#zoom)

## zoom

Gets the current zoom level. Note that in style layout and paint properties, \["zoom"\] may only appear as the input to a top-level "step" or "interpolate" expression.

### Syntax

```javascript
["zoom"]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

## [Heatmap](#heatmap)

## heatmap-density

Gets the kernel density estimation of a pixel in a heatmap layer, which is a relative measure of how many data points are crowded around a particular pixel. Can only be used in the `heatmap-color` property.

### Syntax

```javascript
["heatmap-density"]: number
```

| SDK Support | MapLibre GL JS | Android SDK | iOS SDK | macOS SDK |
| --- | --- | --- | --- | --- |
| basic functionality | >= 0.41.0 | >= 6.0.0 | >= 4.0.0 | >= 0.7.0 |

# Tilestats

Source: https://docs.maptiler.com/guides/map-design/tilestats/

This page explains the term "tilestats" (tile statistics) and how they are actually very useful while working with your map, especially when adjusting the map style. You will learn how to find tilestats inside tiles.json file and how tilestats work for all attributes in data sources. You will also learn how to use tilestats while working with filters.

About tilestats
---------------

Tilestats or tile statistics are sometimes called also layer statistics of geostats. They aren't exactly statistics in the sense of the word. Tile statistics encapsulate comprehensive information regarding the layers within your tileset, offering insights into all attributes and geometry types associated with each layer. Tilestats also provide helpful information about available language mutations. In other words, tilestats give you a complete selection of parameters you can use when filtering features for your map. 

You can find layer statistics here: *Layers \- Block (or Layer) \- Data tab \- Add Filter*

![article_layer_statistics_1.png](./16750849385617_009565cd26.png)

In this picture, you can clearly see the historical center of Prague with just the "grass" class selected. The green areas show the grass, and the red areas show the areas that contain other (but not selected) classes \- in this case, it is "farmland" and "wood". The brownish areas show places where several classes overlap (wood and grass). If we select "farmland" "grass" and "wood", the map will look like this:

![article_layer_statistics_2.png](./16750869584529_7f49612537.png)

And this is what the map looks like when you switch it to the style editor. This is the place where you can see/edit the map the way you want to publish it.

![article_layer_statistics_3.png](./16751224435601_83f2ddf3d5.png)

### Example of tilestats for layer landcover

This is what the tilestats for the "landcover" layer look like inside the tiles.json code structure:

``` json
{  
  "layerCount": 1,  
  "layers": [  
    {  
      "layer": "landcover",  
      "geometry": "Polygon",  
      "attributes": [  
        {  
          "type": "String",  
          "values": [  
            "farmland",  
            "ice",  
            "wood",  
            "rock",  
            "grass",  
            "wetland",  
            "sand"  
          ],  
          "attribute": "class"  
        },  
        {  
          "type": "String",  
          "values": [  
            "allotments",  
            "bare_rock",  
            "beach",  
            "bog",  
            "dune",  
            "scrub",  
            "shrubbery",  
            "farm",  
            "farmland",  
            "fell",  
            "forest",  
            "garden",  
            "glacier",  
            "grass",  
            "grassland",  
            "golf_course",  
            "heath",  
            "ice_shelf",  
            "mangrove",  
            "marsh",  
            "meadow",  
            "orchard",  
            "park",  
            "plant_nursery",  
            "recreation_ground",  
            "reedbed",  
            "saltern",  
            "saltmarsh",  
            "sand",  
            "scree",  
            "swamp",  
            "tidalflat",  
            "tundra",  
            "village_green",  
            "vineyard",  
            "wet_meadow",  
            "wetland",  
            "wood"  
          ],  
          "attribute": "subclass"  
        }  
      ],  
      "attributeCount": 2  
    }  
  ]  
}
```

This tilestats example for the place layer reveals the following technical details:

* Number of layers: 1
* Layer name: landcover
* Geometry type: Polygon
* Attributes: Two attributes are associated with this layer.
	1. "class" of type String with a predefined set of values
	2. "subclass: of type String with a predefined set of values

### Example of tilestats for layer place

This is another example of the tilestats, this time for layer "place".

``` json
{  
  "languages": ["de","en","es","fr","it"],  
  "layerCount": 1,  
  "layers": {  
    "layer": "place",  
    "geometry": "Point",  
    "attributes": [  
      {  
        "type": "String",  
        "attribute": "name"  
      },  
      {  
        "type": "Number",  
        "values": [2,3,4,5,6],  
        "attribute": "capital"  
      },  
      {  
        "type": "String",  
        "values": [  
          "continent",  
          "country",  
          "state",  
          "province",  
          "city",  
          "town",  
          "village",  
          "hamlet",  
          "suburb",  
          "quarter",  
          "neighbourhood",  
          "isolated_dwelling",  
          "island"  
        ],  
        "attribute": "class"  
      },  
      {  
        "max": 54,  
        "min": 0,  
        "type": "Number",  
        "attribute": "rank"  
      }  
    ],  
    "attributeCount": 4  
  }  
}
```

This tilestats example for the "place" layer reveals the following technical details:

* Number of layers: 1
* Layer name: place
* Geometry type: Point
* Attributes: Four attributes are associated with this layer.  
	1. "name" of type String
	2. "capital" of type Number with values \[2, 3, 4, 5, 6]
	3. "class" of type String with a predefined set of values
	4. "rank" of type Number with a minimum value of 0 and a maximum value of 54
* Available languages \- language codes according to [ISO 639\-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) :  
	1. "de" \- German
	2. "en" \- English
	3. "es" \- Spanish
	4. "fr" \- French
	5. "it" \- Italian

How does it enhance Map Designer
-----------------------------

For attributes of string type \- like "class" or "subclass", a list of possible values is something that is going to help you design your map quicker and in a convenient way without having to guess the values for each filter you will use.

For numeric attributes like "rank" or "elevation", Map Designer can dynamically render range sliders, allowing users to fine\-tune the styling parameters with precision.

Now let's have a look at how you can use tilestats in all of the filters available in the Map Designer tool. 

### Filter types (visual filters)

Visual filters are great for anyone who wants to filter classes of each data source in their map in an easy and visually appealing way. Visual filters are designed to be as simple as possible and by simply clicking or un\-clicking a certain feature, they let you choose what goes into your data preview and what does not.

![article_layer_statistics_9.png](./16752194545425_627662733f.png)  

They are easy to re\-adjust or reset if you need to start from scratch. The reset button will mark all classes as "selected" (the exact opposite of what is shown in the picture).  

![article_layer_statistics_8.png](./16752194551953_e1bc2cf218.png)  

The visual filters are easy to scrap if you do not need them anymore.

![article_layer_statistics_10.png](./16752194561297_04b7ed50be.png)

### Filter types (native filters)

Native filters are the second type of filters available in the Map Designer tool. They will look familiar to those users who have been working with map design tools for several years already. They are, in fact, using a very similar flow as many open\-source design tools (e.g. Maputnik). The native filters work with the keywords (class names) which are added to or deleted from the textbox. The downside of this approach is that you have to remember all the classes in your data source if you want to work efficiently. The advantage is that you see fewer features, and your workspace is not cluttered with unnecessary content. Which way will you choose?

You can see the native filter dialog window in the picture below.

![article_layer_statistics_11.png](./16752194564113_b7c27707b4.png)

Native filters also work with logical operators that allow the user set different conditions for displaying the classes inside the data source.

![article_layer_statistics_12.png](./16752187773201_403ddc412f.png)

**The native filters offer the following list of values (logical operators):**

* \=\=   is queal to
* \=\=   is not queal to
* \=\=   is any of
* \=\=   is not any of
* \=\=   has any value
* \=\=   does not have value

### Geometry contained (geometry icons and geometry selection)

Geometry is another very important parameter that defines each data source. The most common geometry types supported in the Map Designer tool are a point, a line string, a polygon, or "mixed" (valid for data sources where multiple geometries at once are present. The geometry type is also one of the tile statistics which helps users optimize their work with the application.

![1.png](./16752598911121_621570abe9.png)

![2.png](./16752591920785_82c9bc149f.png)

![3.png](./16752591921041_028bcc5aa8.png)

### Data usage (red/green icons, understanding of how is data source used in style)

As shown at the beginning of this article different areas are shown in different colors relative to whether they are selected or not. In the first picture, it is just the "grass" class selected. The green areas show the grass, and the red areas show the areas that contain other (but not selected) classes \- in this case, it is "farmland" and "wood".

![article_layer_statistics_6.png](./16752722630545_d79fed8a0e.png)

And this is the same area, but this time no data source class is selected. The red color clearly shows the area where there are classes from the data source, but they are currently not selected. They are "grass", "farmland", and "wood". The red color is used to underline and stress the fact that there is something important missing on the map.

![article_layer_statistics_7.png](./16752717991825_7bec4c0f09.png)

### List of available languages

List of available languages is also contained within the tilestats. You can choose a language from the list in *Settings \-\> Worldview \-\> Language*  
  
![](./18565058255121_3442e37d9e.png)

How to create layer statistics
------------------------------

MapTiler provides an open\-source Tilestats tool which can be found in [GitHub repository](https://github.com/maptiler/tilestats). More information about the tool and how to use it can be found in this article: [Tilestats tools - How to generate tilestats for your own vector tiles](/guides/map-design/tilestats-tools-how-to-generate-tilestats-for-your-own-vector-tiles/)

Conclusion
----------

The tilestats or tile statistics are a great way to show a quick overview of all layers attributes in any tileset. Using layer statistics is very useful while filtering the content which you want (or don't want) to use in your map. Filtering is possible in two ways \- visual filtering and native filtering.

Useful links
------------

[Tilestats tools \- How to generate tilestats for your own vector tiles](/guides/map-design/tilestats-tools-how-to-generate-tilestats-for-your-own-vector-tiles)  
[MapTiler Countries dataset](/guides/map-tiling-hosting/data-hosting/maptiler-countries-dataset)  
[Origin of the MapTiler Planet data](/guides/map-tiling-hosting/data-hosting/origin-of-the-maptiler-planet-data)  
[How to download data from the MapTiler website](/guides/self-hosting/self-hosted-maps/how-to-download-data-from-maptiler-website)

# Tilestats tools - How to generate tilestats for your own vector tiles

Source: https://docs.maptiler.com/guides/map-design/tilestats-tools-how-to-generate-tilestats-for-your-own-vector-tiles/

#### Map design Tile statistics

This page describes how to generate tilestats and how to add them to your vector MBTiles.

Tilestats
---------

Tilestats or tile statistics, also known as geostats or layer statistics, encapsulate comprehensive information regarding the layers within your tileset, offering insights into all attributes and geometry types associated with each layer. Tilestats also provide helpful information about available language mutations.

You can find more about tilestats and how they enhance user experience in Map Designer in this article: [Tilestats.](/guides/map-design/tilestats)

Tilestats tool
--------------

MapTiler provides the Tilestats Tool, an utility for generating tile statistics. It's an open\-source project with its own [GitHub repository](https://github.com/maptiler/tilestats). The Tilestats Tool generates tilestats and provides their seamless integration into the metadata of MBTiles. Please,make sure that you use the version 2\.0\.0 or higher.

### How to install

To utilize the Tilestats Tool, you must first install it. Detailed installation instructions can be found at the [Installation](https://github.com/maptiler/tilestats#installation) section of README. Ensure you have the following prerequisites:

* Git
* npm (version greater than 16\)

The installation process involves the following steps:

``` bash
git clone   
cd tilestats   
npm i   
./bin/tilestats-generate --help
```

### How to generate tilestats into JSON file

The Tilestats Tool empowers users to generate tilestats for their MBTiles and save them in standalone JSON files. Execute the following command to achieve this:

``` bash
tilestats/bin/tilestats-generate path/to/your.mbtiles > tilestats.json
```

This command extracts tile statistics from your MBTiles and stores them in a JSON file, allowing for easy access and analysis of the generated tilestats. An example of such a JSON file and its structure is at the end of this article.

### How to generate tilestats into MBTiles metadata

If your objective is to generate tilestats and seamlessly integrate them into the metadata of your MBTiles, employ the "\-\-into\-md" option as follows:

``` bash
tilestats/bin/tilestats-generate path/to/your.mbtiles --into-md
```

By using this option, your tilestats are directly added to the MBTiles metadata, making them available for Map Designer .

### Advanced usage

For users seeking more advanced configuration options and capabilities, the Tilestats Tool offers a range of advanced features. To explore these options, execute:

``` bash
tilestats/bin/tilestats-generate --help
```

Additionally, consult the tool's [README](https://github.com/maptiler/tilestats?tab=readme-ov-file#readme) on its GitHub page for comprehensive guidance and detailed explanations of its advanced functionalities.

Tilestats example
-----------------

``` json
"tilestats":  
{  
  "languages": ["de","en","fr","it"],  
  "layerCount": 3,  
  "layers": [  
    {  
      "layer": "place",  
      "attributeCount": 4,  
      "attributes": [  
        {  
          "attribute": "name",  
          "type": "String"  
        },  
        {  
          "attribute": "class",  
          "type": "String",  
          "values": ["city","town","village"]  
        },  
        {  
          "attribute": "population",  
          "type": "Number",  
          "min": 12,  
          "max": 5213267  
        },  
        {  
          "attribute": "capital",  
          "type": "Boolean",  
          "values": [true,false]  
        }  
      ],  
      "geometry": "Point"  
    },  
    {  
      "layer": "transporation",  
      "attributeCount": 3,  
      "attributes": [  
        {  
          "attribute": "ref",  
          "type": "String"  
        },  
        {  
          "attribute": "type",  
          "type": "String",  
          "values": ["cycleway","ferry","motorway","rail"]  
        },  
        {  
          "attribute": "level",  
          "type": "Number",  
          "values": [0,1,2,3,4]  
        }  
      ],  
      "geometry": "LineString"  
    },  
    {  
      "layer": "water",  
      "attributeCount": 1,  
      "attributes": [  
        {  
          "attribute": "class",  
          "type": "String",  
          "values": ["lake","ocean","river"]  
        }  
      ],  
      "geometry": ["LineString","Polygon"]  
    },  
  ]  
}
```

This tilestats example for the place layer reveals the following technical details:

* Number of layers: 3  
	1. Layer name: "place"  
		+ Geometry type: "Point"
		+ Attributes: Four attributes are associated with this layer.  
			1. "name" of type String
			2. "class" of type String with a predefined set of values
			3. "population" of type Number with the minimum and maximum value
			4. "capital" of type Boolean
	2. Layer name: "transportation"  
		+ Geometry type: "LineString"
		+ Attributes: Four attributes are associated with this layer.  
			1. "ref" of type String
			2. "type" of type String with a predefined set of values
			3. "level" of type Number with a predefined set of values
	3. Layer name: "water"  
		+ Geometry type: "LineString" or "Polygon"
		+ Attributes: One attribute is associated with this layer.  
			1. "type" of type String with predefined set of values
* Available languages \- language codes according to [ISO 639\-1 codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes):  
	1. "de" \- German
	2. "en" \- English
	3. "es" \- Spanish
	4. "fr" \- French
	5. "it" \- Italian

Tilestats structure
-------------------

``` json
{
  // The list of all languages in the vector data
  "languages": Array
  // The number of layers in the source data (max. 1000)
  "layerCount": Number,
  // An array of details about the first 100 layers
  "layers": [
    {
      // The name of this layer
      "layer": String,
      // The geometry type(s) in this layer
      "geometry": String | Array,
      // The number of unique attributes in this layer (max. 1000)
      "attributeCount": Number
      // An array of details about the first 100 attributes in this layer
      "attributes": [
        {
          // The name of this attribute
          "attribute": String,
          // The type of this attribute's values
          "type": String, // More info below ...
          // An array of this attribute's if less than VALUES LIMIT unique values
          "values": [
            // ...
          ],
          // If there are more number values than VALUES LIMIT, the following
          // numeric stats will be reported instead
          "min": Number,
          "max": Number
        }
        // ...
      ]
    }
    // ...
  ]
}
```

Conclusion
----------

MapTiler provides an open\-source tool to generate tilestats into your own vector MBTiles. Tilestats greatly improve user experience when creating a custom style for your own tileset in Map Designer.

Useful links
------------

[Tilestats](/guides/map-design/tilestats)  
[How to make custom map design In MapTiler](/guides/map-design/how-to-make-custom-map-design-in-maptiler-cloud)  
[Global map settings](/guides/map-design/global-map-settings)  
[Layer styling](/guides/map-design/layer-styling)  
[Layer filters](/guides/map-design/layer-filters)

# MapTiler Server

Source: https://docs.maptiler.com/guides/on-prem/server/

[MapTiler Server](https://www.maptiler.com/server/) makes it possible to host and serve maps from your own hardware. Usually, it’s more convenient to host [with us online](https://www.maptiler.com/cloud/) because then you don't have to worry about the hosting infrastructure. Sometimes, however, you want *full control* over your maps to comply with strict security policies, or maybe your users need to access the maps in an *offline environment*. This is where map self-hosting comes into play.

To self-host a map, you'll need:

- **The hosting hardware**, which can be your personal computer, a dedicated on-prem server, or a virtual machine in your private cloud. 
- **MapTiler Server** installed on the hardware. It's the application that takes care of hosting and serving your maps.
- **The maps**. We provide a wide range of professional map styles and ready-to-use [map data](https://www.maptiler.com/data/) for self-hosting.
- Optionally, **custom data** that you want to add to the maps, such as your geodata visualizations or drone imagery.
- To make your on-prem maps searchable, you'll also need a **geocoding index**. [How to set up on-prem search](/guides/geocoding/on-premise-geocoding-in-maptiler-server/)

The resources below help you set it all up and make it work. 

-----

## Getting started

- [Install MapTiler Server](/guides/on-prem/server/installation/)
- [Deploy sample maps](/guides/on-prem/server/getting-started/)

## Working with maps

Learn how to prepare, customize, and view your self-hosted maps.

### Preparing map data

- [Add map data to MapTiler Server](how-to-add-and-host-data-in-maptiler-server)
- [Prepare your imagery for self-hosting](imagery-hosting-geotiff)
- [Combine multiple sets of map data into a **virtual tileset**](/guides/on-prem/server/virtual-tileset/)
- Serve map data from a database:
    - [Set up PostgreSQL](prepare-your-postgres-for-maptiler-server)
    - [Connect PostgreSQL](vector-tiles-from-postgresql)
    - [Use PostGIS and QGIS](how-to-import-spatial-data-to-postgis-for-maptiler-server)
    - [Advanced SQL editing](advanced-sql-editing)
- [Prevent label cropping](tile-margin-in-maptiler-server)

### Customizing map design

- [Try different map styles](how-to-work-with-map-styles-in-maptiler-server)
- [Prepare a custom map style](how-to-use-custom-map-styles-in-maptiler-server-export-from-cloud)
- [Adjust fonts and labels](how-to-work-with-fonts-and-labels-in-maptiler-server)
- [Prepare custom fonts](how-to-create-and-use-custom-fonts-in-maptiler-server)

### Viewing the maps

- [Present a static map](static-maps-in-maptiler-server)
- View in QGIS:
    - [Display your maps in QGIS](how-to-display-self-hosted-maps-from-maptiler-server-in-qgis)
    - [Display your maps in QGIS offline](use-maptiler-vector-tiles-on-local-offline-qgis-instance)
- [View in Tableau](on-premise-tableau-maps)

### Adding place search (geocoding)

- [On-prem geocoding for self-hosted maps](/guides/geocoding/on-premise-geocoding-in-maptiler-server/)

### Adding custom data

To add your own custom data to a map, you need to process it into a map-ready format with **MapTiler Engine**. Learn how in our [data processing documentation](/guides/map-tiling-hosting/data-processing/).

## Administration

Manage MapTiler Server and perform common administration tasks.

- [Use the Service API](maptiler-server-using-admin-api)
- [Monitor and improve performance](how-to-improve-and-monitor-maptiler-server-performance)
- [Access logs](how-to-access-logs-from-the-maptiler-server)
- [Submit a bug report](how-to-submit-a-bug-report-in-maptiler-server)

### License

- [Activate license online](license-activation-in-maptiler-server-online)
- [Activate license offline](license-activation-in-maptiler-server-offline)
- [Use floating license](floating-license-in-maptiler-server)

## Reference

- [Technical specification](maptiler-server-technical-specification)
- [CLI](maptiler-server-cli-command-line-interface)
- [Changelog](https://www.maptiler.com/server/changelog/)
- [API reference](/server/api)
- [OGC API — Tiles](ogc-api-tiles-server)

# Install MapTiler Server

Source: https://docs.maptiler.com/guides/on-prem/server/installation/

This section contains information how to set up and and run [MapTiler Server](/guides/self-hosting/map-server/) on various platforms and operating systems.

## System requirements

MapTiler Server has low hardware requirements and can run on virtually any platform. If you want to be sure that everything works smoothly, check the technical specification to see if your operating system and CPU architecture are officially supported and tested.

## Quick start

Looking just for basic guidance? Here's the fast track to a default installation:

1. [Download the installation package](https://www.maptiler.com/server/download/) and run it.
2. During installation, you set an **admin password** or get an auto-generated one. Copy it.
3. Open the admin interface at [http://localhost:3650/admin](http://localhost:3650/admin). 
4. Use your new admin password to log in.
5. Proceed to [deploy sample maps](/guides/on-prem/server/getting-started/).

If you need more info or want to *customize* your Server setup, see a detailed guide for your operating system (below).

## Basic installations 

These guides help you install MapTiler Server on your personal computer or a minicomputer, either for **trial** purposes or as a **basic production setup**.

- [Windows](/guides/on-prem/server/installation/windows/)
- [macOS](/guides/on-prem/server/installation/macos/)
- [Linux](/guides/on-prem/server/installation/linux/)
- [Raspberry Pi](/guides/on-prem/server/installation/raspberry-pi/)

## Network installations

These guides are intended for a **professional production setup**, virtualized environments, or when serving maps over a local network or the internet.

#### Container orchestration

- [Kubernetes](/guides/on-prem/server/installation/kubernetes/)
- [Docker](/guides/on-prem/server/installation/docker/)
- [Docker Compose](/guides/self-hosting/map-server/how-to-run-maptiler-server-using-docker-compose)

#### Web servers and HTTPS

- [Docker with HTTPS](/guides/self-hosting/map-server/how-to-install-maptiler-server-via-docker-with-https)
- [Nginx with HTTPS](/guides/self-hosting/map-server/maptiler-server-behind-nginx-with-https)
- [Apache](/guides/self-hosting/map-server/maptiler-server-behind-apache)
- [IIS (Windows Server) with HTTPS](/guides/self-hosting/map-server/https-access-to-maptiler-server-using-windows-server-and-microsoft-iis)

# Install and run MapTiler Server on Windows

Source: https://docs.maptiler.com/guides/on-prem/server/installation/windows/

This guide walks you through the installation of [MapTiler Server](/guides/self-hosting/map-server/) on Windows, covering the initial configuration and getting your local map APIs up and running.

## Install MapTiler Server

1. Get the installation package from the [download page](https://www.maptiler.com/server/download/).
2. Run the installation. It uses a standard Windows installation wizard to guide you through the process.



### Initial configuration

During the installation, you'll go over the following settings. We recommend to keep the pre-filled default values if you don't have a specific reason to change them:

- The **installation directory** where the MapTiler Server application will be located.
- The **root directory** where MapTiler Server will upload and store your maps. 
- The **port** over which MapTiler Server will communicate. It determines the local address where MapTiler Server runs.
- The **administrator password** for the MapTiler Server admin interface where you'll upload and manage your self-hosted maps. 

## Run MapTiler Server

After a successful installation, MapTiler Server starts automatically and your default browser opens at `http://localhost:3650/admin`. (If you have changed the default port during the setup, the address will be `http://localhost:/admin`.) Use your administrator password to log in. 

![Log in to MapTiler Server admin interface](/guides/on-prem/server/img/admin-log-in.png)

If the Windows firewall blocks the application, allow it manually. 

### Autostart

MapTiler Server is installed as a standard Windows service. This means that it starts automatically at system boot and runs in the background, making your map services available at all times without manual intervention. 

Because the `maptiler-server` service uses standard system protocols, you can control it using your preferred Windows management tools. For example, you can use the **Windows Services Manager** to change the service's `Startup type` if you prefer to launch MapTiler Server manually rather than automatically at startup.

## What's next

If you're testing MapTiler Server, the next step is to upload your maps. We recommend to 👉 [deploy our free sample maps](/guides/on-prem/server/getting-started/) to see how everything works.

If you're setting up production deployment, you'll want to [put MapTiler Server behind the IIS server](/guides/self-hosting/map-server/https-access-to-maptiler-server-using-windows-server-and-microsoft-iis/).

# Install and run MapTiler Server on macOS

Source: https://docs.maptiler.com/guides/on-prem/server/installation/macos/

This guide walks you through the installation of [MapTiler Server](/guides/self-hosting/map-server/) on macOS, including initial configuration. 

## Select package format

Get the installation package from the [download page](https://www.maptiler.com/server/download/). It's available in two different formats, each with a different setup method. Choose the one you prefer:

- **DMG:** Recommended for most users. Includes the app, a launcher, and the `servicify` tool for configuring MapTiler Server to run permanently as a background service.
- **ZIP:** Contains only the binary. Best for basic testing and manual re-installs.

The download pop-up automatically offers you the correct version of the installation package for your Mac architecture. 



## Install with DMG

1.  Download the DMG file and double-click it to open the copy window.

2.  Drag the **MapTiler Server** icon into the **Applications** folder.

    ![DMG installation: Drag and drop MapTiler Server to Applications](/guides/on-prem/server/img/macos-install-dmg.png)

3.  Go to **Applications** and double-click on **MapTiler Server** to run it. Your default browser opens at .

    ![Log in to MapTiler Server admin interface](/guides/on-prem/server/img/admin-log-in.png)

4.  Log in using the default password: `admin123`

### Change settings and set autostart (advanced)

To change the admin password, set up custom paths, and ensure that MapTiler Server starts automatically when you run your Mac, use the `servicify` tool. It requires admin rights so you need to run it in the terminal.

1.  Close any running MapTiler Server instances. How to do it: Open **Activity Monitor** and quit the `maptiler-server` app.

2.  Open your terminal and navigate to the application resources: 

    ```bash
    cd "/Applications/MapTiler\ Server.app/Contents/Resources"
    ```

3.  Run the installation script: 

    ```bash
    sudo ./servicify install
    ```

4.  Follow the prompts to configure MapTiler Server settings. Each prompt shows the default value; if you want to keep it, just hit `Enter`. You'll be able to set:

      * **User:** The system account running the service.
      * **Working directory:** Where maps and config are stored. 
      * **Port:** Part of MapTiler Server's local URL. Default is `3650`.
      * **Password:** A new admin password of your choice.

When done, `servicify` starts the new instance of MapTiler Server, running as a system service which automatically starts after login. 

To learn how to **stop** or **uninstall** the system service, run `sudo ./servicify` without arguments. *Please note that currently you need to restart your Mac after stopping the service.*

To check your working directory at any time, go to the admin interface directly. This is where you would upload your maps if you wanted to do it manually.

![Where to find your MapTiler Server's working directory](/guides/on-prem/server/img/macos-install-path.png)

## Install with ZIP

1.  Download and unpack the ZIP file.

2.  Double-click the `maptiler-server` executable. A terminal window opens, showing:

    - A newly generated **admin password**. Copy it to clipboard.
    - The local address where MapTiler Server runs: `http://localhost:/admin`. The default address is `http://localhost:3650/admin`.

    ![Terminal output after MapTiler Server installation](/guides/on-prem/server/img/macos-install-terminal-output.png)

3.  Open the local address in your browser and use the copied admin password to log in.

Note that closing the terminal window stops MapTiler Server.

### Run from command line

For more control, you can launch MapTiler Server directly from your favorite terminal. This allows you to set a custom working directory, port, and admin password in a single command. Switch to the folder with the unpacked ZIP file and run:

```bash
./maptiler-server --workDir= --port= --adminPassword=
```

To see all available configuration options, run: `./maptiler-server --help` 

**Note on directories:** Running via double-click defaults the working directory to your home folder (typically `/Users/`), while running via CMD defaults to the directory where you executed the command.

## Run as a background daemon (expert)

If you prefer manual control over the macOS background daemon (`launchd`) instead of using `servicify`, follow these steps:

1.  Create a property list file at `/Library/LaunchDaemons/com.maptiler.server.plist`:

    ```bash
    sudo nano /Library/LaunchDaemons/com.maptiler.server.plist
    ```

2.  Paste the following sample configuration, replacing `${VARIABLES}` with your absolute paths:

    ```xml
    
    
    
    
        Label
        com.maptiler.server
        Program
        ${PATH_TO_MAPTILER_SERVER_BINARY}
        ProgramArguments
        
            --workDir=${WORK_DIR}
            --port=${PORT}
        
        RunAtLoad
        
        WorkingDirectory
        ${WORK_DIR}
        StandardOutPath
        /var/log/maptiler-server.log
        StandardErrorPath
        /var/log/maptiler-server.err
    
    
    ```

3.  Load and start the service:

    ```bash
    sudo launchctl load /Library/LaunchDaemons/com.maptiler.server.plist
    ```

4.  Verify that the service is running (check for a PID):

    ```bash
    sudo launchctl list | grep com.maptiler
    ```

## What's next

With MapTiler Server up and running, you can now self-host some maps. To get started and see how MapTiler Server works 👉 [deploy our free sample maps](/guides/on-prem/server/getting-started/).rted/).

# Install and run MapTiler Server on Linux

Source: https://docs.maptiler.com/guides/on-prem/server/installation/linux/

This page describes the installation of [MapTiler Server](https://www.maptiler.com/server/) on Linux-based systems. 

## Install MapTiler Server

1. Get the installation package from the [Server download page](https://www.maptiler.com/server/download/). We provide DEB packages for Debian-based Linux distributions (Ubuntu, Debian, Mint, ...), RPM packages for RedHat-based distributions (Red Hat, Fedora, CentOS,...) and also universal AppImages.
2. Run the installation:

	- For DEB packages, use: `sudo dpkg -i maptiler-server-x.x.x.deb`
	- For RPM packages, use: `sudo rpm -i maptiler-server-x.x.x.rpm`
	- For AppImages, first allow the package to execute in file properties. (Alternatively, run `chmod u+x maptiler-server-X.X.X-linux.AppImage`.) Then double\-click on the package to install it.

### Run directly

When installed, start MapTiler Server:

```
maptiler-server
```

This command uses the current directory to start MapTiler Server, and generates a random password for the MapTiler Server administration. The password will be printed in the command line. Copy it and use it to log in at `http://localhost:3650/admin`. If you change the default port via a configuration file or environment variable, the address will be `http://localhost:/admin`.

If you want to change the administration password or other settings, run `maptiler-server --help` to list the options.

### Run as a service

Optionally, you can configure and start MapTiler Server as a `systemd` service, so that it keeps running on the machine even after the current user logs out:

```
sudo maptiler-server-servicify
```

This command starts a script which guides you through setting up MapTiler Server's working directory (use absolute path), port, and administration password. Then it creates the `systemd` service file and starts the service.

## What's next

If you've just installed MapTiler Server for the first time, we recommend our [Getting Started with MapTiler Server](/guides/self-hosting/map-server/getting-started) to set up map hosting and quickly test it out. You'll also learn how to set up MapTiler Server for real production deployment [at the end of the guide](/guides/self-hosting/map-server/getting-started/#next-steps).

--------------

## Troubleshooting

This sections helps solve the most common issues with **SELinux (RHEL)**. We use RHEL-8.2 as the reference system here.
 
### Issues with FUSE

MapTilerServer Linux packages use [AppImage](https://en.wikipedia.org/wiki/AppImage) distribution format under the hood, which is based on [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace).

If starting your server results in errors like this:

`fuse: failed to exec fusermount: No such file or directory`

You have to fix your FUSE setup. On reference system, this was easy to fix just with fuse install:

`yum install fuse`

In case you are not able to fix your FUSE setup, you can try to run the server this way

`maptiler-server --appimage-extract-and-run --port=3650`

### Tiles rasterization

Rasterization library we use in MapTiler Server requires `execheap` memory access. If your server is crashing with error similar to:

`swiftshader-1cba0a9c3a8a1961514ac63cd3091c1a376fe84a/src/Reactor/ExecutableMemory.cpp:352
WARNING: ASSERT(result == 0)`

It means that SELinux policies are preventing MapTiler Server from using this access mode.

Like with any other SELinux issues, checking the systemd journal can be helpful:

`systemctl`

You will find here something like:

*SELinux is preventing maptiler-server from using the execheap access on a process.*

You can disable this policy with:

`setsebool -P selinuxuser\_execheap 1`

Or with help from utils you can create a local policy module to allow this access:

`ausearch -c 'maptiler-server' --raw | audit2allow -M my-maptilerserver
semodule -i my-maptilerserver.pp`

As the last resort, try turning the SELinux off.

# Install and run MapTiler Server on Raspberry Pi

Source: https://docs.maptiler.com/guides/on-prem/server/installation/raspberry-pi/

[MapTiler Server](https://www.maptiler.com/server/) supports the ARM64 architecture, allowing you to host maps on Raspberry Pi minicomputers. This lightweight, portable setup is ideal for self-hosting maps on the go, including offline environments.

## Before you start

If your Raspberry Pi device is new, make sure to:

1. Install **Raspberry Pi OS** (64-bit) or another Debian-based ARM64 distribution.
2. Set up **wi-fi connection**. 

For help with these tasks, please refer to the [official Raspberry Pi documentation](https://www.raspberrypi.com/documentation/computers/getting-started.html). 

As a storage for your maps, we recommend a **microSD card** with at least 32 GB of space. You can also use the card for transferring the Server installation package to your Pi.

### Technical requirements

- Only **64-bit** devices are compatible (Raspberry Pi 3 and later).
- A minimum of **2 GB RAM** is required. MapTiler Server may run on a device with less memory, but will be only usable for basic testing. See the full [technical specification](/guides/self-hosting/map-server/maptiler-server-technical-specification). 

## Install MapTiler Server

1. Go to [Server download page](https://www.maptiler.com/server/download/).
2. Get the **Debian (ARM64)** installation package. *There are two Debian package versions available. Be careful to select the one for ARM64 architecture!*
3. Open the command line terminal and switch to your download folder: 

    ```bash
    cd /home//Downloads
    ```

4. Run the installation using the filename with your version number: 

    ```bash
    sudo dpkg -i maptiler-server-.deb
    ```

## Run MapTiler Server

1. When installed, start the application from the terminal: 

    ```bash
    maptiler-server
    ```

2. The command automatically generates an **admin password**. Copy it from the terminal output.
3. Open a web browser and go to the MapTiler Server interface at `http://localhost:3650/admin/`. If you have changed the default port, the address will be `http://localhost:/admin/`.
4. Log in using the generated admin password. 

To change the administration password or other settings, run `maptiler-server --help` to list the options.

### Remote (headless) access

The steps to access the MapTiler Server admin interface assume that you have a monitor, mouse, and keyboard connected to the Raspberry Pi and are working on the device directly. However, if you're connecting via SSH from another computer on the same network, you need to use Raspberry Pi's **IP address** instead of localhost:

1. Find your Pi's IP address by running `hostname -I` in the terminal.
2. On your primary computer, open a browser and go to `http://:/admin/`.

## Set up autostart

Optionally, configure MapTiler Server to start automatically when the Raspberry Pi boots:

1. Run the service configuration script: 

    ```bash
    sudo maptiler-server-servicify
    ```
    
2. Follow the prompts to set up your working directory (use absolute path), port, and custom admin password. 

The script creates a `systemd` service and starts it immediately.

## What's next

MapTiler Server is now running and you can proceed to 👉 [deploy sample maps](/guides/self-hosting/self-hosted-maps/maptiler-data-sample-package/).

## Community resources

For a fun step-by-step walkthrough that includes building a demo map application, see [MapTiler Server on Raspberry Pi – A Geeks' Guide to Self-Hosted Maps](https://dev.to/bolollo/maptiler-server-on-raspberry-pi-a-geeks-guide-to-self-hosted-maps-19d4) on DEV.to.

# How to run MapTiler Server in Kubernetes

Source: https://docs.maptiler.com/guides/on-prem/server/installation/kubernetes/

This page provides instructions on how to run MapTiler Server in Kubernetes using our pre-configured Helm chart.

## Prerequisites

* Running Kubernetes cluster with at least 1 node.
* Running [Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/).
* [Helm](https://helm.sh) installed.

## Steps

1. Install the MapTiler Server Helm chart:

     ``` bash
     helm repo add maptiler https://labs.maptiler.com/maptiler-server-kubernetes/  
     ```

2. Deploy MapTiler Server on the Kubernetes cluster in the default configuration:

     ``` bash
     helm install maptiler-server-app maptiler/maptiler-server
     ```

Complete documentation of the MapTiler Server Helm chart is available at [Artifact Hub](https://artifacthub.io/packages/helm/maptiler/maptiler-server).

## Sample configurations

### nginx Ingress controller

Here’s a sample nginx [Ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) that you can use in the **values.yaml** file included in the Helm chart.

- To use [custom max body size](https://github.com/kubernetes/ingress-nginx/blob/main/docs/user-guide/nginx-configuration/annotations.md#custom-max-body-size) for nginx requests, define the `nginx.ingress.kubernetes.io/proxy-body-size` annotation.
- If you want to use TLS, you need to [create a Kubernetes TLS secret](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret_tls/) named **maptiler\-server\-tls** first.

``` yaml
ingress:  
  enabled: true  
  className: nginx  
  annotations:  
    nginx.ingress.kubernetes.io/proxy-body-size: 300m  
  hosts:  
    - host: maps.company.com  
      paths:  
        - path: /  
          pathType: Prefix  
  tls:  
    - secretName: maptiler-server-tls  
      hosts:  
        - maps.company.com
```

### Shared storage

If you plan to run multiple replicas of MapTiler Server with shared tileset data and configuration, you need to make sure that each replica can access the same [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) where the data and config is stored. To do that, configure the Persistent Volume Claim to use a [Storage Class](https://kubernetes.io/docs/concepts/storage/storage-classes/) which supports the [ReadWriteMany](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) access mode. Alternatively, you can set up an NFS storage.

Here’s a sample Persistent Volume configuration for the **values.yaml** file:

``` yaml
storage:  
  storageClassName: csi-cinder-classic  
  size: 20Gi  
  
volumes:  
  - name: maptiler-server-data  
    persistentVolumeClaim:  
      claimName: maptiler-server-app  
  
volumeMounts:  
  - mountPath: /data/  
    name: maptiler-server-data
```

# How to install MapTiler Server as a Docker image

Source: https://docs.maptiler.com/guides/on-prem/server/installation/docker/

Installation
------------


To install MapTiler Server as a Docker image, use the following command:



```
docker pull maptiler/server
```

Get Started
-----------


There is one command to run MapTiler Server from the command line, anywhere with your GeoPackage or MBTiles in the current working directory:



```
docker run -p 3650:3650 -v "$(pwd)":/data/ maptiler/server
```





### License activation


Your license can be passed with the `-e MAPTILER_SERVER_LICENSE=...` parameter to the Docker image. The software will be automatically deactivated at the end of execution (for example, sending a SIGTERM signal). You can get your MapTiler Server license token from the [Data dashboard](https://data.maptiler.com/server/?utm_source=documentation&utm_medium=description%20%7C%20license&utm_content=license).



```
# Get your MapTiler Server license token from Data dashboard: data.maptiler.com/server/
export MAPTILER_SERVER_LICENSE=ABCDEF-ABCDEF-ABCEDF-ABCDEF
docker run -p 3650:3650 -e MAPTILER_SERVER_LICENSE -v "$(pwd)":/data/ maptiler/server
```

You can prepare an alias for running MapTiler Server



```
alias maptiler-server="docker run -p 3650:3650 -e MAPTILER_SERVER_LICENSE=ABCDEF-ABCDEF-ABCEDF-ABCDEF -v $(pwd):/data/ maptiler/server"

maptiler-server

```

Custom working directory
------------------------


To start serving tiles and maps from your local dir `$WORK_DIR`, use:



```
docker run -p 3650:3650 -v $WORK_DIR:$WORK_DIR maptiler/server --workDir=$WORK_DIR

```

Help
----


Check all supported arguments for the command line:



```
 docker run maptiler/server --help

```

License Deactivation
--------------------


If you put your license in as an environment variable, it will be automatically deactivated during each shutdown of the Docker container. If you fail to shut down your Docker container correctly, your license activation will be "stuck in limbo". If this happens, don't hesitate to contact MapTiler Support for help; they will deactivate your license key.


Useful links
------------


[Docker hub](https://hub.docker.com/r/maptiler/server)  
[MapTiler Server Tutorials](/guides/self-hosting/map-server/)

# Get started with MapTiler Server (trial): Deploy sample maps

Source: https://docs.maptiler.com/guides/on-prem/server/getting-started/

The quickest way to explore [MapTiler Server](/guides/self-hosting/map-server/) and the essential first step for any setup is to deploy our **free sample maps package**. This is the primary way to obtain our professional map styles (designs) together with sample data to test them out. Whether you are starting a trial to evaluate the platform or preparing a full production environment, this package provides the styling foundation needed to make any additional map data work.

At the end of this guide, you'll have:

- A fully functional *local Maps API* running on your machine.
- Our professional *map styles*, ready for importing more data to show the world.
- *Sample map data* for Zurich (Switzerland) to preview the map styles immediately.
- An *application example* with instructions to quickly test the local API.

## Prerequisites

MapTiler Server [installed and running](/guides/on-prem/server/installation/).

## Deploy the map package

1. [Open this link](https://data.maptiler.com/my-extracts/?sample) and download the **map package**. Note that the download may take some time due to the package size.

2. Open the MapTiler Server admin interface, by default at [http://localhost:3650/admin](http://localhost:3650/admin).

3. Use the **New map** button to upload the zipped map package. Alternatively, drag and drop it onto the page.

![New map button](../img/new-map-button.png)

The upload automatically populates your MapTiler Server:

- The **Datasets** section now contains the raw data for your maps. The data included in the starter package is intended for testing, and only covers the Zurich region in Switzerland.
- The **Maps** section lists the map styles (designs). The package provides you with a selection of [our maps](https://www.maptiler.com/maps/) for various purposes to get you started.

[Learn more about data, map styles, and how they relate.](/guides/how-maps-work/)



## Preview and test the maps {#testMaps}

With the maps uploaded, let's see how to display them to their audience. Note that the following examples will only work on your computer and *can't be used to test remote access* to the self-hosted maps. The goal here is to give you an idea of presentation options and let you explore the maps. 



  Remember that the sample package only contains map data for Zurich, which means that the maps get clipped when you zoom out of the Zurich area. This won't happen once you use professional map data available with our paid plans.



### Check public preview

The map upload makes the demo maps available not only in the [administration interface](http://localhost:3650/admin/), but also on the [public preview](http://localhost:3650/). Visit it to see the maps presentation to a non-admin user. This is a simple way to quickly explore the self-hosted map styles.

### Test an API endpoint

1. In the **Maps** section, choose one of the listed maps and use the **Detail** button next to it. This takes you to a page with the map preview and a list of prepared API calls for various uses.
2. Use the **View fullscreen** button below the map. This opens a new tab in your web browser and displays the simplest fullscreen view of the map. The URL in the address bar corresponds to the API request that loaded the map view.

### Test a simple web app

Follow the steps below to see how you can combine your self-hosted map with custom data. You can also [watch it on video](https://vimeo.com/1080820909/2178b2e8f1).

1. Copy the following code and save it as a HTML file on your computer. 

    

2. Open the file in your web browser. What you see is your self-hosted **Dataviz** map displayed using [MapTiler SDK](/sdk-js/), with additional data on top of it. The additional data is pulled from [this file](/sdk-js/assets/zurich-hotels.geojson) which lists hotels in Zurich. They're shown on the map as blue dots.

     ![Example of a local map application](../img/map-app-example.png)
     
3. Open the file in a code editor and find this line:
   
     `style: "http://localhost:3650/api/maps/dataviz/style.json",`

     It refers to the **Dataviz** map style. Replace `dataviz` with another map style hosted in your MapTiler Server, for example `streets`, and reload the browser view to see the hotels data layer on a different map.

## Next steps {#nextSteps}

With the sample maps running, here's what to do next:

- **Mind the license.** The free version you've just deployed is for trial or non-commercial use only. Before you proceed to live production setup, make sure to check out the [features and pricing](https://www.maptiler.com/data/pricing/) of the commercial version of MapTiler Server and data. 

- **Get more map data.** The maps (styles) in the sample package are fully functional out-of-the-box, but they won't show the whole world because the sample package only contains data for the Zurich region. To make your self-hosted maps work correctly in other areas as well, you'll need additional datasets. We offer detail-rich, professionally maintained datasets as well as free OpenStreetMap data.

- **Build your map app.** Explore our [SDK JS](/sdk-js/), particularly the [code examples](/sdk-js/examples/), to see how you can build a browser-based application with your on-prem maps. Also, check how you can implement [on-prem map search](/guides/geocoding/on-premise-geocoding-in-maptiler-server/) that can work completely offline.

# How to add and host data in MapTiler Server

Source: https://docs.maptiler.com/guides/self-hosting/map-server/how-to-add-and-host-data-in-maptiler-server/

This page shows how to add packages of geographical data to MapTiler Server and how to set up the process of data hosting. Follow the steps on this page to build a map with MapTiler Server.

Get your data
-------------


Three main ways how to obtain data for your map project are:



* [Download MapTiler data](#download-maptiler-data)
* [Generate your own using MapTiler Engine](#generate-your-own-using-maptiler-engine)
* [Get geodata from somewhere else](#get-geodata-from-somewhere-else)



### Download MapTiler data


Navigate to the [MapTiler data](https://data.maptiler.com/).


![](./4411329153169_d7d7d43c57.png)


 


Go to the [Datasets](https://www.maptiler.com/on-prem-datasets/planet/) section.


![](./4411329153681_d0bc5404ad.png)


 


Here browse by dataset or continent → country → region, alternatively, you can search for your preferred location.


![](./4411321514001_b450582a12.png)


 


When you have your area of interest selected, click on the Show Detail button for all datasets you want to get:


* **OpenStreetMap** for buildings, roads, natural phenomenons, administrative boundaries, and much more
* **Contour lines** for vector contours
* **Hillshade** for raster hill shading
* **Satellite** raster tiles for color\-toned satellite imagery


Bear in mind, that other datasets like **S****atellite 2021**, **Terrain RGB**,   
**Terrain 3D \- Cesium quantized mesh**, **MapTiler Planet Lite**, or **Landcover** are **only available for downloading the whole Planet**.  


Alternatively, you can click on the Custom Region option to get areas that are not specified in our selection.


![](./4411329156497_2da5431fa4.png)


Generate your own using MapTiler Engine
---------------------------------------


[MapTiler Engine](https://www.maptiler.com/engine/) is able to process your raster images and vector data into map tiles. If you need to turn your geodata into map tiles, read [this how\-to](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-raster-data) for raster tiles and [this how\-to](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-vector-data) for vector tiles.


![](./4411321516177_1ef6d85aff.png)


### Get geodata from somewhere else


MapTiler Server is able to serve MBTiles and GeoPackage files generated by third\-party software. 





Data generated by third\-party software can be served only with a commercial MapTiler Server.  
Check our MapTiler data subscription offer [here](https://www.maptiler.com/data/pricing/).  
  





Upload the data to the server
-----------------------------


Uploading content to a remote server can be annoying. MapTiler Server supports direct upload from its web administration interface. Either drag and drop it in the list area or use the upload button.   
The following file formats are supported:


* **tiles \-** mbtiles or geopackage data are uploaded directly into `$workingDirectory`
* [MapTiler data starter pack](https://data.maptiler.com/server) \- zip containing:


	+ tiles data \- extracted directly into `$workingDirectory`
	+ maps \- extracted into `$workingDirectory/maps`
	+ fonts \- extracted `$workingDirectory/fonts`
* **maps** \- `yourMap.zip` containing `style.json` and `sprites` will be extracted under `$workingDirectory/maps/yourMap/`


MapTiler Server **working directory** can be specified during installation (Windows) / servicification (Linux) or as a CLI parameter \\-\-workDir during on server run. In this directory, server configuration config.json is created and it is the place for map data you want to serve.

When your data is uploaded, you have to publish it to be available for your users.

To do so, go to the Tiles tab, and click on Publish button for each dataset you wish to be published.

![](./4411335057425_b6289a82cf.png)


Style the vector tiles
----------------------


If you have vector tiles and want to use them (or rasterize) you need to define how the map will look like via map styles.


[Read the standalone how\-to](/guides/self-hosting/map-server/how-to-work-with-map-styles-in-maptiler-server), to learn more.


Use your maps
-------------


By clicking on the **Details** for each map style, you will get:


* Embeddable viewer that you can use in an **iframe**
* JSON style you can use in **OpenLayers** or **MapTiler SDK** viewers or **mobile SDK**
* XYZ and TileJSON for **Leaflet,****OpenLayers,** or **MapTiler SDK** viewers or **mobile SDK**
* WMTS or WMS service for desktop GIS applications like **ArcGIS** or **QGIS**
* Vector TMS for **Tableau** data visualizations


![](./4411329163409_6dd1a63615.png)


Useful links
------------


[MapTiler Server Pricing](https://www.maptiler.com/server/pricing/)  
[Download MapTiler Server](https://www.maptiler.com/server/download/)

# How to work with map styles in MapTiler Server

Source: https://docs.maptiler.com/guides/self-hosting/map-server/how-to-work-with-map-styles-in-maptiler-server/

Map Style is a style.JSON document that defines the visual appearance of a map. Style includes information about data sources, such as OpenMapTiles or MapTiler Planet, and the specific styling of the selected layers. All this information can be modified based on the needed purpose of the map.


![](./4409875635601_7409495a38.png)


The data on the left is a raw OpenMapTiles dataset (Dallas). On the right is the same are with the Streets map style applied.


  
We prepared **ready\-to\-use map styles** that cover most of the use cases and fit perfectly with the MapTiler data. Alternatively, you can download a third\-party map style and adjust it or create your own from scratch.


### MapTiler sample data package

To get the sample data package and learn more about it, go to [MapTiler Server sample package](/guides/self-hosting/self-hosted-maps/maptiler-data-sample-package/).

### Preview the sample data with map styles


Once you load your **map styles zip file** into the software, you will be able to preview the content of the sample data. In the **Tiles** tab, you can preview the raw osm dataset of the Zurich area. In **Maps,** you can preview that particular dataset, together with beautiful **map styles** on top of it.


The Map Styles package contains **Basic**, **Dataviz, Outdoor**, **Satellite Hybrid,** and **Streets** styles.


![Screenshot_2022-11-29_at_15.29.24.png](./16109877777297_47aac92b8e.png)


*(**Zurich with bright map style)*


Bear in mind that you will be able to fully zoom ([zoom level](https://maptiler.com/google-maps-coordinates-tile-bounds-projection/#resolution-and-scales) 0 to 14 and 18\+ over zoom) only to the Zurich area, as this is the default dataset we included in the sample package. The exception here is **Satellite\-Hybrid** Map Style where the zoom levels for the whole planet are 0 to 6, with over zoom available.


### Preview other data with the map styles


If you haven't added your data to MapTiler Server yet, you can do it, by navigating to the **Tiles** tab in MapTiler Server and selecting "NEW TILES". Now drag and drop the MBtiles or Geopackage file into the software. Read more here: [How to add and host data in MapTiler Server](/guides/self-hosting/map-server/how-to-add-and-host-data-in-maptiler-server)


If you need guidance on how to download other free data we offer, read this article:   
[How to try MapTiler Server using free MapTiler data](/guides/self-hosting/map-server/getting-started)


 


Map Styles by default are attached to the Zurich dataset that is part of MapTiler sample data. If you want to connect your style.json to other datasets you can do it by using one of the following methods:


 *Change the name of Zurich Dataset to any different name \[e.g zurich\-osm] or delete it.)*  
Rename the downloaded file to "maptiler\-osm". You can do it by hitting on the "DETAIL" button of the downloaded dataset in the **Tiles** tab and then pressing "CHANGE ID".  
![Screenshot_2022-11-30_at_12.29.32.png](./16109877779089_7820a446dd.png) *The path to finding the map styles is at the top of the "MAPS" tab in MapTiler Server).*  
Edit your favorite map style (e.g. maps → streets → style.json) and at the very bottom of the file, replace the URL of the source with the filename of the data you downloaded  
*(e.g replace `"url": "#maptiler-osm"` with  `"url": "#osm-2020-07-03-v3.6.1_europe_germany.mbtiles"` if you want this map style to serve the OSM dataset of Germany)  
![Screenshot_2023-03-16_at_11.21.30.png](./16109829993873_5be8f350bb.png)*


You can now preview the dataset with your favorite map style.   
  
You might not be able to see the full value of the Map Style design as it consists of various datasets and the ones included in the free Map Style Package include data for **Zurich Area only**. To be able to download datasets in other regions, you need to [purchase the map data](https://www.maptiler.com/data/pricing/).


 


![Screenshot_2022-12-01_at_12.59.43.png](./16109877783697_7b4745f2fe.png)


*(Berlin with streets map style)*


Customizing your own Map Style
------------------------------


If the Map Styles that are part of the package are not enough for you, there is a way to customize your own map style and use it in MapTiler Server. To be able to do so you need to go through the process of [customizing and exporting the map style](/guides/self-hosting/map-server/how-to-use-custom-map-styles-in-maptiler-server-export-from-cloud).

# Set up on-prem geocoding (map search)

Source: https://docs.maptiler.com/guides/on-prem/server/geocoding/

[Geocoding](https://www.maptiler.com/cloud/geocoding/) makes it possible to search your maps. We provide the functionality from our cloud but it's also possible to self-host it, and this page explains how.

The key component of the search functionality is a **geocoding index** – a data structure that stores all searchable locations. At MapTiler, we have professionally maintained geocoding indexes for the whole world, and you can use them via our [online Geocoding API](https://www.maptiler.com/cloud/geocoding/). To use them on-prem or completely offline, you need to set them up in your self-hosted environment. By doing that, you'll get a [local Geocoding API](/server/api/geocoding/) which works just like the online one, and you can use it to add a **search box** ([geocoding control](/sdk-js/modules/geocoding/)) to your on-prem maps. 

## Before you start

Before you get to the geocoding setup itself, make sure that [MapTiler Server](/guides/self-hosting/map-server/) is installed and you have some maps ready. If you need help with these tasks, follow the 👉 [Getting started with MapTiler Server](/guides/self-hosting/map-server/getting-started/) guide. 

#### Technical requirements

The geocoding service will run smoothly on a hosting machine with the following parameters:

- 2GHz dual-core CPU
- 4+ GB RAM 
- 200+ GB of free HDD space for global geocoding indexes

For complete specs, see the [MapTiler Server technical specification](/guides/self-hosting/map-server/maptiler-server-technical-specification/).

## Set up the endpoint

First, let's set up the [local Geocoding API](/server/api/geocoding/) endpoint. We'll use a sample geocoding index, which is much smaller than full global indexes and thus more suitable for testing. The sample index only works for Switzerland, so you can test it together with the [sample package](/guides/self-hosting/self-hosted-maps/maptiler-data-sample-package/) which contains map data for the Zurich area in Switzerland. 

When you get the full index for the whole world, you can set it up by following the same steps.

1. [**Open this link**](https://data.maptiler.com/my-extracts/?sample) and download the sample **Geocoding index**. It's a `tar.gz` archive file.

2. Go to your MapTiler Server administration Geocoding page `http://localhost:3650/admin/geocoding`.

3. Use the **Import index file** button to upload the `tar.gz` file. Or just drag & drop it onto the page. 

    ![Geocoding in MapTiler Server](./geocoding-Server.png)

MapTiler Server sets up the geocoding index automatically and your local geocoding API is ready.

#### Test the endpoint

The local geocoding API endpoint is available in the `/api/geocoding/` path. You can test it using `wget` or `curl` commands: 

- Save the JSON file to the folder where MapTiler Server is running: 
     ```bash
     wget -o - http://localhost:3650/api/geocoding/zurich.json
     ```
- Print the file contents to standard output: 
     ```bash
     wget -O - http://localhost:3650/api/geocoding/zurich.json
     ```

To test in the browser, go to `http://localhost:3650/api/geocoding/zurich.json`.

## Add search to your map

The on-prem geocoding functionality is completely independent of the on-prem maps. This means that the setup gives you the API endpoint, but doesn't automatically add the search to your local maps. Instead, you get sample code to help you integrate the search control into a self-hosted map application. Here's how.

1. **Select a basemap style:** Use the dropdown menu to pick any of the maps hosted in MapTiler Server. This will be the basemap to show the search box on. The sample code for your map app will contain a link to this map style, which you can simply replace when you want to use a different map.

    ![Basemap style selector](./geocoding-map-dropdown.png)

2. **Configure the search:** The geocoding feature and the control (aka search box) has plenty of config options, which you can adjust in the right panel. To learn more about the options, see the tooltips and [Geocoding Control module documentation](/sdk-js/modules/geocoding/).

    ![Geocoding control configuration](./geocoding-map-config.png)

3. **Copy the sample code:** Use the provided sample code to add a search box to your map app. The code updates itself dynamically when you make changes in the config panel, so once you're happy with the settings, the code is ready too. There are two options, both using the [MapTiler SDK JS](/sdk-js/):

    - **NPM module** code to add the geocoding control to your Node.js project. Start by using the first provided code block to install the SDK and geocoding control, then include the second code block in your JavaScript file. 
    - **Basic JavaScript** with complete code for a simple web map application. To use it, copy the code, paste it into a code editor or plain text editor, and save it as a .html file. Test it by opening in your web browser. 

> [!WARNING]
> Remember that if you're using maps with [sample data](/guides/self-hosting/self-hosted-maps/maptiler-data-sample-package/) instead of the [full data](https://www.maptiler.com/data/) and a sample geocoding index instead of the [full index](#full-index), you'll only get a sample map application too – with a clipped map and limited search. Specifically, you'll be only able to search and display places in Zurich, Switzerland.

If you want to use a specific framework or another map library to implement the search box in your map app, you need to modify the code accordingly. We have a complete set of [code examples for various libraries](/sdk-js/modules/geocoding/examples/) using the online Geocoding API, which you can check out and adapt for on-prem use.

#### Offline use

You may notice that the code refers to online stylesheets and scripts from our SDK, meaning it won't work when fully offline. To update it for offline use, you need to download the dependencies and replace URLs in the file header with local paths to the downloaded files. For example, in the basic JavaScript code, you'd replace `` with ``, replacing `path/to/` with the relative path to the file in your project directory.



  When downloading any dependencies for local use, note the version listed in the sample code and preferably get this exact version. These versions are tested. Different minor versions should work as well but it's not guaranteed, and different major versions are usually not compatible.





## What's next: Get full index

Once you've tested on-prem geocoding using the sample index limited to Switzerland, you may want to get a full index for the whole world. If your license doesn't include on-prem geocoding, first [contact our Sales team](https://www.maptiler.com/contacts/#contact) to arrange it. The global indexes will be then available on the [Downloads page](https://data.maptiler.com/my-extracts/) in your MapTiler account.

![Full geocoding index](./geocoding-full-index.png)

## Useful links

- [Geocoding live demo](https://www.maptiler.com/showcase/geocoding/)
- [Geocoding product page](https://www.maptiler.com/cloud/geocoding/)
- [On-prem geocoding API reference](/server/api/geocoding/)
- [Geocoding control – SDK module documentation](/sdk-js/modules/geocoding/)
- [Geocoding control – code example](/sdk-js/examples/geocoder-component/)
- [NPM geocoding package](https://www.npmjs.com/package/@maptiler/geocoding-control)

# How to create a virtual tileset

Source: https://docs.maptiler.com/guides/on-prem/server/virtual-tileset/

A **virtual tileset** makes it possible to blend drone, aerial, and satellite imagery into a seamless color-toned mosaic. For example, you can combine MapTiler low-res satellite data with your own hi-res drone imagery to get a map with global context and local detail where needed. Also, you can combine vector datasets from multiple sources to get one complete tileset with all the data. Virtual tilesets are easy to deploy and maintain, allowing you to adjust your map data sources without re-processing them. 

[MapTiler Server](/guides/on-prem/server/) has an in-built **Virtual Tileset Editor** to create virtual tilesets out of your existing self-hosted tilesets. You select two or more tilesets, match their colors, and combine them into a virtual tileset. Then you can use it just like a regular tileset. 

![Virtual Tileset Editor: A drone image over medium-res satellite before color toning](./server-vte-datasets.png)

*A drone image over medium-res satellite, **before** and **after** color-toning.*

![Virtual Tileset Editor: A drone image over medium-res satellite after color toning](./server-vte-toned.png)

Technically, a virtual tileset is a JSON-based configuration file, so it doesn't contain any map data. Instead, it tells MapTiler Server which physical tilesets to combine and how to render them into a single map layer. 



Virtual tilesets reference the physical tilesets using their IDs. If you change an ID of a physical tileset, make sure to also update any virtual tilesets referencing it, otherwise the virtual tilesets stop working.



## Before you start

- **MapTiler Server** must be [installed and running](/guides/on-prem/server/installation/).
- The datasets you want to combine must be hosted in MapTiler Server: 
    - You need at least 2 datasets,
    - They must be of the [same type](/guides/how-maps-work/map-data/) (either all **raster** or all **vector**),
    - They must use the [Mercator](/guides/how-maps-work/coordinate-systems/#web-mercator) projection.

## Create a virtual tileset

1. In the MapTiler Server admin interface, go to **Datasets**.

2. Click **New dataset**, then click **Create virtual tileset**.

3. Select the first dataset you want to use. Click **Add**.

4. In the editor, click **Add dataset** again to select another dataset to combine with the first. *Datasets of incompatible type are marked in red and you cannot add them.*

5. The left panel of the editor shows the datasets added. Drag them to arrange their vertical order.

    Layers on top cover the layers below, so make sure smaller datasets are above the base layer to keep them visible. *This also applies to vector tilesets (vector data layers are not transparent).*

    If the initial view shows a blank page, you're probably in a part of your dataset that doesn't contain any data. Zoom and pan until you see where you are. It also helps to hide other layers using the little eye icon. 
    
    Note that each layer might be visible on different zoom levels (see Visibility to check).

6. Select a dataset in the left panel and adjust its properties:

    - **Visibility** and **opacity** on different zoom levels. Using **zoom range styling** in the advanced settings, you can add breakpoints and define opacity for specific zoom levels to create effects such as gradually appearing overlay when zooming in.
    - **Color toning:** To blend raster datasets, modify their contrast and bias, saturation, and color balance as needed. For more help, hover over any control to see its tooltip.
    - **Masking:** For vector datasets that contain a mask property, turning on the mask hides all data in the masked area. You can then use another dataset to "fill in" that area.

8.  **Save** your work and close the editor. The new virtual tileset is listed on the **Datasets** page.

## Next steps

You can use a virtual tileset in the exact same ways as a standard, non-virtual tileset:

- A **raster** virtual tileset is essentially a complete map, so you can serve it directly via the local [Tiles API](/server/api/tiles/).
- A **vector** virtual tileset is "raw", so you'll typically want to combine it with a raster base layer to create a map. To do so, open the preview of your virtual tileset and click **Add to map**. You can then serve your new map via the [Maps API](/server/api/maps/).
- You can also use any virtual tileset to build a full self-hosted map application. See our [code examples](/sdk-js/examples/) for inspiration.

# Technical Specification

Source: https://docs.maptiler.com/guides/self-hosting/map-server/maptiler-server-technical-specification/

This page lists the technical details of MapTiler Server, including system requirements and supported formats.

## Platforms and CPU architectures

* **Linux**
    - Ubuntu 20\.04\+ (primary support)
    - Debian 10+
    - RHEL 8+
    - Fedora 37\+
    - Centos 9\+
    - Mint 6 or 20\+
* **Windows**  
    - Windows 10\+  
    - Server 2019\+
* **macOS** 10\.15\+
* **Docker** 25\+
* **Kubernetes**

### Feature support

| **Platform/feature**| Basic map hosting | Rasterization | Virtual tilesets | Geocoding |
| :---               | :----:            | :----:        | :----:           | :----:    |
| Linux x64          | ✅               | ✅            | ✅               | ✅  |
| Linux ARM64        | ✅               | ✅            | ✅               | ✅  |
| Windows x64        | ✅               | ✅            | ✅               | ✅  |
| Windows ARM64      | ❌               | ❌            | ❌               | ❌  |
| macOS x64          | ✅               | ✅            | ✅               | ✅  |
| macOS ARM64        | ✅               | ✅            | ✅               | ✅  |
| Docker x64         | ✅               | ✅            | ✅               | ✅  |
| Docker ARM64       | ✅               | ✅            | ✅               | ✅  |


## Hardware requirements

### Tiles serving

* 2 CPUs
* 2GB RAM
* 1 GB of storage for installation (additional for tiles)

### Maps rasterization (whole planet)

* 4 CPUs
* 16GB RAM
* 100 GB of storage for tiles, fonts, and other assets

### Geocoding (full indexes)

* 2 CPUs
* 4GB RAM
* 200+ GB of storage for global geocoding indexes

> [!TIP]
> These are the standard specifications that work well for typical use. If your usage grows, you may need to upgrade your hardware. For more info and tips, see [MapTiler Server performance and how to improve it](/guides/self-hosting/map-server/how-to-improve-and-monitor-maptiler-server-performance).

## Standards

* OGC API — Tiles
* WMS
* WMTS

## Formats

### Tiles

* Raster .mbtiles 1
* Vector .mbtiles 1
* Raster .mtpkg 2
* Vector .mtpkg 2
* Raster .gpkg 1
* Quantized mesh terrain (3D) .gpkg 1
* [Tiles from PostGIS geometries](https://www.maptiler.com/server/vector-tiles-from-postgis/)  

1 The free version of MapTiler Server supports only tiles included in [MapTiler data](https://www.maptiler.com/data/) or produced by [MapTiler Engine](https://www.maptiler.com/engine/).

2 MTPKG is MapTiler's proprietary format. It is optimized for smaller data size and enables remote reading of tiles from MapTiler Server as well as local access.

### Maps

* Mapbox style

## Coordinate reference systems

* Tiles
	+ The complete EPSG database \+ custom\-defined SRS via Proj4\. Over 6000 systems worldwide
* Maps
	+ Mercator sources only

## Viewers 

### For desktop

* Google Earth
* ArcGIS for Desktop
* QGIS (Quantum GIS)
* [Tableau](/guides/self-hosting/map-server/on-premise-tableau-maps)
* uDIG
* Any viewer supporting OGC WMTS

### For web

* MapLibre GL JS
* Leaflet
* OpenLayers
* CesiumJS

### Mobile native viewers

* Google Maps SDK for iOS
* Google Maps SDK for Android
* MapLibre iOS SDK
* MapLibre Android SDK
* Apple MapKit
* RouteMe
* OSMDroid
* Any viewer supporting OGC WMTS or TileJSON

# MapTiler Server API

Source: https://docs.maptiler.com/server/api/

v1.0



  

    API Base URL
  

  

    MapTiler API: https://api.maptiler.com/
  






## Additional Information

[Contact Support](https://docs.maptiler.com/support/requests/)

[Premium support](https://www.maptiler.com/support/)

[Terms of Service](https://www.maptiler.com/terms/)

# Geocoding API | MapTiler Server API

Source: https://docs.maptiler.com/server/api/geocoding/

[On-prem geocoding](/guides/geocoding/on-premise-geocoding-in-maptiler-server/) makes it possible to add place search to your self-hosted maps. It includes both forward geocoding (search by place name) and reverse geocoding (search by coordinates).

# Maps API | MapTiler Server API

Source: https://docs.maptiler.com/server/api/maps/

_No overview content available._

# Static Maps API | MapTiler Server API

Source: https://docs.maptiler.com/server/api/static-maps/

_No overview content available._

# Tiles API | MapTiler Server API

Source: https://docs.maptiler.com/server/api/tiles/

_No overview content available._

# Other | MapTiler Server API

Source: https://docs.maptiler.com/server/api/other/

_No overview content available._

# MapTiler Server Admin API

Source: https://docs.maptiler.com/server/admin-api/

v1.0



  

    API Base URL
  

  

    MapTiler API: https://api.maptiler.com/
  






## Additional Information

[Contact Support](https://docs.maptiler.com/support/requests/)

[Premium support](https://www.maptiler.com/support/)

[Terms of Service](https://www.maptiler.com/terms/)

# Authentication Token Auth | MapTiler Server Admin API

Source: https://docs.maptiler.com/server/admin-api/authentication/

All Admin API requests must be authorized using a Token.

Tokens are ideal for use in desktop or mobile applications, adding a digital signature to each request. This makes it impossible to steal the credentials during transmission. Token authorization provides much better security and prevents credentials misuse.

> [!WARNING]
> **DO NOT** use this type of authorization in environments where the source code of your application is visible to the potential attacker (such as client-side web applications). Keep this token private – treat it the same way as you would a password.

### How to use Token Authorization

Your MapTiler token is available in your **MapTiler Server**, in the **Credentials Settings** section.

For more information, read this [guide to using secure authentication for MapTiler Server API](/guides/self-hosting/map-server/maptiler-server-using-admin-api).

Example Token:

```Token cd43c591d8404400a11e2fre48afedc9_f80f4be2adf86dfb6bc489229669877d6cfcad293f48ffe6e77898f25ab65607```

Don’t forget to set the `Authorization` header in the form of `Token {YOUR_TOKEN}`, so we know it’s you making the requests.

# Maps API | MapTiler Server Admin API

Source: https://docs.maptiler.com/server/admin-api/maps/

_No overview content available._

# Tiles API | MapTiler Server Admin API

Source: https://docs.maptiler.com/server/admin-api/tiles/

_No overview content available._

# Tile Ingest API | MapTiler Server Admin API

Source: https://docs.maptiler.com/server/admin-api/tile-ingest/

_No overview content available._

# Get started with MapTiler Engine

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-processing/getting-started/

This friendly beginner guide helps you install MapTiler Engine and create your first map tileset from a sample drone image. We'll explain briefly what's happening at every step, so that you understand how MapTiler Engine works.

At the end of the tutorial, you'll have the sample drone image tiled, georeferenced, and saved on your local drive (optionally also in MapTiler) in a special map-ready format. You'll get a preview of the result and learn what to do next. 

Here are the steps we'll go through:

1. [Install MapTiler Engine](#install)
2. [Download a sample image](#sample-image)
3. [Georeference the image](#georeference)
4. [Set tiling parameters](#parameters)
5. [Preview the result](#result)
6. [Next steps](#next-steps)

-----


## Install MapTiler Engine

1. Go to the [Engine download page](https://www.maptiler.com/engine/download/) and select the installation package for your operating system. 

2. Install and run MapTiler Engine. Note that MapTiler Engine will be a new and unknown application to your system, so you may need to handle some security pop-ups in the process. Get more information in the detailed installation guides: 

     - [Windows](/guides/map-tiling-hosting/data-processing/installation-on-windows/)
     - [Linux (via Docker)](/guides/map-tiling-hosting/data-processing/maptiler-engine-in-docker/)


## Download a sample image

We’ll show you the tiling process using a drone image of the Moturiki Island in New Zealand. It’s a regular JPG, without any geospatial metadata attached to it. 

> [!NOTE]
> Processing an image with MapTiler Engine is called **raster tiling**. MapTiler Engine can also process other types of data, but images are the easiest type to start with.

1. Download the sample image here. 

2. Run MapTiler Engine and open the sample image in it. You can either drag and drop the file in the dashed line area, or use the button.

     ![Select task](./1-select-workflow.png)


## Georeference the image

Georeferencing is the process of assigning coordinates to an object (in this case a drone image). Geospatial coordinates determine the object's position on Earth, and so make it possible to display the object on a map.

1. When you upload the image, you’re asked to specify its geographical location. There are multiple options to provide this information, but most require that you already know the coordinates or have them ready in a file. We don't have that, so we’ll **assign location visually** using the georeferencer tool.

     ![Assign geolocation](./2_assign_location.png)

     To use the visual georeferencer, you’ll need to log in to MapTiler. If you don’t have an account, you get a sign-up screen to create one instantly—it’s free and with no obligations.

    > [!NOTE]
    > You need to log in just once. MapTiler Engine will remember your details and keep you logged in for next time. 

2. Visual georeferencer opens. First, let's switch the basemap to a more suitable one. Use the little **globe button** to open the basemap selector.

     ![Georeferencer](./3-georeferencer.png)

3. Select the satellite map to use it as the georeferencer basemap. This will help you identify the drone image location more easily.

     ![Change basemap](./4-georeferencer-changemap.png)

4. Now, use the **search button** to find the right area on the map. For our sample image, look up "Mount Maunganui" in the Bay of Plenty, New Zealand. 

     ![Find area on basemap](./5-georeferencer-find.png)

5. Moturiki is a small island located at the end of the city beach. Zoom in until you see the narrow pathway connecting the island with the beach—this is the area captured on our sample drone image.

     ![Moturiki island location](./6-georeferencer-area.png)

6. You're now ready to georeference the image. How to do it: Click on a spot in the image and then on the same spot on the map (or vice versa). This creates a point with the corresponding location in the image and on the map. You can position the point precisely thanks to the optical sight which appears on click.

    > [!IDEA]
    > To make the task easier, place the point in a visually distinctive spot, such as a path crossing or a prominent rock formation.

     ![Add points](./7-georeferencer-point.png)

8. Repeat the previous step in different parts of the image to get at least three points (more is better). Place them as accurately as possible. If you make a mistake, just click on a point to reposition or remove it.

     With the third point placed, the image rotates to match the orientation of the map. Add a few more points for accuracy and continue to the next step. 

     ![Three points added](./8-georeferencer-points.png)


## Set tiling parameters

1. When you close the visual georeferencer, you'll see an overview of the image setup. Keep the default values and continue. 

     ![Image settings](./9-settings.png)

2. On the next screen, select the output format **GeoPackage**. This will be the format of the whole tileset container (which is different from the format of the individual tiles inside). 

     You can learn more about the [output formats](/guides/map-tiling-hosting/data-processing/folder-vs-mbtiles-vs-geopackage/) but it's not necessary for this tutorial.

     ![Output format](./10-output-format.png)

3. The output settings let you set up the format of the tiles (images within the tileset) and related details. MapTiler Engine pre-fills this screen based on an analysis of the input data, so you should always get good results if you keep the recommended values. The only change you need to do here: Select the **Non-commercial use** checkbox (unless you're already using a paid MapTiler Engine license).

     ![Output settings](./11-output-settings.png)

4. Select where to save the tiling output on your local machine.

5. Select where to upload the tiling output. (This doesn't affect the local output set in the previous step. You always get local output, no matter if you decide to also upload to cloud or not.) We recommend uploading to MapTiler where your tileset will be conveniently ready for further work and testing. 

     ![Upload options](./12-upload-options.png)

6. In the last configuration step, you can edit the filename for the cloud upload. When the processing is done, you'll find your new tileset under that name in your MapTiler account.

     ![Upload settings](./13-upload-settings.png)


## Preview the result

1. After MapTiler Engine guides you through all the settings, it automatically starts processing the file. You can watch the progress on screen. The sample image shouldn't take more than a few minutes to process.

     ![Tiling in progress](./14-processing.png)

2. When the processing is complete, go to the **Options** menu and select **Output preview**. 

     ![Tiling finished](./15-finished-options.png)

3. In the preview, MapTiler Engine shows your new tileset on top of a basemap. This gives you an idea of what your image might look like when integrated into an actual map. Try zooming and panning to see how the map will behave. You can also adjust transparency with the slider to see how accurately you’ve positioned the image and how well it blends with the basemap. 

     ![Tiling output preview](./16-preview.png)
 
Closing the preview takes you back to the finished task. All key functions are accessible from the **Options** menu, so be sure to explore it. From there, you can view a simple task report, open the location where your tileset is stored (on the local drive and in MapTiler), save the task settings for backup, or edit the task and run it again. 


## Next steps

**Proceed to adding your new tiles to a map:** Now that you have your tileset ready [in MapTiler](https://cloud.maptiler.com/tiles/), you can easily integrate it into a real map. 👉 Learn [how to use your image as part of a map](/guides/map-tiling-hosting/data-hosting/how-to-host-your-own-geodata/#use-your-image-as-part-of-the-map). 

If you prefer to self-host your tiles and maps, you'll want to check out [MapTiler Server](/guides/self-hosting/map-server/).

**Keep exploring Engine:** MapTiler Engine can process more than just images. 👉 Find out [what is vector data](/guides/map-tiling-hosting/data-processing/vector-feature/) and [how to tile it](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-vector-data/).

> [!IDEA]
> Ready for full speed? See what features and benefits you can unlock with a MapTiler Engine [commercial license](https://www.maptiler.com/engine/pricing/).

# Manage your tasks

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-processing/intelligent-workflows/

This page explains what kind of tasks can MapTiler Engine do for you, how to create and manage them, and how to work with a task queue.

> [!NOTE]
> Tasks were called **projects** in the previous versions of MapTiler Engine. If you have some saved projects, you can [open them](#open-task) and use just like tasks.

## Start a task

To create map tiles from your data, start by dropping your files on the first screen of MapTiler Engine. 

![MapTiler Engine initial page](./Engine_home.png)

MapTiler Engine detects the format of the uploaded data and walks you through the processing setup:

  - If the input files are _images_, you’ll be [creating tiles from raster data](/guides/map-tilling-hosting/data-processing/how-to-create-tiles-from-raster-data/).
  - If the input files are _[vector features](/guides/map-tilling-hosting/data-processing/vector-feature/)_, you’ll be [creating tiles from vector data](/guides/map-tilling-hosting/data-processing/how-to-create-tiles-from-vector-data/).

If you want to do something else with your data, use the options button on the first screen and select another task:

![MapTiler Engine initial page: Options](./Engine_home_options.png)

- **Merge tilesets** allows you to merge raster MBTiles, or replace parts of your tilesets with different data, which is handy if you need to update your existing tileset with new data. See [Merge multiple tilesets](/guides/map-tilling-hosting/data-processing/how-to-merge-tilesets-mbtiles/).

- **Upload to cloud** is available as part of creating or merging tilesets, but you can also select it as a separate task if needed. It uploads a single tileset to MapTiler or your private cloud (Amazon S3, Microsoft Azure, Google Cloud Storage). See [Upload to MapTiler Cloud](/guides/map-tilling-hosting/data-processing/how-to-upload-a-tileset-to-maptiler-cloud/) or [Upload to Amazon S3 Cloud](/guides/map-tilling-hosting/data-processing/amazon-s3-map-hosting/).



## Manage task queue

When you need to prepare multiple tasks for processing, you can put them in a queue. Simply create a new task while another one is running. 

> [!WARNING]
> There’s a limit of **1 task in progress** and **2 tasks in a queue**, ready for processing.

Note that closing MapTiler Engine erases the task queue, so it's no longer available when you reopen the application. However, you can [save your tasks](#save-task) before you close the app.

![Add a new task to queue](./task_queue_new.png)

## View task report

To view a detailed report for a specific task, simply click on its status. Alternatively, go to the task queue and select **Options** > **Task report**. 

A report is only available when the task processing is finished.

![View task report](./task_queue_report.png)



## Save a task

Tasks can have their own unique configuration, different from the [global settings](/guides/map-tilling-hosting/data-processing/global-settings/), and can be saved with that configuration during or after processing for later reuse or as a backup. 

For example, if you're processing large data, rendering can take hours. Ideally, keep the process running; if you put your computer to sleep and then wake it up, the task that was in progress will automatically resume. However, if you need to shut the computer down, all running and queued tasks would be cancelled. Here’s how to not lose your prep work:

1. On *My tasks* screen, click on **Options** next to your running task.
2. In the menu, select **Save task to file** to save the task configuration as an .mtp file. 
3. Then select **Cancel task** or simply close MapTiler Engine.

![Save and cancel a running task](./task_queue_save.png)



## Open a saved task

To load a previously saved task: 

1. Open MapTiler Engine and use the three-dot options button on the first screen. 
2. Select **Open saved task** to upload your .mtp file.

![Open a saved task](./Engine_home_options_open.png)

# Settings

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-processing/global-settings/

In MapTiler Engine, you can review and adjust the [global settings](#global-settings) that store various default configurations. In addition to that, you have the possibility to modify certain settings only for a specific tiling task in [advanced task settings](#advanced-task-settings), which overrides the global defaults.

## Global settings

To access global settings, go to **File > Settings**. These settings are saved permanently and applied to any processing task by default, unless modified in [advanced task settings](#advanced-task-settings). 

![global_settings.png](./global_settings.png)

### Image tab

**Resampling** and **overviews resampling** 

_Can be overriden with [advanced task settings](#advanced-task-settings)_

First of all, you can see the combo boxes controlling the resampling methods that are being used. You will probably be interested in these either when over\-zooming your data or when experimenting with the options to find out which setting will result in the best output for you. For detailed information go to [Resampling tiles](/guides/map-tiling-hosting/data-processing/resampling-tiles/). These options are available from MapTiler Engine Plus.

The default value for resampling is **bilinear** and for overviews resampling **average.**

**Tiling scheme** 

_Can be overriden with [advanced task settings](#advanced-task-settings)_

Different map providers work with different tiling schemes, so make sure you are using the correct scheme depending on further usage of your output. The schemes differ in the way your output tiles are named. For detailed information on the available options, go to [Tiling scheme](/guides/map-tiling-hosting/data-processing/tiling-scheme-in-folder-output/).

The Default value is **XYZ.**

**Sparse output** 

_Can be overriden with [advanced task settings](#advanced-task-settings)_

This option controls how the **empty tiles** in your output are treated. In some cases, e.g. when your input data are very geographically distant, you'll get a huge amount of empty tiles between them, which can lead to high disk space usage. If you leave the **default** setting, the blank tiles will be produced for *MBTiles* and *GeoPackage* outputs otherwise will be skipped. By setting this option to **sparse** (skip empty tiles) or **no\-sparse** (don't skip), you have full control over this.

The default value is "**default"** (depending on the used store option).

**ECW memory usage**

This option allows you to set the maximum amount of memory to be used for in\-memory caching by the **ECW driver** of the GDAL library. This setting should be used with care and in reasonable cases, since using a high value may slow your system down or make it temporarily irresponsive.

The default and suggested value for ECW Memory usage is **80%.**

**Allow large JPEG**

Enabling **large JPEG** allows you to process very large images. It also should be used only in reasonable cases since it can have the same negative impact on your system as a large ECW memory usage.

By default, large JPEG support is **disabled.**

### General tab

**Proxy settings**

If you use a computer without direct access to the internet, enable the system proxy to load the proxy settings from your system configuration.

**Saved georeferences**

By leaving this option enabled, you will be offered to use the geolocation previously saved by [Assign visually](/guides/map-tiling-hosting/data-processing/georeferencing/) when you add a new input file.

By default, saving georeferences is **enabled.**

**MBTiles compatibility**

_Can be overriden with [advanced task settings](#advanced-task-settings)_

Enabling this option make the generated *GeoPackage* conform to the *MBTiles* specification for the tiles table. The tilegrid is in the selected output coordinate system, which is not defined for *MBTiles*.

By default, MBTiles compatibility is **disabled.**

**Save EPSG code**

_Can be overriden with [advanced task settings](#advanced-task-settings)_

![wkt-save-epsg.png](./4414014344209_e75a06f1b6.png)

Changes the format of coordinate system representation to be used. Disabling this option causes saving the full WKT string (left) instead of the short EPSG code (right) within the project file or report message. [EPSG.io](https://epsg.io/) is a nice tool to switch between different formats. For the lower versions of the application, this option is hidden and set to true. Changing this option is enabled in MapTiler Engine Pro.

By default, saving EPSG code instead of WKT string is **enabled.**

**Google Maps API key**

Use this field to save your Google Maps API key, which is used to secure Google Maps Platform products from unauthorized use. You can get this key by following steps described in the [Google guides](https://developers.google.com/maps/documentation/javascript/get-api-key#create-api-keys). For more details, go to [Google maps API key](/guides/map-tiling-hosting/data-processing/google-maps-api-key/).

### Directories tab

This tab defines local directories that MapTiler Engine uses. These are the default locations:

- `C:\Windows\Temp` to store working and temporary files (`/tmp` on Linux and Mac)
- `C:\Users\\Pictures` to look for input files
- `C:\Users\\Desktop` to save output files and finished tasks (.mtp files)

Note that these locations (except Temp) are only used as a starting point, meaning that you'll be still able to browse for a different directory each time you open or save a file. However, setting a custom location can be faster and more convenient. To set a custom location, check the respective box and select your preferred directory.

*Setting custom directories is only available in MapTiler Engine Plus and above.*

**Save the last selected directory for user directories**

With this option enabled, when you select a different path (in the application), it will get saved to settings in the background. This option is available from MapTiler Engine Plus.

Let's say you have set the Engine*/* location for adding a file, but you add a file from Engine*/files\-to\-process/* folder, this folder gets saved in settings for you and replaces the Engine*/* folder just as you would have done it in settings. The next time you add a file, the file dialog will navigate in Engine*/files\-to\-process/*.

This works only for paths that have been set **custom**!

**Remember the last selected directory in the application's lifetime**

With this option enabled, when you select a different path (in the application), it will be remembered (but not saved) until you restart the application. This option is available from MapTiler Engine Plus.

Let's say you did not touch the "add a file" path (set to *Pictures/*), but you add a file from Engine*/files\-to\-process/* folder, you'll be offered this path every time you attempt to add a file until you change it in the settings, open a file from a different location, or quit the application. After the application restarts, the file dialog will navigate in the default location (*Pictures/*) again.

### Watermark tab

MapTiler Engine allows you to set the custom watermark to be used in your outptut. You can choose either **image** (which will need to meet some criteria for this purpose), or quickly create a **text watermark** using the simple in\-build editor. Either way, you'll see the result in the preview below. Read the [Custom watermark](/guides/map-tilling-hosting/data-processing/custom-watermark/) article for more detailed description. This option is available in MapTiler Engine Pro and by default, the "No watermark" option is set.

Saved watermark settings (both image and text) last through the application lifetime and get loaded on the next startup.

## Advanced task settings

To access advanced task settings, start configuring a tiling task. When you get to the output settings, use the **Advanced settings** button. Any changes in these settings will only apply to this specific task, and won't be propagated to the global settings. If you [save your task](/guides/map-tiling-hosting/data-processing/intelligent-workflows/#cancel-a-running-task-and-save-it), the advanced settings specific for the task will be saved too.

![advanced_task_settings_open.png](./advanced_task_settings_open.png)

Advanced task settings contain the same options as the [Image](#image-tab) and [General](#general-tab) tabs in global settings. If you update these options in the advanced task settings, they'll override the global settings, but only for that one task. 

Additionally, you can configure the **HiDPI / Retina** scaling in the advanced task settings dialog. To learn more about this option, go to [Custom retina scale](/guides/map-tiling-hosting/data-processing/custom-retina-scale/).

# Supported input formats

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-processing/supported-formats/

This is a complete list of vector and raster input formats supported by current version of [MapTiler Engine](https://www.maptiler.com/engine/download/).  
All below listed formats are supported on all operating systems (Windows, Mac, Linux) and can be converted to MBTiles or GeoPackage format, or to the folder with tiles.

* [Raster formats](#raster-formats)
* [Vector formats](#vector-formats)

## Raster formats

| **Code** | **Format Name** |
| --- | --- |
| AAIGRID | [Arc/Info ASCII Grid](https://gdal.org/en/stable/drivers/raster/aaigrid.html#raster-aaigrid) |
| ADRG | [ADRG/ARC Digitilized Raster Graphics (.gen/.thf)](https://gdal.org/en/stable/drivers/raster/adrg.html#raster-adrg) |
| AIGRID | [Arc/Info Binary Grid](https://gdal.org/drivers/raster/aig.html) |
| AIRSAR | [AIRSAR Polarimetric](https://www.gdal.org/frmt_airsar.html) |
| ARG | [Azavea Raster Grid](https://www.gdal.org/frmt_various.html#ARG) |
| BMP | [Microsoft Windows Device Independent Bitmap (.bmp)](https://www.gdal.org/frmt_bmp.html) |
| BSB | [BSB Nautical Chart Format (.kap)](https://gdal.org/en/stable/drivers/raster/bsb.html#raster-bsb) |
| CALS | [CALS Type I](https://www.gdal.org/frmt_cals.html) |
| CEOS | [CEOS (Spot for instance)](https://gdal.org/drivers/raster/ceos.html#raster-ceos) |
| COASP | [DRDC COASP SAR Processor Raster](https://gdal.org/drivers/raster/coasp.html) |
| COSAR | [TerraSAR\-X Complex SAR Data Product](https://www.gdal.org/frmt_cosar.html) |
| CTG | [USGS LULC Composite Theme Grid](https://www.gdal.org/frmt_various.html#CTG) |
| DAAS | [DAAS (Airbus DS Intelligence Data As A Service driver)](https://gdal.org/drivers/raster/daas.html) |
| DIMAP | [Spot DIMAP (metadata.dim)](https://www.gdal.org/frmt_various.html#DIMAP) |
| DTED | [Military Elevation Data (.dt0, .dt1, .dt2\)](https://www.gdal.org/frmt_dted.html) |
| ECW | [ERDAS Compressed Wavelets (SDK 5\.4\)](https://gdal.org/drivers/raster/ecw.html) |
| EEDAI | [Google Earth Engine Data API Image](https://gdal.org/drivers/raster/eedai.html) |
| ENVISAT | [Envisat Image Product (.n1\)](https://www.gdal.org/frmt_various.html#Envisat) |
| ERS | [ERMapper (.ers)](https://www.gdal.org/frmt_ers.html) |
| ESRIC | [Esri Compact Cache](https://gdal.org/drivers/raster/esric.html) |
| GFF | [GSat File Format](https://www.gdal.org/frmt_various.html#GFF) |
| GIF | [Graphics Interchange Format (.gif)](https://www.gdal.org/frmt_gif.html) |
| GRIB | [WMO GRIB1/GRIB2 (.grb)](https://www.gdal.org/frmt_grib.html) |
| GSAG | [Golden Software ASCII Grid File Format](https://gdal.org/drivers/raster/gsag.html) |
| GSBG | [Golden Software Binary Grid File Format](https://gdal.org/drivers/raster/gsbg.html) |
| GTIFF | [TIFF / BigTIFF / GeoTIFF / COG (.tif)](https://www.gdal.org/frmt_gtiff.html) |
| GXF | [Grid eXchange File](https://www.gdal.org/frmt_various.html#GXF) |
| HDF5 | [Hierarchical Data Format Release 5 (HDF5\)](https://gdal.org/drivers/raster/hdf5.html) |
| HF2 | [HF2/HFZ heightfield raster](https://www.gdal.org/frmt_hf2.html) |
| HFA | [Erdas Imagine (.img)](https://www.gdal.org/frmt_hfa.html) |
| IDRISI | [Idrisi Raster](https://www.gdal.org/frmt_Idrisi.html) |
| ILWIS | [ILWIS Raster Map (.mpr,.mpl)](https://www.gdal.org/frmt_various.html#ILWIS) |
| IRIS | [IRIS](https://www.gdal.org/frmt_various.html#IRIS) |
| JAXAPALSAR | [JAXA PALSAR Product Reader (Level 1\.1/1\.5\)](https://www.gdal.org/frmt_palsar.html) |
| JDEM | [Japanese DEM (.mem)](https://www.gdal.org/frmt_various.html#JDEM) |
| JP2KAK | [JPEG\-2000 (based on Kakadu SDK)](https://gdal.org/drivers/raster/jp2kak.html) |
| JPEG | [JPEG JFIF (.jpg)](https://www.gdal.org/frmt_jpeg.html) |
| JPIPKAK | [JPIP Streaming (based on Kakadu)](https://gdal.org/drivers/raster/jpipkak.html) |
| KMLSUPEROVERLAY | [KMLSUPEROVERLAY](https://gdal.org/drivers/raster/kmlsuperoverlay.html) |
| L1B | [NOAA Polar Orbiter Level 1b Data Set (AVHRR)](https://www.gdal.org/frmt_l1b.html) |
| LEVELLER | [Daylon Leveller Heightfield](https://www.gdal.org/frmt_leveller.html) |
| MAP | [OziExplorer .MAP](https://www.gdal.org/frmt_map.html) |
| MBTILES | [MBTiles](https://gdal.org/drivers/raster/mbtiles.html) |
| MEM | [In Memory Raster](https://www.gdal.org/frmt_mem.html) |
| MRF | [Meta Raster Format](https://www.gdal.org/frmt_marfa.html) |
| MRSID | [Multi\-resolution Seamless Image Database (MrSID)](https://gdal.org/drivers/raster/jp2mrsid.html) |
| MSGN | [EUMETSAT Archive native (.nat)](https://www.gdal.org/frmt_msgn.html) |
| NETCDF | [Network Common Data Format](https://gdal.org/drivers/raster/netcdf.html) |
| NGSGEOID | [NOAA NGS Geoid Height Grids](https://www.gdal.org/frmt_ngsgeoid.html) |
| NITF | [NITF (.ntf, .nsf, .gn?, .hr?, .ja?, .jg?, .jn?, .lf?, .on?, .tl?, .tp?, etc.)](https://www.gdal.org/frmt_nitf.html) |
| NORTHWOOD | [Northwood/VerticalMapper Classified Grid Format .grc/.tab](https://www.gdal.org/frmt_nwtgrd.html) |
| OGCAPI | [OGC API Tiles / Maps / Coverage](https://gdal.org/drivers/raster/ogcapi.html) |
| PCIDSK | [PCI Geomatics Database File](https://www.gdal.org/frmt_pcidsk.html) |
| PCRASTER | [PCRaster](https://www.gdal.org/frmt_various.html#PCRaster) |
| PDF | [Geospatial PDF](https://www.gdal.org/frmt_pdf.html) |
| PDS | [NASA Planetary Data System](https://www.gdal.org/frmt_pds.html) |
| PLMOSAIC | [Planet Labs Mosaics API](https://gdal.org/drivers/raster/plmosaic.html) |
| PNG | [Portable Network Graphics (.png)](https://www.gdal.org/frmt_various.html#PNG) |
| PRF | [PHOTOMOD raster file (.prf,.x\-dem)](https://www.gdal.org/frmt_prf.html) |
| RIK | [Swedish Grid RIK (.rik)](https://www.gdal.org/frmt_rik.html) |
| RMF | [Raster Matrix Format (\*.rsw, .mtw)](https://www.gdal.org/frmt_rmf.html) |
| RS2 | [RadarSat2 XML (product.xml)](https://www.gdal.org/frmt_rs2.html) |
| SAFE | [Sentinel 1 SAR SAFE (manifest.safe)](https://www.gdal.org/frmt_safe.html) |
| SAGA | [SAGA GIS Binary format](https://www.gdal.org/frmt_various.html#SAGA) |
| SAR\_CEOS | [SAR CEOS](https://www.gdal.org/frmt_various.html#SAR_CEOS) |
| SDTS | [USGS SDTS DEM (\*CATD.DDF)](https://www.gdal.org/frmt_various.html#SDTS) |
| SENTINEL2 | [Sentinel 2](https://www.gdal.org/frmt_sentinel2.html) |
| SGI | [SGI Image Format](https://www.gdal.org/frmt_various.html#SGI) |
| SIGDEM | [Scaled Integer Gridded DEM](https://www.gdal.org/frmt_various.html#SIGDEM) |
| SRTMHGT | [SRTM HGT Format](https://www.gdal.org/frmt_various.html#SRTMHGT) |
| STACIT | [Spatio\-Temporal Asset Catalog Items](https://gdal.org/drivers/raster/stacit.html) |
| STACTA | [Spatio\-Temporal Asset Catalog Tiled Assets](https://gdal.org/drivers/raster/stacta.html) |
| TERRAGEN | [Terragen Heightfield (.ter)](https://www.gdal.org/frmt_terragen.html) |
| TGA | [TARGA Image File Format](https://gdal.org/drivers/raster/tga.html) |
| TIL | [EarthWatch/DigitalGlobe .TIL](https://gdal.org/drivers/raster/til.html) |
| TSX | [TerraSAR\-X Product](https://gdal.org/drivers/raster/tsx.html) |
| USGSDEM | [USGS ASCII DEM / CDED (.dem)](https://www.gdal.org/frmt_usgsdem.html) |
| VRT | [Virtual Datasource](https://www.gdal.org/drv_vrt.html) |
| WCS | [OGC Web Coverage Service](https://gdal.org/drivers/raster/wcs.html) |
| WEBP | [WEBP](https://gdal.org/drivers/raster/webp.html) |
| WMS | [OGC Web Map Service](https://gdal.org/drivers/raster/wms.html) |
| WMTS | [OGC Web Map Tile Service](https://gdal.org/drivers/raster/wmts.html) |
| XPM | [X11 Pixmap (.xpm)](https://www.gdal.org/frmt_various.html#XPM) |
| XYZ | [ASCII Gridded XYZ](https://www.gdal.org/frmt_xyz.html) |
| ZARR | [Zarr](https://gdal.org/drivers/raster/zarr.html) |
| ZMAP | [ZMap Plus Grid](https://www.gdal.org/frmt_various.html#ZMap) |

## Vector formats

| **Code** | **Format Name** |
| --- | --- |
| AMIGOCLOUD | [AmigoCloud](https://gdal.org/drivers/vector/amigocloud.html) |
| AVC | [Arc/Info Binary Coverage](https://www.gdal.org/drv_avcbin.html) |
| CAD | [AutoCAD DWG](https://gdal.org/drivers/vector/cad.html) |
| CARTO | [Carto](https://gdal.org/drivers/vector/carto.html) |
| CSV | [Comma Separated Value (.csv)](https://www.gdal.org/drv_csv.html) |
| CSW | [OGC CSW (Catalog Service for the Web)](https://gdal.org/drivers/vector/csw.html) |
| DGN | [Microstation DGN v7](https://www.gdal.org/drv_dgn.html) |
| DXF | [AutoCAD DXF](https://www.gdal.org/drv_dxf.html) |
| EDIGEO | [EDIGEO](https://www.gdal.org/drv_edigeo.html) |
| ELASTIC | [Elasticsearch: Geographically Encoded Objects for Elasticsearch](https://gdal.org/drivers/vector/elasticsearch.html) |
| FLATGEOBUF | [FlatGeobuf](https://gdal.org/drivers/vector/flatgeobuf.html) |
| GEOJSON | [GeoJSON](https://www.gdal.org/drv_geojson.html) |
| GEORSS | [GeoRSS](https://www.gdal.org/drv_georss.html) |
| GML | [GML](https://www.gdal.org/drv_gml.html) |
| GMLAS | [GMLAS](https://www.gdal.org/drv_gmlas.html) |
| GMT | [GMT](https://www.gdal.org/drv_gmt.html) |
| GPKG | [GeoPackage vector](https://gdal.org/drivers/vector/gpkg.html) |
| GPSBABEL | [GPSBabel](https://www.gdal.org/drv_gpsbabel.html) |
| GPX | [GPX](https://www.gdal.org/drv_gpx.html) |
| GTFS | [General Transit Feed Specification](https://gdal.org/drivers/vector/gtfs.html) |
| IDRISI | [Idrisi Vector (.VCT)](https://www.gdal.org/drv_idrisi.html) |
| ILI | ["INTERLIS 1" and "INTERLIS 2" drivers](https://gdal.org/drivers/vector/ili.html) |
| JML | [OpenJUMP .jml](https://gdal.org/drivers/vector/jml.html) |
| JSONFG | [OGC Features and Geometries JSON](https://gdal.org/drivers/vector/jsonfg.html) |
| KML | [KML](https://www.gdal.org/drv_kml.html) |
| LIBKML | [LIBKML Driver (.kml .kmz)](https://gdal.org/drivers/vector/libkml.html) |
| LVBAG | [Dutch Kadaster LV BAG 2\.0 Extract](https://gdal.org/drivers/vector/lvbag.html) |
| MAPML | [MapML](https://gdal.org/drivers/vector/mapml.html) |
| MEM | [In Memory Raster](https://www.gdal.org/frmt_mem.html) |
| MVT | [Mapbox Vector Tiles](https://www.gdal.org/drv_mvt.html) |
| NAS | [NAS \- ALKIS](https://gdal.org/drivers/vector/nas.html) |
| NGW | [NextGIS Web](https://gdal.org/drivers/vector/ngw.html) |
| ODS | [Open Document Spreadsheet](https://gdal.org/drivers/vector/ods.html) |
| OPENFILEGDB | [ESRI FileGDB](https://www.gdal.org/drv_openfilegdb.html) |
| OSM | [OpenStreetMap XML and PBF](https://gdal.org/drivers/vector/osm.html) |
| PDS | [NASA Planetary Data System](https://www.gdal.org/frmt_pds.html) |
| PGDUMP | [PostgreSQL SQL dump](https://www.gdal.org/drv_pgdump.html) |
| PLSCENES | [Planet Labs Scenes API](https://gdal.org/drivers/vector/plscenes.html) |
| PMTILES | [ProtoMaps Tiles](https://gdal.org/drivers/vector/pmtiles.html) |
| S57 | [S\-57 (ENC)](https://www.gdal.org/drv_s57.html) |
| SDTS | [USGS SDTS DEM (\*CATD.DDF)](https://www.gdal.org/frmt_various.html#SDTS) |
| SELAFIN | [Selafin/Seraphin format](https://www.gdal.org/drv_selafin.html) |
| SHAPE | [ESRI Shapefile / DBF](https://gdal.org/drivers/vector/shapefile.html) |
| SQLITE | [SQLite / Spatialite](https://gdal.org/drivers/vector/sqlite.html) |
| SXF | [Storage and eXchange Format](https://www.gdal.org/drv_sxf.html) |
| TAB | [MapInfo TAB and MIF/MID](https://gdal.org/drivers/vector/mitab.html) |
| VDV | [VDV\-451/VDV\-452/IDF](https://www.gdal.org/drv_vdv.html) |
| VFK | [Czech Cadastral Exchange Data Format](https://gdal.org/drivers/vector/vfk.html) |
| VRT | [VRT \- Virtual Datasource](https://www.gdal.org/drv_vrt.html) |
| WASP | [WAsP .map format](https://www.gdal.org/drv_wasp.html) |
| WFS | [OGC WFS (Web Feature Service)](https://gdal.org/drivers/vector/wfs.html) |
| XLSX | [MS Office Open XML spreadsheet](https://gdal.org/drivers/vector/xlsx.html) |

Useful links
------------

[Folder vs. MBTiles vs. GeoPackage](/guides/map-tiling-hosting/data-processing/folder-vs-mbtiles-vs-geopackage)

# Output formats: GeoPackage, MBTiles, folder

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-processing/folder-vs-mbtiles-vs-geopackage/

When you're processing your data with [MapTiler Engine](/guides/map-tiling-hosting/data-processing/), one of the settings you need to specify is the **output format**. It means the format of the entire tileset, which is the container file containing the map tiles created from your data. This page explains the available formats and helps you choose the best one for your needs.

![Tiling output formats](./output-format.png)



**GeoPackage**

[GeoPackage](https://www.geopackage.org/) is an international open standard, compatible with many viewers and tools. It can contain a mix of formats, such as JPG and PNG tiles, and supports storing metadata. Combining multiple tilesets into one GeoPackage file is also allowed. 



**MBTiles**

MBTiles is an open standard developed by Mapbox. Like GeoPackage, it's a single file, but has a few limitations: It can only contain tiled data, it doesn't support mixing formats within one tileset, and it can take just one tileset as input. However, MapTiler Engine can [merge MBTiles tilesets](/guides/map-tilling-hosting/data-processing/how-to-merge-tilesets-mbtiles/) if needed.

> [!WARNING]
> The **maximum zoom** level for vector MBTiles is currently limited to **22**. If you need larger zoom for vector tiles, please use GeoPackage.
 **Raster** MBTiles aren't limited, but for tilesets with max zoom above 22, there will be **no preview** of the result.



**Folder with tiles**

A folder with tiles contains a structure of subfolders for specific zoom levels. The folder output might be required by legacy applications, or you might prefer it if you're self-hosting in a private cloud – it takes longer to upload to the hosting server, but once it's there, it provides a faster response time. 

Please note that MapTiler Engine only supports direct upload to private clouds for single-file formats, so if you want to use folder with files, you'll need to upload it to your cloud manually.



**Google Earth KML**

Additionally, we offer the [KML format](https://developers.google.com/kml/documentation) to generate map tiles compatible with Google Earth.

## Recommended use

- For **smaller maps**, any format will work fine. If unsure, go for GeoPackage.
- For **larger maps**, use GeoPackage and host your tiles in MapTiler for fast and stable access.
- If you're building **maps for mobile devices**, choose a single-file format (GeoPackage or MBTiles).
- If you plan to use **own map hosting**, folder with tiles is best for fast access to the map.
- If you need map tiles for **Google Earth**, choose KML.

Generally, if you don't have any special requirements such as compatibility with specific software tools, **GeoPackage** is a safe universal choice.

## Format comparison

|                               | **GeoPackage** | **MBTiles** | **Folder with tiles** | 
| :---                          | :----: | :----: | :----: | 
| **Format structure**          | Single file (.gpkg) | Single file (.mbtiles) | Folder with files | 
| **Mixed contents allowed?**   | ✅ | ❌ | ✅ | 
| **Output coordinate system**  | Any incl. national | Global Mercator (EPSG:3857) | Any incl. national | 
| **Direct upload to cloud**    | ✅ | ✅ | ❌ | 
| **MapTiler Server support**   | ✅ | ✅ | ❌ |

# MapTiler Engine technical specification

Source: https://docs.maptiler.com/guides/map-tiling-hosting/data-processing/maptiler-engine-technical-specification/

This article provides an overview of the technical specification of the MapTiler Engine application. It shows which versions of operating systems MapTiler Engine is available for, what input and output file formats are supported, and which coordinate systems can be used.

Operating systems
-----------------

* Windows 10 (1809 or later)
* Windows Server 2016 or newer
* macOS 12\+
* Linux 64bit Debian, Ubuntu, RedHat, Fedora (with glibc \>\= 2\.35\)

Input formats
-------------

* Raster and vector data formats. The complete list of supported file formats can be found [here](/guides/map-tiling-hosting/data-processing/supported-formats).

Output formats
--------------

* OGC GeoPackage
* MBTiles
* Folder with tiles
* OGC KML

Comparison of the output formats is available [here](/guides/map-tiling-hosting/data-processing/folder-vs-mbtiles-vs-geopackage). 

Supported CRS
-------------

* Complete EPSG database, custom\-defined SRS via Proj. Over 6,000 coordinate systems worldwide.

Upload options (Cloud storage)
------------------------------

* [MapTiler](https://www.maptiler.com/cloud/customize/)
* Amazon S3
* Google Cloud Storage
* Microsoft Azure

Key features
------------

* [Intelligent workflows](/guides/map-tiling-hosting/data-processing/intelligent-workflows)
* [Creation of map tiles from raster data](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-raster-data)
* [Creation of map tiles from vector data](/guides/map-tiling-hosting/data-processing/how-to-create-tiles-from-vector-data)
* [Merging multiple tilesets (MBTiles)](/guides/map-tiling-hosting/data-processing/how-to-merge-tilesets-mbtiles)
* [Direct upload to the cloud](/guides/map-tiling-hosting/data-processing/how-to-upload-a-tileset-to-maptiler-cloud)
* [Visual georeferencer for raster data](/guides/map-tiling-hosting/data-processing/how-to-georeference-your-raster-data)

# Installation | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/installation/

MapTiler Engine command line utility comes as part of [MapTiler Engine](https://www.maptiler.com/engine/) product and it is available from the **Pro** subscription plan as *maptiler-engine*.

## [Windows](#windows)

Get the installation package from the [MapTiler Engine download page](https://www.maptiler.com/engine/download/) and start the installation wizard. Once it's finished, run MapTiler Engine from the standard Command Prompt application in Windows:

``` bash
> maptiler-engine
```

### Silent install

To install MapTiler Engine on Windows workstations remotely without the end users' interaction, use the `VERYSILENT` argument in CLI. The installation **requires admin rights**. 

``` bash
>  /VERYSILENT
```

By default, MapTiler Engine gets installed to **C:\Program Files**. If you need to change the location, use the `DIR` argument: 

``` bash
>  /VERYSILENT /DIR=
```

Note that even though the installation itself is silent, the end user might [get a prompt to set firewall rules](/guides/map-tiling-hosting/data-processing/installation-on-windows/#windows-firewall) when they run MapTiler Engine for the first time.

## [macOS](#macos)

Get the installation disk image (DMG) from the [MapTiler Engine download page](https://www.maptiler.com/engine/download/). Open the disk image in macOS and drag the "MapTiler Engine Pro" icon into your "Application" folder. The command line interface can be started from Terminal application:

``` bash
$  /Applications/MapTiler Engine.app/Contents/MacOS/maptiler-engine
```

All versions of macOS higher than 10.12 (Sierra) are supported.

## [Linux](#linux)

Get the installation package from the [MapTiler Engine download page](https://www.maptiler.com/engine/download/). We provide a DEB package for Debian-based Linux distributions (Ubuntu, Debian) and RPM package for RedHat-based distributions (Fedora, CentOS). Then run the installation:

- For DEB packages, use: `sudo dpkg -i maptiler-engine-x.x.x-app-linux.deb` 
- For RPM packages, use: `sudo rpm -i maptiler-engine-x.x.x-app-linux.rpm`
	
The command line utility gets installed in the standard binary location `/usr/bin/`. To start it, run:

``` bash
$ maptiler-engine
```

Another option for running the latest MapTiler Engine on any Linux distribution is via the [Docker container](https://hub.docker.com/r/maptiler/engine/).

# Getting started | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/getting-started/

The main purpose of the software is to generate tiles in a defined tiling system, given some options and inputs. The only mandatory option is -o for the output directory. This directory must not exist yet when you run MapTiler Engine, to avoid overwriting existing data by mistake. As input, you can just provide the source dataset filename(s)[^1].

``` bash
  maptiler-engine -o output_directory input_file.ext
```

an example:

``` bash
  maptiler-engine -o tiles map.tif
```

To render more files at once, just specify them one after another:

``` bash  
  maptiler-engine -o output_directory input1.tif input2.tif input3.tif
```

If you start the maptiler-engine without arguments or with -help option, it will print all available commands:

``` bash
  maptiler-engine -help
```

## [Command Structure](#command-structure)

![maptiler-engine command structure](./maptiler-engine_command_structure.jpg)

The global options apply to all input files, in other words:

**Only arguments specified BEFORE the input filenames are applied to all files!**

Arguments which should be applied only to a single file are specified AFTER the name of such file (for example zoom level range specific only
to that file) and has higher priority than the global options.

## [Setting CPU limits](#setting-cpu-limits)

MapTiler Engine is a multi-threaded program. By default, it will use all the CPUs you have and print the information about the cores. You can also set a limit on the defined number of cores yourself with the `-P` option.

##### [-P [num]](#-p-num)
Set number of CPU cores to be used for render process.

Example:

``` bash
  maptiler-engine -P 4 ...
```

This is especially practical to evaluate the demo application before purchasing a license for a particular number of cores.

The modern CPUs has multiple cores and support of Hyperthreading - which provides multiple logical CPUs per core. This way MapTiler Engine can provide higher performance with `-P` 4 even on a dual-core computer.

[^1]: Depending on your operating system you may need to call the command differently than just maptiler-engine, typically on Linux and Mac in the actual directory as ./maptiler-engine and on Windows as maptiler-engine.exe.

# Input options | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/input-options/

## [Supported input file formats](#supported-input-file-formats)

MapTiler Engine is able to open and process a large number of raster geodata formats, including: GeoTIFF, Erdas Imagine, ECW, MrSID, JPEG2000, SDTS, DTED, NITF, HDF4/5, BSB/KAP, OziExplorer, etc.

The complete list of [supported formats is available online here](https://support.maptiler.com/i279-supported-formats).

## [Spatial reference system](#spatial-reference-system)

Practically any modern existing georeferencing coordinate system (SRS - spatial reference system, e.g. geodetic datum + map projection with parameters) is supported, which means the software can process almost any geodata you may have available from all over the world.

In case the input files contain already the definition of a used coordinate system (SRS) then MapTiler Engine is able to load it and directly use this information for the transformation of the maps. In case this information is missing in the supplied file or it is incorrect (the maptiler place the maps on a wrong location, you can still assign the information about the spatial reference system with an option:

##### [-srs [definition]](#-srs-definition)  
Dataset projection. Can be WKT, EPSG code in the form of 'epsg:XXXX', PROJ.4 string. Beware of escaping. To search for identifiers or definitions use [EPSG.io](https://epsg.io/) or [spatialreference.org](https://spatialreference.org/).

Example of assigning the United Kingdom spatial reference OSGB to a GeoTIFF file before rendering:

``` bash
  maptiler-engine -o tiles -srs EPSG:27700 map_in_osgb.tif
```

## [Transparency from a color](#transparency-from-a-color)

##### [-nodata [r] [g] [b]](#-nodata-r-g-b)  
This command is typically used to eliminate borders of multiple map sheets that are stitched together. You can set a specific color of the map to be considered fully transparent during rendering.

Example for removing fully black border around a map:

``` bash
  maptiler-engine -o tiles map.tif -nodata 0 0 0
```

## [Georeference / calibration](#georeference--calibration)

Georeferencing can also be done visually using [GUI](https://www.maptiler.com/how-to/georeferencing/) or [online tool](https://www.georeferencer.com/).

For proper rendering of the maps the location of supplied input files in the known coordinate system (SRS) must be available. MapTiler Engine is loading the geolocation automatically from the internal headers of the input files (such as GeoTIFF) or from external supportive files (such as ESRI WorldFile) if they are available.

To enforce a custom selected georeference information or loading from external files these options are available:

##### [-bbox [minx] [miny] [maxx] [maxy]](#-bbox-minx-miny-maxx-maxy)
To manually set bounds of a file in the specified spatial reference system.

##### [-geotransform [posX] [scaleX] [rotX] [posY] [rotY] [scaleY]](#-geotransform-posx-scalex-rotx-posy-roty-scaley)  
To assign affine transformation directly. This option can be also used with its short name `-gt`.

##### [-georeference [path_to_file]](#-georeference-path_to_file)
An option to load external georeference from World File, Tab File, OziExplorer Map File or .prj file.

##### [-corners [east1] [north1] [east2] [north2] [east3] [north3]](#-corners-east1-north1-east2-north2-east3-north3)  
To assign affine transformation with 3 corner points: [0, 0], [width, 0], [width, height]. This option can be used with WGS84 Coordinate System (EPSG:4326) as arguments `lng1 lat1 lng2 lat2 lng3 lat3`, which will set up -srs EPSG:4326 for files without a specified Coordinate system.

The geolocation can be specified using three or more control points - GCP (Ground Control Point). Each GCP is defined by the position on the raster (pixel_x and pixel_y), which is associated with a georeferenced location (easting northing [elevation]). The last element (elevation) is mostly zero.

##### [-gcp [x_pixel] [y_pixel] [easting] [northing] [elevation]](#-gcp-x_pixel-y_pixel-easting-northing-elevation)  
To assign a ground control point. At least three control points are required. The last elemet `[elevation]` is optional value.

##### [-order [value]](#-order-value)  
An option to set the polynomial order for transformation method of assigned GCPs. Supported orders are 0 (auto), 1 (affine) and 2 (polynomial of second order). By default, the automatic order is selected based on a number of GCP points.

##### [-tps](#-tps)
Force the use of Thin Plate Spline transformer based on assigned GCP points. This option cannot be used with `-order`. This option is recommended for more than 10 assigned GCPs.

Example for using TPS transformation with assigned GCPs:

``` bash
  maptiler-engine -o tiles map.tif -srs EPSG:26712 -tps -gcp 0 0 386638.171 3999090.834 -gcp 5400 0 399627.528 3999090.834 -gcp 5400 6800 399627.528 3982553.605
```

## [Cutline (Crop)](#cutline-crop)

There are two command line options for cutline: `-cutline` and `-cutline_proj`. They specify the cutline (a clipping path) for an input image in pixels or in projected coordinates. They both expect a file name. The file can be either CSV or an OGR dataset (such as ESRI ShapeFile .shp).

From an OGR file, MapTiler Engine will load all polygons and multi-polygons from all features of the first layer.

The CSV format with pixel coordinates of nodes of a triangle, more lines will create polygon:

``` csv
  X1,Y1
  X2,Y2
  X3,Y3
```

##### [-cutline [path]](#-cutline-path)  
A pixel-based cutline is specific for each input file - so the parameter should be used after a filename (see section [MapTiler Engine Command Structure](#maptiler-engine-command-structure)).

Example of use of such a pixel-based cutline:

``` bash
  maptiler-engine -o outputdir input.tif -cutline polygon.csv
```

##### [-cutline_proj [path]](#-cutline_proj-path)  
A cutline with geocoordinates can be used for multiple files if it is specified before the first input file.

Another example of cutline with geocoordinates stored in a .shp file (may require accompanying .prj file with a coordinate system):

``` bash  
  maptiler-engine -o outputdir input.tif -cutline_proj shape.shp
```

##### [-cutline IGNORE](#-cutline-ignore)
Ignore embedded cutline of the file.

Example:

``` bash
  maptiler-engine -o outputdir input_with_cutline.tif -cutline IGNORE
```

## [Color correction](#color-correction)

MapTiler Engine allows you to specify several parameters in order to improve the colors of the output map. The MapTiler Engine Pro (GUI) is able to estimate these values interactively, but you can also use the following options to specify them manually.

##### [-color_gamma [r] [g] [b]](#-color_gamma-r-g-b)
Specify gamma correction of the individual channels, higher values result in brighter pixels (1 = unchanged).

##### [-color_contrast [contrast] [bias]](#-color_contrast-contrast-bias)
Higher values of "contrast" result in bigger different between dark and light areas (0 = unchanged).

Use "bias" if you want to keep more details in the dark/light areas (0.5 = equal, <0.5 = details in light areas, >0.5 = details in dark areas)

##### [-color_saturation [saturation]](#-color_saturation-saturation)
Modify saturation of the map (1 = unchanged, 0 = grayscale, >1 = colorful)

## [Multiple files into multiple MBTiles or Folders](#multiple-files-into-multiple-mbtiles-or-folders)

MapTiler Engine is designed to produce a single merged layer from multiple input files. If you need to process multiple files and for each produce separate tileset then a batch processing is recommended.

Example:

This command processes every .tif file in a local directory and creates .mbtiles from each in the output directory. If .mbtiles is removed from the command, it produces separate directories instead. The command differs on operating systems:

Windows

``` bash
  for %f in (*.tif) do ( echo %f && maptiler-engine -o output/%f.mbtiles %f )
```

When used in a batch file the %f must be %%f.

Linux / macOS

``` bash
  for %f in *tif; do echo $f; maptiler-engine -o output/`basename $f .tif`.mbtiles $f; done;
```

# Output options | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/output-options/

The default behaviour of MapTiler Engine is to write tiles each into its own file, under the directory structure:

  `output_directory/z/x/y.ext`

Where z is the zoom level, and x and y tile coordinates on relevant zoom level in the tiling profile.

The produced directory structure contains also a simple HTML viewer and description of the dataset in metadata.json, compatible with mb-util and [MapTiler Server](https://www.maptiler.com/server/) project.

MapTiler Engine supports direct output of the rendered map tiles into an SQLite database (MBTiles or GeoPackage format). This simplifies transfer and management of the tilesets and is practical for mobile applications.

## [Tiling profile / Tile Matrix Set](#tiling-profile--tile-matrix-set)

A global option defining the
output system of tiles - the target coordinate system, tile pixel size, etc. MapTiler Engine comes with these predefined most popular systems and possibility to specify a custom profile.

##### [-mercator](#-mercator)  
DEFAULT. The spherical Mercator tile profile compatible with Google, Bing, Yahoo Maps, MapQuest, OpenStreetMap, and mobile maps on iOS and Android. This is the most commonly used profile. It uses coordinate system defined as EPSG:3857 or EPSG:900913. Details [available here](https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection/).

In case you wish to use different tiling system, you must specify it as the first command on the command line. These are the alternatives:

##### [-gearth](#-gearth)  
Tile profile specific for Google Earth according to the KML SuperOverlay definition.

##### [-raster](#-raster)  
Rendering raster files without a need of georeferencing is also possible.

##### [-garmin](#-garmin)  
To produce the format for Garmin GPS devices, with a size 1024x1024 pixels and output to .kml file. Afterwards, pack the tiles and the .kml tiles into a .zip archive, change its extension to .kmz and save it into the device.

##### [-custom](#-custom)  
You can specify your own tiling system. See the appropriate section under the Advanced options chapter for more information.

Example: command for producing tiles for use with Google Earth:

``` bash
  maptiler-engine -gearth -o tiles map.tif
```

Example: command for producing tiles for use with Geodetic WGS84 Plate Caree:

``` bash
  maptiler-engine -raster -o raster-tiles map.tif
```

## [Custom tiling presets](#custom-tiling-presets)

MapTiler Engine offers predefined custom tiling presets (custom tile grids) for Advanced customers. Each custom tiling preset has its own
area coverage, some are for World, other covers only specifical States or group of States.

##### [-preset geodetic](#-preset-geodetic)  
WGS84 Plate Caree / Unprojected. Compatible with most existing WMS servers, OpenLayers base map.

Example:

``` bash
  maptiler-engine -preset geodetic -o wgs84-tiles map.tif
```

##### [-preset standard_grid](#-preset-standard_grid)  
Standard global tilegrid with a selected Coordinate system. This tiling preset keeps the original coordinate system (SRS), and cuts the input map into tiles according to the spherical mercator tile profile. **Note** this is not compatible with Google Mercator profile `mercator`!

Example:

``` bash
  maptiler-engine -preset standard_grid -o st-grid-tiles map.tif
```

##### [-preset baidu](#-preset-baidu)
Tilegrid defined for China customers. This preset cover only China region and is compatible with Baidu Maps service.

Example:

``` bash
  maptiler-engine -preset baidu -o tiles map-china.tif
```

##### [-preset yandex](#-preset-yandex)  
Custom tiling preset used in Russian web mapping service, compatible with Yandex.Maps. Coverage is limitted to Russia and Ukraine.

Example:

``` bash
  maptiler-engine -preset yandex -o tiles map-russia.tif
```

##### [-preset cz_jtsk](#-preset-cz_jtsk)  
National tiling grid for Czechia and Slovakia with a precision up to 1 meter per pixel.

Example:

``` bash
  maptiler-engine -preset cz_jtsk -o cz-tiles map-czechia.tif
```

##### [-preset fr_rgf93](#-preset-fr_rgf93)
Tilegrid defined for precise overlay of maps in France, using Lambert 93 conic projection.

Example:

``` bash
  maptiler-engine -preset fr_rgf93 -o fr-tiles map-france.tif
```

##### [-preset nl_rdnew](#-preset-nl_rdnew)
National tiling grid for Netherlands - Rijksdriehoekstelsel New / Amersfoort.

Example:

``` bash
  maptiler-engine -preset nl_rdnew -o netherlands-map map-amsterdam.tif
```

##### [-preset uk_osgb [zoom_group]](#-preset-uk_osgb-zoom_group)
National tiling grid for the United Kingdom using Ordnance Survey projection. This custom preset requires a specific zoom_group, which limits output zoom levels of this grid. Supported values with zoom levels in the bracket are: `0` (z0), `1` (z1 - z2), `2` (z3 - z6), `3` (z7 - z8), `4` (z9 - z10).

Example:

``` bash
  maptiler-engine -preset uk_osgb 1 -o gb-z1 map-london.tif -zoom 1 2
  maptiler-engine -preset uk_osgb 2 -o gb-z3 map-london.tif -zoom 3 6
```

##### [-preset ch_lv03 [zoom_group]](#-preset-ch_lv03-zoom_group)
Swiss national tiling grid used in Switzerland and Liechtenstein with high precision. This custom preset requires a specific zoom group, with values from 0 to 21. These values are mostly represented for the specific zoom level. Output tiles could be combined and are compatible with SwissTopo maps.

Example:

``` bash
  maptiler-engine -preset ch_lv03 3 -o ch-z3 map-zurich.tif -zoom 3 3
  maptiler-engine -preset ch_lv03 4 -o ch-z4 map-zurich.tif -zoom 4 4
```

Note that, `-zoom 3 3` is not required and it is automatically limited as defined for this zoom group.

##### [-preset nz_nztm [zoom_group]](#-preset-nz_nztm-zoom_group)  
New Zealand Geodetic Datum (NZGD2000), official geodetic datum for New Zealand and its offshore islands. This custom preset requires a specific zoom group, which limits output zoom levels of this grid. Supported values with zoom levels in the bracket are: `0` (z0-z7), `1` (z8-z10), `2` (z11-z13), `3` (z14-z16).

Example:

``` bash
  maptiler-engine -preset nz_nztm 1 -o nz-z8 map-new-zealand.tif
```

## [Retina / HiDPI tiles](#retina--hidpi-tiles)

##### [-scale [value]](#-scale-value)  
To create high-resolution Retina / HiDPI tiles with variable floating scale. Retina tiles are available for each profile and custom tiling presets listed above. Important note, the scale value cannot exceeded max allowed tile size in pixels: 4096 x 4096. It means, max available value for `-scale` is 16.0.

Example: the command for producing standard Retina tiles in Mercator profile

``` bash
  maptiler-engine -mercator -scale 2.0 -o tiles@2x map.tif
```

Example: the command for producing Retina tiles at 1.5 scale in raster profile

``` bash
  maptiler-engine -raster -scale 1.5 -o tiles-retina map.tif
```

## [Zoom levels](#zoom-levels)

##### [-zoom [min] [max]](#-zoom-min-max)  
This option determines which layers of the tile pyramid will be generated. The default is the "native" level calculated from image resolution. In case you need to add additional zoom levels, you can either define them as absolute numeric values or as relative numbers to the “native” levels with prefix + and -.
Each input file can have its own explicit option for zoom levels.

Example: zoom levels are automatically calculated as eg. 1 - 5

``` bash
  maptiler-engine -o tiles map.tif
```

Example: zoom levels are explicitly set to be 3 - 5

``` bash
  maptiler-engine -o tiles map.tif -zoom 3 5
```

Example: zoom levels are set to be 1 - 6 with relative value to native zoom levels

``` bash
  maptiler-engine -o tiles map.tif -zoom +0 +1
```

Example: zoom levels are set to be 2 - 4 with relative value to native zoom levels

``` bash
  maptiler-engine -o tiles map.tif -zoom +1 -1
```

Example: zoom levels are set to 0 - 4, as explicit minimum, relative maximum to native zoom level

``` bash
  maptiler-engine -o tiles map.tif -zoom 0 -1
```

## [Tile formats](#tile-formats)

The produced tiles can be saved in one of several image format. MapTiler Engine includes optimization of the final filesize and used a number of colors (quantization), to minimize the disk size occupied by the rendered maps as well as the time necessary to transfer the maps to clients once the tiles are online.

### [Formats with support for transparency](#formats-with-support-for-transparency)

##### [-f png8a](#-f-png8a)
DEFAULT. Paletted RGBA PNG image optimized for rendering speed and output size

##### [-f png8qa](#-f-png8qa)
Paletted RGBA PNG image

##### [-f png or -f png32](#-f-png-or--f-png32)  
RGBA PNG image

##### [-f webp or -f webp32](#-f-webp-or--f-webp32)  
RGBA WebP image

### [Non-transparent formats](#non-transparent-formats)

##### [-f jpg or -f jpeg](#-f-jpg-or--f-jpeg)
Progressive JPEG image in the YCbCr color space

##### [-f png8](#-f-png8)
Paletted RGB PNG image optimized for rendering speed and output size

##### [-f png8q](#-f-png8q)
Paletted RGB PNG image

##### [-f png24](#-f-png24)
RGB PNG image

##### [-f webp24](#-f-webp24)  
RGB WebP image

## [Tile transparency or a background color](#tile-transparency-or-a-background-color)

No matter what input datasets you specify, after transforming them into the tiling profile projection, MapTiler Engine will handle them as RGBA images. The transparency can come from the image itself as an alpha channel (with support for partly transparent areas), it can be derived from a selected color (so-called NODATA color), or can be just a result of the transformation with the GDAL warping algorithm - for areas without available input data.

If the tile is completely transparent it is never saved to the disk to save the storage space.

If all of the pixels are fully visible (eg. opaque, maximum alpha is 255), the alpha channel is discarded and the tile is marked as non-transparent / opaque. Otherwise, the tile is marked as partly transparent with alpha.

If partly transparent tiles are saved in a tile format without support for transparency (such as JPEG specified with -f jpg option) then the background color is applied. Default background color is white (255,255,255), but you can specify your own with the option:

##### [-bg [r] [g] [b]](#-bg-r-g-b)  
The color of the background replacing transparency in the non-transparent tile formats.

For example:

``` bash
  maptiler-engine -f png8 -bg 0 128 0 ...
```

##### [-ignore_alpha](#-ignore_alpha)  
If your dataset contains four channels, but the fourth channel is not alpha channel, you can use this option to ignore this channel.

For example:

``` bash
  maptiler-engine -f png32 -ignore_alpha input_4bands.tif ...
```

## [Tile store format](#tile-store-format)

##### [-store dir|mbtiles|geopackage](#-store-dirmbtilesgeopackage)  
This option enforces the form of storage which is used for saving the rendered tiles. Possible options are the directory (dir), the MBTiles (mbtiles) and the GeoPackage (geopackage). The default is the directory, but in case the -o parameter ends with .mbtiles or .gpkg then rendering into MBTiles or GeoPackage is selected, respectively. This option specifies the store form explicitly.
**Note:** for more details on this subject read the section [Output](#output) in the chapter Usage above.

##### [-sparse](#-sparse)  
Skip the empty space between separate maps and don't create empty tiles. This option can improve the speed of rendering if there are huge areas between maps. This is the default option for `-store dir`.

##### [-no_sparse](#-no_sparse)
Fills the empty space between separate maps (if there is some) with empty tiles in the background colour. This option can take longer to render and take more disk space, if there are huge areas between maps, as these have to be created. This is a default option for `-store mbtiles` and `-store geopackage`.

Setting the sparse option in GUI is in [Advanced options dialog](https://www.maptiler.com/how-to/advanced-image-settings/).

## [MBTiles compatibility for GeoPackage](#mbtiles-compatibility-for-geopackage)

MapTiler Engine provides a toggle to make the generated GeoPackage conform to the MBTiles specification. The options to control it are:

##### [-mbtiles_compatible](#-mbtiles_compatible)
DEFAULT. The generated GeoPackage will be MBTiles-compatible. >= 11.2

##### [-no_mbtiles_compatible](#no_mbtiles_compatible)
MBTiles compatibility turned off. >= 11.2

As providing compliance with the MBTiles specification requires creating additional structures in the output GeoPackage file, its size will be slightly larger than that of the one generated without MBTiles compatibility.

## [Hybrid tile format](#hybrid-tile-format)

MapTiler Engine allows rendering into a hybrid tile format which allows transparent tiles using transparent format (such as PNG) and tiles without any transparency at all are saved in a different format (such as JPEG). For aerial photos overlays or other datasets, this can mean a significant saving of the storage. Generated files are without extensions. This is done to simplify the generated OpenLayers viewer.

Example of usage:

``` bash
  maptiler-engine -f hybrid   ...
  maptiler-engine -f hybrid jpg png8a ...
```
## [Tile quality](#tile-quality)

There are some options to specify parameters of the conversion into
image formats, which can significantly reduce the size of produced tiles
by degrading the output.

##### [-jpg_quality [value]](#-jpg_quality-value)  
The quality of JPEG compression. A number between 10 and 95. The default is 85.

##### [-quant_quality [value]](#-quant_quality-value)
The quality of quantization. A number between 1 and 100. The default is 100.

##### [-quant_speed [value]](#-quant_speed-value)
Higher speed levels disable expensive algorithms and reduce quantization precision. Speed 1 gives marginally better quality at significant CPU cost. Speed 10 has usually 5% lower quality but is 8 times faster than speed 8. The default is 10.
*If you experience issues with the visual quality of generated tiles with quantization involved try to set -quant_speed to lower values.*

##### [-webp_quality [value]](#-webp_quality-value)  
The quality of WebP compression. A number between 1 and 100. Level 100 means lossless compression. The default is 75.

##### [-webp_alpha_quality [value]](#-webp_alpha_quality-value)  
The quality of WebP alpha channel compression. A number between 1 and 100. Level 100 means lossless compression. The default is 100.

##### [-webp_lossless](#-webp_lossless)
Lossless WebP compression switch. >= 11.1

##### [-webp_lossy](#-webp_lossy)  
Lossy WebP compression switch. >= 11.1

##### [-webp_preset [default|picture|photo|drawing|icon|text]](#-webp_preset-defaultpicturephotodrawingicontext)  
WebP compression presets that use optimal algorithm parameters for a given data type. >= 11.1

Example of the rendering of a seamless map out of file map1.tif and map2.tif into tiles with an internal palette with optimal colors with higher visual:

``` bash
  maptiler-engine -o tiles -f png8a -quant_quality 90 -quant_speed 4 map1.tif map2.tif
```

## [Watermark](#watermark)

##### [-watermark [image_file.png]](#-watermark-image_filepng)  
It is possible to place your own watermark over rendered tiles to protect the online maps. The file should be smaller than a size of tiles. It is placed in a random position and burned into tiles.

A nice watermark file can be easily generated online by calling the Google Chart API:
[https://placehold.co/300x50/ffffff/000000?text=%C2%A9+ABC](https://placehold.co/300x50/ffffff/000000?text=%C2%A9+ABC)

By replacing ABC at the end of this URL a custom text phrase can be specified. We recommend setting the transparency of such watermark file by using a Photoshop or similar tool before applying it with MapTiler Engine.

##### [-watermark_opacity [value]](#-watermark-opacity_value)  
Set the opacity percentage that will be applied to the watermark image. Use the integer number in range from 1 (almost transparent) to 100 (fully visible). When applying the opacity to the image that is already opaque, these opacities will be combined. The default value is 100. >= 12.1

Example of applying the watermark image with 70% opacity:

``` bash
  maptiler-engine -o tiles -watermark watermark_image.png -watermark_opacity 70 map.tif
```

# Map Hosting | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/map-hosting/

## [MapTiler Upload utility](#maptiler-cloud)
The MapTiler Upload utility (introduced in MapTiler Engine 13.2) lets you easily upload tilesets in GeoPackage or MBTiles format directly to your [MapTiler account](https://maptiler.com/cloud/):

``` bash
  maptiler-upload upload filename.gpkg
```
This command uploads the file (tileset) to the MapTiler account that is associated with your MapTiler Engine license. 

If you need to upload the data to another MapTiler account, use the `--token` parameter:

``` bash
  maptiler-upload --token  upload filename.gpkg
```

The `--token` value is the [service token](https://docs.maptiler.com/cloud/api/authentication-token/) associated with the MapTiler account where you want to upload the tileset to.  

## [MapTiler Server](#maptiler-server)

To host MBTiles or GeoPackage from your own infrastructure, we recommend using [MapTiler Server](https://maptiler.com/server/). Upload your maps with a few clicks and display them in your application using [MapTiler SDK](https://www.maptiler.com/sdk-javascript/), MapLibre GL JS, Leaflet, OpenLayers, or CesiumJS. Go to [MapTiler Server documentation]([/guides/self-hosting/map-server/how-to-add-and-host-data-in-maptiler-server](https://docs.maptiler.com/guides/self-hosting/map-server/)) to learn more.

## [Standard web server](#standard-web-server)

It's also possible to easily host your maps on a standard hosting, such as an ordinary company web server: Upload the directory with tiles to your web hosting and the layer is automatically available. The maps can be opened in any viewer supporting OGC WMTS standard.

## [Cloud hosting – CloudPush](#cloud-hosting---cloudpush)

CloudPush enables you to upload your map tiles to Amazon S3, Google Cloud Storage, or Microsoft Azure Blob hosting. *Please note that this feature isn't currently supported on Windows!*

For detailed instructions, there is the [Amazon S3 cloud upload guide](https://www.maptiler.com/how-to/hosting-on-amazon-s3/) that explains how to prepare and upload an MBTiles or GeoPackage file using the MapTiler Engine GUI.

The following examples apply to Amazon S3 storage. To use Google Cloud Storage or Microsoft Azure Blob, replace the `s3` in the commands with `gs` or `az` respectively. 

Upload tiles from an MBTiles file to S3:

``` bash
  maptiler-cloudpush --access_key ACCESS_KEY --secret_key SECRET_KEY s3://bucket_name add filename.mbtiles
```

> [!WARNING]
> Note that the Amazon S3 bucket must already exist, its **Object Ownership** must be set to `ACLs enabled` and **Block Public Access** must be switched off.

List all maps in the CloudPush tile storage:

``` bash
  maptiler-cloudpush --access_key ACCESS_KEY --secret_key SECRET_KEY s3://bucket_name list
```

Delete a map:

``` bash
  maptiler-cloudpush --access_key ACCESS_KEY --secret_key SECRET_KEY s3://bucket_name delete filename
```

Delete the whole CloudPush storage:

``` bash
  maptiler-cloudpush --access_key ACCESS_KEY --secret_key SECRET_KEY s3://bucket_name destroy
```

### [Access credentials](#access-credentials)

The Amazon access and the secure key are available via [IAM service administration](https://portal.aws.amazon.com/gp/aws/developer/account/index.html?action=access-key) interface. The credentials for the Google Cloud Storage are under [Enable interoperable access](https://storage.cloud.google.com/m) in the menu of the service. The Azure Blob Storage requires the **Storage account name** as Access Key and the **Key** from the Microsoft [Azure Portal](https://portal.azure.com/) > Storage Accounts > Access keys.

Instead of providing the access credentials in every command, these can be set as system environment variables.

Example on Windows OS:

``` bash
  REM for Amazon S3
  set AWS_ACCESS_KEY_ID=[THE_ACCESS_KEY]
  set AWS_SECRET_ACCESS_KEY=[THE_SECRET_KEY]
  REM or for Google Cloud Storage
  set GOOG_ACCESS_KEY_ID=[THE_ACCESS_KEY]
  set GOOG_SECRET_ACCESS_KEY=[THE_SECRET_KEY]
  REM or for Microsoft Azure Storage
  set AZURE_STORAGE_ACCOUNT=[ACCOUNT NAME]
  set AZURE_STORAGE_ACCESS_KEY=[KEY]
```

Example on Linux/macOS:

``` bash
  # for Amazon S3
  export AWS_ACCESS_KEY_ID=[THE_ACCESS_KEY]
  export AWS_SECRET_ACCESS_KEY=[THE_SECRET_KEY]
  # or for Google Cloud Storage
  export GOOG_ACCESS_KEY_ID=[THE_ACCESS_KEY]
  export GOOG_SECRET_ACCESS_KEY=[THE_SECRET_KEY]
  # or for Microsoft Azure Storage
  export AZURE_STORAGE_ACCOUNT=[ACCOUNT NAME]
  export AZURE_STORAGE_ACCESS_KEY=[KEY]
```

And call the utility without these arguments:

``` bash
  maptiler-cloudpush s3://bucket_name list
  maptiler-cloudpush s3://bucket_name add filename.mbtiles
  maptiler-cloudpush gs://bucket_name list
  maptiler-cloudpush az://bucket_name list
```

### [Advanced options](#advanced-options)

It is possible to use further options such as:

##### [-create-bucket](#-create-bucket)
Automatically creates bucket, if not existing

##### [-no-index-json](#-no-index-json)
Not handling metadata in CloudPush instance index.json

##### [-raw](#-raw)
Same as –no-index-json

##### [-basename [path]](#-basename-path)
Sets custom basename (default: basename of MBTiles file)

##### [-private](#-private)
Uploaded objects are private (default: public)

##### [-emulator](#-emulator)
Enable Azure Storage Emulator API

List of available parameters can be displayed by running `./maptiler-cloudpush` without any parameter.

Example for using custom basename:

``` bash
  maptiler-cloudpush --basename myfile s3://bucket_name add filename.mbtiles
```

Uploads tiles with URL format `myfile/z/x/y.ext`. Custom basename contains directory separators (slash), for example:

``` bash
  maptiler-cloudpush --basename year/month/myfile s3://bucket_name add filename.mbtiles
```

Result will have URL in format: `year/month/myfile/z/x/y.ext`.

Region-specific hosting can be set up via environment variable AWS_BUCKET_REGION=[value] or with parameter -R [value].

Example for EU (Ireland) region:

``` bash
  maptiler-cloudpush -R eu-west-1 s3://bucket_name add filename.mbtiles
```

The list of S3 regions is provided by the utility with `--more-help` argument or visible at [https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)

To enable uploading tiles into [Azure Storage Emulator](https://docs.microsoft.com/en-us/azure/storage/common/storage-use-emulator), you need to pass the parameter `--emulator` for each command:

Example for emulator (does not require credentials):

``` bash
  maptiler-cloudpush --emulator az://bucket_name add filename.mbtiles
```

The Azure Storage uses the API of [the version 2015-02-21](https://docs.microsoft.com/en-us/rest/api/storageservices/version-2015-02-21).

# Advanced options | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/advanced-options/

## [Options in the optfile](#options-in-the-optfile)

In case you have a large number of arguments to pass to MapTiler Engine, such as many input files (total amount is unlimited for MapTiler Engine or MapTiler Engine Pro), you can prepare a text file with all the arguments and call it with `-optfile myarguments.mtp`. List of files can be easily created with ls or dir commands.

##### [-optfile [myarguments.mtp]](#-optfile-myargumentsmtp)  
Any arguments normally passed on the command line could be part of the `-optfile` text file. MapTiler Engine can combine arguments on the command line with arguments in the text file, such as:

``` bash
  maptiler-engine -o output_directory --optfile myarguments.mtp
```

The `.mtp` extension is acronym for **MapTiler Project**, which can be used in MapTiler Engine Pro GUI, [see our tutorial page](https://www.maptiler.com/how-to/save-and-load-project/).

## [Temporary directory location](#temporary-directory-location)

During rendering, MapTiler Engine also writes a substantial amount of data to a temporary directory. Not as much as will be in the output directory, but still. Please make sure there is enough space in the filesystem for it.

By default, the temporary directory will be created in the system default temporary location (`/tmp/` on Unix-like systems, or path from the environment variable%TEMP% on Windows-like systems). You can override this with the option:

##### [-work_dir [directory]](#-work_dir-directory)  
The location where to store temporary data during rendering. By default the system temporary directory.

Example:

``` bash
  maptiler-engine -work_dir /tmp -o /mnt/data/tiles /mnt/maps/*.tif
```

## [Setting metadata for the output](#setting-metadata-for-the-output)

It is possible to set certain metadata of the output generated with MapTiler Engine. The option is supported for all available output formats.

##### [-name [string]](#-name-string)  
Name of the generated map. >= 11.1

##### [-description [string]](#-description-string)
Description of the generated map. >= 11.1

##### [-legend [string]](#-legend-string)
Legend of the generated map. >= 11.1

##### [-attribution [string]](#-attribution-string)  
Attribution of the generated map, contains author or data sources. >= 11.1

## [Resampling methods](#resampling-methods)

The visual quality of the output tiles is also defined by the resampling method. Selected method is used for interpolation of the values of individual pixels and it affects the sharpness vs smoothness of the produced maps.

##### [-resampling near](#-resampling-near)
Nearest neighbor resampling. Rarely makes sense for production data. Can be used for quick testing, since it is much faster than the others.

##### [-resampling bilinear](#-resampling-bilinear)
DEFAULT. Bilinear resampling (2x2 pixel kernel).

##### [-resampling cubic](#-resampling-cubic)
Cubic convolution approximation (4x4 pixel kernel).

##### [-resampling cubic_spline](#-resampling-cubic_spline)
Cubic B-Spline Approximation (4x4 pixel kernel).

##### [-resampling average](#-resampling-average)
Average resampling, computes the average of all non-NODATA contributing pixels. (GDAL >= 1.10.0)

##### [-resampling mode](#-resampling-mode)
Mode resampling, selects the value which appears most often of all the sampled points. (GDAL >= 1.10.0)

Resampling overviews produced by MapTiler Engine are using the average method, by default. Another possible method is Nearest neighbor.

##### [-overviews_resampling near](#-overviews_resampling-near)
Nearest neighbor overviews resampling. Mostly used for elevation maps or similar.

##### [-overviews_resampling average](#-overviews_resampling-average)
Average overviews resampling, computes the averate of all non-NODATA contributing pixels.

## [Defining a custom tiling profile for a specified coordinate system](#defining-a-custom-tiling-profile-for-a-specified-coordinate-system)

MapTiler Engine allows defining a custom system of tiles which should be rendered. Such tiling scheme, or in the terminology of OGC WMTS service the TileMatrixSet is for the MapTiler Engine defined with parameters which must follow the tile profile option: `-custom`. This is **global option**, need to be specified BEFORE the input filenames

##### [-tiling_srs [definition]](#-tiling_srs-definition)
The spatial reference system, e.g. the coordinate system in which the tiles are created. Follows the definitions known from -srs.

##### [-tiling_bbox [minx] [miny] [maxx] [maxy]](#-tiling_bbox-minx-miny-maxx-maxy)  
The area which should be split into tiles defined in the tiling_srs coordinates.

##### [-tiling_resolution [zoomlevel] [resolution]](#-tiling_resolution-zoomlevel-resolution)  
Resolution in units of the tiling spatial reference system per pixel on the given zoom level. MapTiler Engine will automatically compute values for all other zoom levels, each having half the resolution of the previous one.

##### [-tiling_resolution from_output](#-tiling_resolution-from_output)
Resolution is calculated so as to fit whole input mapset into one tile on zoom level 0 with respect to bbox, srs, and tile size.

##### [-tiling_resolution from_input](#-tiling_resolution-from_input)  
The default behavior if the resolution is not specified. Resolution is calculated so as to not supersample the largest input map with respect to bbox, srs and tile size.

##### [-tile_size [width] [height]](#-tile_size-width-height)  
The pixel dimensions of one tile.

##### [-tiling_centered](#-tiling_centered)
Tile (0, 0) is in the center of the world.

## [Tiling scheme - naming of tiles](#tiling-scheme---naming-of-tiles)

MapTiler Engine uses Google XYZ naming of tiles, by default. It supports also the OSGEO TMS naming (with flipped Y axis), QuadKey naming (known by Microsoft Bing Maps), and ZYX naming (known by Microsoft Bing Maps). These tiling schemes are supported only for tile store in the directory (`-store dir`). This is **global option**, need to be specified BEFORE the input filenames.

##### [-xyz or -zxy](#-xyz-or--zxy)  
Google XYZ (top-left origin) naming of tiles. Folder path as `output_directory/{z}/{x}/{y}.{ext}`.

##### [-tms](#-tms)
OSGEO TMS (bottom-left origin), flipped Y axis as oppose to Google XYZ. This tiling scheme is defined as a standard for MBTiles.

##### [-quadkey](#-quadkey)
Microsoft Bing QuadKey (top-left origin). MapTiler Engine generates files named as quadkey separated into directories named as zoom level (`output_directory/{z}/{quadkey}.{ext}`). Details at [this microsoft website](https://msdn.microsoft.com/en-us/library/bb259689.aspx).

##### [-zyx](#-zyx)
Microsoft Bing ZYX (top-left origin) naming of tiles. Folder path as `output_directory/{z}/{y}/{x}.{ext}`.

## [Choose bands from multiple channels for RGBA color model](#choose-bands-from-multiple-channels-for-rgba-color-model)

MapTiler Engine allows to choose bands for RGB(A) color model from multiple map channels. The example is aerial images such as [Sentinel 2 sources](https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi/resolutions/spatial), which contains multiple spectral bands (channels) with different bandwidth, like Near Infra-Red, vegetation, cloud detection, etc. Only three classical bands are used for rendering via MapTiler Engine - RGB, Red Green and Blue bands, to construct True Color Images. This is **file options**, need to be specified AFTER the name of the input file.

##### [-b [red] -b [green] -b [blue] -b [alpha]](#-b-red--b-green--b-blue--b-alpha)  
Select an input band for the processing color model RGBA. The last part *-b [alpha]* is optional to select Alpha channel. Bands are numbered from 1. This allows to reorder source bands. >= 11.1

Example for Sentinel 2 image, where RGB bands are 4th, 3rd and 2nd, respectively for Red Green Blue colors:

``` bash
  maptiler-engine -o tiles sentinel2-image.multiband.tif -b 4 -b 3 -b 2
```

Example for generating red-only (1st band) image with alpha channel (4th band):

``` bash
  maptiler-engine -o red-tiles image.tif -b 1 -b 1 -b 1 -b 4
```

##### [-band_desc [string]](#-band_desc-string)
Select an input band for the processing color model RGBA by the band description. The `[string]` parameter can be a substring of the full band description string. Usage is the same as for the `-b` command. >= 11.1

## [Define band data scale](#define-band-data-scale)

It is possible to set the data scale for each of the color bands in the output generated with MapTiler Engine.

##### [-data_scale [min] [max]](#-data_scale-min-max)
Set data scale range for a band. The `min` parameter is optional. If omitted, the value will be set to 0. If the command is given only once, the same values will be set for all bands. To set different values for separate bands, the command has to be given 3 times (4 in case the alpha channel is used). >= 11.1

Example for setting all bands to range 0 - 400:

``` bash  
  maptiler-engine -o scaled-bands image.tif -data_scale 400
```

Example for setting different values for RGBA bands:

``` bash  
  maptiler-engine -o scaled-bands image.tif -data_scale 100 -data_scale 200 -data_scale 300 -data_scale 400
```

## [Interrupt and resume long-time rendering](#interrupt-and-resume-long-time-rendering)

The long-time rendering job can be interrupted by the end-user or a system failure (power-failure, no free space on the disk). MapTiler Engine supports only simple resume mode - render process can be continued on the same computer with the same options.

##### [-keep_unfinished](#-keep_unfinished)
To prevent deleting the existing output tiles and temporary files created by the application.

##### [-resume](#-resume)
To continue in the unfinished or interrupted rendering process. Requires the same arguments on the same computer. It skips encoding of the existing tiles. This option can be used also for the startup of the rendering process, it will automatically keep unfinished tiles.

## [Advanced warping arguments](#advanced-warping-arguments)

The advanced warping algorithms parameters can be specified with the option:

##### [-wo “NAME=VALUE”](#-wo-namevalue)
The warp options. See the [papszWarpOptions field at GDAL](https://gdal.org/api/gdalwarp_cpp.html#_CPPv415GDALWarpOptions).

Example:

``` bash
  maptiler-engine -o tiles -wo "SAMPLE_GRID=YES" t.tif -wo "SOURCE_EXTRA=16"
```

## [Watch progress in a frontend](#watch-progress-in-a-frontend)

MapTiler Engine can produce progress easily parsed in a frontend application. Simply use the first argument `-progress` and application output the progress on the standard output in the TSV (tabulator separated values) format: Stage TAB Percentage TAB Iteration TAB Total

Example:

``` bash
  maptiler-engine -progress -o tiles map1.tif map2.tif map3.tif

  Opening    16 %    1    6
  Opening    33 %    2    6
  Opening    50 %    3    6
  Opening    66 %    4    6
  Opening    83 %    5    6
  Opening   100 %    6    6
  Warping     0 %    0    4
  Warping    25 %    1    4
  Warping    50 %    2    4
  Warping    75 %    3    4
  Warping   100 %    4    4
  Rendering   0 %    0    512
  ...
  Rendering   100 %    512    512
```

## [Usage on a computer cluster](#usage-on-a-computer-cluster)

MapTiler Engine can run on an MPI cluster if a cluster-specific binary has been requested. If you have the MPI version, a shell wrapper to run it on a cluster is delivered as well.

A version of MapTiler Engine utilizing Map Reduce approach and Hadoop is under development, this will replace the older MPI.

More details are available on [MapTiler Cluster page](https://www.maptiler.com/cluster/).

## [Toptile options for cluster processing](#toptile-options-for-cluster-processing)

With MapTiler Engine it is possible to limit tiles generation to a specified tile subpyramid, what can dramatically reduce the rendering time in case only a part of the input is needed to be rendered. The coordinates of the required toptile need to be passed in `z/x/y` format to the following command. It is also possible (but not required for the subpyramid to generate) to specify a custom location in format of `path/to/file.tif`, where the toptile file will be saved as a watermark-free image. >= 12.1

Example

``` bash
maptiler-engine -o tiles -cluster_job 12/770/1607 -cluster_toptile toptile/toptile_image.tif ~/home/maps/high-res-map.tif
```

## [Vector inputs](#vector-inputs)

MapTiler Engine v10.0 and higher version supports rendering of Vector inputs into [MVT](https://github.com/mapbox/vector-tile-spec) (Vector tile) format. Vector rendering support requires an underlying GDAL library version 2.3.0 or higher, which is limited on the native Linux distribution. Using a [docker image](https://www.maptiler.com/engine/download/) with MapTiler Engine is recommended way for vector rendering on Linux OS. [MapTiler Engine](https://www.maptiler.com/engine/) offers GUI for Vector layers with a [practical sample](https://www.maptiler.com/how-to/) how-to article.

Vector input consist of one or more layers, which are rendered into the specific target layer in MVT format. Each feature of the source layer contains `key=value` attributes, that could be processed or renamed into the final attributes of the target layer. The following arguments are supported for the Vector input: `-srs`, `-zoom`, and `-bbox`, as they are described above. Other arguments are not respected for Vector rendering yet.

##### [-layer [src_name]](#-layer-src_name)
Select the **source layer** for the further processing of the vector input by the name. This argument is required for the arguments below.

##### [-target [name]](#-target-name)
Select (or create a new) **target layer** in the final tiles of MVT format. This is the name of the layer, which could be styled. This argument may be repeated more times to process features into a separate target layer with a different list of fields.

##### [-field [output_name] [src_name]](#-field-output_name-src_name)  
Set the attribute field with the name **src_name** from the **source_layer** to be presented in the final **target layer** as a attribute key **output_name**. The attribute value for each features from **source layer** is copied. This argument may be repeated more times to copy more attributes.

##### [-vector_tile_size [size]](#-vector_tile_size-size)
Set the output vector tile size in pixels. >= 11.1

##### [-vector_compress](#-vector_compress)
Use compression of the output vector tiles. >= 11.1

##### [-vector_no_compress](#-vector_no_compress)
Do not use compression of the output vector tiles. >= 11.1

Let assume, we have one Vector input with two **source layers**: *lines* and *polygons*. The source layer *lines* consists of the streets with these attributes keys *Name*, *Identifier* and *Main*. The source layer *polygons* contains geometry of some buildings with attributes keys *Ident*, *Num* and *Name*. We do want to create two **target layers** with renamed attributes.

Example

``` bash
  maptiler-engine -o mymap.mbtiles \
  input.shp \
  -layer lines \
    -target streets \
    -field id Identifier \
    -field name Name \
    -field is_main Main \
  -layer polygons \
    -target buildings \
    -field id Ident \
    -field name Name \
    -field number Num
```

The example above creates two new output layers: **streets** with attributes keys *id*, *name*, and *is_main*; and **buildings** layer with attributes keys *id*, *name*, and *number*.

# Merge MBTiles utility | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/utilities/

*This CLI utility is only available in [MapTiler Engine editions](https://www.maptiler.com/engine/pricing/) that include command line automation. Alternatively, you can merge your MBTiles [in a visual interface](/guides/map-tiling-hosting/data-processing/how-to-merge-tilesets-mbtiles/).* 

The utility enables you to merge multiple MBTiles into one file. This is useful if you need to update a previously rendered dataset, replacing a small existing area in a large dataset with a different, newly rendered raster data. 

## Basic usage

``` bash
  maptiler-merge-mbtiles [OPTION] BASE.mbtiles DETAIL.mbtiles [DETAIL_2.mbtiles]...
```

## Example

A typical usage scenario would consist of these steps:

1. **Render a large dataset with MapTiler Engine.** Merge several smaller input files into one large MBTiles file (with JPEG or PNG tiles internally) named `large.mbtiles`.

2. **Update one of the previously rendered input files.** Render just this one updated file into MBTiles, with the PNG32 format and zoom levels on which you want it to appear in the existing dataset. Save the new input file as `patch.mbtiles`.

3. **Update the large dataset with the new input file.** With the original dataset `large.mbtiles` and updated file `patch.mbtiles` ready, run the merge command:

``` bash
  maptiler-merge-mbtiles large.mbtiles patch.mbtiles
```

Existing tiles available in both sets will be merged. On the zoom levels that both tilesets contain, `patch.mbtiles` will replace the original `large.mbtiles`. The `large.mbtiles` file will be updated in place.

## Options

##### [-P [n]](#-p-n)
Set limit on the defined number of cores.

##### [-no_sparse](#-no_sparse)  
Fills the empty space between separate maps (if there is some) with empty tiles in a background color. This option can take longer to render, if there are huge areas between maps, as these have to be created. In case the maps overlap each other, there is no extra action involved. Default behavior without this option does not fill the empty space between separate maps.

##### [-reencode](#-reencode)
This option is useful when the 2 merged maps have a different format (e.g. jpeg and png). By default, the result is a hybrid format (combination of both of them). If reencode option is used, the chosen file is encoded to the actual format (which can slow down the process).

# License activation | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/license-activation/

## [Software activation online](#software-activation-online)

After a purchase of the software, when you receive your license key, it is necessary to activate MapTiler Engine. After activation, the demo version no longer enforces the “MapTiler DEMO” overlays.

To perform the online activation, use the following command:

##### [-activate [YOUR-OWN-LICENSE-KEY]](#-activate-your-own-license-key)
Activates MapTiler Engine with a proper license key. You can get your [license key online here](https://www.maptiler.com/pricing/).

Example:

``` bash
  maptiler-engine -activate YOUR-OWN-LICENSE-KEY
```

**In case you require to reinstall the computer, use the** `-deactivate` **command to be able to re-activate the license later on.**

The software activation for MapTiler Engine Pro via GUI [is described here](https://support.maptiler.com/i56-license-activation).

### [Software activation in a virtual machine](#software-activation-in-a-virtual-machine)

The activation process for MapTiler Engine running in a virtual machine requires online activation only via environment variable `MAPTILER_LICENSE`. The software will be automatically deactivated in the end.

The `MAPTILER_LICENSE` environment variable needs to be set before calling MapTiler Engine. There are two ways to do so. The first (and recommended) way is to add the `MAPTILER_LICENSE` variable to the system environment variables list. Then, you can call MapTiler Engine directly, like:

``` bash
  maptiler-engine ...
```

Alternatively, when you are calling MapTiler Engine from a script, or using it manually in a command line session, you need to set the `MAPTILER_LICENSE` environment variable before calling MapTiler Engine:

**Example on Windows OS (in command prompt)**

``` bash
  set MAPTILER_LICENSE=YOUR-OWN-LICENSE-KEY
  maptiler-engine ...
```
**Example on Windows OS (in Powershell)**

``` bash
  set $env:MAPTILER_LICENSE = 'YOUR-OWN-LICENSE ...
```


**Example on Linux / macOS**

``` bash
  export MAPTILER_LICENSE=YOUR-OWN-LICENSE-KEY
  maptiler-engine ...
```

**Notice:** This activation process via environment variable requires a **not-activated MapTiler Engine** instance on that computer! Starting MapTiler Engine application without setting this environment variable `MAPTILER_LICENSE`, you should see either **MapTiler Engine Pro Demo**, or **Your trial period has expired** error message.

You can also run MapTiler Engine in Docker. To learn more, please refer to [this documentation article](/guides/map-tiling-hosting/data-processing/maptiler-engine-in-docker).

## [Software deactivation online](#software-deactivation-online)

You can deactivate MapTiler Engine via command line, in order to transfer the application to another computer. Note that after the deactivation, MapTiler Engine will continue to run in DEMO mode, but the trial period of 14 days will **NOT** start again.

To do the online deactivation, use the following command:

##### [-deactivate](#-deactivate)
Deactivates activated MapTiler Engine software. MapTiler Engine can be used in Demo mode, if trial period has not expired.

Example:

``` bash
  maptiler-engine -deactivate
```

You can deactivate MapTiler Engine Pro [in GUI via License dialog described here](https://support.maptiler.com/i449-license-deactivation).

## [Demo trial extension](#demo-trial-extension)

The demo version of MapTiler Engine Pro is fully usable for 14 days after the first start. In case this trial period for testing the software before purchase expires and you would like to continue to test the demo, it is necessary to submit a request for a trial extension. The process for the GUI application is described [in this support article](/guides/map-tiling-hosting/data-processing/how-to-activate-trial-period-in-maptiler-engine). 

If you're running MapTiler Engine on a headless machine, you'll need to generate a report with the `maptiler-engine -report` command, save the output, and include it in a [request sent to the MapTiler Support](/support/requests/). 

## [License information](#license-information)

To check your license information, use the following command:

##### [-license](#-license)
Prints your license information for activated MapTiler Engine.

Example

``` bash
  > maptiler-engine -license
  License key: 
  License email: 
  Subscribed plan:  payment
  License active until , X days remaining.
  Purchased CPU cores: 4
  Logical CPU cores: 4 available
```

This argument may print additional texts, depending on your License, for example:

``` bash
  Activated offline, please use -deactivate_request command in order to deactivate your license.
```

# Bug report | MapTiler Engine Manual

Source: https://docs.maptiler.com/engine/bug-report/

##### [-report](#-report)
The argument `-report` generates the text report, which should be sent via the web form.

Attaching this file if you are reporting a bug is very important becuase this information helps us to identify the problem and quickly come up with a solution

Sending a bug report from MapTiler Engine GUI application is [described here](/guides/map-tiling-hosting/data-processing/submit-a-report/).

# Georeferencing tool for setting corners on a map

Source: https://docs.maptiler.com/engine/overlay-corners-leaflet/

















Copy&paste into MapTiler Engine under "Geographical location" → "Corners":







or use in the MapTiler Engine command line (CLI) after -corners




For more information about all engine options, visit MapTiler Engine command line documentation