Map Tile API Developer's Guide

Constructing a Request

A request to the Map Tile API includes the basic elements shown in the following table and, in addition, it may contain resource-specific query parameters.

Tile requests must follow the pattern summarized by the following formula:
{Base URL}{Path}{resource (tile type)}/{map id}/{scheme}/{zoom}/{column}/{row}/{size}/{format}
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&{param}={value}
Information requests must follow the pattern summarized by the following formula:
{Base URL}{Path}{resource}
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&{param}={value}
Copyright requests must follow the pattern summarized by the following formula:
{Base URL}{Path}copyright/{map id}
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&{param}={value}
Note: Please note that POST requests are not allowed.
Table 1. Basic request elements
Element Value/Example Note Description
Base URL
Base Map Tiles
https://{1-4}.base.maps.api.here.com
Aerial Tiles
https://{1-4}.aerial.maps.api.here.com
Traffic Tiles
https://{1-4}.traffic.maps.api.here.com
Pano Tiles
https://{1-4}.pano.maps.api.here.com

See also Load Balancing and URLs

Production environment

 
Base Map Tiles
https://{1-4}.base.maps.cit.api.here.com
Aerial Tiles
https://{1-4}.aerial.maps.cit.api.here.com
Traffic Tiles
https://{1-4}.traffic.maps.cit.api.here.com
Pano Tiles
https://{1-4}.pano.maps.cit.api.here.com

See also Load Balancing and URLs

CIT environment: see HERE Server Environments

Path
 /maptile/2.1/
   
Resource (tile type)
maptile
basetile
blinetile
xbasetile
alabeltile
labeltile
linetile
lltile
streettile
rctile
rconlytile
rcdistonlytile
trucktile
truckonlytile
trucknopttile
mapnopttile
info
copyright
version
meta/pois
traffictile
flowtile

[1]

[1]

[1]

[1]

[1]

[1]

[1]

[1]

[1]

[2]

[2]

[2]

[1]

[1]

[3]

[3]

[3]
-

[4]

[4]

GET only. See API Reference, Info or Copyright for a more detailed parameter list for each resource.

Map id newest (example)   Specifies the map version. It can be:
  • version id the map version of the requested map tile resource; request the latest version by using newest as map id.
  • hash A unique key, unambiguously representing a specific map version.

See Requesting the Right Map Version for more information on map versions.

Scheme normal.day (example)   Specifies the view scheme. A complete list of the supported schemes may be obtained by using the Info. The following schemes are available:
  • normal.day – for a normal map view in daylight mode
  • normal.day.grey – for a color-reduced map view in daylight mode (especially used for background maps)
  • normal.day.transit – for a color-reduced map view with a public transport scheme in daylight mode
  • normal.night.transit – for a color-reduced map view with a public transport scheme in night mode
  • normal.traffic.day – for a color-reduced map view designed for displaying traffic in daylight mode
  • normal.traffic.night – for a color-reduced map view designed for displaying traffic in night mode
  • normal.day.custom – for a normal map view in daylight mode
  • normal.night – for a normal map view in night mode
  • normal.night.grey – for a color-reduced map view in night mode (especially used for background maps)
  • pedestrian.day – pedestrian map view in daylight mode
  • pedestrian.day.mobile – pedestrian map view in daylight mode for mobile usage
  • pedestrian.night – pedestrian map view in night mode
  • pedestrian.night.mobile – pedestrian map view in night mode for mobile usage
  • carnav.day.grey – for a normal map view in daylight mode for car navigation
  • normal.day.mobile – mobile version of the scheme
  • normal.day.grey.mobile – mobile version of the scheme
  • normal.day.transit.mobile – mobile version of the scheme
  • normal.night.transit.mobile – mobile version of the scheme
  • normal.night.mobile – mobile version of the scheme
  • normal.night.grey.mobile – mobile version of the scheme
  • reduced.day – for a reduced map view in daylight mode with few colors
  • reduced.night – for a reduced map view in night mode with few colors
  • terrain.day – for a terrain map view in daylight mode
  • satellite.day – for a satellite map view in daylight mode
  • hybrid.day – for a satellite map view with streets in daylight mode
  • hybrid.day.transit – for a satellite map view with public transport scheme in daylight mode
  • hybrid.grey.day – for a satellite map view with streets in daylight mode with few colors
  • hybrid.traffic.day – for a satellite map view with streets designed for traffic
  • terrain.day.mobile – mobile version of the scheme
  • hybrid.day.mobile – mobile version of the scheme

Note: Please be aware that invalid combinations of schemes and Tiles are rejected. For all satellite, hybrid and terrain schemes, the Aerial Tiles base URL must be used instead of the normal one. For the hybrid.traffic.day scheme, the Traffic Tiles base URL must be used instead of the normal one. The other traffic related schemes (normal.traffic.day, normal.traffic.night) are supported by Traffic Tiles and Map Tiles. Originally they are supposed to be used only with Traffic Tiles, but in order to properly support the traffic overlay case where you would request a transparent traffic tile from Traffic Tiles and a base tile from Map Tiles, the Map Tiles also support these schemes.

Zoom 13 (example)   Zoom level of the map image. Minimum and maximum zoom levels are specified in the Info.
Column 4400 (example)  

col – can be any number between 0 and number of columns - 1, both inclusive.

The number of tiles per column is a function of the zoom:

number of columns = 2zoom
Row 2686 (example)  

row –  can be any number between 0 and number of rows - 1, both inclusive.

The number of tiles per row is a function of the zoom: number of rows = 2zoom .

Size 256 (example)   Returned image size. The following sizes ([width, height]) are supported:
  • 256 = [256, 256]
  • 512 = [512, 512]
The following sizes ([width, height]) are deprecated, although usage is still accepted:
  • 128 = [128, 128]

Note: Raster coverage tiles (rctile, rconlytile and rcdistonlytile) only support 256 sizes.

Format png8 (example)   Returned image format. The following image formats are supported:
  • png – PNG format, 24 bit, RGB
  • png8 – PNG format, 8 bit, indexed color
  • jpg – JPG format at 90% quality

Please note that JPG is recommended for satellite and hybrid schemes only.

Application Id
&app_id={YOUR_APP_ID}
Mandatory Query Parameter Substitute your own unique app_id
Application Code
?app_code={YOUR_APP_CODE}
Mandatory Query Parameter Substitute your own unique app_code
Resource Specific Parameters &{parameter=value} Optional Query Parameter Please refer to the API definition for values.

Notes:

[1] Please use the right base URL depending on what kind of tiles you want to get. Keep in mind that for some schemes you should use different base URLs. For more information, see the API reference.
[2] Please use the pano tile base URL for this request.
[3] Please use the right base URL depending on which environment you want to get information from.
[4] Please use the traffic tile base URL for this request.

Load Balancing and URLs

The servers that process requests against the Map Tile API resources are distributed for optimized load balancing. Clients can take advantage of this and improve response times, especially when submitting multiple simultaneous requests, by using URL prefixes (1 - 4). The numeric prefix must be the first part of the request URL after "http://".

There are different ways to take advantage of this mechanism. No method is enforced from the server, although the method used should ensure that your requests are distributed among the different prefixes and do not use only one. We propose the following methods:
  • Choose the prefix randomly.
  • Choose the prefix depending on the parity of the row and column number:
    1 when both the row and the column number are even
    2 when the row number is even, the column number is odd
    3 when the row number is odd, the column number is even
    4 when both the row and the column number are odd
  • Use a simple formula such as:
    1 + ((row_number + column_number) % 4)
    In this formula, % indicates modulo division.