Migrating from HERE EV Charge Points API v2 to HERE EV Charge Points API v3

Overview

This guide explains how to migrate from HERE EV Charge Points API v2 using Option B and Option C from the migration model in Migrating from EV Charge Points API v2.

Option B: HERE Geocoding and Search API v7 plus HERE EV Charge Points API v3 (advanced EV content)

Use HERE Geocoding and Search API v7 for discovery and place IDs, then call HERE EV Charge Points API v3 for richer EV details such as:

• tariffs
• availability predictions
• richer location, EVSE, and connector details

Reference: Introduction to HERE EV Charge Points API v3

Migration flow for Option B

Step 1: Implement Option A baseline

Start with HERE Geocoding and Search API v7 discovery and place ID retrieval as in Option A.

Step 2: Add EVCP v3 enrichment

Use place IDs from HERE Geocoding and Search API v7 to fetch advanced EV data from EVCP v3.

Step 3: Merge HERE Geocoding and Search API v7 and EVCP v3 responses

Create a merged domain response for your clients that combines:

• HERE Geocoding and Search API v7 discovery metadata
• EVCP v3 enrichment fields

Step 4: Add resiliency and fallback

If EVCP v3 enrichment fails, return HERE Geocoding and Search API v7 discovery results and mark advanced EV fields as temporarily unavailable.

Step 5: Validate advanced scenarios

Validate end-to-end behavior for:

• tariff rendering
• availability prediction rendering
• latency and timeout handling under load

Example B: HERE Geocoding and Search API v7 + EVCP v3 flow (Option B)

1) Discover with HERE Geocoding and Search API v7

Request

GET https://browse.search.hereapi.com/v1/discover?at=52.5201,13.4049
Authorization: Bearer <token>

Response (simplified)

{
  "id": "here:cm:namedplace:2038475610",
  "title": "Downtown Charging Hub"
}

2) Enrich with EVCP v3 using the place ID returned by the request above

GET https://evcp.hereapi.com/v3/locations/{placeId}?fields=evses,tariffs
Authorization: Bearer <token>

3) Response

{
  "id": "here:cm:namedplace:2038475610",
  "title": "Downtown Charging Hub",
  "ev": {
    "availability": "AVAILABLE",
    "connectors": [
      {
        "type": "CCS2",
        "powerKw": 150
      }
    ],
    "tariffSummary": "from EUR 0.59 per kWh"
  }
}

Who should choose Option C

Choose Option C if one or more of the following applies:

• you already operate a production search/discovery platform
• your product requires custom ranking, indexing, or blending logic
• your architecture is built around non-GS7 (HERE Geocoding and Search API v7) discovery services
• you still need advanced EV enrichment from HERE

Key Conceptual Changes

This version introduces two primary conceptual changes. First, the EV Charge Points data model is aligned with an industry standard. Second, the responsibilities of discovery and lookup are clearly separated in to two distinct APIs.

Data Model Alignment

HERE EV Charge Points API v2 is loosely based on the eMI³ (eMobility ICT Interoperability Innovation) specification. While flexible, this model does not strictly enforce a standard structure for charging locations and their components.

HERE EV Charge Points API v3 is aligned with OCPI (Open Charge Point Interface) 2.x, with HERE specific extensions. This alignment introduces a standardised object model with a clear hierarchy of locations, EVSEs, and connectors, as well as consistent enumerations. The result is improved interoperability, clearer semantics, and better consistency with the wider EV ecosystem.

Discovery and Lookup Responsibilities

In HERE EV Charge Points API v2, EV charge point discovery and data access are combined in a single API. Applications use EV Charge Points API v2 to perform geospatial discovery, apply EV specific filters, and retrieve detailed charge point information in one step.

In HERE EV Charge Points API v3, discovery and lookup are explicitly separated. Discovery is performed using HERE Geocoding and Search API, which provides geospatial search and filtering across Places, including EV specific attributes such as connector types, charging power, and eMSP (charge card) support. HERE EV Charge Points API v3 is used exclusively for lookup, enriching the discovered places with detailed and structured EV charge point data.

In addition to HERE Geocoding and Search API, EV charging locations can also be discovered through other HERE products, including HERE Map Content, HERE Places offerings, and HERE SDKs, depending on the application architecture and integration requirements.

For details on EV related search attributes supported during discovery, see HERE Geocoding and Search - Developer Guide.

Core Object Model Mapping

The following table shows how the core object model maps between v2 and v3.

