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 Beijing showing the well-known Forbidden City.

First, request a map tile as follows:
https://2.base.maps.hereapi.cn/maptile/2.1/maptile/newest/normal.day/19/431659/198648/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

The response is the following tile:
Figure 1. Center of Beijing in the location of the Forbidden City

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.hereapi.cn/maptile/2.1/maptile/newest/normal.day/19/431659/198648/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": [],
    "labels": [{
      "name": "午门",
      "type": "TEXT",
      "bounding boxes": [{
        "box 2": [195, 3.12, 26, 13]
      }]
    }],
    "city center labels": [],
    "buildings": [{
        "id": "1568999455028946039",
        "vertices": [62, 33.91, 59.69, 0, 256, 0, 256, 82.12, 178, 82.12, 58, 87.34],
        "polygons": [
          [0, 1, 2, 3, 4, 5]
        ],
        "outlines": [
          [0, 1],
          [3, 4, 5, 0]
        ]
      },
      {
        "id": "1568999455028946737",
        "vertices": [29.18, 0, 31.58, 256, 0, 256, 0, 0],
        "polygons": [
          [0, 1, 2, 3]
        ],
        "outlines": [
          [0, 1]
        ]
      }
    ],
    "transit stops": [],
    "POIs": [{
        "name": "故宫博物院南门",
        "geoposition": {
          "latitude": 39.913502,
          "longitude": 116.397271
        },
        "bounding boxes": [{
          "box 1": [201, 210.72, 14, 14]
        }, {
          "box 2": [172, 198.72, 72, 10.50]
        }],
        "info": [{
          "PLACE NAME": "故宫博物院南门",
          "PLACE PHONE NUMBER": "+(86)-1065131892",
          "PLACE CATEGORY": "Tourist Attraction",
          "PLACE ID": "134796334"
        }]
      },
      {
        "name": "午门 /\n右掖门 /\n左掖门",
        "geoposition": {
          "latitude": 39.913588,
          "longitude": 116.397271
        },
        "bounding boxes": [{
          "box 1": [201, 169, 14, 14]
        }, {
          "box 2": [187.86, 137, 40.28, 30.50]
        }],
        "info": [{
          "PLACE NAME": "午门",
          "PLACE PHONE NUMBER": "+(86)-1085007519",
          "PLACE CATEGORY": "Tourist Attraction",
          "PLACE ID": "58741445"
        }]
      }
    ]
  }
}

In the response, we see that the Forbidden City has Tourist Attraction as the category. Referring to the /meta/pois resource, the user creates a filter to display the Tourist Attraction category. The resulting request is as follows:
https://2.base.maps.hereapi.cn/maptile/2.1/maptile/newest/normal.day/19/431659/198648/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}
  &pois=000000004

This response is the following image that contains the icon for Forbidden City.
Figure 2. Center of Beijing 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