Introducing the new Map Image API v3

Greetings! We are so excited to share the release of HERE Map Image API v3, a replacement service for the HERE Map Image API v1. If you are migrating from v1, please refer to this migration guide. 

What is HERE Map Image API v3?

The HERE Map Image API is a RESTful service that empowers the creation of high-quality, customizable static map images for global regions. Unlike Raster or Vector Map Tiles, Map Image sidesteps the need for complex JavaScript or interactive map components, making it ideal for scenarios where a simple image suffices. The flexibility to tailor map appearances to align with branding, coupled with support for extra layers through GeoJSON and compact encoding.

HERE Map Image API v3 belongs under the HERE Map Rendering services, together with Raster Tile API v3 and Vector Tile API. 

Why Choose the Map Image API?

Real World Example: Yahoo!

In a real-world scenario, imagine a user searching for points of interest (POI) on Yahoo! For instance, "deep dish pizza near Chicago." Yahoo! first calls upon HERE Geocoding & Search to get the list of deep-dish pizza locations in Chicago, which then returns a static map image of Chicago with personalized place markers produced from HERE Map Image API. 

Note: Yahoo! is currently using the older version of the Map Image API.

The following map styles are available in the HERE Map Image API:

Changing the map style can be done by setting the style parameter in the request, like below:

        https://maps.hereapi.com/mia/v3/base/mc/center:59.441739,24.754616;zoom=14/480x370/png8
?apikey={YOUR_API_KEY}
&style=lite.day
  

Adding More Features to the Map

HERE Map Image API allows you to create maps that visualize features related to traffic congestion, vehicle access, environmental regulations, and points of interest (POIs).

Enabling map features can be done by setting the features parameter in the request, like below:

        https://maps.hereapi.com/mia/v3/base/mc/center:52.366547,4.911802;zoom=18/335x480/png8
?apikey={YOUR_API_KEY}
&features=vehicle_restrictions:active_and_inactive,pois:disabled
  

Custom Overlays using GeoJSON 

Enhance your data's visual representation and add contextual depth to your maps by incorporating custom overlays through GeoJSON. This flexible format supports various geometry types, including Point, Line, and Polygon, providing a versatile toolkit for highlighting regions, plotting routes, and displaying spatial relationships. 

The following GeoJSON provides information about two points in the map:

        {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "marker":"cp", 
        "size": "large"
      },
      "geometry": {
        "coordinates": [-77.050046,38.892132], // Starting point
        "type":"Point"
      }
    },
    {
      "type": "Feature",
      "properties": {
        "color":"#EA4335",
        "outline-color":"#A60D0D",
        "outline-width":"1px",
        "size":"large"
      },
      "geometry": {
        "coordinates": [-77.029591,38.905713], // Destination point
        "type":"Point"
      }
    }
  ]
}
  

For instance, consider the following request, which seamlessly integrates the MultiLineString feature to represent a route connecting start and destination points while threading through designated stopover markers:

        https://image.maps.hereapi.com/mia/v3/base/mc/overlay:padding=64/600x300/png8
?apikey={YOUR_API_KEY}
&scaleBar=mi
&style=lite.day
&features=pois:disabled
&geojson={<<..above geojson..>>]}
  

This request yields a map image showing two points from the above request:

Custom Overlay using Compact Encoding

Alternatively, the Compact Encoding format offers a more streamlined version of GeoJSON, maintaining support for the same geometry types and style properties to produce equivalent outputs. Featuring specific representations for point, line, and polygon geometries, this encoding ensures a seamless mapping experience.

To create a line representing a canal's length in Venezia. The line is drawn with a custom color (#E82D89) and the width of 30 meters, use the overlay=line or overlay=multiLine parameter format, for example:

        overlay=line:BFktr1IgrlrC5DsJ7IqKzH6FmDuIoJ0JyC8D-GwVGqQtFsSjN-X5F0CzDxCzHrP5J_gBnFzF7I-CtHoI7CkTuC-gB;color=#E82D89;width=30m
  

The request containing the above overlay using compact encoding:

        https://maps.hereapi.com/mia/v3/base/mc/overlay:zoom=10;padding=64/500x300/png8
?apikey={YOUR_API_KEY}
&features=pois:disabled
&overlay=<<..above overlay..>>
&overlay=point:45.439341,12.335684;size=large;label=The Grand Canal;text-color=%23D61A6E;
  

The response image showcases the customized line and point overlays as defined in the request.

Closing Thought

Resources

• HERE Map Image API - Migration Guide
• HERE Map Image API - Styles
• HERE Map Image API - Map Features
• HERE Map Image API - GeoJSON Overlay
• HERE Map Image API - Compact overlay encoding