Map Tile API Developer's Guide

Metainfo Tiles

Metainfo tiles are used to obtain metadata information about specific tiles. This metadata can then be used in many ways; for example, to enable interactivity or to obtain information about the labels or objects rendered on a tile.

Example 1: Customize a map tile depending on the position of the labels, by using the following steps:
  • retrieve a maptile for a particular location
  • request the metadata for that tile
  • depending on the position of the labels, highlight certain labels on the client side
Example 2: Show only clickable road signs on top of a tile, by using the following steps:
  • request a basetile
  • request a metadata map tile for the same location using mgen=2 and filter=1 to obtain only the filtered out road signs
  • overlay the icons of the road signs that were returned by the metadata request
Note: Use the Aerial base URL for all satellite, terrain and hybrid schemes, the Traffic base URL for all traffic and flow requests and the Map base URL for any other requests.

Using the Metadata Parameters for Metainfo Tiles

The following parameters are relevant for metainfo tiles:

  • callback_func: Use this parameter to request that the callback function be run once the response is received by the JavaScript component; a JSON object containing the result is passed to this function.
  • mgen: Use this parameter to differentiate between metadata versions and between the capabilities on top of those versions. Version 2 of mgen returns the road sign icon URI.
  • filter: Use this parameter with Version 2 of mgen only, to filter out metadata from the resulting metainfo tile. This way, you can transfer smaller JSON objects, thus transferring only relevant information.
  • metadata: Use this parameter to enable the output of metadata information. Choose between metatile or metaonly, depending on whether you require the image as well as the metadata.
  • output: Use this parameter to generate base64 encoded values, which is useful when you request several tiles in one request with the parameter range, or when you request a tile to use as input for callback_func.
  • range: Use this parameter to request several tiles in a single request. The tile, specified by column x row, is the top left of the array and it must divide by the array size.
You can combine these parameters to create complex and highly customizable requests, for example:
https://2.base.maps.api.here.com/maptile/2.1/maptile/newest/normal.day/14/8799/5376/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &metadata=metatile
  &mgen=2
  &filter=1
  &range=3x3
  &callback_func=parse_image
This request results in a JSON object that:
  • has nine tiles, since the range is 3x3
  • has tiles that include the metadata and a base64 encoded image, since metadata is metatile
  • has Version 2 metadata information with filtering, since mgen is 2
  • has filtering enabled to show only road signs, since filter is 1
  • indicates the function called when the response is received is parse_image, since callback_func is parse_image
The response is shown below. Note that it has been shortened for readability.
parse_image(
  [
    {
      "image": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAMAAABrrFhUAAADAFBMVEUwMC6 ...",
      "metadata" : {
      "labels":[
        {
          "name":"103",
          "type": "ROADSIGN",
          "bounding boxes": [
            {
              "left":62,
              "top":198,
              "width":28,
              "height":20
            }
          ],
          "region": "DEU",
          "category": 0,
          "route name": "A103",
          "route level": 2,
          "uri": "http://image.maps.cit.api.here.com/mia/1.6/roadsign?category=0&region=DEU&label=A103&route_level=2&app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}"
        },
        {
          "name":"100",
          "type": "ROADSIGN",
          "bounding boxes": [
            {
              "left":212,
              "top":163,
              "width":28,
              "height":20
            }
          ],
          "region": "DEU",
          "category": 0,
          "route name": "A100",
          "route level": 2,
          "uri": "http://image.maps.cit.api.here.com/mia/1.6/roadsign?category=0&region=DEU&label=A100&route_level=2&app_id={YOUR_APP_ID}&app_code={YOUR_APP_ID}"
        },
        {
          "name":"1",
          "type": "ROADSIGN",
          "bounding boxes": [
            {
              "left":188,
              "top":73,
              "width":22,
              "height":15
            }
          ],
          "region": "DEU",
          "category": 1,
          "route name": "B1",
          "route level": 3,
          "uri": "http://image.maps.cit.api.here.com/mia/1.6/roadsign?category=1&region=DEU&label=B1&route_level=3&app_id={YOUR_APP_ID}&app_code={YOUR_APP_ID}"
        },
      ]
    }
  },
  ... (5 more tiles)
] );
If a callback_func parameter is specified, the response contains the callback_id as its first parameter. You can use this value to verify if the response you receive is accurate. For example:
callback_id=1425
returns:
test( '1425', '{ ...}' ); 
Note: The value is URL-encoded, but it is the responsibility of the requester to provide a value that is JavaScript correct.