Map items

The HERE SDK for Android allows you to add several types of items to the map, such as map polylines, polygons, circles, markers and map overlays. They are explained in detail in the sections below.

• Map polylines: Non-moveable rendered lines.
• Map polygons: Non-moveable rendered filled shapes.
• Map circles: Non-moveable rendered filled circles.
• Map markers: Images that can be pinned to 'mark' specific spots on the map.
• Map overlays: A convenient way to show native Android View layouts on the map.

Polylines, polygons and circles, will adjust their size based on the current zoom level, while markers and overlays remain unchanged when zooming.

All map items provide a convenient way to pick them from the map. For polylines, polygons, circles and markers, this can be done using the dedicated PickMapItemsCallback, while a MapOverlay allows native click handling - as for any standard Android View.

Add map polylines

Polylines can be useful to render, for example, a route geometry on the map. They can be created as shown below:

private MapPolyline createPolyline() {
    ArrayList<GeoCoordinates> coordinates = new ArrayList<>();
    coordinates.add(new GeoCoordinates(52.53032, 13.37409));
    coordinates.add(new GeoCoordinates(52.5309, 13.3946));
    coordinates.add(new GeoCoordinates(52.53894, 13.39194));
    coordinates.add(new GeoCoordinates(52.54014, 13.37958));

    GeoPolyline geoPolyline;
    try {
        geoPolyline = new GeoPolyline(coordinates);
    } catch (InstantiationErrorException e) {
        // Less than two vertices.
        return null;
    }

    MapPolylineStyle mapPolylineStyle = new MapPolylineStyle();
    mapPolylineStyle.setWidthInPixels(20);
    mapPolylineStyle.setColor(0xFF0000A0, PixelFormat.RGBA_8888);
    MapPolyline mapPolyline = new MapPolyline(geoPolyline, mapPolylineStyle);

    return mapPolyline;
}

A MapPolyline consists of three elements:

• A list of two or more geographic coordinates that define where to place the polyline on the map.
• A GeoPolyline that contains this list of coordinates.
• A MapPolylineStyle to define how to visualize the polyline. Make sure to set at least a color, otherwise the MapPolyline will remain invisible.

Since a geometric line is defined by two or more points, you need to create an ArrayList, which must contain at least two GeoCoordinates. Otherwise, an exception will be thrown. By using the MapPolylineStyle class, attributes such as draw order, thickness in pixels and color of the line can be defined. See for an example the screenshot.

Setting a draw order can be useful to define what map item should be rendered topmost. Higher values will be drawn on top of lower values. Note that map markers will be always drawn on top of anything else that is rendered on the map, while map polylines are always drawn below extruded buildings, labels and other map polygons and map circles. The most common use case for map polylines is to render a route on the map, while map markers are expected to indicate a location, so they should not be hidden.

• The draw order for map polylines is effective only in relation to other map polylines.
• The draw order for map polygons and map circles is only effective in relation to other map polygons and map circles.

After you have created one or more map polylines, you can add them to a map scene with:

MapPolyline mapPolyline = createPolyline();
MapScene mapScene = mapView.getMapScene();
mapScene.addMapPolyline(mapPolyline);

If a map polyline is already attached to a map scene, any further attempt to add it again will be ignored.

Note that a map view allows only one scene and all map items are placed directly on it. If you want to group your map items, you may want to organize them by using an array and add or remove them individually.

You can remove a mapPolyline from the map immediately by calling:

mapScene.removeMapPolyline(mapPolyline);

Note: MapPolyline items are pickable and it is possible to store the Metadata that can be retrieved when picking the item. For an example, see the section below on map markers.

Update polyline style

As you have seen above, line color and other properties such as the line width can be specified using a MapPolylineStyle instance. It is possible to dynamically change already applied properties. For that, you do not need to create a new MapPolylineStyle instance.

Instead, you can reuse the current style after a map polyline has been added to a map scene, modify some of its properties, and call the updateStyle() method on the map polyline instance - you just have to pass the updated style instance as a parameter. The appearance on the map will change instantly. For example, you can create animated map polylines in this way.

Add map polygons

A MapPolygon is a shape that consists of at least three coordinates, otherwise it cannot be rendered. Similar to MapPolyline, the coordinates are connected. Polygons can be useful to highlight an area on the map.

Note: The order of the coordinates do matter.

