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:
- Adapt or change the authentication method
- Update request parameters
- Update non-supported parameters
- 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/256/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/256/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/256/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/256/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=vehicle_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=vehicle_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/256/png8?apiKey={API_KEY} |
HERE Raster Tile API v3 |
https://maps.hereapi.com/v3/base/mc/11/1100/671/png8?features=vehicle_restrictions:active_and_inactive&style=explore.day&apiKey={API_KEY} |
HERE Raster Tile API v3 supports the same image formats as HERE Map Tile API v2. The value names are different.
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/256/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 default value |
512 | 512 |
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?size=512&apiKey={API_KEY} |
6. Language
In the HERE Raster Tile API v3, language is specified using lang
and lang2
parameters 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 | lang2 |
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
and lang2
are 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/256/png8?lg=HIN&lg2=ENG&apiKey={API_KEY} |
HERE Raster Tile API v3 |
https://maps.hereapi.com/v3/base/mc/11/1438/914/png8?lang=hi&lang2=en&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/256/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/256/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 all POIs, by setting 'all' or 'disable' respectively.
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&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:all,congestion_zones:all&apiKey={API_KEY} |
Non-supported parameters
HERE Raster Tile API v3 does not support metadata queries. Alternatives are:
Remove the metadata query parameters:
metadata
output
callback_func
filter
mgen
range