Traffic API Developer's Guide

Quadkeys

Specifying the grid location of a map tile in terms of zoom level, column and row as described under The Mercator Projection is easy to understand and intuitive in practise. However, the grid is a two-dimensional array and as such does not offer efficient storage and retrieval. A better solution is a one-dimensional array, where each item is uniquely addressable by a single value. This is made possible by quadkeys, which combine the zoom level, column and row information for a tile in a one value.

In fact, a quadkey is a string containing a numeric value. The value is obtained by interleaving the bits of the row and column coordinates of a tile in the grid at the given zoom level, then converting the result to a base-4 number (the leading zeros are retained). The length of a quadkey string (the number of digits/characters) equals the zoom level of the tile.

For example, we can obtain the quadkey for a map tile in column 3 and row 5 at zoom level 5 as follows:

// Convert the column (x) and row (y) values
// to their binary (b) equivalents:
x = 3 -> 011b

y = 5 -> 101b

// Interleave the binary values (b), convert the
// combined result to a base-4 (q) number and
// finally convert that to a string:
quadkey = 100111b -> 213q -> "213"

The code below shows a JavaScript implementation of the algorithm that calculates quadkeys. The inputs are the coordinates of the a map tile and the zoom level. The return value is a string containing the quadkey. The lower part of the code block shows the function called to calculate a quadkey for zoom level 16, which is also the length of the output string shown on the last line.

--- input ---
xTile: 35210  // Column
yTile: 21493  // Row
z: 16     // Zoom Level

--- JavaScript ---
function tileXYToQuadKey(xTile, yTile, z) {
  var quadKey = "";
  for (var i = z; i > 0; i--) {
    var digit = "0",
    mask = 1 << (i - 1);
    if ((xTile & mask) != 0) {
      digit++;
    }
    
    if ((yTile & mask) != 0) {
      digit = digit + 2; 
    }
    quadKey += digit;
  } // for i return quadKey; 

  return quadKey;
}
quadKey = tileXYToQuadKey(35210, 21493, 16);

--- output ---
quadKey = "1202102332221212"

Note that when using a quadkey address, you cannot specify the size or format of the map tile image. The response always includes an image that measures 256 x 256 pixels and the format is png32.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.