Map Tile API Developer's Guide

Info

info is a resource that retrieves information about the map rendering service available on the server (metadata about the service), including the available map versions, map tile formats, resolutions, map view schemes, supported map languages, etc.

Metadata requests retrieve information specific to the base URLs they target. This information cannot be used in subsequent requests that use other base URLs. For example, to obtain a base map version, use metadata from the response to a request addressed to the Base Map Tiles base URL, but for a version of an aerial map, use metadata from the response to a request addressed to the Aerial Tiles base URL.

Note: Info requests are sometimes referred to as metadata info requests, please note that they are not the same as metadata requests using the parameter metadata.
Note: Please see Requesting the Right Map Version for information on how to use hashcodes.

The following example shows a request to this resource.

https://{1-4}.base.maps.cit.api.here.com
/maptile/2.1/info
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&{param}={value}

Mandatory Query Parameters

The following table lists the mandatory parameters that need to be specified with every request. Not specifying these parameters will make the system reject the request.

Table 1. Mandatory Query Parameters
Parameter Type Description
app_id String A URL-safe encoded string obtained during the application registration. See Acquiring Credentials for information on getting credentials.
app_code String A URL-safe encoded string obtained during the application registration. See Acquiring Credentials for information on getting credentials.

Note: Usage of token is accepted although is deprecated

Information Specific Query Parameters

Table 2. Information Specific Query parameters
Parameter Type Description
callback_func String A function name that is wrapped around the JSON output. This technique allows for a more secure way of parsing the output with JavaScript, for example:
&callback_func=test

returns:

test( [ ... ] ); 
Note: The value is url-decoded, but it is the responsibility of the requester to provide a value that is JavaScript correct.
callback_id String If specified (associated with callback_func), the function wrapper contains this id as the first parameter This allows the user to check if the response is actually the response to the request, and not some maliciously injected code; for example
callback_id=1425

returns:

test( '1425', '{ ...}' ); 
Note: The value is url-decoded, but it is the responsibility of the requester to provide a value that is JavaScript correct.
hash_for String
Note: The usage of this parameter is deprecated
Used to obtain information about a specific map version. This parameter is only valid if output is set to header. This parameter is designed to offer automated caches a simple way to relate map version strings to their current hash. The valid values of the parameter are:

"newest" – indicates the most recent map version

a string containing the map version ID – indicates that the hash for this specific version is to be retrieved

If the parameter is used, the response header contains a key, maphash, with a hash value identifying the specified map version.

mgen String Specifies the metadata generation to use. This parameter accepts the following values:
  • 1: default
  • 2: optimized out JSON format that filters empty values and allows the usage of parameter filter, the output of this version might change between releases as it is still under development
  • latest: always takes the latest version available
Note: For maptile, this parameter is only available for metadata requests and output JSON.
Note: For info requests, this parameter is only available when using output JSON.
output String Output specifier. The API supports the following output specifier values (and output formats):
  • xml – delivers the API metadata in XML format according to the XSD (this is the default).
  • json – delivers the API metadata in JSON format; for JSONP requests see the parameter callback_func/callback_id
  • xsd – delivers the specific XML schema (XSD) of the API metadata to process and to verify the Service Meta Data Response.

Metadata Request

The following example shows a request for metadata in XML format. An alternative output format is JSON. This is just an example and might not be up to date.

Note: Please be aware that JSON output allows usage of the parameter mgen to get the latest format available.
https://{1-4}.base.maps.cit.api.here.com
/maptile/2.1/info
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}

Metadata Response

The XML response to the above request contains the following data:


<?xml version="1.0" encoding="UTF-8"?>
<response>
  <maps>
    <map region="all" id="newest" />
    <map region="all" newest="true" id="8.30.53.109" hash="be9b70fa2c" />
  </maps>
  <resolutions>
    <resolution id="512" height="512" width="512" />
    <resolution id="256" height="256" width="256" />
    <resolution id="128" height="128" width="128" />
  </resolutions>
  <formats>
    <format encoding="png"  bbp="24" id="png" />
    <format encoding="png8" bbp="8"  id="png8" />
    <format encoding="jpg" bbp="24"  id="jpg" />
  </formats>
  <schemes>
    <scheme id="normal.day" />
    <scheme id="normal.day.grey" />
    <scheme id="normal.day.transit" />
    <scheme id="normal.day.custom" />
    <scheme id="normal.night" />
    <scheme id="normal.night.grey" />
    <scheme id="pedestrian.day" />
    <scheme id="pedestrian.night" />
    <scheme id="carnav.day.grey" />
    <scheme id="normal.day.mobile" />
    <scheme id="normal.day.grey.mobile" />
    <scheme id="normal.day.transit.mobile" />
    <scheme id="normal.night.mobile" />
    <scheme id="normal.night.grey.mobile" />
    <scheme id="reduced.day" />
    <scheme id="terrain.day" />
    <scheme id="satellite.day" />
    <scheme id="hybrid.day" />
    <scheme id="terrain.day.mobile" />
    <scheme id="hybrid.day.mobile" />
  </schemes>
  <styles>
    <style id="default">
      <scheme id="normal.day"/>
      <scheme id="normal.day.grey"/>
      <scheme id="normal.day.transit"/>
      <scheme id="normal.day.custom"/>
      <scheme id="normal.night"/>
      <scheme id="normal.night.grey"/>
      <scheme id="terrain.day"/>
      <scheme id="satellite.day"/>
      <scheme id="hybrid.day"/>
      <scheme id="hybrid.grey.day"/>
      <scheme id="pedestrian.day"/>
      <scheme id="pedestrian.night"/>
      <scheme id="carnav.day.grey"/>
      <scheme id="reduced.day"/>
      <scheme id="reduced.night"/>
      <scheme id="normal.traffic.day"/>
      <scheme id="normal.day.mobile"/>
      <scheme id="normal.day.grey.mobile"/>
      <scheme id="normal.day.transit.mobile"/>
      <scheme id="normal.night.mobile"/>
      <scheme id="normal.night.grey.mobile"/>
      <scheme id="terrain.day.mobile"/>
      <scheme id="hybrid.day.mobile"/>
      <scheme id="pedestrian.day.mobile"/>
      <scheme id="pedestrian.night.mobile"/>
      <scheme id="normal.traffic.night"/>
    </style>
    <style id="fleet">
      <scheme id="normal.day"/>
      <scheme id="terrain.day"/>
      <scheme id="hybrid.day"/>
    </style>
    <style id="dreamworks">
      <scheme id="normal.day"/>
    </style>
    <style id="wings">
      <scheme id="normal.day"/>
      <scheme id="reduced.day"/>
    </style>
    <style id="flame">
      <scheme id="normal.day"/>
      <scheme id="hybrid.day"/>
    </style>
    <style id="alps">
      <scheme id="normal.day"/>
      <scheme id="normal.day.grey"/>
      <scheme id="normal.day.transit"/>
      <scheme id="normal.day.custom"/>
      <scheme id="normal.night"/>
      <scheme id="normal.night.grey"/>
      <scheme id="terrain.day"/>
      <scheme id="satellite.day"/>
      <scheme id="hybrid.day"/>
      <scheme id="pedestrian.day"/>
      <scheme id="pedestrian.night"/>
      <scheme id="carnav.day.grey"/>
      <scheme id="reduced.day"/>
    </style>
    <style id="mini">
      <scheme id="normal.day"/>
      <scheme id="normal.day.grey"/>
      <scheme id="normal.day.transit"/>
      <scheme id="normal.day.custom"/>
      <scheme id="normal.night"/>
      <scheme id="normal.night.grey"/>
      <scheme id="terrain.day"/>
      <scheme id="satellite.day"/>
      <scheme id="hybrid.day"/>
      <scheme id="pedestrian.day"/>
      <scheme id="pedestrian.night"/>
      <scheme id="carnav.day.grey"/>
      <scheme id="reduced.day"/>
    </style>
  </styles>
  <tiletypes>
    <tiletype id="maptile" />
    <tiletype id="basetile" />
    <tiletype id="xbasetile" />
    <tiletype id="alabeltile" />
    <tiletype id="labeltile" />
    <tiletype id="linetile" />
    <tiletype id="streettile" />
    <tiletype id="lltile" />
    <tiletype id="trucktile" />
    <tiletype id="truckonlytile" />
    <tiletype id="rctile" />
    <tiletype id="rconlytile" />
    <tiletype id="rcdistonlytile" />
    <tiletype id="trucknopttile" />
    <tiletype id="mapnopttile" />
  </tiletypes>
  <languages>
    <language id="ARA" />
    <language id="CHI" />
    <language id="CHT" />
    <language id="DUT" />
    <language id="ENG" />
    <language id="FRE" />
    <language id="GER" />
    <language id="GLE" />
    <language id="GRE" />
    <language id="HEB" />
    <language id="HIN" />
    <language id="IND" />
    <language id="ITA" />
    <language id="PER" />
    <language id="POL" />
    <language id="POR" />
    <language id="RUS" />
    <language id="SIN" />
    <language id="SPA" />
    <language id="THA" />
    <language id="TUR" />
    <language id="UKR" />
    <language id="URD" />
    <language id="VIE" />
    <language id="ENG" />
  </languages>
  <zoomLevels min="0" max="20" />
