HERE EV Charge Points API v3 migration guide

Overview

This guide describes how to migrate from HERE EV Charge Points API v2 to HERE EV Charge Points API v3. It is intended for public consumption and focuses on conceptual, structural, and behavioural changes that application developers must address when upgrading.

EV Charge Points API v2 is in maintenance mode and no longer actively developed, while EV Charge Points API v3 is the actively developed successor based on the OCPI 2.x data model and extended by HERE. Migration is therefore strongly recommended.

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 line with HERE Search API.

Data Model Alignment

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.

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 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 EV Charge Points API v3, discovery and lookup are explicitly separated. Discovery is performed using HERE 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. 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 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.

Endpoint and API Behaviour Changes

EV Charge Points API Versioning and Status

• EV Charge Points API v2 endpoints are stable but receive only critical fixes.
• 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

• EV Charge Points API v2 responses are relatively flat and station-centric.
• 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. Some connector definitions were refined during migration, for example Tesla-related connectors were split to distinguish NACS from proprietary Tesla connectors.

Applications relying on numeric connector IDs or legacy names must remap them to the new EV Charge Points API v3 enumeration set.

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

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)

EV Charge Points API v2 provides ad hoc pricing information only. This represents the charging price applicable to non subscription based charging, without using an eMSP (charge card).

EV Charge Points API v3 extends pricing support by adopting the OCPI tariff model. In addition to ad hoc pricing, v3 also provides eMSP specific tariffs, enabling applications to retrieve pricing information associated with charge card based charging. This results in a more complete and standardised representation of EV charging prices across different access models.

Operator and Suboperator

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.

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 EV Charge Points API v2. See POI Naming and Localisation for further information.

Backwards Compatibility Considerations

• Location identifiers remain stable between EV Charge Points API v2 and 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

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