Use a configurable link to map

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:

<a href="https://api.maptiler.com/maps/{mapId}/?key=YOUR_MAPTILER_API_KEY#{zoom}/{latitude}/{longitude}/{bearing}/{pitch}">Link text</a>

The link URL is in fact a request to our Maps API. 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, 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. Make sure to protect the 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.

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=mNLmXyaTH4gRlwJHSYWp#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=mNLmXyaTH4gRlwJHSYWp#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).

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.