Here Map Content (HMC) Bindings

1. Introduction

1.1 HMC

HERE Map Content(HMC) is a global and use-case agnostic Platform Data API catalog. It publishes HERE map data for Location Service development purposes. The catalog enables users to selectively consume features and attributes of interest for their use-case and select updated partitions only when getting the latest map data from the HERE Platform.

For more details: https://developer.here.com/documentation/here-map-content/dev_guide/topics/introduction.html

1.2 Content bindings

Content bindings provide access to content exposed in a layer(s). Bindings can be based on one of the existing layers, or based on a group of more layers.

Goal of content bindings is to provide a uniform way for final users to access a variety of complex data models, in a python-friendly way.

2. Layers supported

• Street Names
• Traffic Patterns
• Sign Text
• Administrative Places
• Administrative Locations
• Administrative Place Profiles
• Indexed Locations
• Environmental Zones
• Topology Geometry
• Road Attributes
• Navigation Attributes
• Advanced Navigation Attributes
• Bicycle Attributes
• Places Metadata
• Building Metadata
• Cartography-Metadata

PySDK also supports below HMC bindings based on multiple layers.

• Administrative boundary for a segment
• Environmental zones for a segment
• Speed limit from navigation and advanced navigation attributes layers
• Street name for a segment

3. Using HMC Bindings

Binding have the following high-level API:

• get gives all the objects for one or more partitions
• get_ref gives a single object
• get_referencing gives all the objects based on reference given

Please note get_ref or get_referencing works only if object_type() have RefType.

Initialization

from here.platform import Platform
from here.geopandas_adapter import GeoPandasAdapter
from here.content.hmc2 import HMC
import pandas as pd
from here.platform.adapter import make_ref
from IPython.display import display, FileLink

platform = Platform()
hmc = HMC(platform, adapter=GeoPandasAdapter())


display(f"Catalog Id: {hmc.content.catalog_hrn} , Version:{hmc.content.version}")

'Catalog Id: hrn:here:data::olp-here:rib-2 , Version:4971'

def types_to_df(types):
    def to_record(kv):
        k, v = kv
        return {
            "Type": k,
            "Data Class": '.'.join([v.__module__, v.__qualname__]),
            "Index by partition": v.indexer.partition is not None,
            "Index by ID": v.indexer.identifier is not None,
            "Ref Types": ", ".join(v.indexer.refs.keys()) or None
        }
    return pd.DataFrame.from_records(map(to_record, types.items()), index="Type")

## Install HERE Map Widget for Jupyter. This is needed for using Here Maps  
#!pip install here-map-widget-for-jupyter

# Functions needed for using Here Maps
from here_map_widget import GeoData
import here.geotiles.heretile as ht 
from here_map_widget import Map
import geopandas as gpd
from shapely.geometry.polygon import Polygon
import os

# replace your API key here.
api_key = os.environ["LS_API_KEY"]


def plot_geometry(dataFrame, geo_column):
    geoDF = gpd.GeoDataFrame(dataFrame[dataFrame['location.geometry'] != None][[geo_column]].copy(), 
                             geometry=geo_column)
    center_point = geoDF[geo_column].centroid.head(1).values
    geoData = GeoData(geo_dataframe=geoDF, 
                    style={"strokeColor": "rgba(128,0,128,1)"},
                    hover_style={"strokeColor": "rgba(255,0,0,1)"},
                    name='geometry_layer')
    m = Map(
        api_key=api_key,
        center=[center_point.y[0], center_point.x[0]],
        zoom=12,
    )

    m.add_layer(geoData)
    return m



def plot_here_tiles(tile_ids):
    tiles = [Polygon(ht.get_boundary_ring(t)) for t in tile_ids]
    tiles_df = pd.DataFrame(tiles, columns=["geometry"])
    geoDF = gpd.GeoDataFrame(tiles_df, geometry='geometry')
    center_point = geoDF['geometry'].centroid.head(1).values
    geoData = GeoData(geo_dataframe=geoDF, style={"strokeColor": "rgba(128,0,128,1)"},
                      hover_style={"strokeColor": "rgba(255,0,0,1)"},
                      name='here_tiles')
    m = Map(
        api_key=api_key,
        center=[center_point.y[0], center_point.x[0]],
        zoom=12,
    )

    m.add_layer(geoData)
    return m 