See the example below on how a polygon can be created. The coordinates are connected based on their order in the list. The resulting shape can be filled with a color using a new MapPolygonStyle instance:

private MapPolygon createPolygon() {
    ArrayList<GeoCoordinates> coordinates = new ArrayList<>();
    coordinates.add(new GeoCoordinates(52.53032, 13.37409));
    coordinates.add(new GeoCoordinates(52.5309, 13.3946));
    coordinates.add(new GeoCoordinates(52.53894, 13.39194));
    coordinates.add(new GeoCoordinates(52.54014, 13.37958));

    GeoPolygon geoPolygon;
    try {
        geoPolygon = new GeoPolygon(coordinates);
    } catch (InstantiationErrorException e) {
        // Less than three vertices.
        return null;
    }

    MapPolygonStyle mapPolygonStyle = new MapPolygonStyle();
    mapPolygonStyle.setFillColor(0x00908AA0, PixelFormat.RGBA_8888);
    MapPolygon mapPolygon = new MapPolygon(geoPolygon, mapPolygonStyle);

    return mapPolygon;
}

A MapPolygon consists of three elements:

• A list of three or more geographic coordinates that define where to place the polygon on the map.
• A GeoPolygon that contains this list of coordinates.
• A MapPolygonStyle to define how to visualize the polygon. Make sure to set at least a color, or else the MapPolygon will remain invisible.

Since a polygon is defined by three or more points, you need to create an array list, which must contain at least three GeoCoordinates. Otherwise, an exception will be thrown. By using the MapPolygonStyle class, attributes such as draw order or color can be defined. This can be a fill color, like shown above, or a stroke color (and optionally a stroke width) to specify the outline - or both: This way you can create filled and unfilled map polygons. See for an example the screenshot.

Setting a draw order can be useful to define what map item should be rendered topmost. Higher values will be drawn on top of lower values. Note that map markers will be always drawn on top of anything else that is rendered on the map, while map polylines are always drawn below extruded buildings, labels and other map polygons and map circles. The most common use case for map polylines is to render a route on the map, while map markers are expected to indicate a location, so they should not be hidden.

• The draw order for map polylines is effective only in relation to other map polylines.
• The draw order for map polygons and map circles is only effective in relation to other map polygons and map circles.

Map polygons can be used to create complex filled or unfilled shapes. However, a self-intersecting polygon can lead to undesired results as the coordinates are connected in the order of the list. As an alternative you can add multiple polygons - or make sure to add the coordinates as they appear on the outline of the desired shape.

Please note that, unlike a map polyline, the outline of a map polygon is connected automatically between the last coordinate and the first coordinate of the list.

After you have created one or more map polygons, you can add them to a map scene with:

MapPolygon mapPolygon = createPolygon();
MapScene mapScene = mapView.getMapScene();
mapScene.addMapPolygon(mapPolygon);

If a map polygon is already attached to a map scene, any further attempt to add it again will be ignored.

Note that a map view allows only one scene and all map items are placed directly on it. If you want to group your map items, you may want to organize them by using an array and add or remove them individually.

A mapPolygon can be removed immediately from the map by calling:

mapScene.removeMapPolygon(mapPolygon);

Note: MapPolygon items are pickable and it is possible to store Metadata that can be retrieved when picking the item. For an example, see the section below on map markers.

Update polygon style

As you have seen above, fill color and other properties such as the outline stroke width can be specified using a MapPolygonStyle instance. It is possible to dynamically change already applied properties. For that, you do not need to create a new MapPolygonStyle instance.

Instead, you can reuse the current style after a map polygon has been added to a map scene, modify some of its properties, and call the updateStyle() method on the map polygon instance - you just have to pass the updated style instance as a parameter. The appearance on the map will change instantly. For example, you can create animated map polygons in this way.

Add map circles

A MapCircle is a circular shape that can be useful to highlight areas on the map - or to mark a distinct spot on the map.

private MapCircle createMapCircle() {
    float radiusInMeters = 300;
    GeoCircle geoCircle = new GeoCircle(new GeoCoordinates(52.530932, 13.384915), radiusInMeters);
    MapCircleStyle mapCircleStyle = new MapCircleStyle();
    mapCircleStyle.setFillColor(0x00908AA0, PixelFormat.RGBA_8888);
    MapCircle mapCircle = new MapCircle(geoCircle, mapCircleStyle);

    return mapCircle;
}

