Map Tile API Developer's Guide

Filter POIs by Categories

The Map Tile API provides a POI Categories resource that you can use to show or hide POIs on the map.

A typical use case is when the user only wants to see a certain category or just a subset of the categories available. For example, the user wants to see a certain location in the center of Berlin showing the well-known Brandenburg Gate.

First, request a map tile as follows:
https://2.base.maps.api.here.com/maptile/2.1/
  maptile/newest/normal.day/20/563253/343903/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

The response is the following tile:
Figure 1. Center of Berlin in the location of the Brandenburg Gate

Once the user has verified that the tile is as expected, the user then requests the metadata information of the tile to determine in which category the POI is.
https://2.base.maps.api.here.com
  /maptile/2.1/maptile/newest/normal.day/20/563253/343903/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &pois
  &mgen=2
  &metadata=metaonly
The response is a JSON object containing information on the POIs in the tile.
{
  "metadata" : {
    "street labels":[ { "name":"Pariser Platz", "font size":"13", "vertices": 
    [ 168.73, 138.98, 204.18, 134.84, 215.62, 133.47, 243.81, 131.50 ] } ],
    
    "labels":[],
    "city center labels":[],
    "buildings":[
       {
          "id": "1609370975087560592", "sectors": [
             {
              "info": { "bottom height": 0, "height": 8 }, 
              "vertices": [ 8.44, 0, 10, 13.56, 110.66, 0 ], 
              "polygons": [ [ 0, 1, 2]], 
              "outlines": [ [ 2, 1, 0 ]] }, 
              {
                 "info":
                 {
                   "bottom height": 0, "height": 19.875 }, 
                   "vertices": [ 160, 220.62, 148, 115.44, 10, 13.56, 0, 13.56, 0, 48.62, 23.66, 256, 163.83, 256, 
                   110.66, 0, 132.39, 0, 158, 112.19, 144.72, 0, 168, 220.62, 172.31, 256, 0, 48.62 ], 
                   "polygons": [ [ 0, 1, 2, 3, 4, 5, 6], [ 7, 2, 1, 8], [ 8, 1, 9, 10], [ 11, 0, 6, 12]], 
                   "outlines": [ [ 5, 13 ], [ 3, 2, 7 ], [ 10, 9, 1, 0, 11, 12 ]] } ] } ],
                   "transit stops":[  ],
                   
                   "POIs":[
                      {
                         "name":"Brandenburg Gate",
                         "geoposition":
                         {
                           "latitude":52.516279, "longitude":13.377700
                         },
                         "bounding boxes":[
                           {
                             "icon box":[ 89, 177.50, 14, 14 ]
                           },
                           {
                             "annotation box":[ 53.55, 165.50, 84.91, 10.50 ] 
                           }
                           ],
                           "info": [
                             {
                               "PLACE NAME":"Brandenburg Gate", 
                               "PLACE CATEGORY":"Historical Monument", 
                               "PLACE ID":"800842663"
                             }
                          ]
                      }
                  ]
      }
}

In the response, we see that the Brandenburg Gate has Historical Monument as the category. Referring to the /meta/pois resource, the user creates a filter to display the Historical Monument category. The resulting request is as follows:
https://2.base.maps.api.here.com
  /maptile/2.1/maptile/newest/normal.day/20/563253/343903/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &pois=000000001

This response is the following image that contains the icon for Brandenburg Gate.
Figure 2. Center of Berlin showing the filtered POI Category

Using the /meta/pois Resource

Use the /meta/pois resource to retrieve an up-to-date list of all categories the API supports. You specify the parameter as a mask for the POI Categories contained in the map. Each symbol, written in hexadecimal, represents four POI categories, starting from 0 – 3 until 386 – 389. You can use the mask in one of the following ways:

  • enable all categories (default behavior) – pois=0
  • disable all categories – pois=F
  • enable categories that are present for POIs, disable the others – pois=F
  • enable categories that are not present for POIs, disable the others – pois=!F
  • customize the categories by specifying the values as a mask – pois=123.....F