How to get country coverage for eMSPs, CPOs, and connector details

This tutorial explains how to use the HERE EV Charge Points API v3 to retrieve details about supported Charge Point Operators (CPOs) and e-Mobility Service Providers (eMSPs), and connector types and maximum power levels by country.

The information is available via the countryMetadata endpoint. For more information, see the API reference.

Prerequisites

Before you start, complete your HERE platform onboarding and obtain application credentials. For more information about onboarding and credentials, see Get started.

This section requires you to understand basic requests in the HERE EV Charge Points API v3 API as covered in Get one or multiple charging locations.

HTTP call to the endpoint

To access the HERE EV Charge Points API v3 countryMetadata endpoint, send this request:

GET /v3/countryMetadata
Host: evcp.hereapi.com
User-Agent: curl/8.6.0
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

The following examples all use cURL syntax.

List the supported countries

To get a list of full EV data country coverage, call the HERE EV Charge Points API v3 endpoint countryMetadata as follows:

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata" | jq

The response contains the country codes (ISO 3166-1 alpha 3) in alphabetical order for all the countries with EV data:

{
  "countries": [
    {
      "countryCode": "ABW"
    },
    {
      "countryCode": "ALA"
    },
    ...
    {
      "countryCode": "VNM"
    },
    {
      "countryCode": "ZAF"
    }
  ]
}

Global CPO support

To get a list of all the countries and CPOs in each country, call the HERE EV Charge Points API v3 endpoint countryMetadata with the query parameter fields=operators:

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=operators" | jq

The response contains the CPOs present in each country separately:

{
  "countries": [
    {
      "countryCode": "ABW",
      "operators": [
        {
          "name": "Blink Charging",
          "partnerId": "2db7622a-cca5-11ed-b4aa-42010aa40002"
        },
        ...
        {
          "name": "Dynaf (USD)",
          "partnerId": "e37c524c-5de5-11ee-8c2c-42010aa40002"
        }
      ]
    },
    {
      "countryCode": "ALA",
      "operators": [
        {
          "name": "ABC-lataus",
          "partnerId": "fad11a0c-e09c-11ed-91cb-42010aa40002"
        },
        ...
        {
          "name": "Virta",
          "partnerId": "2ddbbf76-cca5-11ed-9f0f-42010aa40002"
        }
      ]
    },
    ...
    {
      "countryCode": "VNM",
      "operators": [
        {
          "name": "vinfast",
          "partnerId": "3a632824-cca5-11ed-8029-42010aa40002"
        }
      ]
    },
    {
      "countryCode": "ZAF",
      "operators": [
        {
          "name": "AUDI",
          "partnerId": "295adedc-cca5-11ed-8fa2-42010aa40002"
        },
        ...
        {
          "name": "Virta",
          "partnerId": "2ddbbf76-cca5-11ed-9f0f-42010aa40002"
        }
      ]
    }
  ]
}

Global eMSP support

To get a list of all the countries and eMSPs in each country, call the HERE EV Charge Points API v3 endpoint countryMetadata with the query parameter fields=eMobilityServiceProviders:

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=eMobilityServiceProviders" | jq

The response contains the eMSPs present in each country separately:

{
  "countries": [
    {
      "countryCode": "ABW",
      "eMobilityServiceProviders": [
        {
          "name": "ChargePoint",
          "partnerId": "1f90fdf0-cca5-11ed-be23-42010aa40002"
        },
        ...
        {
          "name": "EVgo",
          "partnerId": "2d6527bc-cca5-11ed-803a-42010aa40002"
        }
      ]
    },
    {
      "countryCode": "ALA",
      "eMobilityServiceProviders": [
        {
          "name": "Bosch",
          "partnerId": "268699a8-cca5-11ed-951e-42010aa40002"
        },
        ...
        {
          "name": "Travel Card",
          "partnerId": "1f97d800-cca5-11ed-aef4-42010aa40002"
        }
      ]
    },
    ...
    {
      "countryCode": "VNM",
      "eMobilityServiceProviders": [
        {
          "name": "vinfast",
          "partnerId": "3a632824-cca5-11ed-8029-42010aa40002"
        }
      ]
    },
    {
      "countryCode": "ZAF",
      "eMobilityServiceProviders": [
        {
          "name": "Aral Pulse",
          "partnerId": "2ba02436-cca5-11ed-bbf3-42010aa40002"
        },
        ...
        {
          "name": "Vattenfall InCharge",
          "partnerId": "1f3c093a-cca5-11ed-bb19-42010aa40002"
        }
      ]
    }
  ]
}