A MapCircle consists of three elements:

• A set of geographic coordinates that defines where to place the circle's center on the map.
• A GeoCircle that contains these coordinates and the radius of the circle in meters.
• A MapCircleStyle to define how to visualize the circle. Make sure to set at least a color, or else the MapCircle will remain invisible.

By using the MapCircleStyle class, attributes such as draw order and color can be defined. This can be a fill color, like shown above, or a stroke color (and optionally a stroke width) to specify the outline - or both: This way you can create filled and unfilled map circles. See the screenshot for an example.

Setting a draw order can be useful to define what map item should be rendered topmost. Higher values will be drawn on top of lower values. Note that map markers will be always drawn on top of anything else that is rendered on the map, while map polylines are always drawn below extruded buildings, labels and other map polygons and map circles. The most common use case for map polylines is to render a route on the map, while map markers are expected to indicate a location, so they should not be hidden.

• The draw order for map polylines is effective only in relation to other map polylines.
• The draw order for map polygons and map circles is only effective in relation to other map polygons and map circles.

After you have created one or more map circles, you can add them to a map scene with:

MapCircle mapCircle = createMapCircle();
MapScene mapScene = mapView.getMapScene();
mapScene.addMapCircle(mapCircle);

If a map circle is already attached to a map scene, any further attempt to add it again will be ignored.

Note that a map view allows only one scene and all map items are placed directly on it. If you want to group your map items, you may want to organize them by using an array and add or remove them individually.

A mapCircle can be removed immediately from the map by calling:

mapScene.removeMapCircle(mapCircle);

Note: MapCircle items are pickable and it is possible to store the Metadata that can be retrieved when picking the item. For an example, see the section below on map markers.

Update circle style

As you have seen above, fill color and other properties such as the outline stroke width can be specified using a MapCircleStyle instance. It is possible to dynamically change already applied properties. For that you do not need to create a new MapCircleStyle instance.

Instead, you can reuse the current style after a map circle has been added to a map scene, modify some of its properties, and call the updateStyle() method on the map circle instance - you just have to pass the updated style instance as a parameter. The appearance on the map will change instantly. For example, you can create animated map circles in this way.

Add map markers

You can use map markers to precisely point to a location on the map. Map markers will be always drawn on top of anything else that is rendered on the map.

The following method will add a custom map marker to the map:

MapImage mapImage = MapImageFactory.fromResource(context.getResources(), R.drawable.here_car);

MapMarker mapMarker = new MapMarker(geoCoordinates);
mapMarker.addImage(mapImage, new MapMarkerImageStyle());

mapView.getMapScene().addMapMarker(mapMarker);

In this example, we load a PNG ("here_car.png") from the resources and create a MapImage out of it. This MapImage can then be added to a MapMarker instance.

To see the image, we must add the MapMarker to a map scene. Please note that the MapImage will be displayed centered on the provided geoCoordinates.

You can also update the geoCoordinates after the marker is added to the map: It will instantly appear at the new location after mapMarker.setCoordinates() is called.

By default, any new MapMarker instance is invisible, unless we add one or more map images. A MapMarker can be composed out of multiple map images - and each map image may use a different anchor point.

Update image style

Anchor points and other image properties such as scale and rotation angle can be specified using a MapMarkerImageStyle instance. It is possible to dynamically change already applied properties. For that you do not need to create a new MapMarkerImageStyle instance.

Instead, you can reuse the current style after a map marker has been added to a map scene, modify some of its properties, and call the updateImageStyle() method on the map marker instance - you just have to pass the updated style instance as a parameter. The appearance on the map will change instantly. For example, you can create animated map markers in this way.

You can read more about anchor points in the following section below.

Anchored POI markers

By default, each image is centered on the location provided, and you may want to change this for some types of markers. An example is the POI marker, which usually points to the location with its bottom-middle position.

Therefore, the location of where the image is rendered must be shifted. The default center lies at (0.5, 0.5). If the bottom-right corner of the view should point to the set GeoCoordinates location, then the anchor point must be set to (1, 1).

Anchor points provide a convenient way to specify the location where a marker should be rendered: The top-left corner equals an anchor point of (0, 0) while the bottom-right corner equals an anchor point of (1, 1). Independent of how large the view is, the point that is half the width or height will always be 0.5 - this is similar to the concept of normalized texture UV-coordinates.

