Add custom layers

The HERE SDK provides extensive options for customizing your map with the HERE Style Editor and the Style class. More options are described below.

Custom raster layers: Overlay tiled images on top of your map schemes with raster data sources.
Point, tile, and polygon custom layers: Use point, tile and polygon layers to add customizable content to the map.
Tile data sources for point, tile, and polygon custom layers: Efficiently manage and display large datasets by supplying point, tile, or polygon sources.

Add custom raster layers

With custom raster layers you can add your own raster tile service on top of the HERE MapScheme styles. This can be your own server where you host tiles that you want to show as an overlay on top of selected areas of the world - or a public tile server such as OpenStreetMap. Fully opaque and transparent map tile overlays are supported. It is also possible to add more than one raster layer to the map at the same time.

Note

Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

To add custom raster layers, you need to create a RasterDataSource. A RasterDataSource represents the source of raster tile data to display. It also allows changing its configuration. With a RasterDataSourceConfiguration you can specify a configuration for the data source, including URL, tiling scheme, storage levels and caching parameters.

Finally, with the MapLayerBuilder you can create a MapLayer to add a renderable map overlay to the map.

Use MapLayerVisibilityRange to specify at which zoom levels the map layer should become visible.
Use the MapLayerPriority to specify the draw order of the MapLayer.
Use the MapContentType to specify the type of data to be shown by the MapLayer.
Optionally, use the Style API to adjust properties such as opacity or brightness at runtime. More about this can be found in the style guide for custom layers.

In case of raster tile images, use MapContentType.rasterImage.

Default map gesture actions such as pinch, rotate and zoom behave in the same way for raster tiles as for HERE vector maps - except for a few differences: for example, raster tiles are loaded as bitmaps and therefore a rotated raster map tile rotates all labels and street names contained together with the tile.

Note

When loading a map scene with a custom map style or the default map style, the map will be rendered using vector tiles where the map information is represented as vector data consisting of vertices and paths for better scalability and performance. By contrast, raster tiles are regularly spaced and square, and consist of bitmap images that represent only pixel information. Note that the satellite map style is also raster based.

Create a RasterDataSource as follows:

private func createRasterDataSource(dataSourceName: String) -> RasterDataSource {
    // Note: As an example, below is an URL template of an outdoor layer from thunderforest.com.
    // On their web page you can register a key. Without setting a valid API key, the tiles will
    // show a watermark.
    // More details on the terms of usage can be found here: https://www.thunderforest.com/terms/
    // For example, your application must have working links to https://www.thunderforest.com
    // and https://www.osm.org/copyright.
    // For the below template URL, please pay attention to the following attribution:
    // Maps © www.thunderforest.com, Data © www.osm.org/copyright.
    // Alternatively, choose another tile provider or use the (customizable) map styles provided by HERE.
    final templateUrl = 'https://tile.thunderforest.com/outdoors/{z}/{x}/{y}.png'

    let storageLevels: [Int32] = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
    var rasterProviderConfig = RasterDataSourceConfiguration.Provider(
        urlProvider: TileUrlProviderFactory.fromXyzUrlTemplate(templateUrl)!,
        tilingScheme: TilingScheme.quadTreeMercator,
        storageLevels: storageLevels)

    // If you want to add transparent layers then set this to true.
    rasterProviderConfig.hasAlphaChannel = false

    // Raster tiles are stored in a separate cache on the device.
    let path = "cache/raster/mycustomlayer"
    let maxDiskSizeInBytes: Int64 = 1024 * 1024 * 128 // 128 MB
    let cacheConfig = RasterDataSourceConfiguration.Cache(path: path,
                                                          diskSize: maxDiskSizeInBytes)

    // Note that this will make the raster source already known to the passed map view.
    return RasterDataSource(context: mapView.mapContext,
                            configuration: RasterDataSourceConfiguration(name: dataSourceName,
                                                                         provider: rasterProviderConfig,
                                                                         cache: cacheConfig))
}

Note that - if desired - you can also hook into the calls of the templateUrl like so:

var rasterProviderConfig =
    RasterDataSourceConfiguration.Provider(tilingScheme: TilingScheme.quadTreeMercator,
                                           storageLevels: storageLevels,
                                           urlProvider: tileUrlRequestHandler)

...

// Handle tile requests for RasterDataSourceConfiguration.Provider.
private func tileUrlRequestHandler(x: Int32, y: Int32, level: Int32) -> String {
    return "https://tile.thunderforest.com/outdoors/\(level)/\(x)/\(y).png"
}

The latter gives you an option to listen to each tile request and, for example, allows for finer control on the requested tiles, if needed.

Note that custom raster layers use their own cache directory, which can be independent of the map cache that is used for vector-based map data. Find more details in the API Reference for the RasterDataSourceConfiguration.