</response>

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <maps>
    <map region="all" id="newest" />
    <map region="all" newest="true" id="8.30.53.109" hash="be9b70fa2c" />
  </maps>
  <resolutions>
    <resolution id="512" height="512" width="512" />
    <resolution id="256" height="256" width="256" />
    <resolution id="128" height="128" width="128" />
  </resolutions>
  <formats>
    <format encoding="png"  bbp="24" id="png" />
    <format encoding="png8" bbp="8"  id="png8" />
    <format encoding="jpg" bbp="24"  id="jpg" />
  </formats>
  <schemes>
    <scheme id="normal.day" />
    <scheme id="normal.day.grey" />
    <scheme id="normal.day.transit" />
    <scheme id="normal.day.custom" />
    <scheme id="normal.night" />
    <scheme id="normal.night.grey" />
    <scheme id="pedestrian.day" />
    <scheme id="pedestrian.night" />
    <scheme id="carnav.day.grey" />
    <scheme id="normal.day.mobile" />
    <scheme id="normal.day.grey.mobile" />
    <scheme id="normal.day.transit.mobile" />
    <scheme id="normal.night.mobile" />
    <scheme id="normal.night.grey.mobile" />
    <scheme id="reduced.day" />
    <scheme id="terrain.day" />
    <scheme id="satellite.day" />
    <scheme id="hybrid.day" />
    <scheme id="terrain.day.mobile" />
    <scheme id="hybrid.day.mobile" />
  </schemes>
  <styles>
    <style id="default">
      <scheme id="normal.day"/>
      <scheme id="normal.day.grey"/>
      <scheme id="normal.day.transit"/>
      <scheme id="normal.day.custom"/>
      <scheme id="normal.night"/>
      <scheme id="normal.night.grey"/>
      <scheme id="terrain.day"/>
      <scheme id="satellite.day"/>
      <scheme id="hybrid.day"/>
      <scheme id="hybrid.grey.day"/>
      <scheme id="pedestrian.day"/>
      <scheme id="pedestrian.night"/>
      <scheme id="carnav.day.grey"/>
      <scheme id="reduced.day"/>
      <scheme id="reduced.night"/>
      <scheme id="normal.traffic.day"/>
      <scheme id="normal.day.mobile"/>
      <scheme id="normal.day.grey.mobile"/>
      <scheme id="normal.day.transit.mobile"/>
      <scheme id="normal.night.mobile"/>
      <scheme id="normal.night.grey.mobile"/>
      <scheme id="terrain.day.mobile"/>
      <scheme id="hybrid.day.mobile"/>
      <scheme id="pedestrian.day.mobile"/>
      <scheme id="pedestrian.night.mobile"/>
      <scheme id="normal.traffic.night"/>
    </style>
    <style id="fleet">
      <scheme id="normal.day"/>
      <scheme id="terrain.day"/>
      <scheme id="hybrid.day"/>
    </style>
    <style id="dreamworks">
      <scheme id="normal.day"/>
    </style>
    <style id="wings">
      <scheme id="normal.day"/>
      <scheme id="reduced.day"/>
    </style>
    <style id="flame">
      <scheme id="normal.day"/>
      <scheme id="hybrid.day"/>
    </style>
    <style id="alps">
      <scheme id="normal.day"/>
      <scheme id="normal.day.grey"/>
      <scheme id="normal.day.transit"/>
      <scheme id="normal.day.custom"/>
      <scheme id="normal.night"/>
      <scheme id="normal.night.grey"/>
      <scheme id="terrain.day"/>
      <scheme id="satellite.day"/>
      <scheme id="hybrid.day"/>
      <scheme id="pedestrian.day"/>
      <scheme id="pedestrian.night"/>
      <scheme id="carnav.day.grey"/>
      <scheme id="reduced.day"/>
    </style>
    <style id="mini">
      <scheme id="normal.day"/>
      <scheme id="normal.day.grey"/>
      <scheme id="normal.day.transit"/>
      <scheme id="normal.day.custom"/>
      <scheme id="normal.night"/>
      <scheme id="normal.night.grey"/>
      <scheme id="terrain.day"/>
      <scheme id="satellite.day"/>
      <scheme id="hybrid.day"/>
      <scheme id="pedestrian.day"/>
      <scheme id="pedestrian.night"/>
      <scheme id="carnav.day.grey"/>
      <scheme id="reduced.day"/>
    </style>
  </styles>
  <tiletypes>
    <tiletype id="maptile" />
    <tiletype id="basetile" />
    <tiletype id="xbasetile" />
    <tiletype id="alabeltile" />
    <tiletype id="labeltile" />
    <tiletype id="linetile" />
    <tiletype id="streettile" />
    <tiletype id="lltile" />
    <tiletype id="trucktile" />
    <tiletype id="truckonlytile" />
    <tiletype id="rctile" />
    <tiletype id="rconlytile" />
    <tiletype id="rcdistonlytile" />
    <tiletype id="trucknopttile" />
    <tiletype id="mapnopttile" />
  </tiletypes>
  <viewtypes>
    <viewtype id="mapview" />
    <viewtype id="baseview" />
    <viewtype id="xbaseview" />
    <viewtype id="alabelview" />
    <viewtype id="labelview" />
    <viewtype id="lineview" />
    <viewtype id="streetview" />
    <viewtype id="llview" />
    <viewtype id="truckview" />
    <viewtype id="truckonlyview" />
    <viewtype id="trucknoptview" />
    <viewtype id="mapnoptview" />
  </viewtypes>
  <languages>
    <language id="ARA" />
    <language id="CHI" />
    <language id="CHT" />
    <language id="DUT" />
    <language id="ENG" />
    <language id="FRE" />
    <language id="GER" />
    <language id="GLE" />
    <language id="GRE" />
    <language id="HEB" />
    <language id="HIN" />
    <language id="IND" />
    <language id="ITA" />
    <language id="PER" />
    <language id="POL" />
    <language id="POR" />
    <language id="RUS" />
    <language id="SIN" />
    <language id="SPA" />
    <language id="THA" />
    <language id="TUR" />
    <language id="UKR" />
    <language id="URD" />
    <language id="VIE" />
    <language id="ENG" />
  </languages>
  <zoomLevels min="0" max="20" />
