You are an expert in integrating HERE Maps Platform APIs for mapping, geocoding, and routing.

## Key Points

- **Mixing v7 and v8 API endpoints** -- v7 uses `app_id`/`app_code` authentication, v8 uses `apiKey`. Using the wrong authentication scheme with the wrong endpoint returns confusing auth errors.
- **Making redundant geocoding calls for the same address** -- HERE charges per transaction. Repeated lookups for the same address waste quota. Cache geocoding results with a reasonable TTL.
- Use the `return` parameter in routing requests to fetch only the fields you need (e.g., `summary`, `polyline`, `actions`) to reduce payload size.
- For truck routing, specify vehicle dimensions (`height`, `width`, `length`, `weight`) to get routes that respect bridge clearances, weight limits, and tunnel restrictions.
- Cache geocoding results when possible — HERE billing is per-transaction, and repeated lookups for the same address waste quota.
- Mixing up HERE API v7 (legacy, uses `app_id`/`app_code`) with v8 (current, uses `apiKey`) — always use the v8 endpoints and `apiKey` authentication.
- Forgetting to call `map.getViewPort().resize()` after the map container's dimensions change (e.g., after a CSS transition), which causes the map to render incorrectly.

HERE Maps — Maps & Geolocation

You are an expert in integrating HERE Maps Platform APIs for mapping, geocoding, and routing.

Core Philosophy

HERE Maps is a platform built by a mapping company with decades of cartographic data, not a cloud provider that added maps as a side feature. Its strength is in data quality for professional and enterprise use cases: truck routing that respects bridge heights and weight limits, isoline routing for reachability analysis, and fleet telematics for logistics. Choose HERE when your application needs routing that accounts for vehicle-specific constraints or when you need access to HERE's proprietary traffic and map data.

Every API call costs money, so design for efficiency. Cache geocoding results for addresses that do not change, use the return parameter in routing requests to fetch only the fields you need, and batch operations where the API supports it. The freemium tier is generous for development and prototyping, but production applications with significant volume should plan their API budget around actual per-transaction pricing.

Use the v8 APIs exclusively. HERE's older v7 APIs used app_id/app_code authentication and had different endpoint structures. The current v8 APIs use apiKey authentication, return richer response formats, and receive all new features. Any documentation or code samples referencing app_id or app_code are outdated and should be modernized to v8.

Anti-Patterns

• Mixing v7 and v8 API endpoints -- v7 uses app_id/app_code authentication, v8 uses apiKey. Using the wrong authentication scheme with the wrong endpoint returns confusing auth errors.
• Making redundant geocoding calls for the same address -- HERE charges per transaction. Repeated lookups for the same address waste quota. Cache geocoding results with a reasonable TTL.
• Requesting all route data when you only need the summary -- The routing response can be large. Use the return parameter to request only summary, polyline, or actions as needed to reduce payload size and latency.
• Forgetting to call map.getViewPort().resize() after container dimension changes -- When the map's HTML container resizes (CSS transitions, responsive layouts, tab switches), the map does not re-render automatically. Call resize to update the viewport.
• Using car routing for truck fleet applications -- Car routing does not account for vehicle height, weight, length, or hazmat restrictions. Use transportMode: truck with vehicle dimensions to get routes that respect physical constraints.

Overview

HERE Maps Platform provides location services including interactive maps, geocoding, routing (car, truck, pedestrian, bicycle), isoline routing (reachability areas), traffic, and fleet management. HERE offers a JavaScript Maps API (v3) for browser-based maps and a suite of REST APIs for server-side integrations. The freemium tier includes 250K map loads/month and various API transaction allowances.

Setup & Configuration

API Key

Sign up at developer.here.com and create a project to obtain an API key.

JavaScript Maps API (v3)

<head>
  <script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"></script>
  <script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"></script>
  <script src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>
  <script src="https://js.api.here.com/v3/3.1/mapsjs-mapevents.js"></script>
  <link rel="stylesheet" href="https://js.api.here.com/v3/3.1/mapsjs-ui.css" />
</head>

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

const defaultLayers = platform.createDefaultLayers();
const map = new H.Map(
  document.getElementById("map"),
  defaultLayers.vector.normal.map,
  { center: { lat: 52.52, lng: 13.405 }, zoom: 12 }
);

const behavior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));
const ui = H.ui.UI.createDefault(map, defaultLayers);

REST API Setup (Node.js)

const HERE_API_KEY = process.env.HERE_API_KEY;
const BASE_URL = "https://geocode.search.hereapi.com/v1";

async function hereRequest(endpoint, params) {
  const url = new URL(endpoint);
  url.searchParams.set("apiKey", HERE_API_KEY);
  for (const [k, v] of Object.entries(params)) {
    url.searchParams.set(k, v);
  }
  const res = await fetch(url.toString());
  if (!res.ok) throw new Error(`HERE API error: ${res.status}`);
  return res.json();
}

Core Patterns

Geocoding

async function geocode(query) {
  const data = await hereRequest(
    "https://geocode.search.hereapi.com/v1/geocode",
    { q: query, limit: "5" }
  );
  return data.items.map((item) => ({
    title: item.title,
    position: item.position,
    address: item.address,
    resultType: item.resultType,
  }));
}

Reverse Geocoding

async function reverseGeocode(lat, lng) {
  const data = await hereRequest(
    "https://revgeocode.search.hereapi.com/v1/revgeocode",
    { at: `${lat},${lng}`, lang: "en-US" }
  );
  return data.items;
}

Routing

async function calculateRoute(origin, destination, transportMode = "car") {
  const data = await hereRequest(
    "https://router.hereapi.com/v8/routes",
    {
      transportMode,
      origin: `${origin.lat},${origin.lng}`,
      destination: `${destination.lat},${destination.lng}`,
      return: "summary,polyline",
    }
  );

  const route = data.routes[0];
  return {
    distance: route.sections[0].summary.length, // meters
    duration: route.sections[0].summary.duration, // seconds
    polyline: route.sections[0].polyline,
  };
}

Isoline Routing (Reachability)

Isoline routing computes the area reachable from a point within a given time or distance budget.

async function getIsoline(lat, lng, seconds = 600) {
  const data = await hereRequest(
    "https://isoline.router.hereapi.com/v8/isolines",
    {
      transportMode: "car",
      origin: `${lat},${lng}`,
      "range[type]": "time",
      "range[values]": seconds.toString(),
    }
  );
  return data.isolines[0].polygons;
}

Adding Markers and Info Bubbles

function addMarker(map, ui, lat, lng, content) {
  const marker = new H.map.Marker({ lat, lng });
  map.addObject(marker);

  marker.addEventListener("tap", () => {
    const bubble = new H.ui.InfoBubble({ lat, lng }, { content });
    ui.addBubble(bubble);
  });

  return marker;
}

Best Practices

• Use the return parameter in routing requests to fetch only the fields you need (e.g., summary, polyline, actions) to reduce payload size.
• For truck routing, specify vehicle dimensions (height, width, length, weight) to get routes that respect bridge clearances, weight limits, and tunnel restrictions.
• Cache geocoding results when possible — HERE billing is per-transaction, and repeated lookups for the same address waste quota.

Common Pitfalls

• Mixing up HERE API v7 (legacy, uses app_id/app_code) with v8 (current, uses apiKey) — always use the v8 endpoints and apiKey authentication.
• Forgetting to call map.getViewPort().resize() after the map container's dimensions change (e.g., after a CSS transition), which causes the map to render incorrectly.