How to make maps with MapTiler Cloud API - Use cases and examples
The MapTiler Cloud API allows access to all the data, maps, and resources in the MapTiler Cloud 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 Cloud 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 Cloud 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=5lu005ch1iT9mtSq5nZH
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 Cloud Maps page and select a map.
Example of maps:
- https://api.maptiler.com/maps/bright/?key=5lu005ch1iT9mtSq5nZH
- https://api.maptiler.com/maps/openstreetmap/?key=5lu005ch1iT9mtSq5nZH
- https://api.maptiler.com/maps/74f0e2cf-0dc3-46ba-98ed-c2395d4c71e2/?key=5lu005ch1iT9mtSq5nZH
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/?key=5lu005ch1iT9mtSq5nZH#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
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/?key=5lu005ch1iT9mtSq5nZH#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=5lu005ch1iT9mtSq5nZH#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 MapLibre 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=5lu005ch1iT9mtSq5nZH
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=5lu005ch1iT9mtSq5nZH
Example 256x256 pixels tile:
https://api.maptiler.com/maps/basic-v2/256/3/4/2.png?key=5lu005ch1iT9mtSq5nZH
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=5lu005ch1iT9mtSq5nZH
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=5lu005ch1iT9mtSq5nZH
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
3.1. How to create an image of a map
Sometimes, you just want to have an image of a map for a website, graphic design, etc. Thanks to the API, you can create images of your maps.
There are several ways to create an image of a map. The easiest way is called a Center-based URL where the image is defined by the map identifier, the coordinates of the image center, a zoom level, and the size of the image.
https://api.maptiler.com/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}.{format}?key=YOUR_API_KEY
Example: https://api.maptiler.com/maps/pastel/static/8.579446,47.127792,16/825x350.png?key=5lu005ch1iT9mtSq5nZH. This URL produces the following image.
In the previous example:
- mapId = pastel
- lon = 8.579446
- lat = 47.127792
- zoom = 16 (Zoom level must be an integer)
- width = 825
- height = 350
- format = png
To obtain images in “retina”/HiDPI, the scale (@2x) of the image must be indicated.
Example “retina”/HiDPI: https://api.maptiler.com/maps/pastel/static/8.579446,47.127792,16/825x350@2x.png?key=5lu005ch1iT9mtSq5nZH
The other option, called a bounds-based URL, instead of indicating the coordinates of the center of the map and a zoom level, the map area is defined by the bounding box formed by a pair of coordinates: the lower left (minx, miny) and upper right corners (maxx, maxy).
https://api.maptiler.com/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}?key=YOUR_API_KEY
Example bounds-based URL:
In the previous example:
- mapId = basic-v2
- minx = -70.3
- miny = -46.5
- maxx = 70.3
- maxy = 46.5
- width = 825
- height = 350
- format = png
The API also offers the possibility of adding information to these images, such as a marker at a specified position or drawing a line or a polygon on the map.
3.2. How to make a map image with markers
To add markers to a map image, a parameter called markers must be used in the URL. More than one marker can be added to the map. Each marker is a lng,lat pair separated by commas. Individual markers are separated by a pipe symbol ( | ).
Example map with multiple markers (default marker):
Each marker can also have a different color - specified as the 3rd parameter (e.g. 14.4,50.1,red|8.6,47.4,blue).
Marker colors can be defined using hexadecimal values, rgba or the name of the colors (e.g. red, rgba(255,255,255,0.5), #0000ff).
Example map with multiple markers (default marker multiple colors):
|2.4,48.9,%23ffaa00){kind=link}
A custom image can also be used as a marker.
Example map with a custom image marker:
For multiple markers, you can only use one custom image.
Use case - Display a list of locations of offices on a web page
A good example of a use for static maps would be to display a list of locations of offices, stores, businesses, real estate, etc. The following example combines the descriptions of the offices with the image of the location map.
Headquarters:
Höfnerstrasse 98
6314 Unterägeri
Switzerland
Dev center:
Tišnovská 137
614 00 Brno
Czech Republic
We combined the Static Maps API with the Maps API in the example above. Combining these 2 APIs, we achieve that an interactive map opens when the user clicks on the image.
Code example of an image with an associated interactive map.
<a href="https://api.maptiler.com/maps/pastel/?key=5lu005ch1iT9mtSq5nZH#17.87/49.21256/16.626597" target="_blank" rel="noopener">
<img src="https://api.maptiler.com/maps/pastel/static/16.626597,49.21256,15/200x200.png?key=5lu005ch1iT9mtSq5nZH&markers=icon:https://tinyurl.com/yakrjl3t|anchor:center|16.626597,49.21256">
</a>
3.3. How to create a map image with lines or polygons
We can also add lines or polygons to the images of the static maps. The polygon or polyline can be passed in a path query parameter. Coordinates of the individual path vertices are comma-separated lng, lat pairs. The vertices are separated by a pipe symbol. The path can also be encoded according to Google Encoded Polyline Format
The properties to paint the lines or polygons are:
- width = width of the stroke in pixels. (Default: 1px)
- stroke = the color of the path stroke (Default: blue)
- fill = color to use as the fill (Default: rgba(255, 255, 255, 0.5))
Example of using a line to indicate how to get from the parking lot to a restaurant:
To add multiple lines you must use the path parameter several times.
Multiple line example:
Example of using a polygon to highlight a real estate property:
|-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){kind=link}
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/sprite.png
https://api.maptiler.com/maps/bright/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 Cloud 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=5lu005ch1iT9mtSq5nZH",
......
}
6. Vector data Tilesets
In the previous examples, we have seen how to use our maps through the API; however, MapTiler Cloud 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 Cloud 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 Cloud using API
Example of Satellite tileset:
https://api.maptiler.com/tiles/satellite-v2/?key=5lu005ch1iT9mtSq5nZH
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=5lu005ch1iT9mtSq5nZH",
"tileSize": 512,
"type": "raster"
},
"openmaptiles": {
"url": "https://api.maptiler.com/tiles/v3/tiles.json?key=5lu005ch1iT9mtSq5nZH",
"type": "vector"
}
}
.........
}
7. How to use GeoJSON data in your map
In cases where you have data that is light (less than 5 MB and less than 5,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=5lu005ch1iT9mtSq5nZH
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=5lu005ch1iT9mtSq5nZH
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:
https://github.com/maptiler/samples/tree/main/cloud/reverse-geocoding-maplibre
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: https://github.com/maptiler/samples/tree/main/web/geocoder-component
Related guides
- Add a new style layer
- Add custom watermark to your map
- Change language in a map
- Choose a map style
- Contours and mountain peaks in feet
- Creating a custom vector dataset (GeoJSON)
- Data sources
- Disputed borders on your maps
- Edit style: Quick customization of the map (Roads and traffic)
- Editing JSON