Introduction
Welcome to the ExpressMaps API. You can use our API to manage your ExpressMaps API keys including the following operations:
- Listing your keys
- Creating a new key
- Modifying an existing key
- Adding or removing domain referrer restrictions
- Enabling or Disabling a key
- Deleting a key
We have language bindings in cURL / Shell, JavaScript and PHP. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Authentication
We use Bearer authentication for requests to the ExpressMaps API endpoints.
Before you can use this API, you'll need to retrieve one of your API Management keys. These can be found on your ExpressMaps Console / Settings page. You should have two keys:
Read-Only Key - used for read only operations (for example, listing your keys or reading a specific key)
Read-Write Key - required when adding, editing or deleting a key
We suggest you use the Read-Write key to get started.
Authenticate your requests by passing one of these keys in the Authorization header as "Bearer {your-api-key}".
Authorization: Bearer your-api-key
Keys
List all keys
curl -X GET https://api.expressmaps.com/keys \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.expressmaps.com/keys',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.expressmaps.com/keys', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
?>
The above command returns JSON structured like the following:
{
"keys": [
{
"name": "Friendly key name",
"uuid": "em7fa91fbc9d344ec1994e4ccf2d3d00",
"created": 1601018765,
"modified": 1601020595,
"status": "Enabled",
"referrer_restrictions": [
"example.com",
"other-website.com"
],
"ip_restrictions": null
}
GET /keys
This endpoint retrieves all keys in your account and returns them in a JSON array of keys.
Create a key
curl -X POST https://api.expressmaps.com/keys \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"name": "Key name",
"status": "Disabled",
"referrer_restrictions": [
"new-url.com"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.expressmaps.com/keys',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('POST','https://api.expressmaps.com/keys', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
?>
Body Parameters
{
"name": "Key name",
"status": "Disabled",
"referrer_restrictions": [
"new-url.com"
]
}
POST /keys
This endpoint creates a new API key. Once the key is created, it is immediately activated and can be used to access ExpressMaps mapping services.
By default, the key is not restricted in any way so we recommend adding domain restrictions to the key using the Update a key method.
| Parameter | In | Description |
|---|---|---|
| name | body | The key name [Required] |
| status | body | 'Enabled' or 'Disabled' (defaults to 'Enabled') |
| referrer_restrictions | body | A JSON array of domain names (defaults to none) |
The above command returns JSON structured like the following:
{
"key": {
"uuid": "ea6a3c647c5847bbbfa601d723b2612b",
"name": "My Key name",
"created": 1619956381,
"modified": "",
"status": "Enabled"
},
"status_message": "OK"
}
Update a key
curl -X PATCH https://api.expressmaps.com/keys/{keyUUID} \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
const inputBody = '{
"name": "New key name",
"status": "Disabled",
"referrer_restrictions": [
"new-url.com"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.expressmaps.com/keys/{keyUUID}',
{
method: 'PATCH',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('PATCH','https://api.expressmaps.com/keys/{keyUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
?>
Body Parameters
{
"name": "New key name",
"status": "Disabled",
"referrer_restrictions": [
"new-url1.com",
"new-url2.com"
]
}
PATCH /keys/{keyUUID}
This endpoint updates an existing API key. The key can be renamed, enabled or disabled and the domain restrictions can be updated.
By default, the key is not restricted in any way so we recommend adding domain restrictions to the key using the Update a key method.
| Parameter | In | Description |
|---|---|---|
| keyUUID | path | The uuid of the key that you are updating [Required] |
| name | body | The new key name |
| status | body | "Enabled" or 'Disabled' |
| referrer_restrictions | body | A JSON array of domain names or either an empty array or a null value to clear all existing restrictions |
The above command returns JSON structured like the following:
{
"key": {
"uuid": "ea6a3c647c5847bbbfa601d723b2612b",
"name": "My Key name",
"created": 1619956381,
"modified": "",
"status": "Enabled"
},
"status_message": "OK"
}
Delete a key
curl -X DELETE https://api.expressmaps.com/keys/{keyUUID} \
-H 'Authorization: Bearer {your-api-key}'
const headers = {
'Authorization':'Bearer {your-api-key}'
};
fetch('https://api.expressmaps.com/keys/{keyUUID}',
{
method: 'DELETE',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
?php
require 'vendor/autoload.php';
$headers = array(
'Authorization' => 'Bearer {your-api-key}',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('DELETE','https://api.expressmaps.com/keys/{keyUUID}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
?>
DELETE /keys/{keyUUID}
This endpoint deletes an existing API key.
| Parameter | In | Description |
|---|---|---|
| keyUUID | path | The uuid of the key that you are deleting [Required] |
The above command returns JSON structured like the following:
{
"status_message": "OK"
}
Displaying maps
Everything you need to put a map on a page is one URL. Each ExpressMaps style is a MapLibre style document that references our vector tiles, sprites and fonts, so any library that reads that format can draw the map.
Style URLs
https://tiles.expressmaps.com/styles/{style}.json?key={your-key-uuid}
Replace {style} with one of the names below and {your-key-uuid} with the uuid of an API key from your console. Keys are public by design, so restrict each one to the domains that will use it.
| Style | Look | Page |
|---|---|---|
| standard | Familiar colours, points of interest, road shields (recommended default) | /styles/standard |
| basic | Clean light base, no points of interest | /styles/basic |
| enhanced | Most detailed light style, buildings and POIs | /styles/enhanced |
| navigator | Navigation-first, strong road hierarchy | /styles/navigator |
| subtle | Pastel land, soft water, quiet roads | /styles/subtle |
| greyscale | Neutral monochrome | /styles/greyscale |
| autobahn | Road-atlas look, yellow motorways | /styles/autobahn |
| lithium | Flat mid-grey, black labels | /styles/lithium |
| darklands | Charcoal dark theme | /styles/darklands |
| mulberry | Indigo and plum dark theme | /styles/mulberry |
| porcelain | White land, grey-teal water, no POIs | /styles/porcelain |
| chalk | Ultra-light greys, soft labels, no icons | /styles/chalk |
| silver | Fully desaturated, darker water | /styles/silver |
| linen | Warm cream land, sky-blue water | /styles/linen |
| moss | Dark green-grey, no labels | /styles/moss |
| canvas | Standard colours, no labels | /styles/canvas |
| meadow | Pale grey, aqua water, olive parks, no labels | /styles/meadow |
| ink | Charcoal roads on light grey, no labels | /styles/ink |
| pewter | Soft greys, bold black town names | /styles/pewter |
| carbon | Near-black greys, dim labels | /styles/carbon |
MapLibre GL JS
<link href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
<div id="map" style="width: 100%; height: 400px;"></div>
<script>
var map = new maplibregl.Map({
container: 'map',
style: 'https://tiles.expressmaps.com/styles/standard.json?key={your-key-uuid}',
center: [-0.1276, 51.5072],
zoom: 12
});
map.addControl(new maplibregl.NavigationControl());
new maplibregl.Marker().setLngLat([-0.1276, 51.5072]).addTo(map);
</script>
MapLibre GL JS is the open-source library we recommend. It is a fork of Mapbox GL JS 1.x with the same API, no access token and no telemetry. Change styles at runtime with map.setStyle(url); all twenty styles share one tileset, so switching is instant and does not count as another load.
The expressmaps package
<!-- or: npm install expressmaps maplibre-gl -->
<link rel="stylesheet" href="https://unpkg.com/expressmaps@1.1.0/dist/expressmaps.css">
<script src="https://unpkg.com/expressmaps@1.1.0/dist/expressmaps.umd.js"></script>
<script>
// after maplibre-gl.js
var map = expressmaps.createMap({ container: "map", key: "YOUR_API_KEY", marker: true });
map.addControl(new expressmaps.StyleSwitcher({ key: "YOUR_API_KEY" }), "top-left");
</script>
The optional expressmaps package (MIT, no dependencies, under 3 KB gzipped) adds three helpers on top of MapLibre GL JS: styleUrl(style, key) returns a style URL, createMap(options) creates a map with a navigation control and optional marker, and StyleSwitcher is a style picker control that carries your own sources and layers across style changes. Install it with npm install expressmaps maplibre-gl and import { createMap, StyleSwitcher } from "expressmaps", or load the UMD build from unpkg or jsDelivr as shown, which exposes a global expressmaps.
Mapbox GL JS
<link href="https://api.mapbox.com/mapbox-gl-js/v1.13.3/mapbox-gl.css" rel="stylesheet" />
<script src="https://api.mapbox.com/mapbox-gl-js/v1.13.3/mapbox-gl.js"></script>
<script>
var map = new mapboxgl.Map({
container: 'map',
style: 'https://tiles.expressmaps.com/styles/standard.json?key={your-key-uuid}',
center: [-0.1276, 51.5072],
zoom: 12
});
</script>
Mapbox GL JS 1.x works unchanged: no accessToken is needed when the style comes from ExpressMaps. Versions 2 and later require a Mapbox token to initialise, so for new projects use MapLibre.
Leaflet
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
<link href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.22/leaflet-maplibre-gl.js"></script>
<div id="map" style="width: 100%; height: 400px;"></div>
<script>
var map = L.map('map').setView([51.5072, -0.1276], 12);
L.maplibreGL({
style: 'https://tiles.expressmaps.com/styles/standard.json?key={your-key-uuid}'
}).addTo(map);
L.marker([51.5072, -0.1276]).bindPopup('Our office').addTo(map);
</script>
We serve vector tiles only, so Leaflet needs the maplibre-gl-leaflet plugin to render them. Everything else in Leaflet (markers, popups, layers, plugins) works as normal on top. Note that Leaflet uses [lat, lng] order and MapLibre uses [lng, lat].
OpenLayers
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10.2.1/ol.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10.2.1/dist/ol.js"></script>
<script src="https://cdn.jsdelivr.net/npm/ol-mapbox-style@12.3.5/dist/olms.js"></script>
<div id="map" style="width: 100%; height: 400px;"></div>
<script>
olms.apply('map', 'https://tiles.expressmaps.com/styles/standard.json?key={your-key-uuid}')
.then(function (map) {
map.getView().setCenter(ol.proj.fromLonLat([-0.1276, 51.5072]));
map.getView().setZoom(12);
});
</script>
ol-mapbox-style reads the style and builds the OpenLayers layers. The promise resolves with the Map, after which it is ordinary OpenLayers. See the OpenLayers guide.
React, WordPress and mobile
React: wrap MapLibre in a component, or use react-map-gl/maplibre and pass the style URL as mapStyle.
WordPress: install the ExpressMaps plugin for a block and a [expressmaps] shortcode.
iOS and Android: MapLibre Native accepts the same style URL. Native apps send no referrer, so create a separate key per app without referrer restrictions and watch its usage in the console.
Tiles, sprites and glyphs
{
"sources": {
"expressmaps": {
"type": "vector",
"url": "https://tiles.expressmaps.com/tiles/tzadcr/tile.json"
}
},
"sprite": "https://tiles.expressmaps.com/sprites/standard",
"glyphs": "https://tiles.expressmaps.com/fonts/{fontstack}/{range}.pbf"
}
Every style references the same resources, shown on the right. You only need these if you write your own style.
- Tiles follow the OpenMapTiles schema, zoom 0 to 14, built from OpenStreetMap. Labels use
name:latinplusname:enand local-language names where OpenStreetMap has them. - Sprites are referenced by the styles that draw icons (for example
/sprites/standard), with the usual.json,.png,@2x.jsonand@2x.pngvariants. Basic and Enhanced draw no icons and have no sprite. - Fonts available as glyph ranges: Roboto, Noto Sans, Open Sans, PT Sans and Metropolis in their regular, bold and italic weights.
- Attribution: the style includes "© OpenStreetMap contributors", which the data licence requires you to display. Keep the attribution control enabled.
The CDN adds your key to tile, sprite and glyph requests automatically when the page's referrer matches the key's domain restrictions, so only the style URL needs the key parameter. Requests with no referrer (server-side renderers, some native apps) are refused for referrer-restricted keys; use an unrestricted key for those and keep it private.
Key restrictions
Restrict every key in the console or with the Update a key endpoint. referrer_restrictions is a list of the domains that will embed the map, for example example.com. A request from any other referrer receives HTTP 403 with a JSON message, as does a request using a disabled key or one whose plan quota has been reached (status QuotaReached). Changes apply to new requests shortly after saving.
Usage
Get usage
curl -X GET "https://api.expressmaps.com/usage?period=daily" \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {your-api-key}'
fetch('https://api.expressmaps.com/usage?period=daily', {
headers: { 'Accept': 'application/json', 'Authorization': 'Bearer {your-api-key}' }
})
.then(function (res) { return res.json(); })
.then(function (body) { console.log(body.loads); });
<?php
$ch = curl_init('https://api.expressmaps.com/usage?period=daily');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Accept: application/json', 'Authorization: Bearer {your-api-key}'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = json_decode(curl_exec($ch));
print_r($body->loads);
?>
The above command returns JSON structured like the following:
{
"loads": [
{
"uuid": "em7fa91fbc9d344ec1994e4ccf2d3d00",
"day": "2026-11-11",
"loads": 1532,
"urls": {
"https://www.example.com/contact": 1498,
"https://www.example.com/stores": 34
}
}
],
"status_message": "OK"
}
GET /usage
Returns map load counts for every key in your account, oldest first. Either management key (read-only or read-write) can call it.
| Parameter | In | Description |
|---|---|---|
| period | query | daily (default) for one row per key per day, or minutely for one row per key per minute, in which case the day field is replaced by minutestamp, a Unix timestamp. |
| uuid | query | Limit the result to one key uuid. |
Each row's urls object maps the page URLs that loaded the map to their counts, which is the same breakdown the console's analytics page shows. Rows are added as loads are recorded, so the current day is partial. Use daily for long-term reporting; minutely rows are kept for a limited period.
Errors and limits
{
"status_message": "Error",
"error_message": "Invalid API key"
}
The management API returns errors as JSON with status_message set to Error and a human-readable error_message. Check status_message rather than the HTTP status, which is 200 for application errors.
| Message | Meaning |
|---|---|
| Missing API key | No Authorization: Bearer header was sent. |
| Invalid API key | The bearer token is not one of your management keys. |
Tile and style requests are answered by the CDN and use HTTP status codes: 403 when the key is disabled or the referrer is not allowed, 404 for an unknown style, and 204 for a tile with no data.
Quotas. The free plan includes 100,000 map loads a month. When it is exhausted we email you and maps stop until the next month or until a paid plan is started, which re-enables them immediately. Paid plans (Essential 250,000; Business 1,000,000; Enterprise 5,000,000, then $0.05 per 1,000) have a 30-day grace period, and unused loads roll over to the next month up to one month's quota. There is no per-second rate limit on tiles; the CDN is built for bursts.