Maps API for JavaScript Developer's Guide

Filters

HERE Maps API for JavaScript provides filtering functionality that helps create the map with the desired appearance. You can filter map features provided by the HERE Vector Tile API using any property from the data layer.

Layer filtering

Any data layer can be associated with one or several logical layers that describe how to the data layer is rendered. To define what data layer provides geometries for rendering, layer property of the data block is used. The following example demonstrates two logical layers that use the same data layer. The logical layers render geometry provided by the water data layer as polygons (water_area) and polylines (water_outline). Note that both logical layers use the same data layer provided by the data block layer property.
Table 1.
Style The map after using two logical layers

sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  water_areas:
    data: {source: omv, layer: water}
    draw:
      polygons:
        order: 1
        color: [0.055, 0.604, 0.914, 0.50]
  roads:
    data: {source: omv, layer: water}
    draw:
      lines:
        order: 2
        width: 3px
        color: [0.055, 0.604, 0.914, 1.00]
          
For the full list of the available data layers, refer to the HERE Vector Tile API documentation.

Feature filtering

To narrow down how the logical layer is applied, you can include the filter block element into the logical definition. The filter block defines the features from the data layer that are rendered with the given style. In the following example, the filter block is not defined and, by default, all geometries of the roads data layer are rendered with the lines style.
Table 2.
Style The map with the layer without filter

sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  roads:
    data: {source: omv, layer: roads}
    draw:
      lines:
        order: 2
        width: 2px
        color: [0.561, 0.561, 0.561, 1.00]
          
Adding the filter to the example, above reduces the number of features that belong to this logical layer. The following example shows how to apply the filter block to the existing layer. The block contains the key-value pairs, where key is the name of the property used for filtering and the value is the data value against which the filter match is performed.
Table 3.
Style The map with the "major_road" filter

sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  roads:
    data: {source: omv, layer: roads}
    filter:
      kind: major_road
    draw:
      lines:
        order: 2
        width: 2px
        color: [0.561, 0.561, 0.561, 1.00]
          
Single filter can perform matching against several different properties and follows the logical AND rules. The snippet, below adds a second property - is_tunnel - to select geometries for the logical layer more precisely.
Table 4.
Style The map with the "major_road" AND "is_tunnel" filter

sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  roads:
    data: {source: omv, layer: roads}
    filter:
      kind: major_road
      is_tunnel: true
    draw:
      lines:
        order: 2
        width: 2px
        color: [0.561, 0.561, 0.561, 1.00]
          
Logical layers can be nested (filter blocks follow logical AND rules). Nesting in combination with filters provides a powerful tool that helps to express precisely how the feature should be rendered depending on its properties and enables reuse of draw instructions. In the example, below the road network from the roads data layer is rendered colored gray. Three nested logical layers show how filters are applied to highlight the bridges on the map. If a map feature represents:
  • a bridge (is_bridge == true) then feature color is red
  • a bridge (is_bridge == true) AND the road class is tertiary (kind_detail == tertiary) then feature color is green
  • a bridge (is_bridge == true) AND the road class is tertiary (kind_detail == tertiary) AND the road segment is marked as a one-way segment (oneway == true) then feature color is blue
Table 5.
Style The map with the nested logical layers and filters

sources:
  omv:
    type: OMV
    max_zoom: 17
    min_display_zoom: 1
layers:
  road:
    data: {source: omv, layer: roads}
    draw:
      lines:
        order: 2
        color: [0.8, 0.8, 0.8, 1.00]
        width: 3px
    bridges:
      filter:
        is_bridge: true
      draw:
        lines:
          color: red
      tertiary:
        filter:
          kind_detail: tertiary
        draw:
          lines:
            color: green
        oneway:
          filter:
            oneway: true
          draw:
            lines:
              color: blue
          

Filter functions and keywords

The filtering system provides additional means to control what features are used in the given logical layer - functions and keywords:
  • Embedded functions include logical functions not, any, all and none and range functions min and max
    • not - is a logical NOT operator and can take a filter object. The following snippet will filter out all tertiary roads.
      
      filter:
        not: {kind_detail: tertiary}
              
    • any - is a logical OR operator and takes a list of the filter objects. The example below filters out all roads if the are not tertiary OR marked as bridge.
      
      filter:
        any: 
          - kind_detail: tertiary
          - is_bridge: true
              
    • all - is a logical AND operator and takes a list of the filter objects. The following example filters out all features that are not tertiary roads AND are bridges.
      
      filter:
        all: 
          - kind_detail: tertiary
          - is_bridge: true
              
    • none - is a logical NOR operator and takes a list of the filter objects. The snippet, below filters out all features that are bridges OR Tertiary roads OR both bridges and tertiary roads.
      
      filter:
        none:
          - {kind_detail: residential}
          - {is_bridge: true}
              
    • min/max define the range [min, max), if the value of feature property falls in this range the geometry is rendered.
      
      filter:
        height: {min: 10, max: 25}
              
  • Keywords $zoom and $geometry help to filter data layer features based on the zoom level and geometry type.
    • $zoom - matches the current zoom level of the map and the filter value. In the following example, logical layer's features are rendered only when the map's zoom level is [10, 11).
      
      filter:
        $zoom: 10
              
    • $geometry - matches the feature geometry type and is used when the data layer contains more than one geometry type. Possible values are point, line and polygon
      
      filter:
        $geometry: polygon