How to make maps with MapTiler API - Use cases and examples
The MapTiler API allows access to all the data, maps, and resources in MapTiler without having to open a browser. The API specification is at https://docs.maptiler.com/cloud/api/.
Through the API, you can add a map directly to your website, create an image with a location map for your business, search for addresses, etc. Explore the MapTiler API to see all its features.
This article uses different use cases and examples to explain how to use the main options offered by the MapTiler API to create maps.
- Authentication - Get API key for FREE
- How to create an interactive map
- How to make a static map
- Map symbols (sprites)
- Available map fonts (Typography)
- Vector data Tilesets
- How to use GeoJSON data in your map
- How to search for places (Geocoding)
1. Authentication - Get API key for FREE
The first thing we need to know to use the API is that all of the requests to the API have to be authorized using your API key. Your MapTiler account access key is on your MapTiler Cloud account page or Get API key for FREE.
The API key must be passed in a parameter called key in API requests.
Examples
https://api.maptiler.com/maps/basic-v2/?key=YOUR_API_KEY
https://api.maptiler.com/maps/basic-v2/?key=mNLmXyaTH4gRlwJHSYWp
2. How to create an interactive map
2.1. How to create a link to a map
To create a link to a map, you must indicate the map identifier (mapId) in the URL path https://api.maptiler.com/maps/{mapId}/.
To get the map identifier, go to the MapTiler Maps page and select a map.
Example of maps:
- https://api.maptiler.com/maps/bright-v2/?key=mNLmXyaTH4gRlwJHSYWp
- https://api.maptiler.com/maps/openstreetmap/?key=mNLmXyaTH4gRlwJHSYWp
- https://api.maptiler.com/maps/74f0e2cf-0dc3-46ba-98ed-c2395d4c71e2/?key=mNLmXyaTH4gRlwJHSYWp
To create a link in a specific map location you must indicate that position in the URL hash.
For example, a map centered on Spain: https://api.maptiler.com/maps/bright-v2/?key=mNLmXyaTH4gRlwJHSYWp#6/40.018/-3.779
The position hash is composed of zoom level/map center latitude/map center longitude.
In the example above:
- Zoom level = 6
- Map center latitude = 40.018
- Map center longitude = -3.779
You can get the position hash by opening the Map Editor navigating to a desired area and copying the hash from the URL.
Additionally, two variables can be added: bearing and pitch.
Adding the bearing and pitch to a map centered on Barcelona we get a map where the coastline is aligned with the screen.
Example: https://api.maptiler.com/maps/bright-v2/?key=mNLmXyaTH4gRlwJHSYWp#12.83/41.39474/2.16377/-45/60
In the example above:
- Zoom level = 12.83
- Map center latitude = 41.39474
- Map center longitude = 2.16377
- Bearing = -45
- Pitch = 60
Examples of a map centered in Barcelona create by a link: left (without bearing and pitch), right (with bearing and pitch)
2.2. How to add an interactive map on a web page
Even though you can do a lot with a link to a map, there are occasions when we need to have an interactive map on a web page, blog post, etc.
The easiest way to add a map to your website is through an iframe. To do this you must use the map link in the src attribute of the iframe.
<iframe
width="700"
height="350"
src="https://api.maptiler.com/maps/basic-v2/?key=mNLmXyaTH4gRlwJHSYWp#0.7/16.20423/16.64662"
></iframe>
If you have already developed a map viewer and want to use one of our maps or want to have more control over the interactive map, you have different options.
2.2.1. How to use vector tiles in your map
To make a map with vector tiles you can use the API to call the Style JSON of the map. The style JSON conforms to the schema described in the GL Style Specification.
https://api.maptiler.com/maps/{mapId}/style.json?key=YOUR_API_KEY
Example style JSON:
https://api.maptiler.com/maps/basic-v2/style.json?key=mNLmXyaTH4gRlwJHSYWp
Check out the examples we have prepared on how to use vector tiles with:
2.2.2. How to use raster tiles in your map
All maps are available as a raster tile service. The API offers the ability to load 256x256 pixels and 512x512 pixels tiles.
Example 512x512 pixels tile:
https://api.maptiler.com/maps/basic-v2/3/4/2.png?key=mNLmXyaTH4gRlwJHSYWp
Example 256x256 pixels tile:
https://api.maptiler.com/maps/basic-v2/256/3/4/2.png?key=mNLmXyaTH4gRlwJHSYWp
Take a look at the examples we have prepared on how to use raster tiles with:
To obtain images of tiles in “retina”/HiDPI, the scale (@2x) of the image must be indicated.
Example 256x256 pixels tile in “retina”/HiDPI:
https://api.maptiler.com/maps/basic-v2/256/3/4/2@2x.png?key=mNLmXyaTH4gRlwJHSYWp
2.2.3. How to use the OGC WMTS service in your map
If you need to work with OGC standard services, you also have your maps available as a WMTS service.
The API gives you access to the WMTS Capabilities XML document describing the metadata of the map as well as a link to the XYZ tiles.
Example WMTS capabilities URL:
https://api.maptiler.com/maps/basic-v2/WMTSCapabilities.xml?key=mNLmXyaTH4gRlwJHSYWp
This can be used with various desktop GIS software (e.g. QGIS) to display the map. The WMTS service can also be used in web applications, as you can see in the next example.
Live example - How to load a OGC WMTS service on a map developed with OpenLayers
Check the live example code at: https://github.com/maptiler/samples/tree/main/cloud/wmts-openlayers
3. How to make a static map
For how to make a static map image, see the docs section Static maps.
4. Map symbols (sprites)
Every map can use its own icons to display points of interest, highway shields, etc.
A set of icons that are combined into one large image and a file that defines which icon should be used for which purpose are called sprites.
MapTiler’s default styles in the cloud contain some sprites that you can use in your maps.
Example sprite image:
https://api.maptiler.com/maps/openstreetmap/sprite.png
Example sprite image and icons description:
https://api.maptiler.com/maps/bright-v2/sprite.png
https://api.maptiler.com/maps/bright-v2/sprite.json
To display icons in a vector tile custom style, you must write the sprite image URL in the sprite property of the JSON style
https://api.maptiler.com/maps/{mapId}/sprite
Example - JSON style fragment
{
.........
"sprite": "https://api.maptiler.com/maps/openstreetmap/sprite",
.......
}
5. Available map fonts (Typography)
One of the main features offered by MapTiler is the ability to customize your maps. Oneof these customization options is the ability to select the font types you use on your maps.
The fonts available in the cloud are Amatic, Cabin, Cinzel, Giraffey, Lato, Libre Baskerville, M PLUS 1p, Merriweather, Metropolis, Noto Sans, Noto Serif, Nunito, Open Sans, PT Sans, PT Serif, Pacifico, Roboto, Ubuntu, Varela, Vollkorn, Yanone Kaffeesatz.
To add the available fonts in a vector tile custom style, you must write the following in the glyphs property of the JSON style.
https://api.maptiler.com/fonts/{fontstack}/{range}.pbf?key=YOUR_API_KEY
Example - JSON style fragment
{
.......
"glyphs": "https://api.maptiler.com/fonts/{fontstack}/{range}.pbf?key=mNLmXyaTH4gRlwJHSYWp",
......
}
6. Vector data Tilesets
In the previous examples, we have seen how to use our maps through the API; however, MapTiler also offers Tiles. 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 API 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.
To upload your own Tileset check the article on: How to upload MBTiles or GeoPackage into MapTiler using API
Example of Satellite tileset:
https://api.maptiler.com/tiles/satellite-v2/?key=mNLmXyaTH4gRlwJHSYWp
Live example - MapTiler planet tileset
To add a tileset in a vector tile custom style, you must 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 2 tileset
{
..........
"sources": {
"satellite": {
"url": "https://api.maptiler.com/tiles/satellite-v2/tiles.json?key=mNLmXyaTH4gRlwJHSYWp",
"tileSize": 512,
"type": "raster"
},
"openmaptiles": {
"url": "https://api.maptiler.com/tiles/v3/tiles.json?key=mNLmXyaTH4gRlwJHSYWp",
"type": "vector"
}
}
.........
}
7. How to use GeoJSON data in your map
In cases where you have data that is light (less than 10 MB of size and 10 000 elements), it can be consumed directly as GeoJSON and not through tiles.
Like a vector tileset, a dataset is a collection of geometries and their attributes. The difference is that the dataset is not tiled and is always accessed as a single object. This means that they must be limited in size because each client needs to fetch the whole thing even to render just a small part of the map.
Example NY Subway lines as GeoJSON:
Live example - Choropleth GeoJSON
Check out the examples we have prepared on how to use the GeoJSON data with:
8. How to search for places (Geocoding)
8.1. Geocoding API features
Do you have a list of addresses and want to obtain the coordinates of those addresses? Or do you have a list of locations (coordinates) and want to know which address they correspond to? You can do these operations using the Geocoding API.
Geocoding API features:
- Fast responses for interactive search
- Search with language preference
- Limit search to a given bounds
- Proximity search
- Reverse geocoding
The Geocoding API returns a GeoJson with the results. The result features have multiple attributes that provide extra information; some of these attributes are:
- place_type: indicates the type of place: a street, a municipality, a country, etc.
- bbox: geometry bounding box. (Useful to zoom en the element)
- text: short name
- place_name: full name
8.2. How to search places by name (forward)
The search by name option transforms place names to geographical coordinates.
https://api.maptiler.com/geocoding/{query}.json?key=YOUR_API_KEY
Example search Barcelona (results around the world):
https://api.maptiler.com/geocoding/Barcelona.json?key=mNLmXyaTH4gRlwJHSYWp
Example search Barcelona limit search to Spain bounds (results only in Spain):
8.3. How to search places by coordinates (reverse)
The search by coordinates option transforms coordinates into place names.
https://api.maptiler.com/geocoding/{longitude},{latitude}.json?key=YOUR_API_KEY
Example search longitude = -0.12547 and latitude = 51.49928 (Westminster):
https://api.maptiler.com/geocoding/-0.12547,51.49928.json?key=mNLmXyaTH4gRlwJHSYWp
Live example - Calling the geocoding API from a map developed with MapLibre. Click on the map to get the reverse geocoding results
Check the live example code at:
How to search places by coordinates (reverse geocoding)
Live example - Geocoder component integrated into a map developed with MapLibre. Search for places in the map search box.
Check the live example code at: Geocoding control how to search places