Tile Layers

The data in the HERE Vector Tile API is organized in layers according to the definitions specified by the Tilezen open-source project started by Mapzen. The HERE Vector Tile API has some changes and simplifications on top of that layer definition, but all these changes are backwards compatible and comply with the specification. Specifically, all mandatory properties and all must-have values are still included. Some optional properties have been removed from the HERE Vector Tile API to better align the layer structure with the HERE Vector Tile API own data and processing logic.

The sections below include all the information necessary to understand the layer structure. The HERE Vector Tile API uses the same structure as the original layer definition to make it easier to find the changes, and follows the same SEMANTIC VERSIONING statement as originally formulated by Tilezen.

Need help displaying vector tiles in a map? Here are several examples using the HERE Vector Tile API to style in your favorite graphics library including HERE Maps API for JavaScript, Mapbox, and Tangram.

Overview

Data Sources and Attribution

The HERE Vector Tile API uses data from HERE. For more information, see Required Copyright Notice.

Source Property Usage in Tiles

The property source is generally omitted in all tiles. Assume that the value is here.com unless stated otherwise.

However, for some regions of the world within the core layer parameter (for example, Japan), this property is present, and the property value indicates the data source provider. In case of Japan, the value is ipc.

Definition of Terms

• common - These layers, properties, and kinds are generally available across all features in a response.
  • Establishes basic selection of features and their arrangement into specific named layers.
  • Core properties needed for display and labeling of features:
    • Special bits that make vector tile content interoperable, including kind, kind_detail, landuse_kind, min_zoom, and sort_rank.
    • Fundamental properties like name (including localized names) that are included in almost every feature.
• common-optional - These are meant to be part of a common set but may not be present because they aren't relevant or because we don't have the data (primarily feature properties, but could also be layers).
  • Used to refine feature selection.
  • Lightly transformed interoperable properties based on original data values.
  • Fundamental properties like population.
• optional - These are properties of a specific, less important kind, or generally present across kinds, but only in exceptional cases.
  • Often used to "decorate" features already selected for display.

Feature Names

Most features in a vector tile include a basic name property in the common list of properties, such as:

• name - Generally the name the locals call the feature, in the local language script.

This definition supports several additional name-related properties (optional):

• name:short - For example, CA for California.
• name:left - The name to be shown on the left side of the border.
• name:right - The name to be shown on the right side of the border.

There are some layers in which the name property is considered optional. For example, for features in the boundaries layer, instead of name, the properties name:left and name:right are used for oriented labeling on the appropriate side of the boundary line. This allows the labeled polygon's text to appear inside that polygon consistently. The example below illustrates the usage of the left and right properties. In this case, the country labels in the boundaries layer would include something like:

  kind : country
  name:left : Қазақстан
  name:right : Россия

This means that for that particular location, if you are using local languages to render your map, you should label the left side of the border with "Қазақстан" and the right side with "Россия".

Name Localization

HERE includes all language variants of the name:* values to enable full internationalization when available.

Language variants are identified by an ISO 639-1 two-letter language code and, optionally, ISO 15924 four-letter script code for example, en for English and zh-Hant for Traditional Chinese. As a result, the country of Greece would use something like:

  kind : country
  name : Ελλάδα
  name:en : Greece

Localized Name Properties (common-optional)

• name:* - The name to call the feature in a localized language indicated by its language code. For example, name:en : Germany.
• name:en - The name to call the feature in English. If no data is available basing on the language code, might be compiled from English/Latin transliteration of existing language representations.
• name:left:* - The localized name to be shown on the left side of the border.
• name:right:* - The localized name to be shown on the right side of the border.

Geometry Types

Individual vector tile layers can include mixed geometry types. This is common in the landuse, water, and buildings layers.

A tile geometry can be one of three types:

• point - point, multipoint
• line - linestring, multilinestring
• polygon - polygon, multipolygon

Data Updates

The vector tile content is updated regularly, sometimes multiple times per day.

Changelog

The current version of the HERE vector tile layer definition is v1.0.28.

Tiles are still in active development, but we try to minimize backwards incompatible breaking changes. Data model promises are listed in the SEMANTIC VERSIONING statement.

Read the full details in the changes section.

Feature Ordering

The ordering of features, which determines which features are rendered "on top of" other features, can be an important issue when rendering maps. To assist map rendering, there is a sort_rank property on some features that suggests in what order the features should appear. Lower numbers indicate that features should appear "towards the back" and higher numbers indicate "towards the front". These numbers are consistent across layers.

