Migrate from HERE Map Tile API v2 to HERE Raster Tile API v3

The HERE Raster Tile API v3 is a REST API that allows you to request map tile images for all regions in the world. These map tiles, when combined in a grid, form a complete map of the world.

This is the replacement service for the HERE Map Tile API v2 service.

Changes overview

The following general actions must be taken to complete the migration:

  1. Adapt or change the authentication method
  2. Update request parameters
  3. Update non-supported parameters
  4. Remove metadata specific query parameters

Authentication method

HERE Raster Tile API v3 supports the API key and OAuth token authentication methods. For more information, refer to the Authentication section of HERE Raster Tile API v3 Reference Document.

Update request parameters

The HERE Raster Tile API v3 definition is different than that of the HERE Map Tile API v2. Please refer to the HERE Raster Tile API v3 Reference Document for a detailed documentation.

In order to migrate from the HERE Map Tile API v2 to the HERE Raster Tile API v3, please take a look at the updated request parameters below:

1. Map version

In the HERE Raster Tile API v3, the map version is specified as an optional parameter mv in comparison to the mandatory parameter map id of HERE Map Tile API v2.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/540f1ab0fd/normal.day/11/1100/671/512/png8?apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?mv=in306jp113&apiKey={API_KEY}

The example URLs above contain a map version which may no longer be available.

Query the /info resource to check the available map version for HERE Raster Tile API v3.

If the mv parameter is not specified in a HERE Raster Tile API v3 query, the latest map is used always to render the tile. The same behavior is achieved in the HERE Map Tile API v2 by setting map id to newest.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/11/1100/671/512/png8?apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?apiKey={API_KEY}

2. Content and appearance (domain / scheme / style)

In the HERE Map Tile API v2, content and appearance of the rendered map tile is defined using the service domain, scheme resource and style parameter. To achieve the same in HERE Raster Tile API v3, the style parameter is used.

In the HERE Raster Tile API v3, style is an optional parameter having as default value explore.day.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.night/11/1100/671/512/png8?style=default&apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?style=explore.night&apiKey={API_KEY}

To view satellite tile images in the HERE Map Tile API v2 the aerial domain is used. In the HERE Raster Tile API v3, specifying style=satellite.day parameter renders a satellite tile image.

Example
HERE Map Tile API v2
https://1.aerial.maps.ls.hereapi.com/maptile/2.1/maptile/newest/satellite.day/11/1100/671/512/png8?apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?style=satellite.day&apiKey={API_KEY}

Query the /info resource to check available HERE Raster Tile API v3 styles and specify the query accordingly.

3. Resource

In the HERE Map Tile API v2 tile content is defined using resource.

HERE Raster Tile API v3 supports only the following 'resource' values: base, background and label.

Resource name migration
Description HERE Map Tile API v2 HERE Raster Tile API v3
Administrative Labels alabeltile not supported
Base Map Tile basetile background
Base Line Map Tile blinetile not supported
Label Tile labeltile label
Line Tile linetile not supported
Lines and Labels Tile lltile not supported
Map Tile maptile base
Street Tile streettile not supported
Truck Tile trucktile base with parameter features=truck_restrictions:active_and_inactive
Truck Only Tile truckonlytile not supported
Extra Base Map Tile xbasetile not supported
Truck No Public Transport Tile trucknopttile base with parameter features=truck_restrictions:active_and_inactive
Map No Public Transport Tile mapnopttile base

Query the /info resource to check available HERE Raster Tile API v3 resources.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/trucktile/newest/normal.day/11/1100/671/512/png8?apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?features=truck_restrictions:active_and_inactive&style=explore.day&apiKey={API_KEY}

4. Image format

HERE Raster Tile API v3 supports the same image formats as HERE Map Tile API v2. The value names are different.

Image format value migration
HERE Map Tile API v2 HERE Raster Tile API v3
png png
png8 png8
jpg jpeg
Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/11/1100/671/512/jpg?apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/jpeg?apiKey={API_KEY}

5. Size

In the HERE Raster Tile API v3, the map tile image size is specified as an optional parameter size as opposed to the mandatory parameter size of HERE Map Tile API v2.

Image size value migration
HERE Map Tile API v2 HERE Raster Tile API v3
128 not supported, use 256 or 512 instead
256 256
512 512 default value
Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/11/1100/671/128/png8?apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?size=256&apiKey={API_KEY}

6. Language

In the HERE Raster Tile API v3, language is specified as lang parameter in comparison to lg and lg2 parameters of HERE Map Tile API v2.

Language parameter name migration
Description HERE Map Tile API v2 HERE Raster Tile API v3
First language lg lang
Second language - dual labeling lg2 not supported, support planned
Language parameter value migration

In the HERE Map Tile API v2 the value of the lg and lg2 parameters is in the MARC three-letter language code.

In the HERE Raster Tile API v3, lang is BCP47 language code limited to ISO 639-1 two-letter language code and, optionally, ISO 15924 four-letter script code.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/11/1438/914/512/png8?lg=HIN&apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1438/914/png8?lang=hi&&apiKey={API_KEY}

Query the /languages resource of HERE Raster Tile API v3 to check available languages and update the HERE Map Tile API v2 query accordingly.

7. Pixels per inch (PPI)

HERE Raster Tile API v3 supports different ppi values than HERE Map Tile API v2.

PPI value migration
HERE Map Tile API v2 HERE Raster Tile API v3
72 100
250 400
320 400
500 400
Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/11/1100/671/512/png8?&ppi=500&apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?ppi=400&apiKey={API_KEY}

8. Geopolitical views

Query the /meta/pviews resource to check geopolitical views supported in HERE Map Tile API v2.

Query the /politicalViews resource to check geopolitical views supported in HERE Raster Tile API v3. Update HERE Map Tile API v2 query if a non-supported geopolitical view is used.

Geopolitical view parameter value migration

In the HERE Map Tile API v2, the pview parameter is using the ISO 3166-1 alpha-3 country code.

In the HERE Raster Tile API v3, the pview parameter is using the ISO 3166-1 alpha-2 country code.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/11/1100/671/512/png8?&pview=ARG&apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?pview=AR&apiKey={API_KEY}

9. POIs

In the HERE Map Tile API v2, POIs are handled using the pois parameter. The pois specifies mask of POI categories.

In the HERE Raster Tile API v3, POIs can be handled using the pois feature. The feature can only enable or disable POIs.

Query the /features resource to check available features corresponding to HERE Raster Tile API v3 styles.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/17/70399/42969/256/png8?pois=0&apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/17/70399/42969/png8?features=pois:disabled&size=256&apiKey={API_KEY}

10. Congestion Zones and Environmental Zones

In the HERE Map Tile API v2, congestion and environmental zone display is handled with the congestion parameter.

In the HERE Raster Tile API v3, congestion zones and environmental zones are handled independently with the congestion_zones and environmental_zones features.

Example
HERE Map Tile API v2
https://1.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/9/272/177/256/png8?congestion&apiKey={API_KEY}
HERE Raster Tile API v3
https://maps.hereapi.com/v3/base/mc/9/272/177/png8?features=environmental_zones:enabled,congestion_zones:enabled&size=256&apiKey={API_KEY}

Non-supported parameters

1. Metadata queries

HERE Raster Tile API v3 does not support metadata queries. Alternatives are:

Remove the metadata query parameters:

  • metadata
  • output
  • callback_func
  • filter
  • mgen
  • range

results matching ""

    No results matching ""