Self-Hosting

This guide explains how to run HERE Maps API for JavaScript with your own hosted assets and custom service endpoints. It covers the practical setup flow for self-hosting API runtime files, map style assets, and service URL configuration.

What self-hosting means in this guide

In this guide, self-hosting includes:

• Serving API runtime assets from your domain (for example, JavaScript modules and CSS files).
• Serving style and theme assets from your domain (for example, styles, fonts, and sprites).
• Routing API requests through your own domain or proxy endpoints by configuring service URLs at runtime.

This guide focuses on setup and configuration. For security policy details, see Configure Content Security Policy.

1. Prepare hosted assets

Download the API modules NPM package

This guide assumes the API JS files are fetched with NPM and then published from your infrastructure.

For the complete setup steps, see Bundle the HERE Maps API for JavaScript with Webpack and Rollup.

Download the style assets NPM package

Use the same NPM registry setup as in the step above. If you have not configured it yet, run:

npm config set @here:registry https://repo.platform.here.com/artifactory/api/npm/maps-api-for-javascript/

Then install the HERE Maps API for JavaScript style assets package:

npm install @here/maps-api-for-javascript-assets

The package contains:

@here/maps-api-for-javascript-assets/
├── HERE_NOTICE
├── LICENSE
├── README.md
├── package.json
└── styles/

Copy the styles/ folder to your hosted location and publish it from your infrastructure.

2. Configure service endpoints through your domain

If your network policy requires API traffic through your own gateway or proxy, configure service endpoints with the platform service configuration object.

For example:

const servicesConfig = {};
const requestOptions = { apikey: "<YOUR_API_KEY>" };

// HERE Vector Tile API v2
servicesConfig[H.service.omv.Service.CONFIG_KEY] = {
  baseUrl: new H.service.Url(
    "https", "custom.domain", "v2/vectortiles/core/mc", requestOptions
  )
};

// HERE Routing API v8
servicesConfig[H.service.RoutingService8.CONFIG_KEY] = {
  baseUrl: new H.service.Url(
    "https", "custom.domain", "v8/routes", requestOptions
  )
};

const platform = new H.service.Platform({
  apikey: "<YOUR_API_KEY>",
  servicesConfig
});

For a broader service list and examples, see Set custom domain names and service paths.

3. Configure map style loading from your domain

Use one of the following approaches depending on whether you use default layers or custom layers.

Use case 1: Create default layers with self-hosted style assets

When using H.service.Platform.createDefaultLayers, set the styleBaseUrl option to the base URL where your self-hosted style configuration files and related resources are stored.

const defaultLayers = platform.createDefaultLayers({
  styleBaseUrl: "https://<YOUR_ASSET_HOST>/PATH/TO/styles/"
});

const map = new H.Map(
  document.getElementById("mapContainer"),
  defaultLayers.vector.normal.map,
  { center: { lat: 52.531, lng: 13.385 }, zoom: 10 }
);

Use case 2: Create custom layers with a self-hosted style JSON file

When creating custom layers, initialize H.map.render.harp.Style with the URL of your self-hosted style configuration JSON file.

const style = new H.map.render.harp.Style(
  "https://<YOUR_ASSET_HOST>/PATH/TO/styles/harp/oslo/normal.day.json"
);

const omvService = platform.getOMVService();
const omvLayer = omvService.createLayer(style);

Related topics

• Set custom domain names and service paths
• Configure Content Security Policy
• Get started with HERE Maps API for JavaScript