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 to enable interactivity, for example, or to obtain information about the labels or objects rendered.

One possible use case would be getting a maptile for a certain location, requesting the metadata for the same tile and then using the position of the labels to enable highlighting of certain labels on the client side.

Another example would be showing only clickable roadsigns on top of a tile. You would request a basetile, then request a metadata tile for the same location using mgen=2 and filter=1 to obtain only the filtered out roadsigns and finally overlay the icons of those roadsigns 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.

Metainfo parameter usage

The relevant parameters for metadata requests are:

Table 1. Metainfo request 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.
filter String This parameter accepts two values:
  • 0 (no effect)
  • 1 (filter out only roadsigns)
Note: This parameter only filters out information in a metadata response.
Note: This parameter only works in combination with the parameter mgen.
metadata String Type of metadata to generate, valid values are:
  • metaonly: only metadata are returned; output=base64 is automatically enabled
  • metatile: both the requested image and the associated metadata are returned; output=base64 is automatically on
Note: Optionally, the parameter callback_func can be used as well.
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 Can only have the value base64, which indicates that the map tile is returned as base64 encoded text instead of as a standalone image.
Note: Please be aware that this feature is not available for traffic.
pois String This parameter works as a mask for the POIs Categories contained in the map. If present, pois are shown at a zoom level greater than or equal to 15, if not present, regular tiles are shown. Each symbol of the mask is written in hexadecimal. Every symbol groups four POI categories, the first available symbol groups categories 0-3 and the last one 386-389. The mask can be used as follows:
  • all enabled (default): pois
  • all disabled: pois=0
  • using disabled by default: pois=F (it only enables the categories present, all others are disabled)
  • using enabled by default: pois=!F (it only disables the categories present, all others are enabled)
  • all customized: pois=123.....F (all possible values are given in the mask)
Note: Hexadecimal uses the symbols 0-9 to represent values zero to nine, and A, B, C, D, E, F (or alternatively a-f) to represent values ten to fifteen.
Note: There are several ways in which this API can be used, please check POI Filtering Usage for details.
Note: There are currently 390 POI categories, but you should check the /meta/pois chapter for further information about how to get the most up to date list of categories.
Note: In metainfo tiles you must use this parameter if you want to see POI information.
range String Only relevant if output=base64 is also specified as a parameter range must be one of 2x2, 3x3 or 4x4, which indicates the size of the array of tiles returned. The tile specified by col and row is the top left of the array, and must divide by the array size.

Usage of parameters for metainfo tiles

The parameter callback_func can be used in a JavaScript component to request that the callback function be executed when the request comes back from the server and that a JSON object (the result) be passed to it.

The parameter mgen stands for metadata generation. This is used to differentiate between meatadata versions and between the capabilities on top of those versions. Version 1 includes street labels, roadsigns shown as labels and city center labels. This version is deprecated as there are no new features added to it. Version 2 is the current generation and it is still under development as new features are added almost in every release. From the content side it includes the labels from Version 1 as well as other fields such as buildings, roadsigns, transit stops, transit access and POIs. If there is no data available for a given empty it will be filtered out from the response. You can always use latest to get the latest version of the metadata. The roadsign information contained in version 2 returns the uri to obtain the icon of the roadsign, thus enabling the use case explained in this example.

The parameter filter can be used only with Version 2 of metadata generation to filter out metadata from the resulting metainfo tile. Use of this parameter allows for the transfer of smaller JSON objects and for the transfer of only the relevant information.

The parameter metadata is the most important parameter for metainfo tiles. It enables the output of metadata information. When the value is metaonly, the response only includes the metadata information. This means only the text (JSON) object is returned. When the value metatile is used, then the encoded base64 tile is also returned in addition to the metadata information in the JSON object. This enables the transfer of the image along with the metadata information.

The parameter output is used to generate base64 encoded values, useful when requesting several tiles in one request with the parameter range, for example, or to request a tile for use as an input for callback_func.

The parameter range is used to request several tiles in a single request. The tile specified by col and row is the top left of the array and it must divide by the array size.

All parameters can be combined to create complex and highly customizable requests, for example the following request:

https://2.base.maps.cit.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 (range is 3x3),

has tiles that include the metadata and a base64 encoded image (metadata is metatile),

has generation two metadata information (mgen is 2), which means filtering is available,

has filtering enabled to show only roadsigns (filter is 1) and

indicates the function called when the request is received is parse_image (callback_func is parse_image).

The output of this request is shown below (Note that the response has been simplified to only show one tile out of nine and that the base64 images have 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)
] );

Metainfo tiles content

Table 2. Metainfo tiles content
Parameter Type Description
callback_id String (optional) If specified (associated with callback_func), the function wrapper contains this id as its 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 requestor to provide a value that is JavaScript correct.

Metainfo tile format for metadata generation one

Every metainfo tile displays the following information in a JSON structure
  • metadata - container for the response
    • street labels - array of street labels
      • name
      • font size
      • vertices - array of tile coordinates
        • x
        • y
    • labels - array of labels
      • name
      • type
      • bounding boxes - array of boxes
        • left
        • top
        • width
        • height
    • city center labels - array of city center labels
      • name
      • text box
        • left
        • top
        • width
        • height
      • bullet box
        • left
        • top
        • width
        • height
      • city center info
        • type
        • name
        • alternative names - array of names
          • country code
          • name
        • country code
        • position
          • latitude
          • longitude
        • population