The locationId in v3 corresponds to the poolId in v2. This preserves charging location identity across versions while adopting the OCPI aligned object model.

Read more about the Key concepts of the EV Charge Points.

Endpoint and API Behaviour Changes

HERE EV Charge Points API Versioning and Status

• HERE EV Charge Points API v2 endpoints are stable but receive only critical fixes.
• HERE EV Charge Points API v3 endpoints are active and evolving, with regular data and feature updates.

Applications should plan for incremental improvements when adopting v3.

Response Structure

• HERE EV Charge Points API v2 responses are pretty nested and station-centric. There is no EVSE level.
• HERE EV Charge Points API v3 responses are hierarchical:
  • Location
    • EVSE
      • Connector or ConnectorGroup

Client code must be updated to traverse this hierarchy rather than assuming a single station object.

Connector and Enumeration Changes

Connector Types

Connector enumerations in EV Charge Points API v3 are aligned with OCPI and match OCPI values exactly. Applications relying on numeric connector IDs or legacy names must remap them to the new HERE EV Charge Points API v3 enumeration set.

Note! The HERE Geocoding and Search API continues to use legacy numeric connector IDs for filtering and will do so going forward. These identifiers are not part of HERE EV Charge Points API v3 and need to be mapped to the v3 connector enumeration.

Connector mapping table

Status mapping table

The following table shows the differences in EVSE real‑time status codes between OCPI (used in the HERE EV Charge Points API v3) and eMI³ (used in the HERE EV Charge Points API v2).

POI Naming and Localisation

The HERE EV Charge Points API v3 does not translate default or fallback POI names into local languages.

• When CPO (Charge Point Operator) details are available, the POI name is the CPO brand name.
• When CPO details are missing, a generic default name "EV Charging Station" is returned.
• This default text is not localised and is always returned in English.

For production use, HERE recommends that applications implement their own POI naming scheme.

EV Pricing (Tariffs)

The HERE EV Charge Points API v2 exposes ad hoc (pay‑as‑you‑go) pricing only. Subscription‑based pricing and charging via eMSPs or CPO charge cards are not supported.

The HERE EV Charge Points API v3 extends pricing support by adopting the subscription tariff model. In addition to ad hoc (pay‑as‑you‑go) pricing, v3 provides both eMSP‑specific tariffs and CPO subscription prices. This enables applications to retrieve pricing information for charge card–based charging as well as operator‑specific subscription models, resulting in a more complete and standardised representation of EV charging prices across different access models.

Read more about tariffs.

Operator and Suboperator

The HERE EV Charge Points API v2 exposes only a single operator brand. This value is derived from OCPI data and represents either the suboperator, if available, or the operator otherwise. Applications cannot distinguish between these two roles.

The HERE EV Charge Points API v3 publishes both operator and suboperator attributes as defined by the OCPI data model. This allows applications to explicitly choose which entity to present or use, depending on their use case.

To preserve backward compatibility, the POI name continues to represent the operator brand, following the same mapping approach as in HERE EV Charge Points API v2. See POI Naming and Localisation for further information.

Non-supported pre-calculated values

The HERE EV Charge Points API v2 exposes some attributes that are not included in The HERE EV Charge Points API v3 but can be derived on the client side using the more granular data model introduced in the HERE EV Charge Points API v3.

• totalNumberOfConnectors can be calculated by counting the connector objects returned in the response. Alternatively, the total number of connectors can be derived by summing the connectorCount values provided under connectorGroups.
• powerFeedType provided a precomputed classification of charging power levels at connector type level. In EVCP API v3, the same information is represented more explicitly at connector level, using OCPI‑aligned electrical attributes defined under evses, including: powerType (AC or DC), maxVoltage, and maxCurrent.
• customerChargeLevel provided a precomputed classification of charging speed categories based on the maximum supported charging power at connector type level. In the HERE EV Charge Points API v3, the same information is represented through connectorGroups as a maxPower value, expressed in watts (W).
• stationId can be derived in most of the cases, but there are some very old charging locations where there is special mapping needed. Please contact to HERE support in case you need help with this attribute.

Backwards Compatibility Considerations

• Location identifiers remain stable between HERE EV Charge Points API v2 and HERE EV Charge Points API v3.
• Enumeration values may differ and must not be assumed to be identical.
• Response payloads are not backwards compatible and require client changes.

No automatic compatibility layer is provided between the APIs.

Further Reading

• HERE EV Charge Points API v2 Developer Guide
• HERE EV Charge Points API v3 Developer Guide