The layers that include sort_rank on their features are:

• boundaries
• buildings
• landuse
• roads
• transit
• water

Layer Reference

HERE includes ten (10) layers:

• boundaries
• buildings
• earth
• landuse
• places
• pois
• roads
• road_labels (optional)
• transit
• water

All of these layers are part of the tile in the response when you use the API to make a request within the base layer parameter. For more information on the available endpoints and parameters, see the Swagger spec.

Roads (Transportation)

The following figure illustrates an example of a road rendered from the data.

The layer content is defined as follows.

• Layer name: roads
• Geometry types: line, point

This layer contains information about all kinds of transportation including, but not limited to, highways, major roads, minor roads, paths, railways and ferries. Sort them with sort_rank to correctly represent layered overpasses, bridges, and tunnels.

The landuse_kind value is calculated by intercutting roads with the landuse layer to determine if a road segment is over a park, hospital, university or other landuse feature. Use this property to modify the visual appearance of roads over these features. For instance, light gray minor roads look great in general, but aren't legible over most landuse colors unless they are darkened.

To improve performance, some road segments are merged at low and mid zooms. To facilitate this, certain properties are dropped at those zooms. Examples include is_bridge and is_tunnel, name, network, oneway, and ref. The exact zoom varies by feature class.

Road Properties (common)

The following properties are used to define a road.

• name - Generally the name the locals call the feature, in the local language script.
• kind - Roads can be one of the options listed below.
• kind_detail - See the kind_detail values list below.
• landuse_kind - For more information, see the description above.
• sort_rank - This property contains a suggestion in which order to render features. The value is an integer where smaller numbers suggest that features should be "behind" features with larger numbers. At zoom 14 and higher, the sort rank is adjusted to realistically model bridge and tunnel. For example, sort_rank = 377 for is_bridge at zoom 13 becomes sort_rank = 427 at zoom 14.
• min_zoom - This property indicates a suggested minimum zoom at which this road should become visible.
• ref - A commonly used reference for this road - for example, "I 90" for Interstate 90. To use with shields, see the network and shield_text properties.
• network - This property is useful for shields and road selections - for example, US:I for the United States Interstate network. It contains only road network types. For more information, see a full list of possible road network values.
• shield_text - This property contains the text to display on a shield. For example, I 90 would have a network of US:I and a shield_text of 90. The ref value, I 90, is less useful for shield display without further processing. For some roads, this property can include non-numeric characters - for example, the M1 motorway in the UK has a shield_text value of M1 rather than just 1.
• all_shield_texts - All the shield texts of which this road is a part. This is given as semicolon-separated shield_text values. See shield_text above.
• all_networks - All the networks of which this road is a part. This is given as semicolon-separated network values. See network above.
• all_route_types - All the route types of which this road is a part. This is given as semicolon-separated numeric codes used for shield styling depending on the country.
• all_refs - All the references used for this road. This is given as semicolon-separated ref values. See ref above.
• hgv_restriction - This property indicates limitations to heavy goods vehicle truck access. See the hgv_restriction values list below. Always available only on points.

Road Properties (common-optional)

The following properties are used to define additional information about a road.

• is_bridge - true if the road is part of a bridge. This property is not present if the road is not part of a bridge.
• is_link - true if the road is part of a highway link or ramp. This property is not present if the road is not part of a highway link or ramp.
• is_tunnel - true if the road is part of a tunnel. This property is not present if the road is not part of a tunnel.
• is_present_in_landuse - true if the road has a detailed polygonal representation by the landuse kinds expressway, urban_expressway, national_road, major_road, and other_road, or formed as an area not covered by the landuse kind block for minor roads. This property is present only within the core layer parameter with limited coverage for Japan at zoom 14. It allows filtering of road centerlines while showing detailed road geometries from the landuse data. For more information, see Polygonal Roads.
• is_present_in_city - true if the rail is part of the city rail network. This property is present only within the core layer parameter with limited coverage for Japan at zoom 14 and higher. Rails with this property are used only for labeling while showing line geometries from the city rail network. Available only for the rail kind.
• public_access - true if the public has an official and legally protected right to access the element.
• private - true if the element is not open to the public, and access is only granted with individual permission.
• delivery_road - true if access to the element is only allowed when making deliveries to it.
• through_traffic - true if passage is allowed through the road only if both the origin and destination points are located outside the current road.

