Custom Location Extension API Developer's Guide

Key Concepts

The Custom Location Extension API allows you to search for shapes and POIs using map tils and quadkeys. The following sections contain more information on what map tiles and quadkeys are.

Note: HERE APIs use a WGS-84-compliant latitude and longitude values. This is the reference system currently being used by the Global Positioning System (GPS).

Map Tiles

HERE uses map tiles to represent locations on a sphere (the Earth) in a 2-dimensional space, by using a normalized Mercator projection to convert between the two. The result of the conversion is that the Earth is represented as a square grid of map tiles. The size of the grid depends on the map zoom level. At the lowest zoom level, the world is contained in one map tile. As the zoom level increases, the world is two tiles wide by two tiles high (2x2), then the grid is 4x4, 8x8, 16x16, and so on up to the maximum zoom for a particular region.

Choosing a Tiling Level

When you upload a layer, the service indexes the geometries internally, to enable fast spatial search operations. The default, level 12, is a 3km x 3km tiling grid which provides good performance for standard use cases. Nevertheless, if you have special data distribution requirements, you should choose a tiling grid size for optimum performance.

If a layer contains large amounts of locally high density geometries, such as 10,000 points within a city center of 2km x 2km, then you should choose a smaller grid size. Otherwise, each search operation in this city involves all 10,000 points. For reference, level 13 is a 1.5km x 1.5km grid and level 14 is a 750m x 750m grid.

If geometries in a layer are sparsely distributed over a big region, say 100 points around the globe, then you should choose a bigger grid size. Otherwise, each search operation operates on 10,000s of empty tiles. For reference, level 11 is a 6km x 6km grid, level 12 a 12km x 12km grid, level 13 is a 24km x 24km grid, and level 14 is a 48km x 48km grid.


In theory, specifying the grid location of a map tile as a combination of zoom level, column, and row, is easy. In practice, the grid is a two-dimensional array that 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 into one value.

A quadkey is simply a string containing a numeric value that 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 with its leading zeroes retained. The length of a quadkey string equals to the zoom level of the tile.

For example, if you had a quadkey for a column with 35210, a row with 21493, and a zoom level of 16, then the quadkey value is 1202102332221212.

Attribute Columns

Geometry rows in CSV and Shapefile format can have arbitrary attribute columns. Column names must conform to [A-Za-z][A-Za-z0-9_]*. Column values must be plain text strings not exceeding 4000 characters in UTF-8 encoding. They must not contain whitespaces other than blanks (no tabs, CR, LF, backspace, unicode FFFE or similar breaks). Escape characters like quotes of backslashes are not supported, which means that they are interpreted as plain characters without special semantics. The geometry column WKT in CSV files must be the last column. Otherwise, it is moved behind the last column.

If the layer contains a GEOMETRY_ID column, then it must be numeric and unique within the layer. If the layer doesn't contain a GEOMETRY_ID column, then it gets added, to uniquely identify each geometry record, e.g. for modify and delete calls.