Tile layers - HERE Vector Tile API

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 map 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. A special case is "latin", which is used when the user has requested a language-variant using latin script, but no exact match was found. As a result, the country of Greece would use something like:

  kind : country
  name : Ελλάδα
  name:latin : Greece
  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.
translit:* - The localized transliteration of the default name (name).

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 changelog.

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:

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