• hgv - This property indicates general truck heavy goods vehicle truck access. Available only on lines. Values include: no.

  Note

  If the hgv property has the value no, then the road has no hgv_restriction and hgv_restriction_shield_text properties. In other cases, the road can have the hgv_restriction and hgv_restriction_shield_text properties.

• hgv_restriction - This optional property indicates limitations to heavy goods vehicle truck access. Available on both points and lines. See the hgv_restriction values list below. See also hgv_restriction_shield_text.

• hgv_restriction_shield_text - This optional property is always paired with hgv_restriction and indicates the value of limitation to heavy goods vehicle truck access. Because the units are different per restriction, an abbreviation is provided next to the value, for example, 5.1m or 16'9" (US or GB), 4t or 4.4T (US). Such values are specified with one decimal precision, but the value of 5.0m is given as 5m. See the hgv_restriction_shield_text values list below.
• hgv_time_restrictions - This optional property specifies when heavy goods vehicle truck access is restricted. See the hgv_time_restrictions values list below.
• fclass - This property indicates a functional class numeric value for roads with kind_detail = motorway and kind_detail = motorway_link. For more information, see Road Transportation fclass Values.
• under_construction - true. This property indicates that the road is under construction and may not be usable by some or all types of traffic. The property is not present if the road is not under construction.
• surface - unpaved if the road is unpaved. This property is not present if the road is paved.
• oneway - An optional property that indicates if traffic is one-way and travels in the same direction as the linestring. This property can only have the following values: yes.
• toll - An optional boolean property that indicates if a fee must be paid by general traffic to travel the feature. This property can only have the following values: true.

Road Transportation kind Values

• aerialway - line
• ferry - line
• hgv_restriction - point, indicates limitations to heavy goods vehicle truck access
• highway - line
• major_road - line
• minor_road - line
• path - line
• rail - line
• piste - line

Road Transportation kind_detail Values

• ferry - for ferry kind
• motorway - for highway kind
• trunk - for highway kind
• primary - for major_road kind
• secondary - for major_road kind
• tertiary - for major_road kind
• residential - for minor_road kind
• service - for minor_road kind
• unclassified - for minor_road kind
• pedestrian - for path kind
• footway - for path kind
• rail - for rail kind
• chair_lift - for aerialway kind
• downhill - for piste kind

Road Transportation service Values for kind_detail = service

• parking_aisle - for minor_road kind service kind_detail

Road Transportation kind_detail Values for Certain Areas in core

The following list of kind_detail values is only applicable for some regions of the world within the core layer parameter. For more information about the layer parameters available in the HERE Vector Tile API, see Layer Parameter.

Below are these kind_detail values within the core layer parameter for Japan:

• light_rail - for rail kind
• subway - for rail kind
• speed_rail - for high-speed railroads with rail kind
• private_rail - for privately owned railroads with rail kind
• state_rail - for state-owned railroads with rail kind
• monorail - for monorails with rail kind
• cable_car - for aerialway kind
• gondola - for aerialway kind

Road Transportation hgv_restriction Values

For the hgv_restriction property indicates general restrictions to heavy goods vehicle truck access, the values include:

• weight - weight restriction
• height - height restriction
• length - length restriction
• width - width restriction
• wpa - weight per axle restriction
• axles - number of axles restriction with or without maximum weight per axle
• kpra - kingpin to rear axle length restriction
• hazmat - restriction for vehicles that carry hazardous materials
• trailers - trailers restriction
• other - other restriction
• multiple - if more than one restriction (represented by points along the line, where every point indicates specific restriction that applies to this road)

Road Transportation hgv_restriction_shield_text Values

For weight restriction:

• weight value, for example, 4t or 4.4T (US)

For height, length, width, and kpra restrictions:

• height, length, or width value, for example, 5.1m or 16'9" (US or GB)

For wpa restriction:

• weight value, for example, 1.8t or 2T (US)
• text value, where N is weight value:
  • Single axle N
  • Tandem axle N

For axles restriction:

• weight value, for example, 1.8t or 2T (US).
• text value, where N is weight value. Not added in case of zero value:
  • Two or more axles N
  • Three or more axles N
  • Four or more axles N
  • Five or more axles N
  • Six or more axles N