eMSP/CPO support with named tariffs

Lists of eMSPs/CPOs may contain additional information about specific tariffs names for a partner.

These names may be useful when working with Tariffs.

To get a list of all the countries and CPOs in each country, call the HERE EV Charge Points API v3 endpoint countryMetadata with the query parameter fields=operators,tariffs:

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=operators,tariffs" | jq

Response:

{
  "countries": [
    {
      "countryCode": "ABW",
      "operators": [
        {
          "name": "Dynaf (USD)",
          "partnerId": "e37c524c-5de5-11ee-8c2c-42010aa40002"
        }
      ]
    },
    {
      "countryCode": "ALB",
      "operators": [
        {
          "name": "bp pulse",
          "partnerId": "226512fa-cca5-11ed-8bd5-42010aa40002"
        },
        {
          "name": "ChargeFox",
          "partnerId": "2fee53b4-cca5-11ed-ab04-42010aa40002",
          "tariffs": [
            {
              "name": "Chargefox - subscription"
            }
          ]
        },
        {
          "name": "ChargeHub",
          "partnerId": "0b185e3a-cfb6-11ee-a712-42010aa40002"
        },
        [...]
        {
          "name": "Zero Carbon Charge",
          "partnerId": "f1e9f8f8-a72b-11ef-8130-42010aa40019"
        }
      ]
    }
  ]
}

Some items for CPO may contain a tariffs field, which is an array of objects with a name field. A name field contains the name of the tariff for the partner. You can use this to filter tariffs in the Get Tariffs for connector groups or EVSE tutorial.

To get a list of tariffs for each eMSP, you can use the same modifier tariffs with eMobilityServiceProviders.

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=eMobilityServiceProviders,tariffs" | jq

Returns a list of eMSPs, some of which may have the same tariffs field mentioned in the context of CPOs.

Global Connector Types and Maximum Power Levels

To retrieve a list of countries with their available connector types and maximum power levels, call the countryMetadata endpoint of HERE EV Charge Points API v3 and include the query parameter: fields=connectorTypes:

Please read more about the maximum power levels from connectors tutorial

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=connectorTypes" | jq

The response includes the connector types and the maximum power levels available for each country individually.

{
  "countries": [
    {
      "countryCode": "ABW",
      "connectorTypes": [
        {
          "standard": "IEC_62196_T1",
          "commonName": "Type 1 (SAE J1772)",
          "maxPower": 7400
        },
        {
          "standard": "IEC_62196_T2",
          "commonName": "Type 2",
          "maxPower": 22000
        }
      ]
    },
    {
      "countryCode": "ALB",
      "connectorTypes": [
        {
          "standard": "CHADEMO",
          "commonName": "CHAdeMO",
          "maxPower": 50000
        },
        {
          "standard": "IEC_62196_T2",
          "commonName": "Type 2",
          "maxPower": 22000
        },
        {
          "standard": "IEC_62196_T2_COMBO",
          "commonName": "CCS2",
          "maxPower": 50000
        }
      ]
    },
    ...
        {
      "countryCode": "VNM",
      "connectorTypes": [
        {
          "standard": "IEC_62196_T2",
          "commonName": "Type 2",
          "maxPower": 22000
        },
        {
          "standard": "IEC_62196_T2_COMBO",
          "commonName": "CCS2",
          "maxPower": 360000
        }
      ]
    },
    {
      "countryCode": "ZAF",
      "connectorTypes": [
        {
          "standard": "CHADEMO",
          "commonName": "CHAdeMO",
          "maxPower": 75000
        },
        {
          "standard": "DOMESTIC_A",
          "commonName": "Country specific domestic plug/socket",
          "maxPower": 12800
        },
        {
          "standard": "IEC_62196_T2",
          "commonName": "Type 2",
          "maxPower": 32000
        },
        {
          "standard": "IEC_62196_T2_COMBO",
          "commonName": "CCS2",
          "maxPower": 400000
        }
      ]
    }
  ]
}

