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).

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.

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.

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 and it 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 predict 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.

Session types

• Map session: Interacting with a standard map (zooming, panning, changing map themes) or loading vector, raster, and 3D terrain tiles.
• Geocoding session: Search box interactions, including text search queries and autocomplete suggestions.
• Weather session: Visualizing weather conditions such as temperature, precipitation, and wind layers.
• 3D session: Interacting with 3D models implemented using GeoSplats technology. Includes the underlying basemap.

All these session types are tracked independently. For example, a web application displaying a map with a search box and weather animation generates one map session, one geocoding session, and one weather session.

Map and weather sessions share the same usage pool. While tracked separately, both count against the same total quota limit. Geocoding and 3D sessions each have their own separate quotas.

3D sessions automatically include the basemap. Loading a 3D model on a basemap counts as a single 3D session, with no additional map session.

Comparison

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.

• If your map app includes a 3D model implemented with the GeoSplats SDK, loading and interacting with the model is tracked by session. Individual API requests are not supported due to the high data density and rendering complexity of splat models.

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

          <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>
          

          <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>