The format is as follows:

{
  "metadata": {
    "street labels": [],
    "labels": [],
    "city center labels": []
  }
}

Street labels

The street labels field displays an array of labels containing the name of the street, the font size used to render it and an array of vertices to draw the polyline that represents the bounding box. The format is as follows:

"name": "",
"font size": "",
"vertices: [
  "x":,
  "y":
]
Name Type Description
name String Name of the street
font size String Font size used to render the label, it is a number displayed as a string
vertices Array of tile coordinates Array containing all vertices needed to draw a polyline that creates a bounding box on the street label.

Labels

This labels field only display information about roadsigns, including the name, the type and the location (bounding box). The format is an array of labels, each one with the following format:

"name": "",
"type": "ROADSIGN",
"bounding boxes": []
Name Type Description
name String Name of the city
type String One of the following types: Roadsign
bounding boxes Array of Bounding Box Array containing all the bounding boxes of the label

City Center Labels

This field displays an array of city center labels, each one including the name and location (bounding box) of the name, location (bounding box) of the bullet box, which is the small square showing the city center and the city center additional information, which shows the type of city, official displayed name, the alternative names in different languages, the country code, position (latitude and longitude) and population. The format is as follows:

"name": "",
"text box" : {
  "left": ,
  "top": ,
  "width": ,
  "height":
},
"bullet box" : {
  "left": ,
  "top": ,
  "width": ,
  "height":
},
"city center info": {
  "type": "",
  "name": "",
  "alternative names": [
    [
      "",
      ""
    ]
  ],
  "country code": "",
  "position": {
    "latitude":,
    "longitude":
  },
  "population":
}
Name Type Description
name String Name of the city
text box Bounding Box Location of the label in the tile
bullet box Bounding Box Location of the bullet in the tile
city center info Structure Structure containing additional information for a city

Common fields

Field Name Type Description
Bounding Box left Integer Location of the left coordinate in the tile
top Integer Location of the top coordinate in the tile
width Integer Width of the bounding box
height Integer Height of the bounding box
Geo coordinate latitude Float ( 6 decimals ) Latitude of the geo coordinate
longitude Float ( 6 decimals ) Longitude of the geo coordinate
City Center Info type String Type of city between National Capital, Provincial Capital and Other
name String Official name of the city
alternative names Array of arrays Alternative names of the city, each array containing the country code as String and the name as String
country code String Three letter country code following MARC coding
position Geo coordinate Location of the city center
population Integer Population of the city
Tile Coordinate x Integer Coordinate x of the tile coordinate
y Integer Coordinate y of the tile coordinate

Two examples are provided in this section, both using mgen=1, to illustrate the format described above. To get additional information about how to use it please check the Examples section.

This example shows a parameter in Berlin and the request looks like:
https://2.base.maps.cit.api.here.com
/maptile/2.1/maptile/newest/normal.day/9/275/167/256/png8
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&metadata=metaonly
&mgen=1
The response looks like:

{ "metadata" : {
"street labels":[

],
"labels":[
{"name":"1", "type": "ROADSIGN", "bounding boxes": [ { "left":96, "top":240, "width":18, "height":12 } ] },
{"name":"158", "type": "ROADSIGN", "bounding boxes": [ { "left":166, "top":129, "width":22, "height":12 } ] },
{"name":"114", "type": "ROADSIGN", "bounding boxes": [ { "left":13, "top":158, "width":23, "height":16 } ] },
{"name":"10", "type": "ROADSIGN", "bounding boxes": [ { "left":73, "top":173, "width":22, "height":16 } ] },
{"name":"11", "type": "ROADSIGN", "bounding boxes": [ { "left":64, "top":153, "width":22, "height":16 } ] },
{"name":"2", "type": "ROADSIGN", "bounding boxes": [ { "left":54, "top":172, "width":18, "height":12 } ] },
{"name":"109", "type": "ROADSIGN", "bounding boxes": [ { "left":49, "top":28, "width":22, "height":12 } ] }
],
"city center labels":[
{"name": "Berlin", "text box": { "left":9, "top":218, "width":49.45, "height":20.50 }, "bullet box": { "left":4, "top":234, "width":5, "height":5 }, "city center info": {"type":"NATIONAL CAPITAL", "name": "Berlin", "alternative names":[["ARA", "برلين"], ["BAQ", "Berlin"], ["BUL", "Берлин"], ["BUX", "Berlin"], ["CAT", "Berlín"], ["CHI", "柏林"], ["CHT", "柏林"], ["CZE", "Berlín"], ["CZX", "Berlin"], ["DAN", "Berlin"], ["DUT", "Berlijn"], ["ENG", "Berlin"], ["EST", "Berliin"], ["ESX", "Berliin"], ["FIN", "Berliini"], ["FRE", "Berlin"], ["GER", "Berlin"], ["GRE", "Βερολίνο"], ["GRX", "Verolino"], ["HIN", "बर्लिन"], ["HIX", "Barlin"], ["HUN", "Berlin"], ["HUX", "Berlin"], ["ICE", "Berlín"], ["IND", "Berlin"], ["ITA", "Berlino"], ["JPN", "ベルリン"], ["JPX", "Berurin"], ["KOR", "베를린"], ["KOX", "Be Reul Rin"], ["LAV", "Berlīne"], ["LAX", "Berline"], ["LIT", "Berlynas"], ["LIX", "Berlynas"], ["MAY", "Berlin"], ["NOR", "Berlin"], ["POL", "Berlin"], ["POR", "Berlim"], ["POX", "Berlin"], ["PYN", "Bo Lin"], ["RMX", "Berlin"], ["RUM", "Berlin"], ["RUS", "Берлин"], ["RUX", "Berlin"], ["SCR", "Berlin"], ["SLO", "Berlín"], ["SLX", "Berlin"], ["SPA", "Berlín"], ["SRX", "Berlin"], ["SWE", "Berlin"], ["THA", "เบอร์ลิน"], ["TUR", "Berlin"], ["TUX", "Berlin"], ["UKR", "Берлін"], ["UKX", "Berlin"]], "country code": "DEU", "position": {"latitude":52.514648, "longitude":13.375854}, "population": 3442675 } },
{"name": "Eberswalde", "text box": { "left":167, "top":36, "width":58.22, "height":11.75 }, "bullet box": { "left":165, "top":45, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Eberswalde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.833252, "longitude":13.815308}, "population": 41175 } },
{"name": "Bernau bei Berlin", "text box": { "left":83, "top":117, "width":55.08, "height":22.75 }, "bullet box": { "left":81, "top":137, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Bernau bei Berlin", "alternative names":[], "country code": "DEU", "position": {"latitude":52.679443, "longitude":13.584595}, "population": 36154 } },
{"name": "Strausberg", "text box": { "left":191, "top":192, "width":51.91, "height":10.50 }, "bullet box": { "left":189, "top":200, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Strausberg", "alternative names":[], "country code": "DEU", "position": {"latitude":52.575073, "longitude":13.881226}, "population": 26221 } },
{"name": "Wandlitz", "text box": { "left":43, "top":83, "width":40.47, "height":10.50 }, "bullet box": { "left":41, "top":91, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Wandlitz", "alternative names":[], "country code": "DEU", "position": {"latitude":52.756348, "longitude":13.474731}, "population": 21530 } },
{"name": "Neuenhagen bei Berlin", "text box": { "left":121, "top":211, "width":58.64, "height":20.50 }, "bullet box": { "left":119, "top":229, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Neuenhagen bei Berlin", "alternative names":[], "country code": "DEU", "position": {"latitude":52.525635, "longitude":13.688965}, "population": 16755 } },
{"name": "Ahrensfelde", "text box": { "left":81, "top":192, "width":56.22, "height":10.50 }, "bullet box": { "left":79, "top":200, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Ahrensfelde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.575073, "longitude":13.579102}, "population": 13114 } },
{"name": "Bad Freienwalde (Oder)", "text box": { "left":165, "top":56, "width":75.83, "height":20.50 }, "bullet box": { "left":241, "top":74, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Bad Freienwalde (Oder)", "alternative names":[], "country code": "DEU", "position": {"latitude":52.783813, "longitude":14.024047}, "population": 12964 } },
{"name": "Werneuchen", "text box": { "left":137, "top":159, "width":57.83, "height":10.50 }, "bullet box": { "left":135, "top":167, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Werneuchen", "alternative names":[], "country code": "DEU", "position": {"latitude":52.630004, "longitude":13.732910}, "population": 7943 } },
{"name": "Biesenthal", "text box": { "left":105, "top":76, "width":49.03, "height":10.50 }, "bullet box": { "left":103, "top":84, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Biesenthal", "alternative names":[], "country code": "DEU", "position": {"latitude":52.767333, "longitude":13.645019}, "population": 5563 } },
{"name": "Rehfelde", "text box": { "left":207, "top":218, "width":42.12, "height":10.50 }, "bullet box": { "left":205, "top":226, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Rehfelde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.531127, "longitude":13.925170}, "population": 4462 } },
{"name": "Liebenwalde", "text box": { "left":15, "top":13, "width":57.72, "height":10.50 }, "bullet box": { "left":13, "top":21, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Liebenwalde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.871704, "longitude":13.397827}, "population": 4390 } },
{"name": "Chorin", "text box": { "left":189, "top":0, "width":31.52, "height":10.50 }, "bullet box": { "left":187, "top":2, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Chorin", "alternative names":[], "country code": "DEU", "position": {"latitude":52.904663, "longitude":13.875732}, "population": 2430 } },
{"name": "Oderberg", "text box": { "left":203, "top":17, "width":45.25, "height":10.50 }, "bullet box": { "left":249, "top":25, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Oderberg", "alternative names":[], "country code": "DEU", "position": {"latitude":52.866210, "longitude":14.046020}, "population": 2229 } },
{"name": "Britz", "text box": { "left":139, "top":4, "width":23.19, "height":10.50 }, "bullet box": { "left":163, "top":12, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Britz", "alternative names":[], "country code": "DEU", "position": {"latitude":52.888183, "longitude":13.809814}, "population": 2201 } },
{"name": "Rüdnitz", "text box": { "left":99, "top":103, "width":36.39, "height":10.50 }, "bullet box": { "left":97, "top":111, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Rüdnitz", "alternative names":[], "country code": "DEU", "position": {"latitude":52.723388, "longitude":13.628540}, "population": 1839 } },
{"name": "Marienwerder", "text box": { "left":89, "top":30, "width":63.73, "height":10.50 }, "bullet box": { "left":87, "top":38, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Marienwerder", "alternative names":[], "country code": "DEU", "position": {"latitude":52.844238, "longitude":13.6010742}, "population": 1731 } },
{"name": "Prötzel", "text box": { "left":210, "top":152, "width":34.09, "height":10.50 }, "bullet box": { "left":227, "top":164, "width":2, "height":2 }, "city center info": {"type":"OTHER", "name": "Prötzel", "alternative names":[], "country code": "DEU", "position": {"latitude":52.635498, "longitude":13.985595}, "population": 1143 } }
]
}
}

This other example contains a metadata response for a close-up of a location in Berlin including street labels. The request looks like:
https://2.base.maps.cit.api.here.com
/maptile/2.1/maptile/newest/normal.day/13/4402/2685/256/png8
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&metadata=metaonly
&mgen=1
And the response looks like:

{ "metadata" : {
"street labels":[
{ "name":"Hansastraße", "font size":"11", "vertices": [ { "x": 163, "y": 118 },  { "x": 175, "y": 102 },  { "x": 178, "y": 98 },  { "x": 182, "y": 93 },  { "x": 187, "y": 90 },  { "x": 190, "y": 87 },  { "x": 194, "y": 84 },  { "x": 210, "y": 75 } ] },
{ "name":"Weißenseer Weg", "font size":"11", "vertices": [ { "x": 147, "y": 240 },  { "x": 172, "y": 288 },  { "x": 176, "y": 297 },  { "x": 182, "y": 319 } ] }
],
"labels":[
{"name":"Volkspark Prenzlauer Berg", "type": "TEXT", "bounding boxes": [ { "left":64, "top":243, "width":55.03, "height":37.75 } ] },
{"name":"Weißenseepark", "type": "TEXT", "bounding boxes": [ { "left":55, "top":78, "width":77.97, "height":11.75 } ] },
{"name":"Sportforum Hohenschönhausen", "type": "TEXT", "bounding boxes": [ { "left":167, "top":215, "width":11, "height":11 } ] },
{"name":"Sportkomplex Buschallee", "type": "TEXT", "bounding boxes": [ { "left":237, "top":61, "width":11, "height":11 } ] },
{"name":"Sportforum Hohenschönhausen", "type": "TEXT", "bounding boxes": [ { "left":123, "top":190, "width":99.55, "height":23.75 } ] },
{"name":"Sportkomplex Buschallee", "type": "TEXT", "bounding boxes": [ { "left":207, "top":36, "width":71.56, "height":23.75 } ] }
],
"city center labels":[
{"name": "Alt-Hohenschönhausen", "text box": { "left":248, "top":133, "width":126.09, "height":29.50 }, "city center info": {"type":"OTHER", "name": "Alt-Hohenschönhausen", "alternative names":[], "country code": "DEU", "position": {"latitude":52.547607, "longitude":13.500824}, "population": 0 } },
{"name": "Weißensee", "text box": { "left":84, "top":8, "width":70.67, "height":15.50 }, "city center info": {"type":"OTHER", "name": "Weißensee", "alternative names":[], "country code": "DEU", "position": {"latitude":52.561340, "longitude":13.467865}, "population": 0 } }
]
}
}

Metainfo tile format for metadata generation two

Every metainfo tile displays the following information in a JSON structure.
  • metadata - container for the response
    • street labels - array of street labels
      • name
      • font size
      • vertices - array of tile coordinates
    • labels - array of labels
      • name
      • type
      • bounding boxes - array of boxes
    • city center labels - array of city center labels
      • name
      • box 1
      • box 2
      • city center info
        • type
        • name
        • alternative names - array of names
          • country code
          • name
        • country code
        • position
          • latitude
          • longitude
        • population
    • buildings - array of buildings
      • id
      • vertices - array of vertices
      • polygons - array of array of polygons
      • outlines - array of outlines
    • transit stops - array of transit stops
      • name
      • bounding boxes - array of bounding boxes
        • box 1
        • box 2
      • info - array of transit stop information
        • geoposition
          • latitude
          • longitude
        • official name
        • informal name
        • places id
        • operating hours
          • Monday
          • Tuesday
          • Wednesday
          • Thursday
          • Friday
          • Saturday
          • Sunday
          • Holiday
        • parking hours
          • Monday
          • Tuesday
          • Wednesday
          • Thursday
          • Friday
          • Saturday
          • Sunday
          • Holiday
    • POIs - array of POIs (Points of Interest)
      • name
      • geoposition
        • latitude
        • longitude
      • bounding boxes - array of bounding boxes
        • box 1
        • box 2
      • info - array of POI information
The format is as follows:

{
  "metadata": {
    "street labels": [],
    "labels": [],
    "city center labels": [],
    "buildings": [],
    "transit stops": [],
    "POIs": []
  }
}

Street labels

The street labels field displays an array of labels containing the name of the street, the font size used to render it and an array of vertices to draw the polyline that represents the bounding box. The format is as follows:

"name": "",
"font size": "",
"vertices: []
Name Type Description
name String Name of the street
font size String Font size used to render the label, it is a number displayed as a string
vertices Array of tile coordinates Array containing all vertices needed to draw a polyline that creates a bounding box on the street label, an array of x/y values, as in [ x1, y1, x2, y2 ... ]

Labels

Labels field displays information about labels that are not street labels, including the name, the type and the location (bounding box). The format is an array of labels, each one with the following format:

"name": "",
"type": "",
"bounding boxes": []
Name Type Description
name String Name displayed on the label
type String One of the following types: Mountain Peak, Text, Pedestrian Point, Roadsign

When type is Roadsign there are additional fields:

  1. region (ISO country code)
  2. category
  3. route name
  4. route level
  5. uri
bounding boxes Array of Bounding Box Array containing all the bounding boxes of the label, that can contain a box 1 or box 2.

City Center Labels

This field displays an array of city center labels, each one including the name and location (bounding box) of the name, ,the city center additional information, which shows the type of city, official displayed name, the alternative names in different languages, the country code, position (latitude and longitude) and population. The format is as follows:

"name": "",
"box 1" : [],
"box 2": [],
"city center info": {
  "type": "",
  "name": "",
  "alternative names": [
    [
      "",
      ""
    ]
  ],
  "country code": "",
  "position": {
    "latitude":,
    "longitude":
  },
  "population":
}
Name Type Description
name String Name of the city
box 1 Bounding Box Location of the text or icon in the tile
box 2 Bounding Box Location of the text or icon in the tile
city center info Structure Structure containing additional information for a city

Buildings

The "buildings" field contains a list of buildings for current tile. Provided information allows to:
  • identify buildings within single tile or across several tiles using unique building "id";
  • define the shape of a building in order to select or highlight it on the map;
The shape of the building provided as an array of vertices, polygons and outlines, where polygons respect winding logic which determines if the polygon is inner or outer. For each building only the following information is offered, minimum number of polygons (polygons with holes) to cover the whole building top view and the outlines that indicate which sides are actual building limits and which are just tile borders, for example

"buildings":[ { "id": "1597687598890565952", "vertices": [ 256, 133.83, 256, 32.36, 186, 72.56, 224, 154.69 ], "polygons": [ [ 0, 1, 2, 3]], "outlines": [ [ 2, 1 ], [ 0, 3, 2 ]] } ]
The format is as follows:

"id": "",
"vertices": [],
"polygons": [],
"outlines": []
]
Name Type Description
id String Internal id of the building
vertices Array vertices (an array of x/y values, as in [ x1, y1, x2, y2 ... ] )
polygons Array polygons (an array of polygons, each polygon being a set of indices of the vertices array)
outlines Array outlines (an array of outlines, each outline being a set of indices of the vertices array)

Transit stops

The transit stop fields displays the name, bounding boxes and info.
Note: Empty fields are filtered out and not present in the output, such as informal name, places id, operating hours, parking hours.
The format is as follows:

"name": "",
"bounding boxes": [
  "box 1": [],
  "box 2": []
],
"info": [
  {
    "position": {
      "latitude": ,
      "longitude":
    },
    "official name": "",
    "informal name": "",
    "places id": "",
    "operating hours": {
      "Monday": [],
      "Tuesday": [],
      "Wednesday": [],
      "Thursday": [],
      "Friday": [],
      "Saturday": [],
      "Sunday": [],
      "Holiday": []
    },
    "parking hours": {
      "Monday": [],
      "Tuesday": [],
      "Wednesday": [],
      "Thursday": [],
      "Friday": [],
      "Saturday": [],
      "Sunday": [],
      "Holiday": []
    }
  }
]
Name Type Description
name String Name of the transit stop
bounding boxes Bounding box Array of bounding boxes (box 1 or box 2 or both)
info Transit Stop Info

Each transit stop info has:

  1. position (latitude/longitude)
  2. official name
  3. informal name
  4. Places id
  5. operating hours
  6. parking hours
Note: Parking information is provided for Transit Stations (i.e., large Train & Bus Stations) so that users can have an entry level understanding of whether they may be able to Park & Ride at that location. There are two cases covered in the content
  • Parking Hours = Difference between whether or not overnight parking is allowed.

POIs

POIs field show information about different POIs in the map including the name, geoposition, bounding boxes and an array of POI info objects. If you want to get information about POIs in the metainfo tile you need to use the pois parameter The format is as follows:

"name": "",
"geoposition": {
  "latitude": ,
  "longitude":
},
"bounding boxes": [],
"info": []
Name Type Description
name String Name of the POI
geoposition Geo Coordinate Location of the POI
bounding boxes Bounding box Array of bounding boxes (box 1 or box 2)
info Array of POI Info

Each POI info object can have the following attributes:

  • ADDR COUNTRY CODE
  • ADDR COUNTRY NAME
  • ADDR STATE NAME
  • ADDR STATE CODE
  • ADDR PROVINCE NAME
  • ADDR COUNTY NAME
  • ADDR CITY NAME
  • ADDR DISTRICT NAME
  • ADDR POSTAL CODE
  • ADDR TOWNSHIP NAME
  • ADDR NEIGHBORHOOD NAME
  • ADDR STREET NAME
  • ADDR HOUSE NUMBER
  • ADDR CONTINENT NAME
  • ADDR TYPE NAME
  • ADDR POPULATION
  • ADDR BUILDING NAME
  • ADDR BUILDING FLOOR
  • ADDR BUILDING ROOM
  • ADDR BUILDING ZONE
  • PLACE NAME
  • PLACE PRE NAME
  • PLACE POST NAME
  • PLACE TYPE
  • PLACE CATEGORY
  • PLACE CATEGORY ID
  • PLACE DESCRIPTION
  • PLACE PHONE NUMBER
  • PLACE URL
  • PLACE ID
  • PLACE PREMIUM URL ID
  • PLACE PREMIUM NODE ID
  • PLACE ADVERTISEMENT STRING
  • TZ OFFSET MINUTES
  • OTHER DATA
  • PLACE ICON ID
  • LOCATION TYPE
  • LOCATION META
  • LOCATION TEXT
  • ADDR AREA ID
Common fields
Field Name Type Description
Bounding Box left Float Location of the left coordinate in the tile
top Float Location of the top coordinate in the tile
width Float Width of the bounding box
height Float Height of the bounding box
Geo coordinate latitude Float ( 6 decimals ) Latitude of the geo coordinate
longitude Float ( 6 decimals ) Longitude of the geo coordinate
City Center Info type String Type of city between National Capital, Provincial Capital and Other
name String Official name of the city
alternative names Array of arrays Alternative names of the city, each array containing the language code as String and the name as String
country code String Three letter country code following ISO
position Geo coordinate Location of the city center
population Integer Population of the city
Tile Coordinate x Integer Coordinate x of the tile coordinate
y Integer Coordinate y of the tile coordinate

Two examples are provided in this section, both using mgen=2, to illustrate the format described above. To get additional information about how to use it please check the Examples section.

This example shows a parameter in Berlin and the request looks like:
https://2.base.maps.cit.api.here.com
/maptile/2.1/maptile/newest/normal.day/9/275/167/256/png8
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&metadata=metaonly
&mgen=2
The response looks like:

{ "metadata" : {
"street labels":[  ],
"labels":[{ "name": "1", "type":"ROADSIGN", "bounding boxes": [ { "box 1":[ 94.62, 239.56, 18, 12 ] } ], "region": "DEU", "category": 1, "route name": "B1", "route level": 3, "uri": "http://image.maps.api.here.com/mia/1.6/roadsign?category=1&region=DEU&label=B1&route_level=3&app_id=%7BYOUR_APP_ID&app_code=%7BYOUR_APP_CODE%7D" },
{ "name": "158", "type":"ROADSIGN", "bounding boxes": [ { "box 1":[ 166.38, 129.27, 22, 12 ] } ], "region": "DEU", "category": 1, "route name": "B158", "route level": 3, "uri": "http://image.maps.api.here.com/mia/1.6/roadsign?category=1&region=DEU&label=B158&route_level=3&app_id=%7BYOUR_APP_ID&app_code=%7BYOUR_APP_CODE%7D" },
{ "name": "114", "type":"ROADSIGN", "bounding boxes": [ { "box 1":[ 13.38, 158.60, 23, 16 ] } ], "region": "DEU", "category": 0, "route name": "A114", "route level": 2, "uri": "http://image.maps.api.here.com/mia/1.6/roadsign?category=0&region=DEU&label=A114&route_level=2&app_id=%7BYOUR_APP_ID&app_code=%7BYOUR_APP_CODE%7D" },
{ "name": "11", "type":"ROADSIGN", "bounding boxes": [ { "box 1":[ 61.50, 166.63, 22, 16 ] } ], "region": "DEU", "category": 0, "route name": "A11", "route level": 2, "uri": "http://image.maps.api.here.com/mia/1.6/roadsign?category=0&region=DEU&label=A11&route_level=2&app_id=%7BYOUR_APP_ID&app_code=%7BYOUR_APP_CODE%7D" },
{ "name": "2", "type":"ROADSIGN", "bounding boxes": [ { "box 1":[ 36.62, 188.59, 18, 12 ] } ], "region": "DEU", "category": 1, "route name": "B2", "route level": 3, "uri": "http://image.maps.api.here.com/mia/1.6/roadsign?category=1&region=DEU&label=B2&route_level=3&app_id=%7BYOUR_APP_ID&app_code=%7BYOUR_APP_CODE%7D" },
{ "name": "109", "type":"ROADSIGN", "bounding boxes": [ { "box 1":[ 49.88, 28.25, 22, 12 ] } ], "region": "DEU", "category": 1, "route name": "B109", "route level": 3, "uri": "http://image.maps.api.here.com/mia/1.6/roadsign?category=1&region=DEU&label=B109&route_level=3&app_id=%7BYOUR_APP_ID&app_code=%7BYOUR_APP_CODE%7D" }],
"city center labels":[{"name": "Berlin", "box 2":[ 9, 218, 49.45, 20.50 ], "box 1":[ 4, 234, 5, 5 ], "city center info": {"type":"NATIONAL CAPITAL", "name": "Berlin", "alternative names":[["ARA", "برلين"], ["BAQ", "Berlin"], ["BUL", "Берлин"], ["BUX", "Berlin"], ["CAT", "Berlín"], ["CHI", "柏林"], ["CHT", "柏林"], ["CZE", "Berlín"], ["CZX", "Berlin"], ["DAN", "Berlin"], ["DUT", "Berlijn"], ["ENG", "Berlin"], ["EST", "Berliin"], ["ESX", "Berliin"], ["FIN", "Berliini"], ["FRE", "Berlin"], ["GER", "Berlin"], ["GRE", "Βερολίνο"], ["GRX", "Verolino"], ["HIN", "बर्लिन"], ["HIX", "Barlin"], ["HUN", "Berlin"], ["HUX", "Berlin"], ["ICE", "Berlín"], ["IND", "Berlin"], ["ITA", "Berlino"], ["JPN", "ベルリン"], ["JPX", "Berurin"], ["KOR", "베를린"], ["KOX", "Be Reul Rin"], ["LAV", "Berlīne"], ["LAX", "Berline"], ["LIT", "Berlynas"], ["LIX", "Berlynas"], ["MAY", "Berlin"], ["NOR", "Berlin"], ["POL", "Berlin"], ["POR", "Berlim"], ["POX", "Berlin"], ["PYN", "Bo Lin"], ["RMX", "Berlin"], ["RUM", "Berlin"], ["RUS", "Берлин"], ["RUX", "Berlin"], ["SCR", "Berlin"], ["SLO", "Berlín"], ["SLX", "Berlin"], ["SPA", "Berlín"], ["SRX", "Berlin"], ["SWE", "Berlin"], ["THA", "เบอร์ลิน"], ["TUR", "Berlin"], ["TUX", "Berlin"], ["UKR", "Берлін"], ["UKX", "Berlin"]], "country code": "DEU", "position": {"latitude":52.514648, "longitude":13.375854}, "population": 3442675 } },
{"name": "Eberswalde", "box 2":[ 167, 36, 58.22, 11.75 ], "box 1":[ 165, 45, 2, 2 ], "city center info": {"type":"OTHER", "name": "Eberswalde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.833252, "longitude":13.815308}, "population": 41175 } },
{"name": "Bernau bei Berlin", "box 2":[ 83, 117, 55.08, 22.75 ], "box 1":[ 81, 137, 2, 2 ], "city center info": {"type":"OTHER", "name": "Bernau bei Berlin", "alternative names":[], "country code": "DEU", "position": {"latitude":52.679443, "longitude":13.584595}, "population": 36154 } },
{"name": "Strausberg", "box 2":[ 191, 192, 51.91, 10.50 ], "box 1":[ 189, 200, 2, 2 ], "city center info": {"type":"OTHER", "name": "Strausberg", "alternative names":[], "country code": "DEU", "position": {"latitude":52.575073, "longitude":13.881226}, "population": 26221 } },
{"name": "Wandlitz", "box 2":[ 43, 83, 40.47, 10.50 ], "box 1":[ 41, 91, 2, 2 ], "city center info": {"type":"OTHER", "name": "Wandlitz", "alternative names":[], "country code": "DEU", "position": {"latitude":52.756348, "longitude":13.474731}, "population": 21530 } },
{"name": "Neuenhagen bei Berlin", "box 2":[ 121, 211, 58.64, 20.50 ], "box 1":[ 119, 229, 2, 2 ], "city center info": {"type":"OTHER", "name": "Neuenhagen bei Berlin", "alternative names":[], "country code": "DEU", "position": {"latitude":52.525635, "longitude":13.688965}, "population": 16755 } },
{"name": "Ahrensfelde", "box 2":[ 81, 192, 56.22, 10.50 ], "box 1":[ 79, 200, 2, 2 ], "city center info": {"type":"OTHER", "name": "Ahrensfelde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.575073, "longitude":13.579102}, "population": 13114 } },
{"name": "Bad Freienwalde (Oder)", "box 2":[ 165.17, 56, 75.83, 20.50 ], "box 1":[ 241, 74, 2, 2 ], "city center info": {"type":"OTHER", "name": "Bad Freienwalde (Oder)", "alternative names":[], "country code": "DEU", "position": {"latitude":52.783813, "longitude":14.024048}, "population": 12964 } },
{"name": "Werneuchen", "box 2":[ 137, 159, 57.83, 10.50 ], "box 1":[ 135, 167, 2, 2 ], "city center info": {"type":"OTHER", "name": "Werneuchen", "alternative names":[], "country code": "DEU", "position": {"latitude":52.630005, "longitude":13.732910}, "population": 7943 } },
{"name": "Biesenthal", "box 2":[ 105, 76, 49.03, 10.50 ], "box 1":[ 103, 84, 2, 2 ], "city center info": {"type":"OTHER", "name": "Biesenthal", "alternative names":[], "country code": "DEU", "position": {"latitude":52.767334, "longitude":13.645020}, "population": 5563 } },
{"name": "Rehfelde", "box 2":[ 207, 218, 42.12, 10.50 ], "box 1":[ 205, 226, 2, 2 ], "city center info": {"type":"OTHER", "name": "Rehfelde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.531128, "longitude":13.925171}, "population": 4462 } },
{"name": "Liebenwalde", "box 2":[ 15, 13, 57.72, 10.50 ], "box 1":[ 13, 21, 2, 2 ], "city center info": {"type":"OTHER", "name": "Liebenwalde", "alternative names":[], "country code": "DEU", "position": {"latitude":52.871704, "longitude":13.397827}, "population": 4390 } },
{"name": "Chorin", "box 2":[ 189, 0, 31.52, 10.50 ], "box 1":[ 187, 2, 2, 2 ], "city center info": {"type":"OTHER", "name": "Chorin", "alternative names":[], "country code": "DEU", "position": {"latitude":52.904663, "longitude":13.875732}, "population": 2430 } },
{"name": "Oderberg", "box 2":[ 203.75, 17, 45.25, 10.50 ], "box 1":[ 249, 25, 2, 2 ], "city center info": {"type":"OTHER", "name": "Oderberg", "alternative names":[], "country code": "DEU", "position": {"latitude":52.866211, "longitude":14.046021}, "population": 2229 } },
{"name": "Britz", "box 2":[ 139.81, 4, 23.19, 10.50 ], "box 1":[ 163, 12, 2, 2 ], "city center info": {"type":"OTHER", "name": "Britz", "alternative names":[], "country code": "DEU", "position": {"latitude":52.888184, "longitude":13.809814}, "population": 2201 } },
{"name": "Rüdnitz", "box 2":[ 99, 103, 36.39, 10.50 ], "box 1":[ 97, 111, 2, 2 ], "city center info": {"type":"OTHER", "name": "Rüdnitz", "alternative names":[], "country code": "DEU", "position": {"latitude":52.723389, "longitude":13.628540}, "population": 1839 } },
{"name": "Marienwerder", "box 2":[ 89, 30, 63.73, 10.50 ], "box 1":[ 87, 38, 2, 2 ], "city center info": {"type":"OTHER", "name": "Marienwerder", "alternative names":[], "country code": "DEU", "position": {"latitude":52.844238, "longitude":13.601074}, "population": 1731 } },
{"name": "Prötzel", "box 2":[ 210.95, 152, 34.09, 10.50 ], "box 1":[ 227, 164, 2, 2 ], "city center info": {"type":"OTHER", "name": "Prötzel", "alternative names":[], "country code": "DEU", "position": {"latitude":52.635498, "longitude":13.985596}, "population": 1143 } }],
"buildings":[  ],
"transit stops":[  ],
"POIs":[  ]
}
}
This other example contains a metadata response for a close-up of a location in Berlin including street labels. The request looks like:
https://2.base.maps.cit.api.here.com
/maptile/2.1/maptile/newest/normal.day/13/4402/2685/256/png8
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&metadata=metaonly
&mgen=2
And the response looks like:

{ "metadata" : {
"street labels":[ { "name":"Hansastraße", "font size":"11", "vertices": [ 163.53, 118.07, 175.55, 102.83, 178.97, 98.52, 183, 93.89, 187.21, 90.07, 190.71, 87, 194.13, 84.78, 210.95, 75.05 ] },
{ "name":"Weißenseer Weg", "font size":"11", "vertices": [ 147.10, 240.99, 172.97, 288.05, 176.50, 297.99, 182.69, 319.32 ] } ],
"labels":[{ "name": "Volkspark Prenzlauer Berg", "type":"TEXT", "bounding boxes": [ { "box 2":[ 64.67, 243, 55.03, 37.75 ] } ] },
{ "name": "Weißenseepark", "type":"TEXT", "bounding boxes": [ { "box 2":[ 55.70, 78.21, 77.97, 11.75 ] } ] },
{ "name": "Sportforum Hohenschönhausen", "type":"TEXT", "bounding boxes": [ { "box 1":[ 167.44, 215.11, 11, 11 ] } ] },
{ "name": "Sportkomplex Buschallee", "type":"TEXT", "bounding boxes": [ { "box 1":[ 237.81, 60.93, 11, 11 ] } ] },
{ "name": "Sportforum Hohenschönhausen", "type":"TEXT", "bounding boxes": [ { "box 2":[ 123.16, 190.11, 99.55, 23.75 ] } ] },
{ "name": "Sportkomplex Buschallee", "type":"TEXT", "bounding boxes": [ { "box 2":[ 207.53, 35.93, 71.56, 23.75 ] } ] }],
"city center labels":[{"name": "Alt-Hohenschönhausen", "box 1":[ 248.95, 133.43, 126.09, 29.50 ], "city center info": {"type":"OTHER", "name": "Alt-Hohenschönhausen", "alternative names":[], "country code": "DEU", "position": {"latitude":52.547607, "longitude":13.500824}, "population": 0 } },
{"name": "Weißensee", "box 1":[ 84.66, 8.86, 70.67, 15.50 ], "city center info": {"type":"OTHER", "name": "Weißensee", "alternative names":[], "country code": "DEU", "position": {"latitude":52.561340, "longitude":13.467865}, "population": 0 } }],
"buildings":[  ],
"transit stops":[  ],
"POIs":[  ]
}
}

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.