Locations module

Module Identifier: locations

The Location objects live in the CPO back-end system. They describe the charging locations of that operator.

Module dependency: the eMSP endpoint is dependent on the Tariffs module

1. Flow and Lifecycle

The Locations module has Locations as base object, Locations have EVSEs, EVSEs have Connectors. With the methods in the eMSP interface, Location information/statuses can be shared with the eMSP. Updates can be done to the Location, but also to only an EVSE or a Connector.

When a CPO creates Location objects it pushes them to the eMSPs by calling PUT on the eMSPs Locations endpoint. Providers who do not support push mode need to call GET on the CPOs Locations endpoint to receive the new object.

If the CPO wants to replace a Location related object, they push it to the eMSP systems by calling PUT on their Locations endpoint.

Any changes to a Location related object can also be pushed to the eMSP by calling the PATCH on the eMSPs Locations endpoint. Providers who do not support push mode need to call GET on the CPOs Locations endpoint to receive the updates.

When the CPO wants to delete an EVSE they must update by setting the status field to REMOVED and call the PUT or PATCH on the eMSP system. A Location without valid EVSE objects can be considered as expired and should no longer be displayed. There is no direct way to delete a location.

When the CPO is not sure about the state or existence of a Location, EVSE or Connector object in the eMSPs system, the CPO can call the GET to validate the object in the eMSP system.

2. Interfaces and endpoints

There is both a CPO and an eMSP interface for Locations. Advised is to use the push direction from CPO to eMSP during normal operation. The CPO interface is meant to be used when the connection between 2 parties is established, to retrieve the current list of Location objects with the current status, and when the eMSP is not 100% sure the Locations cache is completely correct. The eMSP can use the CPO GET Object interface to retrieve a specific Location, EVSE or Connector, this might be used by a eMSP that wants information about a specific Location, but has not implemented the eMSP Locations interface (cannot receive push).

2.1 CPO Interface

Example endpoint structure: /ocpi/cpo/2.0/locations

<div><!-- ---------------------------------------------------------------------------- --></div>

2.1.1 GET Method

Depending on the URL Segments provided, the GET request can either be used to retrieve information about a list of available locations and EVSEs at this CPO: GET List Or it can be used to get information about a specific Location, EVSE or Connector: GET Object

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

GET List Request Parameters

Example endpoint structures for retrieving a list of Locations: /ocpi/cpo/2.0/locations/?date_from=xxx&date_to=yyy /ocpi/cpo/2.0/locations/?offset=50 /ocpi/cpo/2.0/locations/?limit=100 /ocpi/cpo/2.0/locations/?offset=50&limit=100

If additional parameters: {date_from} and/or {date_to} are provided, only Locations with (last_updated) between the given date_from and date_to will be returned. If an EVSE is updated, also the 'parent' Location's last_updated fields is updated. If a Connector is updated, the EVSE's last_updated and the Location's last_updated field are updated.

This request is paginated, it supports the pagination related URL parameters.

<div><!-- ---------------------------------------------------------------------------- --></div>

GET List Response Data

The endpoint returns a list of Location objects The header will contain the pagination related headers.

Any older information that is not specified in the response is considered no longer valid. Each object must contain all required fields. Fields that are not specified may be considered as null values.

<div><!-- ---------------------------------------------------------------------------- --></div>

GET Object Request Parameters

Example endpoint structures for a specific Location, EVSE or Connector: /ocpi/cpo/2.0/locations/{location_id} /ocpi/cpo/2.0/locations/{location_id}/{evse_uid} /ocpi/cpo/2.0/locations/{location_id}/{evse_uid}/{connector_id}

The following parameters can be provided as URL segments.

<div><!-- ---------------------------------------------------------------------------- --></div>

GET Object Response Data

The response contains the requested object.

<div><!-- ---------------------------------------------------------------------------- --></div>

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

2.2 eMSP Interface

Locations is a client owned object, so the end-points need to contain the required extra fields: {party_id} and {country_code}. Example endpoint structures: /ocpi/emsp/2.0/locations/{country_code}/{party_id}/{location_id} /ocpi/emsp/2.0/locations/{country_code}/{party_id}/{location_id}/{evse_uid} /ocpi/emsp/2.0/locations/{country_code}/{party_id}/{location_id}/{evse_uid}/{connector_id}

