Map Tile API Developer's Guide

POI Categories Filtering

This chapter explains how to use the pois parameter.

This parameter is used to show/hide POIs on the map.

POI Filtering parameter usage

The relevant parameters for poi filtering requests are:

Table 1. POI Categories request parameters
Parameter Type Description
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.

Usage of poi filtering

The parameter pois can be used in a tile request to show certain POIs.

A typical use case is that the user only wants to see a certain category or just a subset of the categories available.

In this example the user wants to see a certain location in the center of Berlin showing the well known Brandenburg Gate. In order to do that the user first requests the maptile as follows.

https://2.base.maps.cit.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}

This requests renders the following tile

Figure 1. Center of Berlin in the location of the Brandenburg Gate

After checking that the tile is the expected one, the user requests the metadata information of the tile to figure out what category is the POI.

https://2.base.maps.cit.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 result of the previous requests is a JSON object containing the information of the POIs of 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"}] } ]
}
}

Checking the result, we can see that Brandenburg Gate has the category Historical Monument. Therefore, after checking /meta/pois resource, the filter is created to display that category and the resulting tile request is shown below.

https://2.base.maps.cit.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 request results in the following image that contains the icon for the Brandenburg Gate.

Figure 2. Center of Berlin showing the filtered POI Category

Usage of /meta/pois resource

The resource /meta/pois must be used to get an up to date list of all the categories supported and the corresponding index. Since every four categories are grouped into a single hexadecimal symbol, the easiest way to calculate the mask is to create some client code to handle it and offload this logic from the customer.

The easiest way to do it is to get all the poi categories in a JSON object and then put them in a list. Once that is done you can just create a mask on the fly depending on what the user has selected. You can use the original list to create a list with checkboxes and let the user select which ones are of interest. Below you can find an example snippet code in JavaScript that demonstrates this.


        // 1. get poi categories /meta/pois?output=json and store them in a list
        // 2. create a list with inputs of type checkbox
        // 3. create a 'change' listener that includes the following logic
         var bit, bits = '0', hex = '', n=1;
         // please pay attention as the index starts on '1' as the
         // first bit is always initialized to '0' because it is a reserved bit
        $('.poi').each(function(i) {
            bit = $(this).is(':checked') ? '1' : '0';
            bits = bits + bit;
            if ((n+1)%4 == 0) {
              hex = hex + parseInt(bits, 2).toString(16);
              bits = '';
            }
            n = n + 1
        });
        if (bits !== '') hex = hex + parseInt(bits, 2).toString(16);
        // we remove the trailing zeroes as they are not needed
        hex =  hex.replace(/0+$/g, '');
        // trigger a map update using the parameter &pois=hex
      

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.