def plot_multiple_geometry(geometries):
    geoData_1 = GeoData(geo_dataframe=geometries['Nodes'], 
                    style={"strokeColor": "rgba(128,0,128,1)"},
                    hover_style={"strokeColor": "rgba(255,0,0,1)"},
                    name='geometry_layer_1')
    geoData_2 = GeoData(geo_dataframe=geometries['Segments'], 
                    style={"strokeColor": "rgba(128,0,128,1)"},
                    hover_style={"strokeColor": "rgba(255,0,0,1)"},
                    name='geometry_layer_2')
    center_point = (geometries['Nodes'].set_crs(epsg=4328, allow_override=True)).centroid.head(1).values
    m = Map(
        api_key=api_key,
        center=[center_point.y[0], center_point.x[0]],
        zoom=12,
    )

    m.add_layer(geoData_1)
    m.add_layer(geoData_2)
    return m

3.1 Street Names

Layer Id - Street Names

tiles = ['23671200-25332448-25332461', '1469256839-1469256831']

street_names = hmc.street_names
types_to_df(street_names.object_types())

df = street_names.get(tiles, 'street')
df.head(2)

df = street_names.get(tiles, 'context')
df.head(2)

df = street_names.get(tiles, 'street_section')
df.head(2)

3.2 Traffic Patterns

Layer Id - traffic-patterns

tiles = [23618502]

traffic_patterns = hmc.traffic_patterns
types_to_df(traffic_patterns.object_types())

traffic_pattern = traffic_patterns.get(tiles,"traffic_pattern")
traffic_pattern.head(2)

holiday_pattern = traffic_patterns.get(tiles,"holiday_pattern")
holiday_pattern.head(2)

### Construct a new Reference by giving partition and identifier.
traffic_pattern_ref = make_ref(23618502,"here:cm:segment:76770511")

traffic_pattern_attributes = traffic_patterns.get_referencing(
        23618502, "traffic_pattern", "first_segment", 
)
traffic_pattern_attributes.head(2)

holiday_pattern_attributes = traffic_patterns.get_referencing(
        23618502, "holiday_pattern", "first_segment", 
)
holiday_pattern_attributes.head(2)

3.3 Sign Text

Layer Id - sign-text

tiles = [18011924]
sign_text = hmc.sign_text
types_to_df(sign_text.object_types())

display(sign_text.ref_types())

{'sign_attribute': ['first_segment', 'segment']}

df = sign_text.get(tiles, "sign_attribute")
df.head(2)

df = sign_text.get_referencing(tiles, "sign_attribute", "segment")
df.head(2)

df = sign_text.get_referencing(tiles, "sign_attribute", "first_segment")
df.head(2)

3.4 Administrative Places

Layer Id - administrative-places

admin_places = hmc.admin_places

types_to_df(admin_places.object_types())

admin_tiles = ["20000001", "20000001-20000002-20030132"]

df = admin_places.get(admin_tiles, "place")
df.head(2)

df = admin_places.get(admin_tiles, "context")
df.head(2)

3.5 Administrative Locations

Layer Id - administrative-locations

admin_locations = hmc.admin_locations
types_to_df(admin_locations.object_types())

df = admin_locations.get(partition="21000001", object_type="location") 
df.head(2)

3.6 Administrative Place Profiles

Layer Id - administrative_place_profiles

admin_place_profiles = hmc.admin_place_profiles

df = admin_place_profiles.get(partition = "21000001", object_type="admin_place_profile_attributes")
df.head(2)

### Construct a new Reference by giving partition and identifier.
ref = make_ref("21000001", "here:cm:namedplace:21000002")

admin_place_profiles.get_referencing(
        partition = "21000001", object_type="admin_place_profile_attributes", ref_type="place", referenced_obj=ref
)

3.8 Indexed Locations

Layer Id - indexed_locations

admin_index = hmc.admin_index

types_to_df(admin_index.object_types())

country_partitions = ["FIN", "HND", "IRL"]
country_tiles = admin_index.get(country_partitions, "country")
country_tiles

## You can always use the `explode` function to convert a list in multiple rows.
country_tiles.explode("tile_id")

plot_here_tiles(country_tiles.loc["FIN"]["tile_id"])