<div><!-- ---------------------------------------------------------------------------- --></div>

2.2.1 GET Method

If the CPO wants to check the status of a Location, EVSE or Connector object in the eMSP system, it might GET the object from the eMSP system for validation purposes. The CPO is the owner of the objects, so it would be illogical if the eMSP system had a different status or was missing an object. If a discrepancy is found, the CPO might push an update to the eMSP via a PUT or PATCH call.

Request Parameters

The following parameters can be provided as URL segments.

<div><!-- ---------------------------------------------------------------------------- --></div>

Response Data

The response contains the requested object.

<div><!-- ---------------------------------------------------------------------------- --></div>

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

2.2.2 PUT Method

The CPO pushes available Location/EVSE or Connector objects to the eMSP. PUT is used to send new Location objects to the eMSP, or to replace existing Locations.

Request Parameters

This is an information push message, the objects pushed will not be owned by the eMSP. To make distinctions between objects being pushed to an eMSP from different CPOs, the {party_id} and {country_code} have to be included in the URL, as URL segments.

<div><!-- ---------------------------------------------------------------------------- --></div>

Request Body

The request contains the new/updated object.

<div><!-- ---------------------------------------------------------------------------- --></div>

2.2.3 PATCH Method

Same as the PUT method, but only the fields/objects that have to be updated have to be present, other fields/objects that are not specified are considered unchanged.

Example: a simple status update

This is the most common type of update message to notify eMSPs that an EVSE (EVSE with uid 3255 of Charge Point 1012) is now occupied.

PATCH To URL: https://www.server.com/ocpi/emsp/2.0/locations/NL/TNM/1012/3255
 
{
	"status": "CHARGING"
}

Example: change the location name

In this example the name of location 1012 is updated.

PATCH To URL: https://www.server.com/ocpi/emsp/2.0/locations/NL/TNM/1012
 
{
	"name": "Interparking Gent Zuid"
}

Example: set tariff update

In this example connector 2 of EVSE 1 of Charge Point 1012, receives a new pricing scheme.

PATCH To URL: https://www.server.com/ocpi/emsp/2.0/locations/NL/TNM/1012/3255/2
 
{
    "tariff_id": "15"
}

Example: add an EVSE

To add an EVSE, simply put the full object in an update message, including all its required fields. Since the id is new, the receiving party will know that it is a new object. When not all required fields are specified, the object may be discarded.

PUT To URL: https://www.server.com/ocpi/emsp/2.0/locations/NL/TNM/1012/3256
 
{
	"uid": "3256",
	"evse_id": "BE-BEC-E041503003",
	"status": "AVAILABLE",
	"capabilities": ["RESERVABLE"],
	"connectors": [
		{
			"id": "1",
			"standard": "IEC_62196_T2",
			"format": "SOCKET",
			"tariff_id": "14"
		}
	],
	"physical_reference": 3,
	"floor_level": -1
}

Example: delete an EVSE

An EVSE can be deleted by updating its status property.

PATCH To URL: https://www.server.com/ocpi/emsp/2.0/locations/NL/TNM/1012/3256
 
{
	"status": "REMOVED"
}

Note: To inform that an EVSE is scheduled for removal, the status_schedule field can be used.

3. Object description

Location, EVSE and Connector have the following relation.

3.1 Location Object

The Location object describes the location and its properties where a group of EVSEs that belong together are installed. Typically the Location object is the exact location of the group of EVSEs, but it can also be the entrance of a parking garage which contains these EVSEs. The exact way to reach each EVSE can be further specified by its own properties.

<div><!-- ---------------------------------------------------------------------------- --></div>

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

Example