This code uses a tile source from Thunderforest. More details on the terms of usage can be found on https://www.thunderforest.com/terms/ and on https://www.osm.org/copyright.

Here, the zoom value represents the map's current zoom level, and xTile and yTile defines the horizontal and vertical tile numbers. For example, to show the standard OSM map, use the following template URL:

let templateUrl = "https://a.tile.openstreetmap.org/{z}/{x}/{y}.png"

More tile servers following the OSM format are listed here. Note that the HERE SDK supports only tile servers. Servers that provide vector data are not supported. Vector based tiles can only be used with the HERE Style Editor and the embedded map styles (see above).

Once a tile source is created, a MapLayer can be built:

private func createMapLayer(dataSourceName: String) -> MapLayer {
    // The layer should be rendered on top of other layers including the "labels" layer
    // so that we don't overlap the raster layer over POI markers.
    let priority = MapLayerPriorityBuilder().renderedAfterLayer(named: "labels").build()

    // And it should be visible for all zoom levels. The minimum tilt level is 0 and maximum zoom level is 23.
    let range = MapLayerVisibilityRange(minimumZoomLevel: MapCameraLimits.minTilt, maximumZoomLevel: MapCameraLimits.maxZoomLevel)

    let mapLayer: MapLayer

    do {
        // Build and add the layer to the map.
        try mapLayer = MapLayerBuilder()
            .forMap(mapView.hereMap) // mandatory parameter
            .withName(dataSourceName + "Layer") // mandatory parameter
            .withDataSource(named: dataSourceName,
                            contentType: MapContentType.rasterImage)
            .withPriority(priority)
            .withVisibilityRange(range)
            .build()
        return mapLayer
    } catch let InstantiationException {
        fatalError("MapLayer creation failed Cause: \(InstantiationException)")
    }
}

Above we reference the "labels" layer. More information on existing layers and their names can be found in the API Reference for the MapLayerPriorityBuilder.

Finally, the visibility can be controlled by enabling or disabling the layer as shown below. Note that we also need to provide a unique name. Each RasterDataSource can be created only once:

let dataSourceName = "myRasterDataSourceOutdoorStyle"
rasterDataSourceOutdoorStyle = createRasterDataSource(dataSourceName: dataSourceName)
rasterMapLayerOutdoorStyle = createMapLayer(dataSourceName: dataSourceName)

rasterMapLayerOutdoorStyle.setEnabled(true)

The resulting layer looks like this:

Screenshot: An outdoor map layer from Thunderforest.com shown on top of a map view.

The above screenshot shows that you can easily combine custom raster tiles with other HERE SDK features. For example, you can render several MapMarker instances on top of the tile data from a tile server.

Note

One of the main advantages of custom raster layers is that you can easily enhance the HERE map styles with a transparent custom tile source on top, for example, to show weather data or any other data you want to see on top of the map. When using an opaque raster tile source, it is recommended to combine this with an empty base map style.

If you do not use an empty base map style, then the underlying map scheme will "shine" through until the raster layer tiles are loaded. The accompanying example app shows how this looks like.

There are certain other parameters that you can adjust:

If your app uses multiple raster layers, you can define a load priority when building a layer with the MapLayerBuilder. This allows to specify an integer value: Higher values will lead to load the layer before layers with lower values. Note that this controls just the time when the layer is loaded.
The MapLayerPriority controls how the layer is rendered: For example, optionally, you can append renderedLast() which means that the layer will be rendered on top of all other layers.
For showing transparent map styles, set rasterProviderConfig.hasAlphaChannel to true.
For more parameters, please consult the API Reference.

Another option to reduce the loading time while panning the map can be to adjust the feature configuration (only available for Navigate).

Add custom layers to hold lines, polygons and points

Another alternative to customize the map's appearance is by adding your own custom line, polygon and point layers with the Style class. This provides more flexibility to update the visual appearance at runtime. For most use cases, consider to use MapMarker, MapPolyline or MapPolygon instead. See the map items section. When you are working with a very large amount of custom data, consider to use line, polygon and point tile sources instead to ensure better performance and scalability.

Add custom line layers

Custom geodetic lines can be added to the map's appearance by adding your own custom data layer on top of the HERE MapScheme styles. A geodetic line is the shortest line between any two points on the Earth's surface, with each point represented through geodetic coordinates.

Note

Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

To add custom line layers, you need to create a LineDataSource. A LineDataSource represents the source of geodetic lines data to display. Each geodetic line can be coupled with a set of custom data attributes that can be used to customize the look of each line when displayed on top of the map.

On top of a LineDataSource, with MapLayerBuilder you can create a MapLayer to add a renderable map overlay to the map.

