# MapTiler documentation Source: https://docs.maptiler.com/ 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   Building maps with AI For beginners and hobbyists: See options how you can quickly get your map with AI. Learn more   MapTiler Agent Skill For professional developers: Get the skill for your AI agent directly from GitHub. Get the skill   # 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/) - [**MapTiler Geocoding** – main index changelog](/updates/geocoding/geocoding-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-09 ### GeoSplats terrain blending {#terrain-blending} We've added the possibility to blend your splat model with terrain for smooth, realistic result. You can use the feature in our 👉 [3D Editor](/guides/geosplats/3d-editor/get-started/#terrain-blending). *On 25th August 2026, we added terrain blending to how we process your splat models, so it works only with models uploaded after that date. To use it with an earlier model, re-upload the model and edit it again. The feature is supported in [GeoSplats SDK](/geosplats-sdk/) 1.1.0 and later.* ## 2026-08 ### EU-based API endpoint We've added a new API endpoint `api.maptiler.eu` for organizations requiring guarantees that their end-users' requests are processed strictly within the European Union. 👉 [Learn how to use the EU-based API endpoint](/guides/api/eu-based-api-endpoint/) ### API key security improvement We've converted all **default API keys** to regular custom keys to improve platform security. Previously, each account had one default key that was special and couldn't be protected. Now your default key behaves just like a standard API key, and you can apply security restrictions to it too. 👉 [Learn how to protect your API keys](/guides/maps-apis/maps-platform/how-to-protect-your-map-key) ## 2026-06 ### GeoSplats We're adding support for a new technology able to build fast photorealistic 3D maps. This includes a new **[3D Editor](/guides/geosplats/3d-editor/)** and **[GeoSplats SDK](/geosplats-sdk/)**. 👉 [Learn more and get started with GeoSplats](/guides/geosplats/) ### Icon sets management We've introduced advanced options to add, style, and replace map icons and other images. 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-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/) ## 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 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 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. 👉 [What deprecated v3 maps mean for your projects](/updates/deprecated/) 👉 [More about the v4 generation of MapTiler maps](https://www.maptiler.com/news/2025/10/new-generation-of-maptiler-maps) (blogpost) ## 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-09-26 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. ## Key statistics | Metric | Current count | Δ vs. previous | | :--- | :---: | :---: | | **Total objects** | 15,450,759,817 | 60,243,669 | | Nodes | 10,889,167,177 | 31,232,508 | | Ways | 1,220,281,432 | 2,809,427 | | Relations | 14,769,219 | 45,984 | | POI count | 56,821,714 | 184,072 | | Average tile size | 14kB | 10B | ## 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 # MapTiler Geocoding – release 2.15.24 Source: https://docs.maptiler.com/updates/geocoding/geocoding-latest/ This report provides a snapshot of our [Geocoding](/cloud/api/geocoding/) services. We regularly update the indexes to integrate the latest data and introduce new search features. - Status: **Upcoming** - Production deployment date: **2026-10-21** - Index version (data portal): **2.15.24** ## Main changes * **Global data refresh:** Full rebuild of the global indexes, adding **482,444** new POIs, **18,101** new natural and landform features, **16,112** new places, **5,844** new postal codes, and **4,677** new roads. This provides more comprehensive and up-to-date search results for users worldwide. ## Global and regional changes * **Global:** Full data refresh from recent OpenStreetMap updates and database improvements. ## Data trends and impact The table below provides a comparison of feature counts between the previous and new database versions, and explain what the change means in practice. | **Layer / file** | **Previous version (2.15.23)** | **New version (2.15.24)** | **Diff** | **Impact** | | :--- | :---: | :---: | :---: | :--- | | `address` | 31,121,249 | 30,436,318 | -684,931 | Address coverage is lower in this release. | | `poi` | 66,998,900 | 67,481,344 | +482,444 | Updated points of interest from OpenStreetMap. | | `place` | 5,139,426 | 5,155,538 | +16,112 | Continued growth of populated place coverage. | | `major_landform` | 4,139,520 | 4,157,621 | +18,101 | Updated natural and landform features. | | `road` | 1,159,159 | 1,163,836 | +4,677 | Added new road geometries and routing linkages. | | `postal_code` | 4,728,506 | 4,734,350 | +5,844 | Added new postal zones. | | `neighbourhood` | 83,104 | 83,861 | +757 | Updated neighborhood data. | | `locality` | 153,170 | 153,421 | +251 | Updated local administrative hierarchies. | | **Total** | **114,023,252** | **113,867,386** | **-155,866** | Overall database size changed by **-0.137%**. | *Only layers with meaningful changes are listed individually. The total reflects the entire global database.* ## Required actions **None.** This release is fully backward-compatible. All index updates apply automatically. API parameters, index names, and response shapes are unchanged. ## Update history You can find the history of all updates on the [MapTiler Geocoding updates](/updates/geocoding/) page. # Deprecated maps and datasets Source: https://docs.maptiler.com/updates/deprecated/ In your MapTiler account, older resources now have a `deprecated` label. A resource can be either a [**map** (style)](/guides/how-maps-work/#map-style) or a [**dataset** (tileset)](/guides/how-maps-work/maptiler-datasets/). Deprecation means that the map or dataset has become legacy and we have replaced it with a newer version. For example, the [3rd generation](/schema/planet/) of our main dataset MapTiler Planet has been deprecated and replaced with [4th generation](/schema/planet-v4/). Note that some deprecated maps and datasets may no longer be listed in your MapTiler account at all, as their use in new projects is not recommended. ## How it affects your maps We don't remove deprecated maps and datasets. We just stop active development to focus on the latest versions, so there won't be any further maintenance of the deprecated resources except for critical bug fixes. > [!NOTE] > Existing projects built with deprecated resources **continue to work** normally. Your map applications or websites don't break, they just **won't receive updates** anymore. - **API endpoints:** Existing API endpoints, TileJSON URLs, `style.json` URLs, and XYZ raster tile requests continue to serve data. - **Data updates:** Deprecated vector and raster tilesets don't receive updates. New roads, changed points of interest (POIs), or modified political boundaries won't show up. - *Exception: The MapTiler Planet v3 tileset will continue to receive data updates for a limited transition period of a few months.* - **Map updates:** Deprecated map styles don't receive design updates, typography tweaks, or new map layer additions. - **Maintenance:** We don't patch technical issues, rendering artifacts, or data anomalies discovered in deprecated versions. - *Exception: We'll fix critical bugs that could cause your projects to stop working.* ## Use latest resources For all new projects, we strongly recommend using the latest datasets and map styles, labelled `new` in your MapTiler account. These resources will be now getting the maintenance, improvements, and features unavailable in previous versions. Main benefits of using new resources include: - Continuous global data updates - Better performance thanks to optimized data schemas - Better customization experience in [Map Designer](/guides/getting-started/map-design/) - New rendering features: 3D buildings, dynamic terrain, localization, etc. ## Migrate existing projects The steps to replace deprecated resources in your existing projects depend on the project implementation: ### Catalog maps If you're using one of our older catalog maps *without any design customization*, upgrade it to a new map style by updating the `map_id` or the `style.json` URL in your map initialization code. **Example** This iFrame code uses the older [Outdoor v2](https://cloud.maptiler.com/maps/outdoor-v2/) map: `` To update the code to use the new [Outdoor v4](https://cloud.maptiler.com/maps/outdoor-v4/) map instead, replace the map style ID `outdoor-v2` with `outdoor-v4`. > [!NOTE] > In map applications implemented with [MapTiler SDK JS](/sdk-js/), you don't have to update anything – the latest in-built map styles are used automatically. See the [complete list of supported styles](/sdk-js/api/map-styles/#mapstylelist). If you specifically want to keep using the previous map style, add the `_V2` suffix. ### Custom maps Upgrading a deprecated custom map is more complex because different product generations use different internal data structures, so older maps are incompatible with newer datasets and vice versa. For example, the [Streets v2](https://cloud.maptiler.com/maps/streets-v2/) map uses [MapTiler Planet v3](https://cloud.maptiler.com/tiles/v3/) as its main data source, and it cannot be switched to [MapTiler Planet v4](https://cloud.maptiler.com/tiles/v4/). This means that if you have a custom map based off of an older catalog map like [Streets v2](https://cloud.maptiler.com/maps/streets-v2/), you can't simply replace the underlying data source to get the latest data updates. In this case, you have two options: - Re-create your custom map design using the new map style, or - Keep the old design which continues to work, but without data updates. ### Tilesets If your map project is consuming raw vector tiles, please review the [schema documentation](/schema/) for the new generation, as schema modifications may have introduced breaking changes to data parsing. # 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/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/using-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](/guides/credentials/api-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/using-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/using-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 use your map [in ATAK](/guides/using-map/atak-maps/). - 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/map-data/add-your-data/) so that it shows whatever you want to share with the world. Optionally, you can also [adjust the map design](/guides/map-design/editor/) 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/streets-v4/static/8.57,47.35,8.8/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE) 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. > [!NOTE] > Static maps **don't work with a free plan**. Get them with [any paid plan](https://www.maptiler.com/cloud/pricing/), 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 [secure the key](/guides/credentials/api-key/#secure-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/streets-v4/` 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/#tag/static-maps/GET/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}.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 [secure the key](/guides/credentials/api-key/#secure-key) before you publish it. _Bearing and pitch aren't supported at the moment._ ### Example [https://api.maptiler.com/maps/dataviz-v4/static/8.581627,47.137726,16/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE](https://api.maptiler.com/maps/dataviz-v4/static/8.581627,47.137726,16/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE) ![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/dataviz-v4/static/8.581627,47.137726,16/825x350@2x.png?key=YOUR_MAPTILER_API_KEY_HERE](https://api.maptiler.com/maps/dataviz-v4/static/8.581627,47.137726,16/825x350@2x.png?key=YOUR_MAPTILER_API_KEY_HERE) ## 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/base-v4/static/-70.3,-46.5,70.3,46.5/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE](https://api.maptiler.com/maps/base-v4/static/-70.3,-46.5,70.3,46.5/825x350.png?key=YOUR_MAPTILER_API_KEY_HERE) ![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=YOUR_MAPTILER_API_KEY_HERE&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 [secure the key](/guides/credentials/api-key/#secure-key) before you publish it. ![Add multiple basic markers](../img/basic-markers.webp) ## 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.webp) ## 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. - The icon image dimensions are max 4096 pixels (e.g. 64 × 64 px) - The icon size is max 64 KiB - 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/dataviz-v4/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.webp) ## 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/streets-v4/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.webp) Add multiple colored lines: https://api.maptiler.com/maps/base-v4/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.webp) Use a polygon to highlight a real estate property: https://api.maptiler.com/maps/hybrid-v4/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.webp) # Use a configurable link to map Source: https://docs.maptiler.com/guides/using-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/streets-v4/` 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 [secure the key](/guides/credentials/api-key/#secure-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/bright-v2/?key=YOUR_MAPTILER_API_KEY_HERE\#6/40\.018/\-3\.779](https://api.maptiler.com/maps/bright-v2/?key=YOUR_MAPTILER_API_KEY_HERE#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/streets-v4/?key=YOUR_MAPTILER_API_KEY_HERE\#12\.83/41\.39474/2\.16377/\-45/60](https://api.maptiler.com/maps/streets-v4/?key=YOUR_MAPTILER_API_KEY_HERE#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.webp) _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/using-map/iframe/). # Insert map with iFrame Source: https://docs.maptiler.com/guides/using-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. Prefer to have an AI assistant generate it for you instead? See [how to use MapTiler with AI](/guides/ai/how-to-use-with-ai/). ## 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) 4. Select the [API key](/cloud/api/authentication-key/) you want to use for this iFrame. ## Protect the API key The iFrame code looks like this: ```html ``` Note the part `YOUR_MAPTILER_API_KEY`. In this place, the code contains the API key you've selected. Before publishing the iFrame code, make sure to [**protect the key**](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/) so that it only allows usage on your website. ## 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.webp) _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. Select which of your [API keys](/cloud/api/authentication-key/) should be used in the code. 5. Copy the source code directly into your project. > [!WARNING] > Newly created API keys are not secured, so they're only suitable for internal testing. Before deploying the code to production, make sure 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/streets-v4/style.json?key=YOUR_MAPTILER_API_KEY_HERE). 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=YOUR_MAPTILER_API_KEY_HERE](https://api.maptiler.com/maps/streets-v4/256/3/4/2@2x.png?key=YOUR_MAPTILER_API_KEY_HERE) ### Other options If a JavaScript library is not required, use these standard integration methods: - [Embeddable viewer (iFrame)](/guides/using-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.webp) ## 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.webp) 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.webp) 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.webp) Click on the *Import...* button ![](./file_ba36bf5ead.webp) Import your TMS file and enjoy the beautiful map from your MapTiler account! ![](./file_ba26b3602a.webp) 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) # Use MapTiler maps in ATAK Source: https://docs.maptiler.com/guides/using-map/atak-maps/ [TAK](https://tak.gov/) (Team Awareness Kit) is a family of map-centric situational awareness apps used mainly in defense, emergency response, and public safety. This guide covers **ATAK**, the Android version, and explains how to show MapTiler maps in it. You can serve them either from the MapTiler API or from your own self-hosted MapTiler Server. ## Add a MapTiler map to ATAK ATAK consumes maps as raster XYZ tiles, fetched on demand as you pan and zoom, and the mapping service is defined in a MOBAC-format XML file. Adding a MapTiler basemap therefore means creating one small file and copying it to the right folder, with no further configuration needed. Here are the steps: 1. [Open the map](https://cloud.maptiler.com/maps/) you want to use in ATAK. It can be any map, including your own custom style. Note its **style ID**. For example, in `https://cloud.maptiler.com/maps/streets-v4/` the ID is **streets-v4**. Custom maps have a generated ID of random letters and numbers. 2. Copy your [MapTiler API key](https://cloud.maptiler.com/account/keys/). We strongly recommend that you create a new dedicated key for ATAK, so you can revoke it without affecting your other projects. > [!WARNING] > The key is stored as plain text in the XML file on the device, so anyone with access to the device can read it. If you lose the device, revoke the key. 3. Create an XML file with this content: ```xml MapTiler Streets 0 22 png None https://api.maptiler.com/maps/streets-v4/256/{$z}/{$x}/{$y}.png?key=YOUR_MAPTILER_API_KEY_HERE #000000 ``` 4. In the XML file, adjust these parts of the `` parameter: - `streets-v4`: Replace with the map style ID from step 1. - `YOUR_MAPTILER_API_KEY_HERE`: Replace with the API key from step 2. - **Do not** replace or edit the `{$z}/{$x}/{$y}` MOBAC placeholders. Edit other parameters if needed: - ``: This is the name you'll see in ATAK's map list. - `` / ``: available zoom range. 0–22 is a safe range for MapTiler maps. Custom maps can differ, depending on their data. - ``: the tile format, `png` by default. If you change it to `jpg`, also change it in the `` so that the two match. - ``: Caching behavior, don't edit manually. See [Maps for offline use](#caching) below. - ``: What color to show if map tiles are missing. > [!TIP] > To check that the URL works before you copy the file to your device, open it in a browser with real numbers, for example `https://api.maptiler.com/maps/streets-v4/256/3/4/2.png?key=YOUR_MAPTILER_API_KEY_HERE`. You should see a map tile. 5. Save the file (for example as `MapTiler_Streets.xml`) and copy it to the `atak/imagery` folder on your Android device. 6. Open ATAK. The map appears in the layer selector. If maps in ATAK blink over each other or look mixed up, make sure there's only one XML file in `atak/imagery`. ## Self-hosted deployments For air-gapped or fully offline deployments, [MapTiler Server](/guides/on-prem/server/) hosts maps on your own infrastructure (Windows, Linux, macOS, or Docker). ATAK connects to your server the same way, using the same XML format. Only the `` differs, pointing to your server instead of MapTiler's public API. ```xml MapTiler Server Streets 0 22 png None http://your-server:3650/api/maps/streets/256/{$z}/{$x}/{$y}.png #000000 ``` Replace `your-server:3650` with your server's address and port, and `streets` with the ID of your map. No API key is needed. The Android device must be able to reach the server over the network. MapTiler Server works with modern vector map data, which is compact and rich in detail. It renders the data into raster PNG tiles on the fly, because raster tiles are the format ATAK consumes. You don't need to prepare any raster data yourself. For help with setting up MapTiler Server and self-hosted maps on your own infrastructure, see [Installation](/guides/on-prem/server/installation/) and [Getting started](/guides/on-prem/server/getting-started/). ## Maps for offline use {#caching} ATAK can download map tiles for a selected area in advance, so the map works offline in the field. For details on how to set it up, refer to ATAK's documentation. Keep in mind that downloading large areas at high zoom levels takes significant time and device storage. Downloading an area in advance isn't the same as automatic caching, where an app or browser briefly keeps the tiles you've already viewed. Check that your MapTiler plan covers it: - **MapTiler API**: Bulk downloading map tiles from the API requires a [Custom plan](https://www.maptiler.com/cloud/pricing/). - **MapTiler Server** (recommended for offline use): Downloading from your own server is fine, but using the maps on multiple devices requires an [On-prem Custom plan](https://www.maptiler.com/data/pricing/). To agree on the right plan, [contact our Sales team](https://www.maptiler.com/contacts/#contact). # 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/) > [!NOTE] > 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/how-maps-work/raster-vector-tiles/). 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/map-data/add-your-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/map-design/) 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/how-maps-work/maptiler-datasets/) to learn what datasets we offer and how to use them - [Schemas](/schema/) with detailed description of our vector tilesets # Get started with Map Designer Source: https://docs.maptiler.com/guides/map-design/editor/ Our **Map Designer** is a no-code map design editor. It enables you to customize every visual detail of a map: colors, icons, fonts, transparency, shading, highlighting, language of labels, and much more. > [!TIP] > Although Map Designer is fairly intuitive to work with, it's still helpful to know some basics, especially the difference between [a map, map style, and map data](/guides/how-maps-work/#what-a-map-consists-of). ## Design your custom map The easiest way to get started is to customize one of [MapTiler maps](https://cloud.maptiler.com/maps/). They're professionally crafted to fit their purpose, be aesthetically pleasing, and work well at all zoom levels. This makes them an ideal starting point to get your custom map in high quality and short time. Open Map Designer After opening, Map Designer loads a default general-purpose map, but you can select any other map to start with.
How to open Map Designer with another map

  1. Open your MapTiler account, page Maps.

  2. Click NEW MAP to open the map selection wizard, and pick the map style that's visually closest to what you need. The maps are grouped into categories and each has a description explaining what it's best suited for. Many of our maps come in color variants. In the wizard, they're listed as thumbnails at the bottom of each map for yout to check out too:

    • Dark modes are beneficial for navigation at night or for highlighted data visualizations.

    • Light and pastel modes are monochromatic grey or soft-colored base maps that let your data stand out.

      ![Map selection wizard](./map-selection-wizard.webp)

  3. Click Customize button to open the selected map in Map Designer, ready to be modified.

