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 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. 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 to two distinct APIs.
Data Model Alignment
EV Charge Points API v2 is loosely based on the eMI3 (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 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. 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.
| EV Charge Points API v2 | EV Charge Points API v3 | Description |
|---|---|---|
| Pool or Station | Location | A charging location that groups one or more EVSEs |
| EVSE | EVSE | A single charge point (charger) supplying power to one vehicle |
| Connector | Connector | A physical plug or socket attached to an EVSE |
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
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 pretty nested and station-centric. There is no EVSE level.
- EV Charge Points API v3 responses are hierarchical:
- Location
- EVSE
- Connector or ConnectorGroup
- EVSE
- Location
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 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 EV Charge Points API v3 and need to be mapped to the v3 connector enumeration.
Connector mapping table
| standard (EV CP API v3) | connectorType.id (EV CP API v2) | connectorType.name (EV CP API v2) | More information |
|---|---|---|---|
| DOMESTIC_B | 5 | Domestic plug/socket type B (NEMA 5-15) | Domestic plug/socket type B (NEMA 5-15) |
| NEMA_5_20 | 6 | NEMA 5-20 (3 pin) | Domestic plug/socket type B (NEMA 5-20 (3 pin)) |
| DOMESTIC_D | 7 | Domestic plug/socket type D (BS 546, 3 pin, 5A) | Domestic plug/socket type D (BS 546, 3 pin, 5A) |
| DOMESTIC_E | 8 | Domestic plug/socket type E (CEE 7/5) | Domestic plug/socket type E (CEE 7/5) |
| DOMESTIC_F | 9 | Domestic plug/socket type F (CEE 7/4 (Schuko)) | Domestic plug/socket type F (CEE 7/4 (Schuko)) |
| DOMESTIC_G | 11 | Domestic plug/socket type G (BS 1363, IS 401 & 411, MS 58) | Domestic plug/socket type G (BS 1363, IS 401 & 411, MS 58) |
| DOMESTIC_H | 12 | Domestic plug/socket type H (SI 32) | Domestic plug/socket type H (SI 32) |
| DOMESTIC_I | 13 | Domestic plug/socket type I (AS/NZS 3112) | Domestic plug/socket type I (AS/NZS 3112) |
| DOMESTIC_K | 20 | Domestic plug/socket type K (Section 107-2-D1) | Domestic plug/socket type K (Section 107-2-D1) |
| DOMESTIC_L | 22 | Domestic plug/socket type L (CEI 23-16/VII) | Domestic plug/socket type L (CEI 23-16/VII) |
| DOMESTIC_M | 23 | Domestic plug/socket type M (South African 15 A/250 V) | Domestic plug/socket type M (South African 15 A/250 V) |
| CHADEMO | 29 | JEVS G 105 (CHAdeMO) | CHAdeMO |
| IEC_62196_T1 | 30 | IEC 62196-2 type 1 (SAE J1772) | Type 1 (SAE J1772) |
| IEC_62196_T2 | 31 | IEC 62196-2 type 2 (Type 2) | Type 2 |
| IEC_62196_T3C | 32 | IEC 62196-2 type 3c (SCAME) | Type 3c |
| IEC_62196_T1_COMBO | 33 | IEC 62196-3 type 1 combo (SAE J1772) | CCS1 |
| IEC_62196_T2_COMBO | 34 | IEC 62196-3 type 2 combo (Mennekes) | CCS2 |
| IEC_60309_2_SINGLE_16 | 35 | IEC 60309 : industrial P + N + E (AC) | Industrial blue AC |
| IEC_60309_2_THREE_16 IEC_60309_2_THREE_32 IEC_60309_2_THREE_64 | 36 | IEC 60309 : industrial 3P + E + N (AC) | Industrial red AC |
| DOMESTIC_J | 42 | Domestic plug/socket type J (SEV 1011) (T13, T23) | Domestic plug/socket type J (SEV 1011) (T13, T23) |
| SAE_J3400 | 43 | Tesla Connector | North American Charging Standard (NACS, SAE J3400) |
| DOMESTIC_A | 48 | Domestic plug/socket type A (NEMA 1-15, 2 pins) | Domestic plug/socket type A (NEMA 1-15, 2 pins) |
| DOMESTIC_C | 49 | Domestic plug/socket type C (CEE 7/17, 2 pins) | Domestic plug/socket type C (CEE 7/17, 2 pins) |
| IEC_62196_T3A | 50 | IEC 62196-2 type 3a (SCAME) | Type 3a |
| NEMA_14_50 | 51 | Domestic plug/socket type B (NEMA 14-50) | Domestic plug/socket type B (NEMA 14-50) |
| GBT_AC | 52 | GB/T (Chinese) AC connector | GB/T (Chinese) AC connector |
| GBT_DC | 53 | GB/T (Chinese) DC connector | GB/T (Chinese) DC connector |
| NEMA_6_50 | 55 | Domestic plug/socket type B (NEMA 6-50) | Domestic plug/socket type B (NEMA 6-50) |
| CHAOJI | 56 | ChaoJi connector (CHAdeMO 3.0) | ChaoJi |
| DOMESTIC_N | 57 | Domestic plug/socket type N (NBR 14136, 3 pins) | Domestic plug/socket type N (NBR 14136, 3 pins) |
| DOMESTIC_O | 58 | Domestic plug/socket type O (TIS 166-2549, 3 pins) | Domestic plug/socket type O (TIS 166-2549, 3 pins) |
| NEMA_6_30 | 59 | Domestic plug/socket type B (NEMA 6-30) | Domestic plug/socket type B (NEMA 6-30) |
| NEMA_10_30 | 60 | Domestic plug/socket type B (NEMA 10-30) | Domestic plug/socket type B (NEMA 10-30) |
| NEMA_10_50 | 61 | Domestic plug/socket type B (NEMA 10-50) | Domestic plug/socket type B (NEMA 10-50) |
| NEMA_14_30 | 62 | Domestic plug/socket type B (NEMA 14-30) | Domestic plug/socket type B (NEMA 14-30) |
| PANTOGRAPH_BOTTOM_UP | 63 | Bus-up pantograph (SAE J3105-2) | Bus-up pantograph (SAE J3105-2) |
| PANTOGRAPH_TOP_DOWN | 64 | Cross-rail pantograph (SAE J3105-1) | Cross-rail pantograph (SAE J3105-1) |
| TESLA_R | 65 | Tesla Connector R | Tesla Roadster connector |
| MCS | 67 | MCS (Megawatt Charging System) | Megawatt Charging System (MCS) |
| TESLA_S | 68 | Tesla Proprietary Connector (TESLA_S) | Tesla connector Model-S-type (oval, 5 pin). Compatible with Tesla car models only. See NACS for further information |
| CONNECTOR_TYPE_UNDEFINED | 0 | Not used | |
| UNRECOGNIZED | 1 | Not used | |
| 2 | Not used | ||
| 3 | Small Paddle Inductive | Deprecated | |
| 4 | Large Paddle Inductive | Deprecated | |
| 10 | Domestic plug/socket type E+F (CEE 7/7) | Deprecated | |
| 14 | Domestic plug/socket type I (CPCS-CCC) | Deprecated | |
| 15 | Domestic plug/socket type I (IRAM 2073) | Deprecated | |
| 16 | Domestic plug/socket type J (SEV 1011) (T13) | Deprecated | |
| 17 | Domestic plug/socket type J (SEV 1011) (T15) | Deprecated | |
| 18 | Domestic plug/socket type J (SEV 1011) (T23) | Deprecated | |
| 19 | Domestic plug/socket type J (SEV 1011) (T25) | Deprecated | |
| 21 | Domestic plug/socket type K (Thailand TIS 166 - 2549) | Deprecated | |
| 24 | Domestic plug/socket type IEC 60906-1 (3 pin) | Deprecated | |
| 25 | AVCON Connector | Deprecated | |
| 26 | Tesla Connector (high power wall) | Deprecated | |
| 27 | Tesla Connector (universal mobile) | Deprecated | |
| 28 | Tesla Connector (spare mobile) | Deprecated | |
| 37 | IEC 60309 : industrial 2P + E (AC) | Deprecated | |
| 38 | IEC 60309 : industrial P + N + E (AC) (CEEPlus) | Deprecated | |
| 39 | IEC 60309 : industrial 3P + N + E (AC) (CEEPlus) | Deprecated | |
| 40 | Better place plug/socket | Deprecated | |
| 41 | Marechal plug/socket | Deprecated | |
| 44 | IEC 61851-1 | Deprecated | |
| 45 | IEC 62196-2 type 2 (SAE J1772) | Deprecated | |
| 46 | IEC 60309 : industrial 2P + E (DC) | Deprecated | |
| 47 | I-type AS/NZ 3112 (Australian 15A/240V) | Deprecated | |
| 54 | IEC 62196-2 type 2 | Deprecated | |
| 66 | Domestic plug/socket type M (BS 546, 3 pin, 15A) | Deprecated |
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).
| EV API v3 | EV API v2 | OCPI definition |
|---|---|---|
| AVAILABLE | AVAILABLE | The EVSE or connector is able to start a new charging session. |
| BLOCKED | UNAVAILABLE | The EVSE or connector is not accessible because of a physical barrier, commonly a car parking in front of the charging point. |
| CHARGING | OCCUPIED | The EVSE or connector is in use. |
| INOPERATIVE | OUT_OF_SERVICE | The EVSE or connector is not yet active, or temporarily not available for use, but not broken/defect. |
| OUTOFORDER | OUT_OF_SERVICE | The EVSE or connector is currently out of order, one or more parts or components may have failed |
| PLANNED | OFFLINE | EVSE or connector planned, operating soon. |
| REMOVED | OFFLINE | EVSE or connector discontinued/removed. |
| RESERVED | RESERVED | EVSE or connector reserved for a particular EV driver and unavailable for other drivers. |
| UNKNOWN | OTHER | No status information available (also used when offline). |
| OPERATIONAL | OTHER | Non-OCPI status for offline use cases |
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 exposes ad hoc (pay‑as‑you‑go) pricing only. Subscription‑based pricing and charging via eMSPs or CPO charge cards are not supported.
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
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.
Non-supported pre-calculated values
EV Charge Points API v2 exposes some attributes that are not included in EV Charge Points API v3 but can be derived on the client side using the more granular data model introduced in EV Charge Points API v3.
totalNumberOfConnectorscan be calculated by counting the connector objects returned in the response. Alternatively, the total number of connectors can be derived by summing theconnectorCountvalues provided underconnectorGroups.powerFeedTypeprovided 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 underevses, including:powerType(AC or DC),maxVoltage, andmaxCurrent.customerChargeLevelprovided a precomputed classification of charging speed categories based on the maximum supported charging power at connector type level. In the EV Charge Points API v3, the same information is represented throughconnectorGroupsas amaxPowervalue, expressed in watts (W).stationIdcan 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 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.
EV Charge Points APIs: differences explained
| Item | EVCP API v2 | Search API with EV | EVCP API v3 |
|---|---|---|---|
| Schema | Proprietary eMI3-based | Proprietary eMI3-based | OCPI 2.x-based |
| Discovery | EVCP API v2 | Search API | Search API HERE Map Content |
| Customer Profile | Legacy | Basic | Advanced |
| Basic POI attributes (id, name, coordinates, address, route points) | YES | YES | YES |
| EV Charge Point attributes (accessibility, Operator, eMSP) | YES | YES | YES |
| EVSE attributes (EVSE identification, payment methods) | YES Limited | YES Limited | YES |
| Connector attributes (connector type, format, power type, current, voltage, max power) | YES | YES | YES |
| Dynamic availabity status | YES | YES | YES |
| Prices (tariffs) | Ad-hoc | NO | Ad-hoc Subscription (eMSP + CPO) |
| Extended EVCP attributes (restriction reason, parking type, energy mix, facilities, nearby places) | NO | NO | YES |
| Vehicle categories | NO | As filter | YES |
| Truck attributes (truck type, dimensions, restrictions, parking) | NO | NO | YES Truck addon |
| Predictions and reliability | NO | NO | YES Predictions addon |
Further Reading
Updated 3 days ago