Country-specific CPO support

To get a list of CPOs for a set of countries, call the HERE EV Charge Points API v3 endpoint countryMetadata with the query parameter fields=operators&countryCodes=<country codes>. For example, to get a list of supported CPOs for Finland and Sweden, call:

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=operators&countryCodes=FIN,SWE" | jq

The response contains the CPOs supported in Finland and Sweden separately:

{
  "countries": [
    {
      "countryCode": "FIN",
      "operators": [
        {
          "name": "ABB",
          "partnerId": "23391ea6-cca5-11ed-8146-42010aa40002"
        },
        ...
        {
          "name": "VV-Autotalot Oy",
          "partnerId": "2c1dee84-cca5-11ed-adbb-42010aa40002"
        }
      ]
    },
    {
      "countryCode": "SWE",
      "operators": [
        {
          "name": "AB Hufvudstaden",
          "partnerId": "268de15e-cca5-11ed-9622-42010aa40002"
        },
        ...
        {
          "name": "Willys Vimmerby",
          "partnerId": "0cc7d3ca-d09a-11ee-b286-42010aa40002"
        }
      ]
    }
  ]
}

You can always use the modifier tariffs if you use operators or eMobilityServiceProviders.

Country-specific eMSP support

To get a list of eMSPs for a set of countries, call the HERE EV Charge Points API v3 endpoint countryMetadata with the query parameter fields=eMobilityServiceProviders&countryCodes=<country codes>. For example, to get a list of supported eMSPs for Finland and Sweden, call:

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=eMobilityServiceProviders&countryCodes=FIN,SWE" | jq

The response contains the eMSPs supported in Finland and Sweden separately:

{
  "countries": [
    {
      "countryCode": "FIN",
      "eMobilityServiceProviders": [
        {
          "name": "Alfen",
          "partnerId": "1f48288c-cca5-11ed-9bbe-42010aa40002"
        },
        ...
        {
          "name": "Vattenfall InCharge",
          "partnerId": "1f3c093a-cca5-11ed-bb19-42010aa40002"
        }
      ]
    },
    {
      "countryCode": "SWE",
      "eMobilityServiceProviders": [
        {
          "name": "Alfen",
          "partnerId": "1f48288c-cca5-11ed-9bbe-42010aa40002"
        },
        ...
        {
          "name": "ZSE",
          "partnerId": "27ea9cae-cca5-11ed-a4e4-42010aa40002"
        }
      ]
    }
  ]
}

Connector Types and Maximum Power Levels by Country

To get a list of connector types and maximum power levels for specific countries, call the countryMetadata endpoint of HERE EV Charge Points API v3 with the following query parameters:

curl -H "Authorization: Bearer $ACCESS_TOKEN" "https://evcp.hereapi.com/v3/countryMetadata?fields=connectorTypes&countryCodes=FIN,JPN" | jq

Please read more about the maximum power levels from connectors tutorial For example, to retrieve connector types and maximum power levels for Finland and Japan, use:

{
  "countries": [
    {
      "countryCode": "FIN",
      "connectorTypes": [
        {
          "standard": "CHADEMO",
          "commonName": "CHAdeMO",
          "maxPower": 200000
        },
        {
          "standard": "DOMESTIC_F",
          "commonName": "Country specific domestic plug/socket",
          "maxPower": 3700
        },
        {
          "standard": "IEC_62196_T2",
          "commonName": "Type 2",
          "maxPower": 43000
        },
        {
          "standard": "IEC_62196_T2_COMBO",
          "commonName": "CCS2",
          "maxPower": 400000
        }
      ]
    },
    {
      "countryCode": "JPN",
      "connectorTypes": [
        {
          "standard": "CHADEMO",
          "commonName": "CHAdeMO",
          "maxPower": 200000
        },
        {
          "standard": "IEC_62196_T1",
          "commonName": "Type 1 (SAE J1772)",
          "maxPower": 3000
        },
        {
          "standard": "TESLA_S",
          "commonName": "Tesla connector",
          "maxPower": 250000
        }
      ]
    }
  ]
}