HERE Map Rendering: developer insights and best practices

As part of our community insights series, we take real questions from the HERE developer community and turn them into practical guidance. This month, we're putting the spotlight on HERE Map Rendering, exploring some of the common challenges developers encounter and how to solve them.

Maps may look simple on the surface, but rendering them in an application can be more complex than it first appears. Questions around authentication, performance, styling, traffic, labels, routes and customization are common. Whether working with raster tiles, static map images or interactive maps, developers often encounter many of the same challenges.

In this post, we’ve grouped common community questions into key themes, with solutions and practical takeaways to help developers troubleshoot them.

Authentication and request limits

Why am I getting a 401 or 403 error?

One common issue is an authentication or authorization error when requesting map tiles or images.

A valid API key doesn’t necessarily mean every HERE service is available to an application. Access can depend on the services enabled for your organization or project and the credentials being used.

What to check

• Make sure you’re using credentials created for the correct HERE Platform project or organization

• Check that the required map rendering service is enabled for your account

• Confirm that your credentials are being passed correctly

• Test the request using a simple example from the relevant API documentation

• Check HERE system status to see whether a service disruption could be affecting your requests

• If access is still denied, contact HERE support to check the service permissions

Why am I getting a 429 error and how can I avoid it?

A 429 Too Many Requests response means your application has exceeded a rate limit. The cause isn’t always the total number of requests. A sudden burst of traffic can exceed the configured limit even when average request volume seems reasonable.

How to troubleshoot and prevent 429 errors

• Check your configured rate limits. In HERE Platform, review your organization’s rate limits under Profile and Organization Details. For application-level limits, open Access Manager > select the relevant application and check the Rate Limits tab. More information here.

• Understand the limits. RPS (requests per second) and QPS (queries per second) limits vary depending on your account configuration, the services you use and your commercial entitlements.

• Control request patterns. Throttle bursts where appropriate and check for unnecessary or duplicate requests

• Plan for higher traffic. Review limits before performance testing or increasing production traffic. Contact HERE Technical Support or your HERE Account Manager if you need higher throughput.

• Investigate persistent errors. If 429 errors continue despite apparently staying within your limits, check the service-specific limits and contact HERE support.

Routes and static map images

How do I draw routes on a static map without exceeding the request size?

Static map images are useful for route previews, sharing and displaying a map without a full interactive experience. Routes with many geometry points can create URLs that are too long for a request to be processed.

The Map Image API supports route geometry through polylines, but long or complex routes may require more efficient encoding.

What you can do

• Use Flexible Polyline encoding. It can represent route geometry more efficiently. More information here.

• Simplify complex geometry. Remove unnecessary points while preserving the route’s overall shape. More information here.

• Review the full request. Multiple long polylines can increase request size, so consider the combined geometry rather than each route in isolation

Avoid over-simplifying the geometry, as this can change the route’s appearance or remove important details.

Traffic and map layers

How do I add traffic to a raster map?

The Raster Tile API provides the underlying map imagery, while traffic information can be added through the Traffic Raster Tile API.

Using raster tiles for your base map doesn't mean you have to use them for traffic overlays. You can mix raster and vector rendering technologies to suit your application's requirements and the services available to you.

For example, you can combine:

• Raster Tiles with Traffic Raster Tiles

• Vector Tiles with Traffic Vector Tiles

• Vector Tiles with Traffic Raster Tiles

• Raster Tiles with Traffic Vector Tiles

This flexibility lets you choose the base map and traffic rendering options independently, rather than treating them as a single rendering choice. Check the relevant API documentation for supported layer combinations and implementation details.

How do I add separate controls for traffic flow, traffic incidents and satellite imagery?

When building an interactive map with HERE Maps API for JavaScript v3.2[MV1] and WebGL rendering, you may want users to toggle traffic flow and traffic incidents independently or switch between a standard vector map and satellite imagery.

The default map UI may not provide every control your application needs.

What you can do

Create a custom HTML and JavaScript control panel alongside the default map UI. For example, you can add:

• A checkbox to show or hide traffic flow

• A separate checkbox to show or hide traffic incidents

• Options to switch between the standard vector map and satellite imagery