Map(center=[60.1611328125, 19.2919921875], controls=(ZoomControl(alignment='LEFT_TOP'),), layers=(GeoData(data…

plot_here_tiles(country_tiles.loc["IRL"]["tile_id"])

Map(center=[51.5478515625, -10.2392578125], controls=(ZoomControl(alignment='LEFT_TOP'),), layers=(GeoData(dat…

df = admin_index.get_referencing(country_partitions, "location", "location")
df.head(2)

3.8 Environmental Zones

Layer Id - environmental_zones

environmental_zones = hmc.environmental_zones
types_to_df(environmental_zones.object_types())

environmental_zones.ref_types()

{'zone': ['location']}

types_to_df(environmental_zones.object_types())

env_zones = environmental_zones.get("all", "zone")
env_zones.head(2)

### Construct a new Reference by giving partition and identifier.
location_ref = make_ref("23600686", "here:cm:carto-loc:1661293691")

env_zones = environmental_zones.get_referencing("all", "zone", "location", location_ref)
env_zones

3.9 Topology Geometry

Layer Id - topology-geometry

topology_geometry = hmc.topology_geometry
types_to_df(topology_geometry.object_types())

topology_geometry.ref_types()

{'node': [], 'segment': []}

types_to_df(topology_geometry.object_types())

tiles =[19318110]

nodes = topology_geometry.get(tiles, "node")
nodes.head(2)

segments = topology_geometry.get(tiles, "segment")
segments.head(2)

geometries={"Nodes": nodes, "Segments": segments}
plot_multiple_geometry(geometries)

Map(center=[34.0527, -118.22421], controls=(ZoomControl(alignment='LEFT_TOP'),), layers=(GeoData(data={'type':…

3.10 Road Attributes

Layer Id - road-attributes

road_attributes = hmc.road_attributes

types_to_df(road_attributes.object_types())

road_attributes.ref_types()

{'accessible_by': ['first_segment', 'segment'],
 'overpass_underpass': ['first_segment', 'segment'],
 'functional_class': ['first_segment', 'segment'],
 'iso_country_code': ['first_segment', 'segment'],
 'physical': ['first_segment', 'segment'],
 'road_class': ['first_segment', 'segment'],
 'special_traffic_area_category': ['first_segment', 'segment'],
 'display_level': ['first_segment', 'segment']}

types_to_df(road_attributes.object_types())

tiles = [19318110]
df = road_attributes.get(tiles, "functional_class")
df.head(2)

df = road_attributes.get_referencing(tiles, "functional_class", "segment")
df.head(2)

df = road_attributes.get_referencing(tiles, "iso_country_code", "segment")
df.head(2)

df = road_attributes.get_referencing(tiles, "iso_country_code", "segment")
df.head(2)

3.11 Navigation Attributes

Layer Id - navigation-attributes

navigation_attributes = hmc.navigation_attributes

types_to_df(navigation_attributes.object_types())

navigation_attributes.ref_types()

{'access_permission': ['first_segment', 'segment'],
 'access_restriction': ['first_segment', 'segment'],
 'construction_status': ['first_segment', 'segment'],
 'gate': ['first_segment', 'segment'],
 'intersection_category': ['first_segment', 'segment'],
 'lane_category': ['first_segment', 'segment'],
 'through_lane_count': ['first_segment', 'segment'],
 'physical_lane_count': ['first_segment', 'segment'],
 'local_road': ['first_segment', 'segment'],
 'low_mobility': ['first_segment', 'segment'],
 'permitted_driving_manoeuvre': ['first_segment', 'segment'],
 'restricted_driving_manoeuvre': ['first_segment', 'segment'],
 'road_divider': ['first_segment', 'segment'],
 'road_usage': ['first_segment', 'segment'],
 'short_construction_warning': ['first_segment', 'segment'],
 'special_explication': ['first_segment', 'segment'],
 'speed_category': ['first_segment', 'segment'],
 'speed_limit': ['first_segment', 'segment'],
 'supplemental_geometry': ['first_segment', 'segment'],
 'through_route': ['first_segment', 'segment'],
 'toll_structure': ['first_segment', 'segment'],
 'traffic_message_channel_code': ['first_segment', 'segment'],
 'transport_protocol_expert_group': ['first_segment', 'segment'],
 'travel_direction': ['first_segment', 'segment'],
 'urban': ['first_segment', 'segment'],
 'usage_fee_required': ['first_segment', 'segment'],
 'environmental_zone_condition': ['first_segment', 'segment'],
 'junction_divider': ['first_segment', 'segment']}

types_to_df(navigation_attributes.object_types())

tiles = [19318110]
df = navigation_attributes.get(tiles, "speed_limit")
df.head(2)

df = navigation_attributes.get(tiles, "traffic_message_channel_code")
df.head(2)

df = navigation_attributes.get(tiles, "restricted_driving_manoeuvre")
df.head(2)

df = navigation_attributes.get(tiles, "travel_direction")
df.head(2)

df = navigation_attributes.get([18403672], "environmental_zone_condition")
df.head(2)

df = navigation_attributes.get_referencing(tiles, "restricted_driving_manoeuvre", "first_segment")
df.head(2)

3.12 Advanced Navigation Attributes

Layer Id - advanced-navigation-attributes

adv_navigation_attributes = hmc.advanced_navigation_attributes

types_to_df(adv_navigation_attributes.object_types())

adv_navigation_attributes.ref_types()

{'black_spot': ['first_segment', 'segment'],
 'grade_category': ['first_segment', 'segment'],
 'overtaking_restriction': ['first_segment', 'segment'],
 'protected_overtaking': ['first_segment', 'segment'],
 'railway_crossing': ['first_segment', 'segment'],
 'special_speed_situation': ['first_segment', 'segment'],
 'speed_limit': ['first_segment', 'segment'],
 'traffic_signal': ['first_segment', 'segment'],
 'traffic_sign': ['first_segment', 'segment'],
 'variable_speed_limit': ['first_segment', 'segment'],
 'variable_speed_sign': ['first_segment', 'segment'],
 'scenic': ['first_segment', 'segment'],
 'recreational_vehicle_restriction': ['first_segment', 'segment'],
 'vehicle_checkpoint': ['first_segment', 'segment']}

types_to_df(adv_navigation_attributes.object_types())

tiles = [19318110]
df = adv_navigation_attributes.get(tiles, "speed_limit")
df.head(2)

df = adv_navigation_attributes.get(tiles, "traffic_signal")
df.head(2)

df = adv_navigation_attributes.get(tiles, "traffic_sign")
df.head(2)

df = adv_navigation_attributes.get_referencing(tiles, "traffic_sign", "first_segment")
df.head(2)

df = adv_navigation_attributes.get(tiles, "railway_crossing")
df.head(2)

df = adv_navigation_attributes.get_referencing(tiles, "railway_crossing", "segment")
df.head(2)

3.13 Bicycle Attributes

Layer Id - bicycle-attributes

bicycle_attributes = hmc.bicycle_attributes
types_to_df(bicycle_attributes.object_types())

bicycle_attributes.ref_types()

{'bicycle_access_override': ['first_segment', 'segment'],
 'bicycle_protection_type': ['first_segment', 'segment'],
 'bicycle_travel_direction_override': ['first_segment', 'segment'],
 'dedicated_bicycle_path': ['first_segment', 'segment'],
 'bicycle_path': ['first_segment', 'segment'],
 'bicycle_access_verified': ['first_segment', 'segment']}

types_to_df(bicycle_attributes.object_types())

tiles = [19318110]
df = bicycle_attributes.get_referencing(tiles, "bicycle_path", "segment")
df.head(2)

df = bicycle_attributes.get_referencing(tiles, "dedicated_bicycle_path", "segment")
df.head(2)

3.14 Places Metadata

Layer Id - places-metadata

places_metadata = hmc.places_metadata
types_to_df(places_metadata.object_types())

places_metadata.get("all", "category_system")

df = places_metadata.get("all", "category")
df.head(2)

3.15 Building Metadata

Layer Id - building-metadata

building_metadata = hmc.building_metadata
types_to_df(building_metadata.object_types())

building_metadata.get("all", "category_system")

df = building_metadata.get("all", "category")
df.head(2)

3.16 Cartography Metadata

Layer Id - cartography-metadata

cartography_metadata = hmc.cartography_metadata
types_to_df(places_metadata.object_types())

cartography_metadata.get("all", "category_system")

df = cartography_metadata.get("all", "category")
df.head(2)

4. Multilayer Bindings

4.1 Administrative boundary for a segment

This binding associates segment with administrative boundary.

Layer Ids - administrative-places , administrative-locations

segment_admin_boundary = hmc.segment_admin_boundary
types_to_df(segment_admin_boundary.object_types())

df = segment_admin_boundary.get(17302684, "segment_admin_boundary")
df.head(2)

df = segment_admin_boundary.get(17302684, "segment_admin_boundary")
df.head(2)

### Construct a new Reference by giving partition and identifier.
segment_ref = make_ref("17302684", "here:cm:segment:499005300")

segment_admin_boundary_atts = segment_admin_boundary.get_referencing("17302684", "segment_admin_boundary", 
                                                       "segment", segment_ref)
segment_admin_boundary_atts.head(2)

### Construct a new Reference by giving partition and identifier.
place_ref = make_ref("23060936", "here:cm:namedplace:23060936")

place_admin_boundary_atts = segment_admin_boundary.get_referencing("17302684", "segment_admin_boundary", 
                                                       "place", place_ref)
place_admin_boundary_atts

4.2 Environmental zones for a segment

This binding associates segment with environmental zones.

Layer Id - environmental_zones, navigation-attributes

ezc = hmc.environmental_zone_conditions
display(ezc)

<here.content.hmc2.environmental_zone_conditions.EnvironmentalZoneConditions at 0x7f569d02fe50>

types_to_df(ezc.object_types())

data_ezc = ezc.get(partition = 23618402, object_type = 'segment_to_environmental_zone')
data_ezc.head(2)

data_ezc.iloc[0]['zone.location_ref']

[{'partition': '23618400', 'identifier': 'here:cm:carto-loc:1415962522'}]

### Construct a new Reference by giving partition and identifier.
ref = make_ref(23618402, "here:cm:segment:92642459")

data = ezc.get_referencing(partition = 23618402, 
                           object_type = 'segment_to_environmental_zone', 
                           ref_type='segment',
                          referenced_obj=ref)
data

### Construct a new Reference by giving partition and identifier.
ref = make_ref(23618400, "here:cm:carto-loc:1415962522")

data = ezc.get_referencing(partition = 23618402, 
                           object_type = 'segment_to_environmental_zone', 
                           ref_type='location',
                          referenced_obj=ref)
data.head(2)

data_ezc.iloc[0]

segment_ref.ref.partition                                                 23618402
segment_ref.ref.identifier                                here:cm:segment:76338653
segment_ref.inverted                                                         False
segment_ref.offset.start                                                       0.0
segment_ref.offset.end                                                    0.289408
forward                                                                       True
backward                                                                      True
applies_to.automobiles                                                        True
applies_to.buses                                                              True
applies_to.taxis                                                              True
applies_to.carpools                                                           True
applies_to.trucks                                                             True
applies_to.through_traffic                                                    True
applies_to.deliveries                                                         True
applies_to.pedestrians                                                       False
applies_to.emergency_vehicles                                                False
applies_to.motorcycles                                                       False
applies_to.bicycles                                                          False
zone.identifier                                                  here:cm:envzone:2
zone.name                        [{'text': {'value': 'Berlin Umweltzone', 'lang...
zone.info.description            [{'value': 'Die Umweltzone der Stadt Berlin is...
zone.info.website.value          https://www.berlin.de/senuvk/umwelt/luftqualit...
zone.info.website.language                                                        
zone.info.version_date                                                  2019-05-09
zone.info.extent_date                                                   2019-01-01
zone.info.country                                                          GERMANY
zone.vehicle_class               [{'vehicle_attributes': {'category': 'AUTO', '...
zone.environmental_badge         [{'badge_type': 'DEU_GREEN_STICKER', 'zone_acc...
zone.location_ref                [{'partition': '23618400', 'identifier': 'here...
Name: 23618402, dtype: object

4.3 Speed limit from navigation and advanced navigation attributes layers

This binding combines speedlimit from navigation and advanced navigation attributes layers. Advanced navigation attributes layers is premium content thus the access is restricted.

Layer Id - navigation-attributes, advanced-navigation-attributes

speed_limits = hmc.extended_speed_limit
speed_limits

<here.content.hmc2.extended_speed_limit.ExtendedSpeedLimit at 0x7f569d02fca0>

extended_speed_limit = speed_limits.get("17434043", "extended_speed_limit")
extended_speed_limit

### Construct a new Reference by giving partition and identifier.
segment_ref = make_ref("17434043", "here:cm:segment:216802488")

extended_speed_limit_attrs = speed_limits.get_referencing("17434043", "extended_speed_limit", "segment", segment_ref
    )
extended_speed_limit_attrs

4.4 Street name for a segment

This binding associates segment with administrative boundary.

Layer Id - navigation-attributes, Street Names

segment_street_names = hmc.segment_street_names

segment_street = segment_street_names.get(["20371958","17434043"], "street_section")
segment_street.head(2)

segment_street = segment_street_names.get(["20371958","17434043"], "address_range")
segment_street.head(2)

5. Download notebook

To run the notebook on your local machine, please refer to link below.

url = os.path.abspath("")
notebook_name = 'hmc.ipynb'
notebook = FileLink(f"{url}/{notebook_name}", result_html_prefix="Click here to download: ")
display(notebook)

Click here to download: /builds/sdk/pysdk-nagini/dev_guide/notebooks/hmc.ipynb