Map usage: Sessions vs requests

MapTiler offers two models of measuring map traffic: map sessions and tile requests. Each pricing plan including the free one defines a monthly limit on sessions and requests. When you hit either of these two limits, you get charged extra (on a paid plan) or your maps get suspended for the rest of the month (on a free plan).

To see which plan you're on and how many sessions and requests you get, go to your Account settings. To check your current usage stats, see the Analytics page.

Tile requests

A tile request counts each individual request for map tiles. When the user is moving around the map and zooming in and out, the map application needs to load more map tiles (pieces of the map) to show the required areas or details. This happens by requesting new tiles via an API call, and each of these API calls counts as a tile request.

To see how exactly this works, check out our interactive tile request counter.

Request types and how they're counted

Type	Requests
TileJSONs, Style JSONs, Fonts, Viewers, XMLs	Free
Vector tile	1
Rendered raster 512x512px tile including HiDPI/retina	4
Rendered raster 256x256px tile including HiDPI/retina	1
Single tile served from .mbtiles	1
Static maps API image	15
Vector data (GeoJSON)	1
Geocoding	1
Export	50

Map sessions

A map session, sometimes also called map load, starts when a user opens a webpage with your map. Then the user can interact with the map, zoom, pan, change map theme, and it counts as a single map session. A new session starts either when the user reloads the page (with F5, Ctrl+R, Reload button), or after 6 hours of a single session running.

Map sessions are generally much easier to estimate: One session equals one page view, so it’s easy to check your web analytics and estimate map traffic costs. Sessions also tend to be more cost-effective than tile requests, because a single map session typically includes many tile requests: a few tiles to load the initial map view, and then additional tiles as needed when the user interacts with the map.

Comparison

	Map sessions	Tile requests
What’s measured	Map (re)load on a web page	Each individual API call for a map tile
Duration	Until page refresh (F5, Ctrl+R) or up to 6 hours	N/A (usage is per request)
Availability	Only with MapTiler SDK JS or MapTiler plugin for Leaflet	General availability with MapTiler API
Benefits	Much easier to calculate and predict	More granular
Best use case	Applications with heavy user interaction per map view	Many map page views with little user interaction

Which model is used?

Each of your maps can be measured differently, per session or per request; there’s no global setting for the model used. So which one applies? That depends on implementation:

If a map is implemented with MapTiler SDK JS (or the MapTiler plugin for the Leaflet library which also uses the MapTiler SDK), then the map traffic is by default tracked by session. For special use cases where it makes sense, you can optionally switch to requests.
If you built your map using MapTiler API combined with 3rd party clients and libraries, then the traffic is tracked by request. Switching to sessions is not technically possible in this case.

Switching to requests

There are special cases where it might be more cost-effective to use requests rather than sessions. For example, a holiday booking app in which users browse many pages to see available options, but they don’t interact with the maps on those pages. In similar scenarios, a MapTiler SDK JS user might want to switch their map tracking to requests (non-SDK users are on requests by default).

Switching from sessions to requests is done per map. Use the map config option session and add this line to the code of each map which you want tracked per request:

maptilersdk.config.session = false

See where it fits in the code

Here are some examples of a map configured to use requests instead of sessions. We've included just the body part of a fullscreen web app code to show you where the config belongs.

A map implemented with MapTiler SDK JS:

A map implemented with MapTiler plugin for the Leaflet library: