Map Tile Identification: A New Addition to your Toolbox

Pink and blue tiles with flowers painted on them.

At Sparkgeo we don’t just make maps. We address a range of geospatial challenges and pursue the most appropriate solutions with an open and independent mindset. Those solutions sometimes produce pixels. Those pixels are often served over a network.

We’re always striving to improve how we develop, test, and support our solutions. As part of that effort we’ve developed the open source Tile ID API. How does it help? Let’s talk about pixels.


Over recent years we’ve seen a sustained focus on geospatial data formats. New formats, and optimisations within established formats, can help to deliver cloud-native geospatial. A number of formats are changing how we work with vector data. We’ve previously written about FlatGeobuf as one example.

With Cloud Optimised GeoTIFFs (COGs) we can read sub-sets of potentially large raster data without the need for an intermediary, such as an API. This has opened up new opportunities for innovation within our field. However, COGs are not suited to all scenarios. When serving pixels to clients over a network our approach often draws from two well established models.

Customisable & On-Demand Image Generation

The Open Geospatial Consortium (OGC) Web Map Service (WMS) standard has seen widespread use. It describes a mechanism for clients to generate images on-demand from source data. Clients specify a mix of data constraints and image properties in map requests, and WMS servers respond with generated content. WMS provides great flexibility and can incorporate current data (unlike pre-generated images). Those benefits carry a performance cost, as the WMS server must access source data and engage non-trivial compute resources to service each request. The OGC API – Maps standard will eventually supersede WMS, and this standard is expected to support similar capabilities.

Pre-Existing Tile Retrieval

Tiling schemes have proven extremely popular in simplifying and accelerating the delivery of pixels. Maps are represented by one or more tiled images according to a pre-defined tiling strategy. OpenStreetMap has good documentation on this subject, and tools like Mapnik and gdal2tiles assist the generation of tiles from source data.

Tiling schemes are typically used in combination with pre-generated data. This approach brings the potential for high performance and low data delivery overheads. It is possible to dynamically generate tiles according to a client’s request parameters, however this is likely to impact perceived performance at the client.

Google introduced the tiling scheme commonly known as XYZ. Alternate tiling schemes were later developed including Tile Map Service (TMS), Quadkey, and Web Map Tile Service (WMTS). The OGC API – Tiles standard represents the latest development of standards in this area, and also covers vector tiles. Vector tiles do not deliver pixel data, but share several of the same advantages and limitations as image tiles. Development work with vector tiles may also benefit from the Tile ID API.

The Problem

During development we occasionally need to determine the relationships between tiles and locations. For example:

  • As part of an automated test suite we may want to request one or more tiles from a tile server, to ensure that a known dataset is properly represented within those tiles. We need to know which tiles intersect that dataset.
  • During active development we may want to validate that the specific tiles requested by a client are as expected.
  • While working with Sparkgeo’s clients, contractors, or team members whose strengths lie beyond the geospatial domain we may need to support education and onboarding.

The Solutions

A number of tools exist to support these scenarios, including but not limited to:

  • The mercantile Python package. This package might supplement a larger Python application or be consulted on an ad-hoc basis for individual queries.
  • Some JavaScript map libraries can be used to overlay tile information within the browser, as described here for Leaflet. This behaviour may not be supported by all map libraries.
  • This maptiler page overlays tile information on an embedded map as an ad-hoc visual reference.


The Sparkgeo Tile ID API complements this list by taking a different approach. The API supports XYZ, TMS, and Quadkey tiling schemes and can be added as a tile source to any client with one or more of those capabilities. It might be added to a browser-based web map, a native mobile application, or a desktop GIS suite such as QGIS. Each tile request returns a PNG or JPEG containing the tile’s identifiers across all supported tiling schemes. Identifiers are provided in both the image and HTTP response headers. An additional HTTP response header provides the tile’s bounds in WGS84 Longitude & Latitude.

Leaflet map with Tile ID API XYZ layer.

The following URL pattern can be used to add the Tile ID API as a tile source in QGIS. Minor variations on this pattern may be required in different environments, for example where QGIS uses {z} as a placeholder for zoom level MapProxy uses %(z)s.{z}/{x}/{y}

The following video demonstrates adding the Tile ID API in QGIS. Once added, this tile source provides the XYZ, TMS, and Quadkey identifiers for each tile.

Some optional features are documented in the repo that are not demonstrated here.

Give it a try, and feel free to let us know what other tools might help to make your geospatial journeys better.