For hazmat restriction:

• Hazardous material type unknown
• Unspecified hazardous material type
• Explosives
• Gas
• Flammable
• Flammable solid combustible
• Organic
• Poison
• Radioactive
• Corrosive
• Other
• Any hazardous material
• Poisonous inhalation hazard
• Goods harmful for water
• Explosive and flammable
• Tunnel category b
• Tunnel category b1000c
• Tunnel category b d
• Tunnel category b e
• Tunnel category c
• Tunnel category c5000d
• Tunnel category c d
• Tunnel category c e
• Tunnel category d
• Tunnel category d e
• Tunnel category e

For trailers restriction:

• One or more
• Two or more
• Three or more
• Semi or tractor with trailers

For other and multiple restrictions, hgv_restriction_shield_text is omitted.

Road Transportation hgv_time_restrictions Values

Property specifies date and time period during which the condition applies. Value is a string in the Time Domain format. Time Domain is part of the GDF(Geographic Data Files) specification which is an ISO standard. Current standard is GDF 5.1 which is ISO 20524-1:2020.

A basic Time Domain is the combination of a Starting Date and a Time Duration with the following notation: [(Starting Date) {Time duration}]. For example, [(M5d1){d1}] means: • Starting Date: any year, month 5 (May), day 1st, at 0:00 a.m. • Duration: 1 complete day (i.e., 24 hours or 1440 minutes).

Starting Dates and time intervals are defined by means of a set of graphical symbols allowing the description of years, months, weeks, days, and so on down to the smallest time unit, which is the second. The symbols have to be organized in a sequential order starting with the longest time unit. Attached to a starting date, the interval constitutes a basic Time Domain. Without a starting date, it just indicates a duration. If the very first time type code in duration section is preceded by a minus sign, it means that the duration is counted in the reverse order. The following list describes starting date and time interval unit types:

• ynn - Year. Defines either a particular nnnn year in a starting date; or a duration of nn years. For example, [(y1991M11d14h5m30s19){y1}] means from 14 November 1991, 5:30:19 a.m. to 14 November 1992, 5:30:19 a.m. If there is no identical calendar date in the year in question, which occurs only for 29 February, “plus 1 year” leads to 28 February of the following year. Notice that {y1} = {M12}
• Mnn - Month. Defines either a particular month (1 to 12) within a particular year, or any year when no y information is given in starting date; or a duration of nn months. For example, [(y1991M11d14h5m30s19) {M3}] means from 14 November 1991, 5:31:19 a.m. to 14 February 1992, 5:30:19 a.m.
• wnn - Week. Defines either a week (1 to 53) within a previously defined year, or any year when no y information is given in a starting date; or a duration of nn weeks, i.e., nn*7 days. For example, [(y1991M11d14h5m30s19) {w2}] means from 14 November 1991 at 5:30:19 a.m. to 28 November 1991, 5:30:19 a.m. Notice that {w1} = {d7}
• dnn - Day. Defines either a particular day (1 to 28, 29, 30, 31) within a particular month if previously defined with the M format in a starting date; or a duration of nn days, i.e., nn*24 hours. For example, [(y1991M11d14h5m30s19) {d2}] means from 14 November 1991 at 5:30:19 a.m. to 16 November 1991, 5:30:19 a.m. Notice that {d1} = {h24}
• tn - Day. Only in starting date defines a particular weekday (1:Sunday, 2:Monday, 3:Tuesday, 4:Wednesday, 5:Thursday, 6:Friday, 7:Saturday) in a previously (if any) defined week. For example, (M5t2) means each Monday in the fifth month (May) of any year, at 0:00:00 a.m.
• fxn - Day. Only in starting date defines a particular weekday in a previously (if any) defined month, with the following rules: n is used as in the “t” format with the same domain of values, 1:Sunday up to 7:Saturday. For “x” one of the following values has to be substituted: 1:first, 2:second, 3:third, 4:fourth, 5:fifth. For example: (...f12) means the first Monday at 0:00:00 a.m.
• lxn - Day. Only in starting date defines a particular weekday in a previously (if any) defined month, with the following rules: n is used as for the “t” format with the same domain of values, 1:Sunday up to 7:Saturday. x has to be chosen from the following set: 1:first, 2:second, 3:third, 4:fourth, 5:fifth. Values are given in reverse order starting from the end of the month and have the meaning: 1=last, 2=last but one,3=last but two, etc. For example, (...l12) means the last Monday at 0:00:00 a.m.
• hnn - Hour. Defines either a particular hour (0 to 23) within a particular day (if previously defined) in a starting date; or a duration of nn hours, i.e., nn*60 minutes. For example, [(y1991M11d14h5m30s19) {h10}] means from 14 November 1991, 5:30:19 a.m. to 14 November 1991 at 3:30:19 p.m. Notice that {h1} = {m60}
• mnn - Minute. Defines either a particular minute (0 to 59) within a particular hour (if previously defined) in a starting date; or a duration of nn minutes, i.e., nn*60 seconds. For example, [(y1991M11d14h5m30s19) {m11}] means from 14 November 1991 at 5:30:19 a.m. to 14 November 1991 at 5:41:19 a.m. Notice that {m1} = {s60}
• snn - Second. Defines either a particular second (0 to 59) within a particular minute (if previously defined) in a starting date; or a duration of nn seconds. For example, [(y1991M11d14h5m30s19) {s21}] means from 14 November 1991 at 5:30:19 a.m. to 14 November 1991 at 5:30:40 a.m. Notice that {m1} = {s60}
• znn - Fuzzy symbols for special time terms. Currently only 2 variants are used: [(z1){z51}] means dawn til dusk (nighttime) and [(z2){z52}] means dusk til dawn (daytime). May be extended in future.
• string_value - Externally specified string value. For example [*EASTER(h8){h14}] means from 8:00 am to 10:00 pm during Easter