</response>

The table below describes the XML elements in this output.

Table 3. Elements in the output
Element Description
maps Available maps. A map has the following attributes:

region: the region of the world where the map is valid, currently only all (world) is supported.

id: the map version, newest always refers to the latest map version. Several latest map versions for different regions are possible.

newest: identifies the newest hash used in the server, it will be true for just one hash of the possible list.

hash: the unique key used to reference the specific map version in the map id parameter of a map tile request, see Requesting the Right Map Version.

isbn: unique identifier used for validated chinese maps, it will either be empty or not present for international maps.

resolutions Supported map tile image resolutions. A resolution has the following attributes:

id: used to reference the resolution in the size parameter of a map tile request.

height: the height of the supported image resolution.

width: the width of the supported image resolution.

formats Supported image formats. A format has the following attributes:

encoding: the image encoding format, one of: png, png8 or jpg.

bbp: bytes per pixel, 8 bbp refers to a palette based image format, 24 bbp is a true RGB image format.

id: used to reference the format in the format parameter of a map tile request.

schemes

List of all supported map tile schemes. A scheme has the following attribute:

id: used to reference the scheme in the scheme parameter of a map tile request.

styles

List of all supported styles. Every style supports certain schemes, A style has the following attribute:

id: used to reference the style in the style parameter of a map tile request.

List of schemes supported for that style following the same format as the previous entry for schemes.

tiletypes

Supported map tile types. A tiletype has the following attribute:

id: used to reference the scheme in the type parameter of a map tile request.

viewtypes

Supported map tile views. A viewtype has the following attribute:

id: used to reference the scheme in the type parameter of a map view request.

languages Supported languages for rendered map tiles. A language has the following attribute:

id: a MARC three-letter code used to reference the language in the lg parameter of a map tile request.

zoomLevels Minimum and maximum values for the zoom parameter in a map tile request.

min: minimum possible map tile zoom.

max: maximum possible map tile zoom.