Your application can create the required traffic layers using the appropriate traffic vector tile services, then use the map’s layer-management methods to add or remove them. Base map selection can be managed separately. To get started with building a custom map control, see the Map with Custom Map Settings UI Control example. It shows how to build a custom map settings panel, though it doesn't specifically cover the implementation of traffic layers.

Synchronize the custom controls with the map’s current layer state so that the controls accurately reflect what’s visible. Check the implementation against the API version and rendering engine you’re using.

Map styling and visual quality

Can I customize the map style and why does my map look different from another HERE map style?

The Raster Tile API supports predefined styles through the optional style parameter. Examples include explore.day, logistics.day, satellite.day and topo.night, depending on availability.

Example request:

https://maps.hereapi.com/v3/base/mc/{z}/{x}/{y}/png?style=logistics.day&apiKey=YOUR_API_KEY

Replace {z}, {x} and {y} with the appropriate zoom level and tile coordinates, and use your own API key. Supported request parameters may also let you configure certain features, such as points of interest or vehicle restrictions. Refer to the Raster Tile API documentation for the available parameters and valid values.

Customizing vector map styles

If you need detailed control over individual map features or want to create a style that matches your application's visual design, use the Vector Tile API with the HERE Style Editor.

The HERE Style Editor is designed for vector maps, not raster tiles. It allows you to customize how map features are displayed rather than selecting only from predefined raster styles. See the HERE Style Editor introduction.

Why do HERE map styles look different?

Two HERE map styles may look different even when they're based on the same underlying map data. They can use different colors, feature visibility, label treatment and cartographic choices.

The important distinction is that map data and map appearance aren't the same thing. If you need to reproduce a particular visual design, consider whether predefined raster styles provide enough flexibility or whether vector styling is more appropriate.

Why do my raster tiles look blurry in my application?

Satellite imagery may appear blurry in an application even when the same location looks sharper in HERE WeGo or the HERE Style Editor.

One factor to investigate is tile resolution. Standard-resolution tiles may look less sharp on high-density displays than higher-resolution tiles.

What to check

• Tile size and scale: For supported Raster Tile API integrations, check whether settings such as size=512&scale=2 are available and appropriate.

• Request configuration: Compare your tile requests with the settings supported by the relevant service.

• Rendering configuration: Confirm that you’re requesting the intended imagery style and using the appropriate configuration.

• Target device: Compare the same location and zoom level on the device where the issue occurs.

If the imagery remains blurry, consult the documentation for your specific API or SDK and contact HERE support if needed.

Labels and map content

Why don’t all map labels appear in the language I selected?

Setting a language parameter such as lang=en doesn’t guarantee that every place name will be translated or transliterated into the requested language. Language availability can vary by region. For example, some place names in North Africa may not be available in English transliteration, while other names may appear in Latin script through an alternative language such as French.

This can be a limitation of the available language data rather than a rendering issue.

What you can do

• Try another supported language if the expected representation isn’t available

• Check whether the issue affects a few place names or a wider area, including major cities

• Report potential data gaps to HERE support so they can be assessed against the applicable map data specifications

Language parameters can influence how labels appear, but the result depends on the available location data.

Can I remove building numbers or other map labels?

Raster maps are delivered as rendered images, which limits your control over individual features after the image has been generated. If you want to remove a particular category of labels, there may not be a simple parameter that switches off that feature in the raster image.

If you need fine-grained control over how individual map features are rendered, Vector Tiles are the better foundation.

Can I render road reference numbers like those in OpenStreetMap?

The Vector Tile API exposes road attributes that can help you customize how road information is rendered, including the ref property. You can explore these properties in the HERE road properties documentation. The Interactive Basemap example also shows how to inspect map features and their properties.

To display road references in a style similar to OpenStreetMap, investigate the network and shield_text properties, which are relevant to rendering road shields and their text.

You can use these attributes when configuring your vector map style, including rules that control the zoom levels at which labels appear.

Choosing between static and interactive maps

When should I use a static map, and when do I need an interactive map?

The right rendering product depends on the experience you’re building. A static image works well for previews and sharing, while interactive maps offer more flexibility for user-driven experiences.

Consider the following examples:

For a more detailed comparison of map types available through HERE Maps API for JavaScript, see the Map Types documentation.

How can I use a custom image as a map marker?

The approach to using a custom image as a map marker depends on whether you're generating a static map image or building an interactive map.

