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.

📘

Note

Accessing HERE Raster Tile API v3 requires a HERE platform account. Previously used HERE developer accounts do not work for HERE Raster Tile API v3.

Changes overview

You must take the following actions to complete the migration:

1. Ensure that you are using API keys or OAuth tokens corresponding to your HERE platform account.
2. Adapt or change the authentication method.
3. Update request parameters.
4. Update non-supported parameters.
5. 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 documentation.

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

Style and scheme migration

Example

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

Query the /info resource to check the available HERE Raster Tile API v3 styles to specify the query accordingly, for example:

https://maps.hereapi.com/v3/info?apiKey={YOUR_API_KEY}

2. 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, blank and label.

Resource name migration

https://maps.hereapi.com/v3/info?apiKey={YOUR_API_KEY}

Example

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

Example

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

Example

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

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

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

6. Pixels per inch (PPI)

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

PPI value migration

Example

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

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

9. Congestion uones 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

10. Copyright

In the HERE Raster Tile API v3, copyright information is provided through a dedicated /copyright endpoint. This endpoint returns structured JSON data containing copyright providers, their applicable bounding boxes, zoom level ranges, and associated map styles.

❗️

You must display copyright notices in a reasonably conspicuous manner on every visualized map.

For more information about the copyright information display format, client-side constraints, and other details, see Required copyright notice.

Non-supported parameters

1. Map version

HERE Raster Tile API v3 supports only the latest map version.

2. Metadata queries

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

• HERE Vector Tile API, or
• Client side rendering with HERE Maps API for Javascript.

Remove the metadata query parameters:

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