If you want to shift the POI to point to the location, you can keep the default middle location (0.5), but you must shift the image upwards by 1. 1 is just as long as the height of the image. Note that you can also specify values greater than 1 or less than 0, so that you can shift the image to any possible location. 2 would represent twice the height of the image and so on.

To add an anchored POI marker to the map, see the example below:

MapImage mapImage = MapImageFactory.fromResource(context.getResources(), R.drawable.poi);
MapMarker mapMarker = new MapMarker(geoCoordinates);

MapMarkerImageStyle mapMarkerImageStyle = new MapMarkerImageStyle();
mapMarkerImageStyle.setAnchorPoint(new Anchor2D(0.5F, 1));

mapMarker.addImage(mapImage, mapMarkerImageStyle);
mapView.getMapScene().addMapMarker(mapMarker);

You can add multiple map images to a single map marker. When you move the location of a map marker by calling mapMarker.setCoordinates(), all of its added images will move along with it, keeping their relative positions.

Note: For the example, a custom POI image called "poi.png" is added in different resolutions to the project. The Android platform will choose the appropriate image resolution based on the device's display density. See the accompanying example app on how this can be done.

You can also change the size of a MapImage programmatically by setting a scale factor in MapMarkerImageStyle. Values below 1 will shrink width/height proportionally, while values greater than 1 will increase the size of the image. The default scale factor is 1, leaving the image unscaled.

Unlike map circles or polylines, each MapImage will keep its size - regardless of how much the map is zoomed out or in.

Pick map markers

After you have added the map markers onto the map, you can use a tap gesture listener to find out if a user tapped on a map marker:

private void setTapGestureHandler() {
    mapView.getGestures().setTapListener(new TapListener() {
        @Override
        public void onTap(Point2D touchPoint) {
            pickMapMarker(touchPoint);
        }
    });
}

private void pickMapMarker(final Point2D touchPoint) {
    float radiusInPixel = 2;
    mapView.pickMapItems(touchPoint, radiusInPixel, new PickMapItemsCallback() {
        @Override
        public void onMapItemsPicked(@Nullable PickMapItemsResult pickMapItemsResult) {
            if (pickMapItemsResult == null) {
                return;
            }

            MapMarker topmostMapMarker = pickMapItemsResult.getTopmostMarker();
            if (topmostMapMarker == null) {
                return;
            }

            showDialog("Map marker picked:", "Location: " +
                topmostMapMarker.getCoordinates().latitude + ", " +
                topmostMapMarker.getCoordinates().longitude);
        }
    });
}

As soon as the tap gesture is detected, we can use the view coordinates of the tapped location on the screen to ask the map view for any map markers around that location. We can increase the tap radius, but in most cases, specifying a radius of two pixels is adequate. Then the PickMapItemsCallback provides access to the map items found, such as a MapCircle, a MapPolyline, a MapPolygon or a MapMarker.

Adding metadata

In many cases, users may want to interact with the shown markers - for example, by tapping on a search result to see more details about a restaurant. For this purpose, a MapMarker can hold an instance of the Metadata class, so it is possible to attach various types of data to it - even custom types are supported.

Metadata can hold several key/value pairs. Below, we create a new key named "key_poi" and set a String as value containing the information about the type of the marker:

Metadata metadata = new Metadata();
metadata.setString("key_poi", "This is a POI.");
mapMarker.setMetadata(metadata);

Certainly, you can set any information you may need. The moment we want to read the contents of a Metadata instance, we simply ask for the data stored for a key, which is "key_poi" in our example:

Metadata metadata = topmostMapMarker.getMetadata();
if (metadata != null) {
    String message = "No message found.";
    String string = metadata.getString("key_poi");
    if (string != null) {
        message = string;
    }
    showDialog("Map Marker picked", message);
    return;
}

A MapMarker instance, by default, does not contain Metadata and mapMarker.getMetadata() may return null. The data accessed by a key can be null as well, if the Metadata object does not contain such information.

If it does, we look for the String stored for our key "key_poi" and call a helper method to present the contained String to the user. You can choose any string as a key based on your preference, but use a unique key, or you will otherwise overwrite the content stored for a different data item. To see the full example's source code, please check the MapMarker example app.

Flat map markers