{
	"id": "LOC1",
	"type": "ON_STREET",
	"name": "Gent Zuid",
	"address": "F.Rooseveltlaan 3A",
	"city": "Gent",
	"postal_code": "9000",
	"country": "BEL",
	"coordinates": {
		"latitude": "51.047599",
		"longitude": "3.729944"
	},
	"evses": [{
        "uid": "3256",
		"evse_id": "BE-BEC-E041503001",
		"status": "AVAILABLE",
		"status_schedule": [],
		"capabilities": [
			"RESERVABLE"
		],
		"connectors": [{
			"id": "1",
			"standard": "IEC_62196_T2",
			"format": "CABLE",
			"power_type": "AC_3_PHASE",
			"voltage": 220,
			"amperage": 16,
			"tariff_id": "11",
            "last_updated": "2015-03-16T10:10:02Z"
		}, {
			"id": "2",
			"standard": "IEC_62196_T2",
			"format": "SOCKET",
			"power_type": "AC_3_PHASE",
			"voltage": 220,
			"amperage": 16,
			"tariff_id": "11",
        	"last_updated": "2015-03-18T08:12:01Z"
		}],
		"physical_reference": "1",
		"floor_level": "-1",
     	"last_updated": "2015-06-28T08:12:01Z"
	}, {
        "uid": "3257",
		"evse_id": "BE-BEC-E041503002",
		"status": "RESERVED",
		"capabilities": [
			"RESERVABLE"
		],
		"connectors": [{
			"id": "1",
			"standard": "IEC_62196_T2",
			"format": "SOCKET",
			"power_type": "AC_3_PHASE",
			"voltage": 220,
			"amperage": 16,
			"tariff_id": "12",
			"last_updated": "2015-06-29T20:39:09Z"
		}],
		"physical_reference": "2",
		"floor_level": "-2",
     	"last_updated": "2015-06-29T20:39:09Z"
	}],
	"operator": {
		"name": "BeCharged"
	},
	"last_updated": "2015-06-29T20:39:09Z"
}

3.2 EVSE Object

The EVSE object describes the part that controls the power supply to a single EV in a single session. It always belongs to a Location object. It will only contain directions to get from the location to the EVSE (i.e. floor, physical_reference or directions). When these properties are insufficient to reach the EVSE from the Location point, then it typically indicates that this EVSE should be put in a different Location object (sometimes with the same address but with different coordinates/directions).

An EVSE object has a list of connectors which can not be used simultaneously: only one connector per EVSE can be used at the time.

<div><!-- ---------------------------------------------------------------------------- --></div>

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

3.3 Connector Object

A connector is the socket or cable available for the EV to use. A single EVSE may provide multiple connectors but only one of them can be in use at the same time. A connector always belongs to an EVSE object.

<div><!-- ---------------------------------------------------------------------------- --></div>

4. Data types

4.1 AdditionalGeoLocation class

This class defines an additional geo location that is relevant for the Charge Point. The geodetic system to be used is WGS 84.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.1 BusinessDetails class

<div><!-- ---------------------------------------------------------------------------- --></div>

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

4.2 Capability enum

The capabilities of an EVSE.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.3 ConnectorFormat enum

The format of the connector, whether it is a socket or a plug.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.4 ConnectorType enum

The socket or plug standard of the charging point.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.5 EnergyMix class

This type is used to specify the energy mix and environmental impact of the supplied energy at a location or in a tariff.

<div><!-- ------------------------------------------------------------------------------------------------------------------------- --></div>

* These fields can be used to look-up energy qualification or to show it directly to the customer (for well-known brands like Greenpeace Energy, etc.)

Examples

Simple:

"energy_mix": {
	"is_green_energy": true
    }

Tariff name based:

"energy_mix": {
	"is_green_energy":     true,
	"supplier_name":       "Greenpeace Energy eG",
	"energy_product_name": "eco-power"
    }

Complete:

"energy_mix": {
	"is_green_energy": false,
	"energy_sources": [
			{ "source": "GENERAL_GREEN",  "percentage": 35.9 },
			{ "source": "GAS",            "percentage": 6.3  },
			{ "source": "COAL",           "percentage": 33.2 },
			{ "source": "GENERAL_FOSSIL", "percentage": 2.9 },
			{ "source": "NUCLEAR",        "percentage": 21.7 }
		],
	"environ_impact": [
			{ "source": "NUCLEAR_WASTE",  "amount": 0.0006   },
			{ "source": "CARBON_DIOXIDE", "amount": 372      }
		],
	"supplier_name":       "E.ON Energy Deutschland",
	"energy_product_name": "E.ON DirektStrom eco"
    }