Using markers with the Map Image API

The Map Image API supports specific parameters and formats for markers, but it isn't a general-purpose image composition service that can place any arbitrary image URL on a map. Check the supported marker and icon options in the Map Image API image properties documentation.

Using custom image markers with HERE Maps API for JavaScript

If you need to display your own image as a marker on an interactive map, HERE Maps API for JavaScript provides more flexibility. The SVG Graphic Markers example demonstrates how to create markers using custom graphics.

Can I create a heatmap in a static map?

Heatmaps show where a static image reaches its limits compared with an interactive map. The Map Image API doesn’t offer a direct equivalent to the heatmap visualizations available in interactive mapping solutions, and it doesn’t provide the same level of control.

For dynamic heatmap visualization, the HERE Maps API for JavaScript gives you a more flexible environment for creating and controlling the display.

Tile usage and pricing

How are Vector Tile and Raster Tile transactions calculated?

Tile consumption can increase even when the map appears unchanged. Understanding how requests work can help you estimate usage and identify unnecessary requests.

How tile transactions work

The number of requests depends on factors such as the number of tiles needed for the current viewport, zoom level, user interactions and caching behavior.

For example, a map displaying six tiles may require six requests when those tiles need to be fetched. If the application requests them again later, the additional requests may count as further transactions. Neither vector nor raster rendering inherently guarantees fewer transactions. Viewport size, zoom level, panning, caching and application behavior all affect request volume.

The role of caching

An unchanged viewport doesn’t necessarily mean the application stops making requests. Depending on the implementation, tiles may be requested again after cached content expires or when the application explicitly reloads them. Caching behavior differs by service, so consult the relevant documentation and response headers rather than assuming every tile has the same cache lifetime.

Best practices

• Review the number of tiles requested during a typical session

• Check whether the application unnecessarily requests tiles that are already cached

• Avoid reloading unchanged content unless required

• Account for viewport size, zoom level, interactions and session duration when estimating usage

• Consult current service documentation and pricing terms

Do optional Vector Tile layers incur additional charges?

The HERE Map Rendering documentation divides additional Content into two distinct categories: Optional layers and Advanced layers. These categories should not be confused with one another.

Optional layers: Additional map content available through optional layers, such as transit, hillshade and contours.

Advanced layers: Advanced content comprising Advanced Points of Interest and Advanced roads. Advanced Points of Interest provide additional POI content, while Advanced roads provide additional road attributes, including more detailed vehicle restriction information.

Optional layers are not automatically classified as Advanced layers. In the community discussion, HERE representatives clarified that Transit v2, hillshade and contours were considered optional content, not advanced content subject to the higher pricing tier described for Advanced layers.

Vector Tile layers and dedicated APIs

A layer used to visualize information on a map is different from an API used to access data or functionality.

For example, the Transit v2 layer in the Vector Tile API is intended for map visualization. The Public Transit API v8 serves different use cases involving transit data and functionality. Using the transit rendering layer doesn’t mean your application is using the Public Transit API v8.

For details, see the HERE Map Rendering documentation on advanced layers and the HERE pricing page.

Troubleshooting rendering errors

What should I do if I receive an invalid image or a 504 error?

Not every rendering problem is caused by the request itself. This can indicate a problem with the service processing the request, although the response and surrounding circumstances should be checked before drawing a conclusion.

A useful troubleshooting approach

• Test the same request again

• Visit status.here.com to see whether a service disruption has been reported

• Try a simpler request to determine whether the problem is related to the request parameters

• Check the response status and error details

• Determine whether the issue affects one request, one location or the service more broadly

• If the issue persists, contact HERE support with the request details and timestamp

Conclusion

Developer questions about map rendering rarely stop at displaying a map. They usually concern performance under load, how the map looks, which information appears on it, how routes are drawn and how much control developers have over the final result.

Access, request patterns, geometry size, rendering approach, customization and usage each shape the answer. A valid credential doesn’t guarantee service access. Bursts of traffic can trigger 429 errors even when average volume looks fine. Long routes can produce oversized static map requests. Raster and vector rendering suit different levels of control. Tile requests, caching and pricing terms all affect cost.

Community insights exists to turn individual support questions into shared patterns, so developers can solve similar problems faster. If you have a question that other developers might also face, share it with the HERE developer community.