Starting Dates which are composed of several time units (e.g., 14 November 1991) are defined by placing the symbols sequentially in a hierarchical order.

Time periods (duration) which are composed of several time interval units are represented by listing the individual symbols sequentially in hierarchical order. The total time duration of a particular combination of symbols is the sum of all single time intervals. For example, {y2M1w2} means a period of 2 years, 1 month, and 2 weeks. Since Time Domains can be considered as a set of the smallest time unit described here, the second, Time Domains may also be combined with set operations, such as:

• Union of sets notation: +
• Intersection of sets notation: *
• Subtraction of sets notation: -

All the Time Domain strings are stored in prefix form: it uses the polish/prefix operator notation and omit brackets made redundant by this. For example:

[[(d1){w1}]-[(d3){d1}]] has prefix form -(d1){w1}(d3){d1} [[(d1){w1}]*[(d3){-w1}]] has prefix form *(d1){w1}(d3){-w1}

Road Transportation fclass Values

Roads in the HERE Vector Tile API are traditionally categorized into so-called functional classes, which do not match one-to-one Tilezen's roads categorization. The mapping from one to the other are as follows.

Road Transportation fclass Values for Certain Areas in core

The following list of fclass values is only applicable for some regions of the world within the core layer parameter. For more information about the layer parameters available in the HERE Vector Tile API, see Layer Parameter.

Below are these fclass values within the core layer parameter for Japan:

Road Labels (Optional)

This is an optional layer, and its content is defined as follows.

• Layer name: road_labels
• Geometry types: line

This layer contains deduplicated labeling properties (name, ref, network, shield_text) and simplified label placement geometry for all kinds of transportation, including but not limited to highways, major roads, minor roads, paths and ferries, which are present in the roads layer.

In the roads layer, each road segment contains labeling properties, which could be the same (and there are a lot of them) for consecutive road segments. To remove such duplicates and avoid post processing on the client side, the road_labels layer stores already merged and simplified consecutive road segments with the same name properties. However, you still can decide which layer (roads or road_labels) best suits your special needs as a source of labeling properties.

Road Label Properties (common)

• name - Generally the name the locals call the feature, in the local language script.
• ref - A commonly used reference for roads - for example, "I 90" for Interstate 90. To use with shields, see the network and shield_text properties.
• network - This property is useful for shields and road selections - for example, US:I for the United States Interstate network. It contains only road network types. For more information, see a full list of possible road network values.
• shield_text - This property contains the text to display on a shield. For example, I 90 would have a network of US:I and a shield_text of 90. The ref value, I 90, is less useful for shield display without further processing. For some roads, this property can include non-numeric characters - for example, the M1 motorway in the UK has a shield_text value of M1, rather than just 1.
• all_route_types - All the route types of which this road is a part. This is given as semicolon-separated numeric codes used for shield styling depending on the country.