4.6 EnergySource class

Key-value pairs (enum + percentage) of energy sources. All given values should add up to 100 percent per category.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.7 EnergySourceCategory enum

Categories of energy sources.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.8 EnvironmentalImpact class

Key-value pairs (enum + amount) of waste and carbon dioxide emittion per kWh.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.9 EnvironmentalImpactCategory enum

Categories of environmental impact values.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.10 ExceptionalPeriod class

Specifies one exceptional period for opening or access hours.

<div><!-- ---------------------------------------------------------------------------- --></div>

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -->

4.11 Facility enum

<div><!-- ---------------------------------------------------------------------------- --></div>

4.12 GeoLocation class

This class defines the geo location of the Charge Point. The geodetic system to be used is WGS 84.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.13 Hours class

Opening and access hours of the location.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.14 Image class

This class references images related to a EVSE in terms of a file name or url. According to the roaming connection between one EVSE Operator and one or more Navigation Service Providers the hosting or file exchange of image payload data has to be defined. The exchange of this content data is out of scope of OCHP. However, the recommended setup is a public available web server hosted and updated by the EVSE Operator. Per charge point an unlimited number of images of each type is allowed. Recommended are at least two images where one is a network or provider logo and the second is a station photo. If two images of the same type are defined they should be displayed additionally, not optionally.

Photo Dimensions: The recommended dimensions for all photos is a minimum of 800 pixels wide and 600 pixels height. Thumbnail representations for photos should always have the same orientation as the original with a size of 200 to 200 pixels.

Logo Dimensions: The recommended dimensions for logos are exactly 512 pixels wide and 512 pixels height. Thumbnail representations for logos should be exactly 128 pixels in width and height. If not squared, thumbnails should have the same orientation as the original.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.15 ImageCategory enum

The category of an image to obtain the correct usage in a user presentation. The category has to be set accordingly to the image content in order to guarantee the right usage.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.16 LocationType enum

Reflects the general type of the charge points location. May be used for user information.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.17 ParkingRestriction enum

This value, if provided, represents the restriction to the parking spot for different purposes.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.18 PowerType enum

<div><!-- ---------------------------------------------------------------------------- --></div>

4.19 RegularHours class

Regular recurring operation or access hours

<div><!-- ---------------------------------------------------------------------------- --></div>

4.19.1 Example

Operating on weekdays from 8am till 8pm with one exceptional opening on 22/6/2014 and one exceptional closing the Monday after:

  "opening_times": {
    "regular_hours": [
      {
        "weekday": 1,
        "period_begin": "08:00",
        "period_end": "20:00"
      },
      {
        "weekday": 2,
        "period_begin": "08:00",
        "period_end": "20:00"
      },
      {
        "weekday": 3,
        "period_begin": "08:00",
        "period_end": "20:00"
      },
      {
        "weekday": 4,
        "period_begin": "08:00",
        "period_end": "20:00"
      },
      {
        "weekday": 5,
        "period_begin": "08:00",
        "period_end": "20:00"
      }
    ],
    "twentyfourseven": false,
    "exceptional_openings": [
      {
        "period_begin": "2014-06-21T09:00:00Z",
        "period_end": "2014-06-21T12:00:00Z"
      }
    ],
    "exceptional_closings": [
      {
        "period_begin": "2014-06-24T00:00:00Z",
        "period_end": "2014-06-25T00:00:00Z"
      }
    ]
  }

This represents the following schedule, where stroked out days are without operation hours, bold days are where exceptions apply and regular displayed days are where the regular schedule applies.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.20 Status enum

The status of an EVSE.

<div><!-- ---------------------------------------------------------------------------- --></div>

4.21 StatusSchedule class

This type is used to schedule status periods in the future. The eMSP can provide this information to the EV user for trip planning purpose. A period MAY have no end. Example: "This station will be running as of tomorrow. Today it is still planned and under construction."

<div><!-- ---------------------------------------------------------------------------- --></div>

Note that the scheduled status is purely informational. When the status actually changes, the CPO must push an update to the EVSEs status field itself.

5. Schema & Examples

Below are the JSON Schemas and example payloads for this module, embedded inline.

Schemas

Examples