Custom Location Extension API Developer's Guide

Map Objects

Maps

All map objects are stored in maps. There is a default map for each customer, but customers can create many maps. A map is a collection of layers.

Layers

A layer can store a logical group of map objects. Customers can create many layers within each map. Which map objects should reside within the same layer, and which map objects should go into different layers, is application specific. As a rule of thumb, the objects that are being searched / displayed / updated together should go together into one layer.

Within one layer, the map objects must be of the same type: A layers contains either points or lines or polygons. A layer can contain store locations for map display and store locator applications, another layer the arrival isoline polygons around the stores and warehouses and yet another layer the five-minute-accurate positions of the delivery trucks.

Map Objects

Map objects are points, lines and polygons. Besides the geometry, they can contain any 'flat & simple' set of attributes, see below. Flat means that they cannot be repeated groups or reference other map objects or database objects. Simple means that everything is treated as a number or text string, no further structure is known/used by the service.

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.

Core Maps & Custom Maps

HERE offers customers to create their own custom maps/layers/objects. In addition, the whole HERE map content is also available in the HERE, organized exactly in the same way - as maps, layers and map objects. See PDE service for details on the available map data. The HERE map data layers cannot be customized, but can be used for all search and retrieval operations.

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.

Quadkeys

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.