Use MapLayerVisibilityRange to specify at which zoom levels the map layer should become visible.
Use the MapLayerPriority to specify the draw order of the MapLayer.
Use the MapContentType to specify the type of data to be shown by the MapLayer. In case of geodetic lines, use MapContentType.LINE.
Use the Style API to adjust properties such as width or color at runtime. More about this can be found in the style guide for custom layers.

Create a LineDataSource as follows:

let myCustomLinesDataSourceName = "MyCustomLines"

private func createLineDataSource(dataSourceName : String) -> LineDataSource{
    // Creates a new LineDataSource, without custom data.
    // To also add custom lines while creating the data source, `LineDataSourceBuilder.withPolyline` API can be used.
    return LineDataSourceBuilder(mapView.mapContext).withName(dataSourceName).build()
}

Once a line data source is created, custom geodetic lines can be added to it:

private func addLinesToDataSource(linesDataSource : LineDataSource) {
    // Optional: Prepare a list of custom attributes.
    let lineAttributes = DataAttributesBuilder().with(name: "id", value: "my first line").build()

    // Add the line to data source.
    linesDataSource.add(LineDataBuilder().withGeometry(GeoPolyline(vertices: [GeoCoordinates(latitude: point1GeoLatitude, longitude: point1GeoLongitude), ...,
                                                                              GeoCoordinates(latitude: pointNGeoLatitude, longitude: pointNGeoLongitude)]))
                                         .withAttributes(lineAttributes)
                                         .build())

    // Repeat above steps to add more custom lines to the data source.
    // Alternatively, use `LineDataSource.add` to add multiple custom lines with a single call.
    ...
}

Prepare a custom style for your lines layer:

Note

The layer value in the style string must match the name given to the MapLayer in the next steps. In this example, the dataSourceName used is MyCustomLines and the layer name MyCustomLinesLayer.

let myCustomLayerStyle = """
{
  "styles": [
    {
        "layer": "MyCustomLinesLayer",
        "technique": "line",
        "attr": {
            "width": 5.0,
            "color": "#ff0000ff"
        }
    }
  ]
}
"""

private func createCustomStyle() -> Style? {
    do {
        return try JsonStyleFactory.createFromString(myCustomLayerStyle)
    } catch let InstantiationException {
        // Custom exception handling
        ...
    }

    return nil
}

To display a LineDataSource on top of a map, a MapLayer can be built:

private func createMapLayer(dataSourceName: String, layerStyle: Style) -> MapLayer {
    // Set the layer to be rendered on top of other layers.
    let priority = MapLayerPriorityBuilder().renderedLast().build()
    // And it should be visible for all zoom levels. The minimum tilt level is 0 and maximum zoom level is 23.
    let range = MapLayerVisibilityRange(minimumZoomLevel: MapCameraLimits.minTilt, maximumZoomLevel: MapCameraLimits.maxZoomLevel)

    do {
        // Build and add the layer to the map.
        try mapLayer = MapLayerBuilder()
            .forMap(mapView.hereMap) // mandatory parameter
            .withName(dataSourceName + "Layer") // mandatory parameter
            .withDataSource(named: dataSourceName,
                            contentType: MapContentType.line)
            .withPriority(priority)
            .withVisibilityRange(range)
            .withStyle(layerStyle)
            .build()
        return mapLayer
    } catch let InstantiationException {
        fatalError("MapLayer creation failed Cause: \(InstantiationException)")
    }
}

Add custom polygon layers

Custom geodetic polygons can be added to the map's appearance by adding your own custom data layer on top of the HERE MapScheme styles. A geodetic polygon is defined by an exterior geodetic boundary, and optionally one or more interior boundaries. Each boundary is made from a closed sequence of geodetic points (the first point is the same as the last one).

Note

Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

To add custom polygon layers, you need to create a PolygonDataSource. A PolygonDataSource represents the source of geodetic polygon data to display. Each geodetic polygon can be coupled with a set of custom data attributes that can be used to customize the look of each polygon when displayed on top of the map.

On top of a PolygonDataSource, with MapLayerBuilder you can create a MapLayer to add a renderable map overlay to the map.

Use MapLayerVisibilityRange to specify at which zoom levels the map layer should become visible.
Use the MapLayerPriority to specify the draw order of the MapLayer.
Use the MapContentType to specify the type of data to be shown by the MapLayer. In case of geodetic polygons, use MapContentType.POLYGON.
Use the Style API to adjust properties such as color at runtime. More about this can be found in the style guide for custom layers.

Create a PolygonDataSource as follows:

let myCustomPolygonsDataSourceName = "MyCustomPolygons"