By default, map markers do not rotate with the map - nor get tilted when the map is tilted. This can be changed by setting the MapMarker to become flat. Use the following code to change the corresponding MapMarkerImageStyle:

mapMarkerImageStyle.setFlat(true);

The result can be seen in the screenshot below.

Flat map markers rotate along with the rotated map - and the map marker will also be tilted when the map is tilted, allowing for a 3D-like effect. Please note that, by default, flat map markers will not change their scale value together with the zoom level of the map: For example, when zooming out the map, a map marker will still be visible - same as for an unflattened map marker.

Add map overlays

While map markers offer a seamless way to place items on the map, map overlays can be used to pin a native View to the map. This can be useful to show information bubbles, annotations, or customized controls. For example, when tapping on a map marker, you can show a map overlay with additional information about the marker location.

Map overlays can hold multiple Views, and each of them can be used just like any other View, allowing you to add nested layouts of your choice, attach click handlers, or apply animations, for example.

As is the custom, you can define your views in a XML layout file and inflate them programmatically - or generate the desired view content programmatically. For example:

TextView textView = new TextView(context);
textView.setTextColor(Color.parseColor("#FFFFFF"));
textView.setText("Centered MapOverlay");

LinearLayout linearLayout = new LinearLayout(context);
linearLayout.setBackgroundResource(R.color.colorAccent);
linearLayout.setPadding(10, 10, 10, 10);
linearLayout.addView(textView);

This creates a LinearLayout (which is derived from View) holding a TextView. You can also directly add a TextView, without adding it to an intermediate layout. Any combination of views - or single views - can be added.

Now, all we need to do is to add our little view composition to a MapOverlay instance and show it on the map:

GeoCoordinates geoCoordinates = new GeoCoordinates(52.520798, 13.409408);
MapOverlay<LinearLayout> mapOverlay = new MapOverlay<>(linearLayout, geoCoordinates);

mapView.addMapOverlay(mapOverlay);

Once added to the mapView object, the view - including all nested sub-views - will appear centered on the provided geoCoordinates location and its location will automatically adjust to the given geographical location when the map is moved.

It is also possible to apply animations to the view or attach some other interaction listeners. After a View is attached to a MapOverlay object, it will behave like any other Android View - except that it stays fixed on the map and moves along with it when panning or zooming. Note, the MapOverlay does not rotate when you rotate the map - similar to map polylines and map markers.

You can add as many map overlays as you like, but you should take performance into consideration. For example, if you want to indicate multiple search results on the map, then map overlays are less performant than map markers.

To remove an overlay from the map, simply call:

mapView.removeMapOverlay(mapOverlay);

If you have added multiple MapOverlay instances, you can access all overlays from the mapView object by calling:

List<MapOverlay> mapOverlays = mapView.getMapOverlays();

Usually, map overlays are the best choice for showing additional dynamic content for a specific location on the map.

Anchored map overlays

By default, the map overlay will be centered on the provided location. But if you want to use an overlay without covering the area underneath, what can you do?

For this purpose, you can specify an anchor point, which influences the view's position on the screen in the same way as we have already seen for map markers above:

mapOverlay.setAnchorPoint(new Anchor2D(0.5F, 1));

This will place the view centered horizontally on the location, while the bottom of the view is matching the provided coordinate. As visualized in the screenshot below, the map overlay sits on a map circle object that indicates the provided center location of the map overlay.

Anchor points provide a convenient way to specify the location where the view should be rendered: The top-left corner equals an anchor point of (0, 0) while the bottom-right corner equals an anchor point of (1, 1). Independent of how large the view is, the point that is half the width or height will always be 0.5 - this is similar to the concept of normalized texture UV-coordinates. For an illustration, please see the map markers section above.

By default, the anchor point is (0.5, 0.5), which will render the view centered on the location. If the bottom-right corner of the view should point to the set GeoCoordinates location, then the anchor point must be set to (1, 1).

Since a view can be of any size, the maximum width and height will have a value of 1. The dimension of the view is calculated after it is fully inflated. If you know the exact dimensions of your view, you can easily calculate a specific point inside the view in relation to the maximum value of 1.

Note: While offsets allows you to specify the translation along the x- and y-axis, an anchor point defines the relative position of the top-left corner of a rectangle such as a view. In relation to the view's boundaries, it defines the point where the view is centered on the provided GeoCoordinates location.