Alternatively, pick a map directly on the Maps page and click Customize in its detailed view.

## Next steps - [Understand the editor interface and terminology](/guides/map-design/maps-and-styles-basics/) - [Quick edit your map](/guides/map-design/quick-map-editing/) # 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/map-design/editor/) 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.webp) ## 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.webp) ### 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.webp) 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.webp) ### 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.webp) ### 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/outdoor-v4/), [Winter](https://cloud.maptiler.com/maps/winter-v4/), [Topo](https://cloud.maptiler.com/maps/topo-v4/) and [Ocean](https://cloud.maptiler.com/maps/ocean-v4/) 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.webp) ### 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.webp) ## 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.webp) 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.webp) ### 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.webp) ### 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.webp) ### 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.webp) ## 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.webp) ## 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/map-design/editor/) 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.webp) 2\. Shift hue, saturation, or lightness. ![quick-edits-hsl.png](./17654865490065_91b6cf9bea.webp) ## 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.webp) ## 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.webp) ### 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.webp) MapTiler maps with sprites included by default: - [Bright](https://cloud.maptiler.com/maps/bright-v2/) - [OpenStreetMap](https://cloud.maptiler.com/maps/openstreetmap/) - [Outdoor](https://cloud.maptiler.com/maps/outdoor-v4/) - [Streets](https://cloud.maptiler.com/maps/streets-v4/) - [Toner](https://cloud.maptiler.com/maps/toner-v2/) - [Topo](https://cloud.maptiler.com/maps/topo-v4/) - [Winter](https://cloud.maptiler.com/maps/winter-v4/) ### 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.webp)** 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.webp) ### 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.webp) To adjust the position of labels, go to the **Layout** properties (scroll down in the Style tab). ![layout-properties.png](./17414968518801_78ba44a681.webp) ### Raster styling Rasters have specific paint properties depending on the data. For example, in [MapTiler Satellite](https://cloud.maptiler.com/maps/satellite-v4/) map, you can adjust contrast, hue, saturation, or brightness. ![raster-styling.png](./17414968520849_9b0ebe6808.webp) ### 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.webp) ![multiple-layers-reset.png](./17415933644433_dc1013280e.webp) ## 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/icons/) [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.webp) In the [Dataviz map](https://cloud.maptiler.com/maps/dataviz-v4/), we are using zoom range styling for both the **outline color** and **width** of the Country border layer. ![zoom-styling-outline.png](./17582997139345_b0fd040bc6.webp) ![zoom-styling-width.png](./17583042991377_0351e6e76d.webp) ## 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.webp) 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.webp) 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.webp) ## 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.webp) **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.webp) **1\. First, select a source layer from data sources**. ![add-layer-1.png](./17491407635857_582bcd13b4.webp) 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.webp) **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.webp) **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.webp) 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.webp) 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.webp) ## 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.webp) 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.webp) If you select LineString geometry, you get bridge lines. ![geometry-linestring.png](./17494040322193_6de9e420e4.webp) You can visualize the LineString geometry as a **Line, Symbol, or Heatmap**. ![visualization-line-2.png](./17501792724369_ad6b20a760.webp) 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.webp) Apart from filters, you can choose your preferred [Data source](/guides/map-design/data-sources), Data layer, or Geometry.  ![data-panel.png](./17327075908113_490abd791c.webp) ## 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.webp) 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.webp) ## 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.webp) For example, water can have various classes, such as lakes, oceans, or rivers. ![filter-class-water.png](./17327075923217_f8b000e5fe.webp) The filter format can also be switched from Visual to Native, which is similar to the JSON code. ![filter-native.png](./17327051983633_ec8f9e2176.webp) With filters UI, you can either select all values, multiple values, or one specific value. ![filter-select-one.png](./17328873889937_47731b1da6.webp) 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.webp) 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.webp) ## 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/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/using-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. > [!NOTE] > 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. # 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. Our visual editor [Map Designer](/guides/map-design/editor/) enables you to style these icons, change their color, outline, opacity, change the icon image, or use completely custom icons to get a fully personalized map. ![Standard catalog icons in our Winter map (left) vs custom icons](./img/icons-custom.webp) *[Winter map](https://cloud.maptiler.com/maps/winter-v4/) with standard catalog icons (left) and with custom icons* ## Style existing icons {#style-icons} Our maps come with professionally prepared icon sets that you can customize so that they fit your brand, theme, or intended visual style: 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. 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](./img/show-layers.webp) 2. Adjust icon properties as needed: `fill color`, `outline`, `opacity`, `size`, and `anchor` (relative position of the icon and label). The change will apply to all instances of the icon in the map. ## Change icon image {#replace-icon} You can select a different image to use as a specific icon. For example, you may want to show parks in your map as a flower icon instead of the default tree. Here's how to do it: 1. In your map, go to menu **Layers** and click on the map layer which contains the icon you want to replace. 2. In the layer panel, click on the icon. This opens a new panel showing the entire icon set for this map. Search it for the icon you want to use. If the desired icon is not in the current icon set, switch sets using the drop-down menu above the search field. You can also switch to [your own custom icon set](/guides/map-design/icons/prepare-custom-icons/) after you upload one. 3. Click on the new icon to replace all instances of this icon in the map. ![Replace an icon in a map](./img/replace-icon.webp) ## Prepare custom icons If styling or swapping the existing icons isn't enough, you can take the customization to next level and use your own, completely custom icons: 1. **[Prepare a custom icon set](/guides/map-design/icons/prepare-custom-icons/)** 2. **[Use and manage your icon sets](/guides/map-design/icons/manage-custom-icons/)** > [!TIP] > If you're looking for a programmatic way to work with icons, check out the [code examples](https://docs.maptiler.com/sdk-js/examples/?q=icon). # How to prepare custom icons Source: https://docs.maptiler.com/guides/map-design/icons/prepare-custom-icons/ For a fully custom map, you need custom icons – from a single icon to a complete visually consistent set. Whether you download ready-made icons or opt to prepare your own icon set in a graphic design program, here's the technical requirements and tips 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. ## Input format {#format} The best practice is to always prepare your icons in **vector** format, because it preserves the editability of your source files. For the upload, you can export the vectors from your graphic design program into either **vector** or **raster**, based on the specific type of icons you've prepared and how you want them to appear in the map. ### Vector icons (SVG to SDF) {#vector} Icons in vector format 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. **Benefits** Color, outline and other properties are defined per map layer, which means that you can *reuse a vector icon set* across multiple layers or even multiple different maps and have it customized differently in each of them. Also, you can *customize icons and labels together* to achieve a polished unified look. **Requirements** To be able to style and customize your icons as described: - Icons must be **monochrome** (black) - Background must be **transparent** - Design should be **clean and simple** – no tiny details, overlaps, frames, etc. ![How to prepare customizable SVG icons](../img/icon-design-tips.png) The map editor takes just the shape of the icon and applies the selected fill color and outline, meaning that your icons don't preserve any defined colors, overlapping shapes or details inside the icon. ![Vector icon in a map](../img/icon-vector-customizable.png) If you have **multi-color icons** and want them to appear exactly as designed, you have two options: 1. Export icons from your design program and upload them [as rasters](#raster). 2. Use vectors, but turn off the "customizable" (SDF) option [during upload](/guides/map-design/icons/manage-icon-sets/#add). In either case, the icons will be converted to standard raster format, preserve their colors and details, and **won't be customizable** in the map. ![Raster icon in a map](../img/icon-raster-non-customizable.png) **Unsupported features** We don't support animated icons and animations are ignored during upload. The following features are prohibited and a SVG file containing any of them is refused at upload: - Hyperlinks `` - Embedded images `` - Animation controls `` `` - Scripts `