private func createPolygonDataSource(dataSourceName : String) -> PolygonDataSource{
    // Creates a new PolygonDataSource, without custom data.
    // To also add custom polygons while creating the data source, `PolygonDataSourceBuilder.withPolygon` API can be used.
    return PolygonDataSourceBuilder(mapView.mapContext).withName(dataSourceName).build()
}

Once a polygon data source is created, custom geodetic polygons can be added to it:

private func addPolygonsToDataSource(polygonsDataSource : PolygonDataSource) {
    // Optional: Prepare a list of custom attributes.
    let polygonAttributes = DataAttributesBuilder().with(name: "id", value: "my first polygon").build()

    // Add the polygon to data source.
    // Note: The point list must be closed and given in clockwise order.
    polygonsDataSource.add(PolygonDataBuilder().withGeometry(GeoPolygon(vertices: [GeoCoordinates(latitude: point1GeoLatitude, longitude: point1GeoLongitude),
        ...,
        GeoCoordinates(latitude: pointNGeoLatitude, longitude: pointNGeoLongitude),
        ...,
        GeoCoordinates(latitude: point1GeoLatitude, longitude: point1GeoLongitude)])))
        .withAttributes(polygonAttributes)
        .build())

    // Repeat above steps to add more custom polygons to the data source.
    // Alternatively, use `PolygonDataSource.add` to add multiple custom polygons with a single call.
    ...
}

Prepare a custom style for your polygons layer:

Note

The layer value in the style string must match the name given to the MapLayer in the next steps. In this example, the dataSourceName used is MyCustomPolygons and the layer name MyCustomPolygonsLayer.

let myCustomLayerStyle = """
{
  "styles": [
    {
        "layer": "MyCustomPolygonsLayer",
        "technique": "polygon",
        "attr": {
            "color": "#ff0000ff"
        }
    }
  ]
}
"""

private func createCustomStyle() -> Style? {
    do {
        return try JsonStyleFactory.JsonStyleFactory.createFromString(myCustomLayerStyle)
    } catch let InstantiationException {
        // Custom exception handling
        ...
    }

    return nil
}

To display a PolygonDataSource on top of a map, a MapLayer can be built:

private func createMapLayer(dataSourceName: String, layerStyle: Style) -> MapLayer {
    // Set the layer to be rendered on top of other layers.
    let priority = MapLayerPriorityBuilder().renderedLast().build()
    // And it should be visible for all zoom levels. The minimum tilt level is 0 and maximum zoom level is 23.
    let range = MapLayerVisibilityRange(minimumZoomLevel: MapCameraLimits.minTilt, maximumZoomLevel: MapCameraLimits.maxZoomLevel)

    do {
        // Build and add the layer to the map.
        try mapLayer = MapLayerBuilder()
            .forMap(mapView.hereMap) // mandatory parameter
            .withName(dataSourceName + "Layer") // mandatory parameter
            .withDataSource(named: dataSourceName,
                            contentType: MapContentType.polygon)
            .withPriority(priority)
            .withVisibilityRange(range)
            .withStyle(layerStyle)
            .build()
        return mapLayer
    } catch let InstantiationException {
        fatalError("MapLayer creation failed Cause: \(InstantiationException)")
    }
}

Add custom point layers

Custom geodetic points can be added to the map's appearance by adding your own custom data layer on top of the HERE MapScheme styles.

Note

Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

To add custom point layers, you need to create a PointDataSource. A PointDataSource represents the source of geodetic point data to display. Each geodetic point can be coupled with a set of custom data attributes that can be used to customize the look of each point when displayed on top of the map.

On top of a PointDataSource, with MapLayerBuilder you can create a MapLayer to add a renderable map overlay to the map.

Use MapLayerVisibilityRange to specify at which zoom levels the map layer should become visible.
Use the MapLayerPriority to specify the draw order of the MapLayer.
Use the MapContentType to specify the type of data to be shown by the MapLayer. In case of geodetic points, use MapContentType.point.
Use the Style API to adjust properties such as icon at runtime. More about this can be found in the style guide for custom layers.

Create a PointDataSource as follows:

let myCustomPointsDataSourceName = "MyCustomPoints"

private func createPointDataSource(dataSourceName : String) -> PointDataSource{
    // Creates a new PointDataSource, without custom data.
    // To also add custom points while creating the data source, `PointDataSourceBuilder.withPoint` API can be used.
    return PointDataSourceBuilder(mapView.mapContext).withName(dataSourceName).build()
}

Once a point data source is created, custom geodetic points can be added to it:

private func addPointsToDataSource(pointsDataSource : PointDataSource) {
    // Optional: Prepare a list of custom attributes.
    let pointAttributes = DataAttributesBuilder().with(name: "id", value: "my first point").build()

    // Add the point to data source.
    // Note: The point list must be closed and given in clockwise order.
    pointsDataSource.add(PointDataBuilder().withCoordinates(GeoCoordinates(latitude: pointGeoLatitude, longitude: pointGeoLongitude))
                                           .withAttributes(pointAttributes)
                                           .build())

    // Repeat above steps to add more custom points to the data source.
    // Alternatively, use `PointDataSource.add` to add multiple custom points with a single call.
    ...
}

Prepare a custom style for your points layer:

Note

The layer value in the style string must match the name given to the MapLayer in the next steps. In this example, the dataSourceName used is MyCustomPoints and the layer name MyCustomPointsLayer.

let myCustomLayerStyle = """
{
  "styles": [
    {
        "layer": "MyCustomPointsLayer",
        "technique": "icon-text",
        "attr": {
            "icon-source": "my_icon.png"
        }
    }
  ]
}
"""

private func createCustomStyle() -> Style? {
    do {
        return try JsonStyleFactory.JsonStyleFactory.createFromString(myCustomLayerStyle)
    } catch let InstantiationException {
        // Custom exception handling
        ...
    }

    return nil
}

To display a PointDataSource on top of a map, a MapLayer can be built:

private func createMapLayer(dataSourceName: String, layerStyle: Style) -> MapLayer {
    // Set the layer to be rendered on top of other layers.
    let priority = MapLayerPriorityBuilder().renderedLast().build()
    // And it should be visible for all zoom levels. The minimum tilt level is 0 and maximum zoom level is 23.
    let range = MapLayerVisibilityRange(minimumZoomLevel: MapCameraLimits.minTilt, maximumZoomLevel: MapCameraLimits.maxZoomLevel)

    do {
        // Build and add the layer to the map.
        try mapLayer = MapLayerBuilder()
            .forMap(mapView.hereMap) // mandatory parameter
            .withName(dataSourceName + "Layer") // mandatory parameter
            .withDataSource(named: dataSourceName,
                            contentType: MapContentType.point)
            .withPriority(priority)
            .withVisibilityRange(range)
            .withStyle(layerStyle)
            .build()
        return mapLayer
    } catch let InstantiationException {
        fatalError("MapLayer creation failed Cause: \(InstantiationException)")
    }
}

Add custom data attributes to custom layers

Any custom object such as a geodetic line can be coupled with a set of attributes. Such attributes are generic key-value pairs and can be freely defined by the developer.

For example, such user-defined attributes can be used to tag each object with a unique identifier:

let lineAttributes = DataAttributesBuilder().with(name: "id", value: "my first line").build()

Or they can be used along with style expressions to customize the look of each object when displayed on top of the map:

// Define a layer style string that would use per-line object width and color values
// that are stored inside line custom data attributes. For that purpose, the 'get' expression is used.
let myCustomLayerStyle = """
{
  "styles": [
    {
        "layer": "MyCustomLinesLayer",
        "technique": "line",
        "attr": {
            "width": ["get", "lineWidthInMeters"],
            "color": ["to-color", ["get", "lineColor"]]
        }
    }
  ]
}

// Define specific values for "lineWidth" and "lineColor" per line object.
let lineAttributes = DataAttributesBuilder().with(name: "lineWidthInMeters", value: 10.0)
                                            .with(name: "lineColor", value: "#ff0000ff").build();
...

Add custom tile sources

Tile source support for points, lines and polygons is an advanced feature designed for scenarios, where users need to integrate and visualize large volumes of custom geospatial data. For example, to visualize EV charging stations or shop locations around the globe. While APIs like MapMarker or MapPolyline are sufficient for smaller datasets, they become inefficient for large-scale use due to high memory consumption. Also, custom point, tile and polygon layers using custom data sources like PointDataSource are not suitable for large volumes of data. Instead, consider to use PointTileDataSource, LineTileDataSource or PolygonTileDataSource instead - as described in this chapter.

Note

Note that the data is loaded on a per-tile basis, ensuring that the entire dataset is not loaded globally at once.

Add custom point tile source

You can enhance the map's appearance by adding a custom point tile source, allowing additional layers of point data to be rendered on top of the default HERE MapScheme. This approach enables seamless integration of point data, even when its format is not natively supported by the HERE SDK.

A Point Tile Data Source can be used to display locations such as points of interest (POIs), real-time vehicle tracking, event markers, etc.

Note

Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

To add a custom point tile source, you need to create a PointTileDataSource. The PointTileDataSource facilitates the creation of point tile sources, while PointTileSource provides a mechanism to supply custom point data based on the requested TileKey. It uses JSON-based styling to control the appearance of the custom point tile source and integrates it into the map.

On top of a PointTileDataSource, with MapLayerBuilder you can create a MapLayer to add a renderable map overlay to the map.

Use MapLayerVisibilityRange to specify at which zoom levels the map layer should become visible.
Use the MapContentType to specify the type of data to be shown by the MapLayer. In case of geodetic points, use MapContentType.POINT.
Use the Style API to adjust properties such as icon at runtime.

Create a PointTileDataSource as follows:

private let mapView: MapView
private var pointMapLayer: MapLayer!
private var pointDataSource: PointTileDataSource!

init(_ mapView: MapView) {
    self.mapView = mapView

    let camera = mapView.camera
    let distanceInMeters = MapMeasure(kind: MapMeasure.Kind.distanceInMeters, value: 60 * 1000)
    camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
                    zoom: distanceInMeters)

    let dataSourceName = "MyPointDataSource"
    pointDataSource = createPointTileDataSource(dataSourceName: dataSourceName)
    pointMapLayer = createMapLayer(dataSourceName: dataSourceName)

    // Load the map scene using a map scheme to render the map with.
    mapView.mapScene.loadScene(mapScheme: MapScheme.normalDay, completion: onLoadScene)
}

Create a custom point data source and load the tile:

private func createPointTileDataSource(dataSourceName: String) -> PointTileDataSource {
    // Create a PointTileDataSource using a local point tile source.
    // Note that this will make the point source already known to the passed map view.
    return PointTileDataSource.create(context: mapView.mapContext,
                                        name: dataSourceName,
                                        tileSource: LocalPointTileSource())
}

func loadTile(tileKey: TileKey, completionHandler: any PointTileSourceLoadResultHandler) -> (any TileSourceLoadTileRequestHandle)? {
    // For each tile, provide the tile geodetic center as a custom point, with a single
    // named attribute "pointText" containing the tile key representation as a string.
    let pointAttributes = DataAttributesBuilder()
        .with(name: "pointText", value: String(format: "Tile: (%d, %d, %d)", tileKey.x, tileKey.y, tileKey.level))
        .build()
    let tileData = PointDataBuilder().withCoordinates(getTileCenter(tileKey: tileKey))
                                        .withAttributes(pointAttributes)
                                        .build();

    completionHandler.loaded(tileKey: tileKey, data: [tileData],
                                metadata: TileSourceTileMetadata(dataVersion: dataVersion,
                                                                dataExpiryTimestamp: Date(timeIntervalSince1970: TimeInterval(0))))

    // No request handle is returned here since there is no asynchronous loading happening.
    return nil
}

Prepare a custom style for your point tile source:

Note

The layer value in the style string must match the name given to the MapLayer in the next steps. In this example, the dataSourceName used is MyPointTileDataSource and the layer name MyPointTileDataSourceLayer.

private let pointLayerStyle = """
{
    "styles": [
        {
            "layer": "MyPointDataSourceLayer",
            "technique": "icon-text",
            "attr": {
                "text-color": "#ff0000ff",
                "text-size": 30,
                "text": ["get", "pointText"]
            }
        }
    ]
}
"""

To display a pointTileSource on top of a map, a MapLayer can be built:

// Creates a MapLayer for displaying custom point tiles.
private func createMapLayer(dataSourceName: String) -> MapLayer {
    // The layer should be visible for all zoom levels. The minimum tilt level is 0 and maximum zoom level is 23.
    let range = MapLayerVisibilityRange(minimumZoomLevel: MapCameraLimits.minTilt, maximumZoomLevel: MapCameraLimits.maxZoomLevel)

    let mapLayer: MapLayer

    do {
        // Build and add the layer to the map.
        try mapLayer = MapLayerBuilder()
            .forMap(mapView.hereMap) // mandatory parameter
            .withName(dataSourceName + "Layer") // mandatory parameter
            .withDataSource(named: dataSourceName,
                            contentType: MapContentType.point)
            .withVisibilityRange(range)
            .withStyle(JsonStyleFactory.createFromString(pointLayerStyle)) // Creates a custom style for the point layer from the predefined JSON style string.
            .build()
        return mapLayer
    } catch let InstantiationException {
        fatalError("MapLayer creation failed Cause: \(InstantiationException)")
    }
}

The resulting point tile source looks like this:

Add custom line tile source

You can enhance the map's appearance by adding a custom line tile source, allowing additional layers of line data to be rendered on top of the default HERE MapScheme. This approach enables seamless integration of line data, even when its format is not natively supported by the HERE SDK.

A Line Tile Data Source can be ideal for rendering off-road tracks, boundaries, etc.

Note

Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

To add a custom line tile source, you need to create a LineTileDataSource. The LineTileDataSource facilitates the creation of line tile sources, while LineTileSource provides a mechanism to supply custom line data based on the requested TileKey. It uses JSON-based styling to control the appearance of the custom line tile source and integrates it into the map.

On top of a LineTileDataSource, with MapLayerBuilder you can create a MapLayer to add a renderable map overlay to the map.

Use MapLayerVisibilityRange to specify at which zoom levels the map layer should become visible.
Use the MapContentType to specify the type of data to be shown by the MapLayer. In case of geodetic lines, use MapContentType.LINE.
Use the Style API to adjust properties such as icon at runtime.

Create a LineTileDataSource as follows:

private let mapView: MapView
private var lineMapLayer: MapLayer!
private var lineDataSource: LineTileDataSource!

init(_ mapView: MapView) {
    self.mapView = mapView

    let camera = mapView.camera
    let distanceInMeters = MapMeasure(kind: MapMeasure.Kind.distanceInMeters, value: 60 * 1000)
    camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
                    zoom: distanceInMeters)

    let dataSourceName = "MyLineTileDataSource"
    lineDataSource = createLineTileDataSource(dataSourceName: dataSourceName)
    lineMapLayer = createMapLayer(dataSourceName: dataSourceName)

    if let lineMapLayer = lineMapLayer {
        lineMapLayer.setEnabled(false)
    }

    // Load the map scene using a map scheme to render the map with.
    mapView.mapScene.loadScene(mapScheme: MapScheme.normalDay, completion: onLoadScene)
}

Create a custom line data source and load the tile:

private func createLineTileDataSource(dataSourceName: String) -> LineTileDataSource {
    // Create a LineTileDataSource using a local line tile source.
    return LineTileDataSource.create(context: mapView.mapContext,
                                        name: dataSourceName,
                                        tileSource: LocalLineTileSource())
}

func loadTile(tileKey: TileKey, completionHandler: any LineTileSourceLoadResultHandler) -> (any TileSourceLoadTileRequestHandle)? {
    do {
        let lineCoordinates = getTileBounds(tileKey: tileKey)
        let lineGeometry = try GeoPolyline(vertices: lineCoordinates)

        let tileData = LineDataBuilder()
            .withGeometry(lineGeometry)
            .withAttributes(DataAttributesBuilder()
                .with(name: "color", value: "#FF0000") // Example attribute for styling
                .build())
            .build()

        completionHandler.loaded(tileKey: tileKey, data: [tileData],
                                    metadata: TileSourceTileMetadata(dataVersion: dataVersion,
                                                                    dataExpiryTimestamp: Date(timeIntervalSince1970: TimeInterval(0))))
    } catch {
        print("Error creating GeoPolyline: \(error)")
        completionHandler.failed(tileKey)
        return nil
    }

    return nil
}

Prepare a custom style for your line tile source:

Note

The layer value in the style string must match the name given to the MapLayer in the next steps. In this example, the dataSourceName used is MyLineTileDataSource and the layer name MyLineTileDataSourceLayer.

private let lineLayerStyle = """
{
    "styles": [
        {
            "layer": "MyLineTileDataSourceLayer",
            "technique": "line",
            "attr": {
                "color": "#FF0000",
                "width": ["world-scale", 5]
            }
        }
    ]
}
"""

To display a lineTileSource on top of a map, a MapLayer can be built:

// Creates a MapLayer for displaying custom line tiles.
private func createMapLayer(dataSourceName: String) -> MapLayer {
    // The layer should be visible for all zoom levels. The minimum tilt level is 0 and maximum zoom level is 23.
    let range = MapLayerVisibilityRange(minimumZoomLevel: MapCameraLimits.minTilt, maximumZoomLevel: MapCameraLimits.maxZoomLevel)

    let mapLayer: MapLayer

    do {
        try mapLayer = MapLayerBuilder()
            .forMap(mapView.hereMap)
            .withName(dataSourceName + "Layer")
            .withDataSource(named: dataSourceName,
                            contentType: MapContentType.line)
            .withVisibilityRange(range)
            .withStyle(JsonStyleFactory.createFromString(lineLayerStyle))
            .build()
        return mapLayer
    } catch let InstantiationException {
        fatalError("MapLayer creation failed Cause: \(InstantiationException)")
    }
}

The resulting point tile source looks like this:

Add custom raster tile source

You can enhance the map's appearance by adding a custom raster tile source, allowing additional layers of raster data to be rendered on top of the default HERE MapScheme. This approach enables seamless integration of raster data, even when its format is not natively supported by the HERE SDK.

A Raster Tile Source can overlay image-based data such as satellite imagery, weather maps, etc.

Note

Note that this is a beta release of this feature, so there could be a few bugs and unexpected behaviors. Related APIs may change for new releases without a deprecation process.

To add a custom raster tile source, you need to create a RasterDataSource. The RasterDataSource facilitates the creation of raster data sources, while RasterTileSource provides a mechanism to supply custom raster data based on the requested TileKey. It uses JSON-based styling to control the appearance of the custom raster tile source and integrates it into the map.

On top of a RasterDataSource, with MapLayerBuilder you can create a MapLayer to add a renderable map overlay to the map.

Use MapLayerVisibilityRange to specify at which zoom levels the map layer should become visible.
Use the MapContentType to specify the type of data to be shown by the MapLayer. In case of geodetic rasters, use MapContentType.RASTER_IMAGE.
Use the Style API to adjust properties such as icon at runtime.

Create a RasterDataSource as follows:

private var mapView: MapView
private var rasterMapLayerStyle: MapLayer!
private var rasterDataSourceStyle: RasterDataSource!

init(_ mapView: MapView) {
    self.mapView = mapView

    let camera = mapView.camera
    let distanceInMeters = MapMeasure(kind: MapMeasure.Kind.distanceInMeters, value: 60 * 1000)
    camera.lookAt(point: GeoCoordinates(latitude: 52.518043, longitude: 13.405991),
                    zoom: distanceInMeters)

    // Load the map scene using a map scheme to render the map with.
    mapView.mapScene.loadScene(mapScheme: MapScheme.normalDay, completion: onLoadScene)

    let dataSourceName = "myRasterDataSourceStyle"
    rasterDataSourceStyle = createRasterDataSource(dataSourceName: dataSourceName)
    rasterMapLayerStyle = createMapLayer(dataSourceName: dataSourceName)

    // We want to start with the default map style.
    rasterMapLayerStyle.setEnabled(false)

    // Add a POI marker
    addPOIMapMarker(geoCoordinates: GeoCoordinates(latitude: 52.530932, longitude: 13.384915))
}

Create a custom raster data source:

private func createRasterDataSource(dataSourceName: String) -> RasterDataSource {
    // Create a RasterDataSource over a local raster tile source.
    // Note that this will make the raster source already known to the passed map view.
    return RasterDataSource(context: mapView.mapContext,
                            name: dataSourceName,
                            tileSource: LocalRasterTileSource())
}

@Override
func loadTile(tileKey: TileKey, completionHandler: any RasterTileSourceLoadResultHandler) -> (any TileSourceLoadTileRequestHandle)? {
    // Pick one of the local tile images, based on the tile key x component.

    completionHandler.loaded(tileKey: tileKey, data: tileData[Int(tileKey.x % Int32(tileData.count))],
                                metadata: TileSourceTileMetadata(dataVersion: dataVersion, dataExpiryTimestamp: Date(timeIntervalSince1970: TimeInterval(0))))

    // No request handle is returned here since there is no asynchronous loading happening.
    return nil
}

To display a rasterTileSource on top of a map, a MapLayer can be built:

private func createMapLayer(dataSourceName: String) -> MapLayer {
    // The layer should be rendered on top of other layers except the "labels" layer
    // so that we don't overlap the raster layer over POI markers.
    let priority = MapLayerPriorityBuilder().renderedBeforeLayer(named: "labels").build()

    // And it should be visible for all zoom levels. The minimum tilt level is 0 and maximum zoom level is 23.
    let range = MapLayerVisibilityRange(minimumZoomLevel: MapCameraLimits.minTilt, maximumZoomLevel: MapCameraLimits.maxZoomLevel)

    let mapLayer: MapLayer

    do {
        // Build and add the layer to the map.
        try mapLayer = MapLayerBuilder()
            .forMap(mapView.hereMap) // mandatory parameter
            .withName(dataSourceName + "Layer") // mandatory parameter
            .withDataSource(named: dataSourceName,
                            contentType: MapContentType.rasterImage)
            .withPriority(priority)
            .withVisibilityRange(range)
            .build()
        return mapLayer
    } catch let InstantiationException {
        fatalError("MapLayer creation failed Cause: \(InstantiationException)")
    }
}

The resulting raster data source looks like this:

Note (only relevant with Navigate)

The creation of your custom road geometry or POIs requires HERE support and an additional agreement with HERE. Please contact your HERE representative for more details. See also Use custom map catalogs.

Try the example apps

Most of the code snippets mentioned above are available in our "CustomRasterLayers" example apps. You can find these example apps on GitHub for your preferred platform.

Add custom raster layers

Note

Note

Note

Add custom layers to hold lines, polygons and points

Add custom line layers

Note

Note

Add custom polygon layers

Note

Note

Add custom point layers

Note

Note

Add custom data attributes to custom layers

Add custom tile sources

Note

Add custom point tile source

Note

Note

Add custom line tile source

Note

Note

Add custom raster tile source

Note

Note (only relevant with Navigate)

Try the example apps

Related Topics