Map usage: Sessions vs requests

MapTiler offers two models of measuring map traffic and other service usage: sessions and 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).

Idea

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.

Requests

A request (or API request, more specifically) is a single call to our API services. These APIs are the mechanism that makes all our online services work: they display your maps, make it possible to search places, send coordinates, calculate elevation, or show weather animations.

In case of map usage, requests counts each individual API request for map tiles (pieces of the map). When the user is moving around the map and zooming in and out, the map application needs to load more tiles 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 it works, check out our interactive tile request counter.

Some of our services, like geocoding, don’t necessarily involve a map. Geocoding makes it possible to search a place by its name or coordinates in any app, be it a map or a delivery form. The number of requests to the respective API depends on configuration; for example, in case of predictive search where each key stroke gives the user new place suggestions, each key stroke also means a new API request to our API to get those suggestions.

Request types and how they're counted

This table lists all types of API requests, including tile requests, geocoding and other types, and how they're counted against your API quota.

The request numbers in the table are for tracking and billing purposes and might not correspond to the actual number of API requests that technically happened.

Type	Requests
TileJSONs, Style JSONs, Fonts, Viewers, XMLs	Free
Vector tile	1 per tile
Rendered raster 512x512px tile including HiDPI/Retina	4 per tile
Rendered raster 256x256px tile including HiDPI/Retina	1 per tile
Single tile served from .mbtiles	1 per tile
Static maps API image	15 per image
Vector data (GeoJSON)	1 per file
Geocoding Batch geocoding: per each query in a batch *	1 per request
Elevation Batch elevation retrieval: per each query in a batch *	1 per request
Coordinates conversion Batch conversion: per each query in a batch *	1 per request
Export	50 per exported tile

* If a single API request contains multiple queries, each counts separately. For example, a batch of 20 queries counts as 20 requests, even though it’s technically one API call.

Sessions

A session, sometimes also called map load, starts when a user opens a webpage with the map. Then they can freely interact with the map, zoom, pan, change map theme, and it all counts as a single map session. Similarly, in case of geocoding, a session includes all interactions with a search field in one sitting.

For billing purposes, a new session starts when:

User reloads the browser tab (with F5, Ctrl+R, Reload button),
A single continuous session duration exceeds 6 hours,
The session reaches a total of 10,000 requests.

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

Map sessions and geocoding sessions are tracked and billed as separate products. Interaction with a map and a search box on the same page will count as one map session and one geocoding session respectively.

Comparison

	Sessions	Requests
What’s measured	(Re)load of a web page with map or place search	Each individual API call for a map tile or place search
Duration	Until page refresh (F5, Ctrl+R) or up to 6 hours/10k requests	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 predict (1 session = 1 user visit), reduced costs for heavy user interaction, protection from usage spikes	More granular, works with all tools and libraries
Best use case	Applications with heavy user interaction per map view	Many map page views with little user interaction

Are you using sessions or requests?

Each of your map apps 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 your map app is implemented with MapTiler SDK JS (or the MapTiler plugin for the Leaflet library which also uses the MapTiler SDK), then the usage 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 app 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 in MapTiler SDK

If you’re using MapTiler SDK JS, you’re by default using sessions but can optionally switch to requests. This might be the preferred way to track your map usage in special cases where you expect many map views with little interaction. For example, you’re building 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.

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:


          <body>
          <div id="map"></div>
          <script>
            maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
            maptilersdk.config.session = false;
            const map = new maptilersdk.Map({
              container: 'map', 
              style: maptilersdk.MapStyle.STREETS,
              center: [16.62662018, 49.2125578],
              zoom: 14 
            });
          </script>
          </body>

A map implemented with MapTiler plugin for the Leaflet library:


          <body>
          <script>
              const key = 'key';
              maptilersdk.config.session = false;
              const map = L.map('map').setView([0, 0], 1); 
              const mtLayer = L.maptiler.maptilerLayer({
                apiKey: key,
                style: L.maptiler.MapStyle.STREETS, 
              }).addTo(map);
          </script>
          </body>