Use the locations endpoint to retrieve a list of all locations or a specific location (using the location's id).

📘

Note

The location information is retrieved in bulk. Eco-Movement recommends that you retrieve the entire dataset once a day.

Request

See locations and locations/{id} to know more about the parameters that are used with the two versions of the locations endpoint.

Response

The following is a sample response for the locations endpoint:

{
    data: [ 
    
        { location 1 
            [
                { EVSE 1 
                    [{ connnector 1 },{ connector 2 }]},
                { EVSE 2 
                    [{...},{...}]}
            ]
        },
        
        { location 2 [{...}]},
        
    ], 
}

📘

Note

Use the "Try It!" button in locations and locations/{id} to view an actual response from our API.

The following table describes the main objects in the response of the locations endpoint:

Main ObjectDescription
LocationA location is a group of one or more EVSEs that logically belong together. For example, all the charge points at a roadside service area.
EVSEAn EVSE is a spot where a single EV can charge. An EVSE may provide multiple connectors, but only one of these connectors can be active at the same time. This is similar to the various diesel and petrol nozzles present at a single dispenser.
ConnectorA connector is a specific socket or cable available for the electric vehicle.

🚧

Caution

Eco-Movement always upholds the API contract, but we may send new attributes in our JSON response when:

  • we add an OCPI mandatory attribute to the JSON response to be OCPI compliant
  • we improve your licensing module with new features

Hence, we strongly recommend that you handle or ignore unknown JSON fields.

Response Definitions

The main objects consist of several OCPI and Eco-Movement custom attributes.

Standard OCPI Attributes

The following are the standard attributes of OCPI 2.1.1:

AttributeDescription
data.idThe unique id for a location. It is created by Eco-Movement, and it is stable. This attribute may change when two or more locations are merged, which results in one location only.
data.typeIndicates the type of location where the charge point is located. It holds one of the following values:

- ON_STREET
- PARKING_GARAGE
- UNDERGROUND_GARAGE
- PARKING_LOT
- OTHER
- UNKNOWN
data.addressThe street and house number where the charge point is located.
data.cityThe name of the city where the charge point is located.
data.postal_codeThe postal code where the charge point is located. It conforms to the country standard.
data.countryThe ISO 3166-1 alpha-3 code for the country of this location.
data.coordinatesThe coordinates of the location in decimal degrees.
data.coordinates.latitudeThe latitude of the location in decimal degrees.
data.coordinates.longitudeThe longitude of the location in decimal degrees.
data.last_updatedIndicates when the location data was last updated. The date is in ISO 8601 standard and the time zone is UTC. The update could be a status update or any other update (for example, coordinates update).
data.nameThe name of the location.
data.ownerThe details of the location's owner.

Note: The partner_id and ema_id attributes are created by Eco-Movement. Hence, these attributes are described in Eco-Movement Attributes.
data.owner.nameThe name of the location's owner.
data.owner.websiteThe website of the location's owner.
data.operatorThe name and website of the operator of the charge points in the location.

Note: The partner_id and ema_id attributes are created by Eco-Movement. Hence, these attributes are described in Eco-Movement Attributes.
data.operator.nameThe name of the location's operator.
data.operator.websiteThe website of the location's operator.
data.suboperatorThe name and website of the suboperator of the charge points in the location.

Note: The partner_id and ema_id attributes are created by Eco-Movement. Hence, these attributes are described in Eco-Movement Attributes.
data.suboperator.nameThe name of the location's suboperator.
data.suboperator.websiteThe website of the location's suboperator.
data.opening_timesIndicates if the location is always open or has certain opening and closing times.
data.charging_when_closedIndicates if the EVSEs can be used for charging outside the opening hours of the location. For example, when the parking garage closes its barriers overnight, this attribute indicates if you can still charge until the next morning.
data.time_zoneThe time zone of the location. It is one of www.iana.org tzdata's TZ-values representing the time zone of the location.
data.energy_mixDescribes the energy mix and environmental impact of the supplied energy at the location.
data.energy_mix.is_green_energyIndicates true if the supplied energy at the location is 100% from regenerative sources. (CO2 and nuclear waste is zero.)
data.energy_mix.supplier_nameThe name of the energy supplier that delivers the energy for the location.
data.energy_mix.energy_product_nameThe name of the energy supplier's product that is used at the location.
data.energy_mix.energy_sourcesThe type of energy source and the percentage.
data.energy_mix.energy_sources.sourceThe type of energy source. The different types of energy sources are:

- NUCLEAR: Nuclear power source

- GENERAL_FOSSIL: All kinds of fossil power sources

- COAL: Fossil power form coal

- GAS: Fossil power from gas

- GENERAL_GREEN: All kinds of regenerative power sources

- SOLAR: Regenerative power from PV

- WIND: Regenerative power from wind turbines

- WATER: Regenerative power from water turbines
data.energy_mix.energy_sources.percentageThe percentage of the source (0%-100%) in the mix.
data.energy_mix.environ_impactThe environmental impact of nuclear waste and CO2 exhaust of the location.
data.energy_mix.environ_impact.sourceThe type of pollutant. The different types of pollutants are:

- NUCLEAR_WASTE: Produced nuclear waste in grams per kilowatt-hour.

- CARBON_DIOXIDE: Exhausted carbon dioxide in grams per kilowatt-hour.
data.energy_mix.environ_impact.amountThe amount of nuclear waste produced or carbon dioxide exhausted in grams per kilowatt-hour.
data.evses.uidThe unique ID of an EVSE in the system of the CPO. It is created by the CPO and is not unique within Eco-Movement's database.

Note: Use this attribute for PATCH requests as an evse's id.
data.evses.statusIndicates if an EVSE is available for charging or not. It is the real-time status of an EVSE, which is monitored and noise-filtered by Eco-Movement. It can be one of the following:

- AVAILABLE
- BLOCKED
- CHARGING
- INOPERATIVE
- OUTOFORDER
- PLANNED
- REMOVED
- RESERVED
- UNKNOWN
data.evses.capabilitiesThe capabilities of an EVSE. This attribute conforms to OCPI 2.1.1 and is only filled if it is supplied by the CPO. The different types of EVSE capabilities are:

- CHARGING_PROFILE_CAPABLE
- REMOTE_START_STOP_CAPABLE
- CREDIT_CARD_PAYABLE
- RESERVABLE
- RFID_READER
- UNLOCK_CAPABLE
data.evses.last_updatedIndicates when the EVSE data was last updated. The date is in ISO 8601 standard and the time zone is UTC. The update could be a status update or any other update (for example, capabilities update).
data.evses.physical_referenceA number or string printed on the outside of the EVSE for visual identification.

Note: This attribute is limited to 16 characters.
data.evses.evse_idThe unique ID of an EVSE for the outside world. It is unique across all databases, but it is not always available. It is compliant with "eMI3standard version V1.0".

Eco-Movement provides a special endpoint for requesting with this id. See evse endpoint in the API reference guide for more information about using the evse endpoint.
data.evses.parking_restrictionsIndicates if there are any restrictions to the parking lot. This attribute is only filled if it is supplied by the CPO. The different types of parking restrictions are:

- EV_ONLY
- PLUGGED
- DISABLED
- CUSTOMERS
- MOTORCYCLES
data.evses.connectors.idThe identifier of the connector within the EVSE created by the CPO. Two connectors may have the same id as long as they do not belong to the same EVSE object.
data.evses.connectors.standardThe socket or plug standard of the charging point. The standards are:

- CHADEMO: The connector type is CHAdeMO, DC

- DOMESTIC_A: Standard or Domestic household, type "A", NEMA 1-15, 2 pins

- DOMESTIC_B: Standard or Domestic household, type "B", NEMA 5-15, 3 pins

- DOMESTIC_C: Standard or Domestic household, type "C", CEE 7/17, 2 pins

- DOMESTIC_D: Standard or Domestic household, type "D", 3 pin

- DOMESTIC_E: Standard or Domestic household, type "E", CEE 7/5 3 pins

- DOMESTIC_F: Standard or Domestic household, type "F", CEE 7/4, Schuko, 3 pins

- DOMESTIC_G: Standard or Domestic household, type "G", BS 1363, Commonwealth, 3 pins

- DOMESTIC_H: Standard or Domestic household, type "H" SI-32, 3 pins

- DOMESTIC_I: Standard or Domestic household, type "I", AS 3112, 3 pins

- DOMESTIC_J: Standard or Domestic household, type "J", SEV 1011, 3 pins

- DOMESTIC_K: Standard or Domestic household, type "K", DS 60884-2-D1, 3 pins

- DOMESTIC_L: Standard or Domestic household, type "L", CEI 23-16-VII, 3 pins

- IEC_60309_2_single_16: IEC 60309-2 Industrial Connector single phase 16 Amperes (usually blue)

- IEC_60309_2_three_16: IEC 60309-2 Industrial Connector three phase 16 Amperes (usually red)

- IEC_60309_2_three_32: IEC 60309-2 Industrial Connector three phase 32 Amperes (usually red)

- IEC_60309_2_three_64: IEC 60309-2 Industrial Connector three phase 64 Amperes (usually red)

- IEC_62196_T1: IEC 62196 Type 1 "SAE J1772"

- IEC_62196_T1_COMBO: Combo Type 1 based, DC

- IEC_62196_T2: IEC 62196 Type 2 “Mennekes”

- IEC_62196_T2_COMBO: Combo Type 2 based, DC

- IEC_62196_T3A: IEC 62196 Type 3A

- IEC_62196_T3C: IEC 62196 Type 3C "Scame"

- TESLA_R: Tesla Connector "Roadster" - Type (round, 4 pin)

- TESLA_S: Tesla Connector "Model-S" - Type (oval, 5 pin)
data.evses.connectors.formatThe format of the connector. It can be one of the following formats:

- SOCKET
- CABLE
data.evses.connectors.power_typeThe power type of the connector. The different power types are:

- AC_3_PHASE
- AC_1_PHASE
- DC
data.evses.connectors.voltageThe voltage of the connector. This attribute is validated and corrected by Eco-Movement.
data.evses.connectors.amperageThe amperage of the connector. This attribute is validated and corrected by Eco-Movement.
data.evses.connectors.tariff_idCorresponds to the tariffs module. This attribute shows the CPO ad hoc prices. See tariffs endpoint for more information.
data.evses.connectors.last_updatedIndicates when the connector data was last updated. The date is in ISO 8601 standard and the time zone is UTC. The update could be a status update or any other update (for example, voltage update).

Eco-Movement Attributes

The following attributes were additionally created by Eco-Movement. They are not standard in the OCPI protocol. These attributes can be included in the request.

AttributeDescription
data.access_typeEco-Movement classifies all locations as "Public", "Restricted", or "Private". The last category is filtered out by default. "Restricted" locations can be at a hotel, shop, office, etc., and the specific restrictions are shown under separate attributes.
data.location_typeThis attribute is enriched using Eco-Movement's research methods to improve the value in the data.type attribute.
data.location_type.codeIndicates the type of location where a charge point is located. The different types of locations are:

- ALONG_MOTORWAY
- PARKING_GARAGE
- PARKING_LOT
- ON_STREET
data.location_type.descriptionThe description of the location type.

Note: Currently, this attribute's value is a copy of data.location_type.code's value, but it will be updated in the future.
data.facilitiesA list of nearby custom facilities derived by Eco-Movement.

Eco-Movement is only partially OCPI compliant for this attribute because we do not share irrelevant facilities or duplicates or because the information is already available in other attributes. Hence, we deliver more facilities than are available in the OCPI enum.

The facilities that we provide are:

- AIRPORT
- BUSINESS
- BUS_STOP
- CAFE
- CARPOOL_PARKING
- EDUCATION
- FINANCE
- FUEL_STATION
- HEALTH
- HOTEL
- MALL
- MUSEUM
- NATURE
- OTHER
- RECREATION_AREA
- RESTAURANT
- SERVICE
- SPORT
- STORE
- SUPERMARKET
- TRAIN_STATION
data.owner.partner_idThe unique id for an owner. It is created by Eco-Movement, and it is stable.
data.owner.ema_idThe E-Mobility Account Identifier (eMA ID) for the owner. It is created by Eco-Movement by combining the country code where the charging station is located, and the party id of the owner. For example, NL-ECO.

Note: An owner can have multiple eMA IDs. For example, if a company named 'Example Company A' acquired 'Example Company B' and owns the charging stations of Example Company B, then this attribute maps Example Company B's eMA IDs to Example Company A's eMA IDs. For example, ["NL-EXA", "NL-EXB"].
data.operator.partner_idThe unique id for an operator. It is created by Eco-Movement, and it is stable.
data.operator.ema_idThe E-Mobility Account Identifier (eMA ID) for the operator. It is created by Eco-Movement by combining the country code where the charging station is located, and the party id of the operator. For example, NL-ECO.

Note: An operator can have multiple eMA IDs. For example, if a company named 'Example Company A' acquired 'Example Company B' and operates the charging stations of Example Company B, then this attribute maps Example Company B's eMA IDs to Example Company A's eMA IDs. For example, ["NL-EXA", "NL-EXB"].
data.suboperator.partner_idThe unique id for a suboperator. It is created by Eco-Movement, and it is stable.
data.suboperator.ema_idThe E-Mobility Account Identifier (eMA ID) for the suboperator. It is created by Eco-Movement by combining the country code where the charging station is located, and the party id of the suboperator. For example, NL-ECO.

Note: An operator can have multiple eMA IDs. For example, if a company named 'Example Company A' acquired 'Example Company B' and operates the charging stations of Example Company B, then this attribute maps Example Company B's eMA IDs to Example Company A's eMA IDs. For example, ["NL-EXA", "NL-EXB"].
data.brand_nameThe name and website of the main brand that is operating the charging station.

Note: If suboperator is available, then the brand name is the suboperator's name. If suboperator is not available, then the brand name is the operator's name.
data.related_locationsDescribes up to five facilities that are closest to the charge point's location.
data.related_locations.latitudeThe latitude of a facility that is closest to the location of the charge point.
data.related_locations.longitudeThe longitude of a facility that is closest to the location of the charge point.
data.related_locations.nameThe name of a facility that is closest to the location of the charge point.
data.support_phone_numberThe phone number that EV drivers should call when they need assistance at the charge location.
data.roamingA list of all the major MSP cards that are accepted at this location and their details.
data.roaming.emspThe provider of the MSP card.
data.roaming.partner_idThe unique id for a provider. It is created by Eco-Movement, and it is stable.
data.roaming.ema_idThe unique E-Mobility Account Identifier (eMA ID) for a provider. It is created by Eco-Movement by combining the country code where the charging station is located, and the party id of the provider. For example, NL-ECO.

Note: A provider can have multiple eMA IDs. For example, if a company named 'Example Company A' acquired 'Example Company B' and owns the charging stations of Example Company B, then this attribute maps Example Company B's eMA IDs to Example Company A's eMA IDs. For example, ["NL-EXA", "NL-EXB"].
data.roaming.cardThe name of the MSP card.
data.roaming.android_app_linkThe link to the MSP's Android app.
data.roaming.ios_app_linkThe link to the MSP's iOS app.
data.derived_opening_timesAn Eco-Movement algorithm looks at the charging history and discovers patterns using the history. The opening times are created based on these patterns.
data.derived_opening_times.regular_hoursThe opening and closing hours of the location on a particular day of the week.
data.derived_opening_times.regular_hours.weekdayThe number of the day in the week. It starts from Monday (1) and ends in Sunday (7).
data.derived_opening_times.regular_hours.period_beginThe beginning of the regular period in hours and minutes.
data.derived_opening_times.regular_hours.period_endThe ending of the regular period in hours and minutes.
data.derived_opening_times.twentyfoursevenIndicates if the location is always open or has certain opening and closing times.
data.heavy_vehiclesDescribes the dimensions and restrictions for heavy vehicles.
data.heavy_vehicles.heavy_vehicles_heightThe maximum height of the heavy vehicle that is allowed to be parked at the charging station.
data.heavy_vehicles.heavy_vehicles_widthThe maximum width of the heavy vehicle that is allowed to be parked at the charging station.
data.heavy_vehicles.heavy_vehicles_lengthThe maximum length of the heavy vehicle that is allowed to be parked at the charging station.
data.heavy_vehicles.heavy_vehicles_massThe maximum mass of the heavy vehicle that is allowed to be parked at the charging station.
data.heavy_vehicles.heavy_vehicles_restrictionsThe applicable restrictions for the heavy vehicle. The values are:

- N1 - Only N1 type of heavy vehicles can be parked at the charging station. N1 vehicles have a maximum mass not exceeding 3.5 tonnes (7,700 lbs).
- N2 - Only N2 type of heavy vehicles can be parked at the charging station. N2 vehicles have a maximum mass exceeding 3.5 tonnes but not exceeding 12 tonnes (26,000 lbs).
- N3 - Only N3 type of heavy vehicles can be parked at the charging station. N3 vehicles have a maximum mass exceeding 12 tonnes (26,000 lbs).
- N1, N2 - N1 and N2 type of heavy vehicles can be parked at the charging station.
- N1, N2, N3 - N1, N2, and N3 type of heavy vehicles can be parked at the charging station.
- N3+O4 - N3 type of heavy vehicles having O4 type of trailers can be parked at the charging station. N3 vehicles have a maximum mass exceeding 12 tonnes (26,000 lbs) and O4 trailers have a maximum mass exceeding 10 tonnes (22000 lbs).
- UNKNOWN - The restrictions are currently unknown.
data.heavy_vehicles.heavy_vehicles_facilitiesA list of facilities in the location. Facilities can be:

- TRUCK PARKING
- TRUCK WASH
- TRUCK REPAIR
- TRUCK DEALERSHIP
- SECURE TRUCK PARKING
- UNKNOWN
data.heavy_vehicles.heavy_vehicles_dedicatedIndicates whether the location was constructed mainly for the purpose of heavy vehicles like trucks or not.
data.heavy_vehicles.heavy_vehicles_trailer_accessibilityIndicates whether the location is suitable for trucks with trailers or not.
data.heavy_vehicles.heavy_vehicles_drive_throughIndicates whether the location is drive-though or not.
data.heavy_vehicles.heavy_vehicles_dangerous_goodsIndicates whether the location allows charging of heavy vehicles transporting dangerous goods.
data.heavy_vehicles.heavy_vehicles_rigid_vehiclesIndicates whether the location is suitable for rigid heavy vehicles or not.
data.heavy_vehicles.heavy_vehicles_overnight_parkingIndicates whether the location allows overnight charging of heavy vehicles or not.
data.vehicle_dimensionsDescribes the maximum allowed dimensions for any vehicle at the location.
data.vehicle_dimensions.verified_mass_kgThe maximum weight for a vehicle that is allowed at the location in kilograms.
data.vehicle_dimensions.verified_width_mThe maximum width for a vehicle that is allowed at the location in metres.
data.vehicle_dimensions.verified_height_mThe maximum height for a vehicle that is allowed at the location in metres.
data.vehicle_dimensions.verified_length_mThe maximum length for a vehicle that is allowed at the location in metres.
data.administrative_areasThe administrative area for the location.
data.administrative_areas.state_provinceThe state or province where the charging station is located.
data.administrative_areas.municipalityThe municipality where the charging station is located.
data.predicted_occupancyEco-Movement uses this feature to predict the occupancy of the location. The values are updated daily, predicting hour by hour the likelihood of occupancy for the upcoming 7 days. They are based on historical trend lines of seasons, years, months, weeks, and days. Hence, this attribute is accurate and relevant for the EV driver.
data.predicted_occupancy.weekdayThe number of the day in the week. It starts from Monday (1) and ends in Sunday (7).
data.predicted_occupancy.period_beginThe beginning of the time period. The Z after the time indicates that it is in UTC.
data.predicted_occupancy.period_endThe ending of the time period. The Z after the time indicates that it is in UTC.
data.predicted_occupancy.occupancyIndicates the occupancy on a scale from 1 to 10, where 1 means the location is available for charging and 10 means the location is fully occupied.
data.adhoc_authorisation_payment_methodIndicates the authentication and payment methods. The methods are:

- AUTH_BY_CAR_PLUG&CHARGE
- ONLINE_APPLE_PAY
- TERMINAL_IN_APP
- ONLINE_PAYPAL
- SERVICE_PROVIDER_RFID_CARD
- TERMINAL_QR_CODE
- TERMINAL_CREDIT_CARD
- TERMINAL_DEBIT_CARD
- TERMINAL_SMS
- ONLINE_CREDIT_CARD
- OTHER_OTHER
- TERMINAL_CONTACTLESS
- ONLINE_GOOGLE_PAY
- ONLINE_BANK_PAYMENT
- AUTH_BY_CAR_AUTOCHARGE
data.adhoc_authorisation_methodThe custom field for the available ad hoc payment methods. The different types of ad hoc payment methods are:

- CREDIT_CARD
- DEBIT_CARD
- MEMBERSHIP_APP
- MEMBERSHIP_CARD
- OTHER
- OTHER_Apple_Pay
- OTHER_Authentication_by_car
- OTHER_Google_Pay
- QR_CODE
- SMS

Note: In OCPI protocol, there is a standard field named "Capabilities", which is similar, but limited.
data.reliability_score_2Indicates the reliability score of the location. This attribute indicates when the charging points at a location are operating normally, but it does not have details regarding expected occupancy. The algorithm considers the frequency of recent usage (more recent is more relevant) and recent downtime. For example, a score of 1 is the least reliable, and a score of 5 is the most reliable.

Note: A score of 0 indicates that the reliability score is not available for the location yet.
data.charging_behaviourThis attribute relies on AI and it is verified by scientific research. Based on real-time information, the charging behaviour of users is divided into groups.
data.charging_behaviour.codeIndicates the code for the type of charging behaviour. The codes are:

- 1: Urban charging

- 2: Fast charging

- 3: Mixed charging

- 4: Noise charging

- 5: Overnight charging

- 6: Office charging
data.charging_behaviour.descriptionThe description of the charging behaviour.
data.location_categoryThe type of location where a charge point is located. For example, shop.
data.entrance_for_navigationThe coordinates for the location's entrances in decimal degrees. If available, there can be more than one entrances to the location.

Note: This attribute is available only for locations that contain data.location_type.code as ALONG_MOTORWAY.
data.entrance_for_navigation.nameThe name of the entrance. For example, motorway exit.
data.entrance_for_navigation.latitudeThe latitude of a location's entrance in decimal degrees.
data.entrance_for_navigation.longitudeThe longitude of a location's entrance in decimal degrees.
data.number_physical_unitsThe total number of DC physical units at the location.
data.restrictionsThe applicable restrictions at the location. The different types of restrictions are:

- ONLY_CUSTOMERS
- ONLY_TRUCKS
- ONLY_2_WHEELERS
- ONLY_BUS
- ONLY_BRAND
- ONLY_CARSHARING
- ONLY_TAXIS
- ONLY_RESIDENTIAL
- ONLY_EMPLOYEES
- TIME_RESTRICTED
data.evses.hardware_manufacturerThe manufacturer of the charging station's hardware.
data.evses.hardware_classThis attribute is not available yet.
data.evses.hardware_modelThe model of the charging station's hardware.
data.evses.cpo_external_idThe unique ID of the location in the system of the CPO.

This attribute is registered at location level in the system of the CPO, but Eco-Movement stores it at EVSE level. This is because we sometimes merge or split locations to improve the user experience.
data.evses.last_successful_chargeIndicates when the EVSE last had a successful charge. The date is in ISO 8601 standard and the time zone is UTC.
data.evses.connectors.pricing_idCorresponds with id from Prices (Deprecated).

Note: It is created by Eco-Movement and is refreshed whenever a price or product associated with that particular id is updated.
data.evses.connectors.max_powerThe maximum power is calculated by Eco-Movement based on the voltage and amperage.

Note: This attribute is created by Eco-Movement. It does not exist in OCPI 2.1.1 and you can request the attribute as an extra feature.

📘

Note

For the predicted_occupancy, roaming, and derived_opening_times attributes, you must use a location's id parameter behind the locations endpoint in a GET request. Use the "Try It!" button in locations/{id} to use the locations endpoint with a location's id and view an actual response from our API.

If you are interested in receiving these attributes with the bulk request, please contact us. Please note that only 500 results are returned instead of 1000 results with this feature.