OCPI v2.2.1

Introduction

This API uses the oAuth2 client credentials grant type to secure all the communications. For more information, check the Authentication/Authorization guide.

The OCPI API is organized around REST and GraphQL. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

This API provides users with the ability to manage credentials, locations, sessions, tariffs, tokens and charge detail records (CDRs) for electric vehicle (EV) charging infrastructure. Additionally, the GraphQL endpoint allows for more flexible queries and mutations against the data.

This API uses the oAuth2 client credentials grant type to secure all communications. All requests to the API must be authenticated using a bearer token. For more information, check the Authentication/Authorization guide.

Use Cases

The OCPI API provides a robust and efficient way for operators to manage their electric vehicle (EV) charging infrastructure. By leveraging both REST and GraphQL endpoints, users can streamline operations, enhance real-time data access, and improve the overall user experience for both administrators and end-users.

• Digital Transformation for Charging Network Operators

  The OCPI API enables operators to modernize their charging infrastructure management with a simple and intuitive user interface, real-time data access, and comprehensive functionalities.

• New Digital Experience for Operators

  Operators can now interact with a user-friendly digital platform that simplifies the process of managing locations, sessions, tariffs, tokens, and CDRs. The API supports intuitive UIs and provides preview options for real-time data visualization.

• Real-Time Data Management

  With real-time data capabilities, operators can create, update, and synchronize data across all connected systems instantly. This reduces the time and effort required to manage the charging infrastructure and ensures data consistency across the network.

• Improved Session and Tariff Management

  Operators can efficiently manage charging sessions and pricing tariffs, ensuring accurate billing and optimal resource utilization. Access detailed information about specific sessions, including start/end times, energy consumption, and costs. Access comprehensive tariff information to ensure transparent and accurate billing.

• Flexible Data Queries

  Use GraphQL to perform complex queries and retrieve customized data sets for detailed analysis.

Benefits

The primary focus is on enhancing the management experience for EV charging network operators. The benefits of using the OCPI API include:

• Enhanced Operational Efficiency

  Simplified resource management with intuitive interfaces and real-time synchronization of data across multiple systems.

• Flexibility and Customization

  Ability to perform complex queries and operations using GraphQL and use detailed and customizable data retrieval options.

• Improved Data Accuracy and Reliability

  Real-time data validation and error feedback and a comprehensive logging and monitoring of all API interactions.

• Security and Compliance

  Secure communications using OAuth2 client credentials. Compliance with industry standards for data protection.

• Real-Time Error Feedback

  The API provides immediate validation and error feedback for all operations, reducing the likelihood of data entry errors and enabling operators to quickly identify and resolve issues.

• Comprehensive Reporting and Analytics

  The OCPI API supports detailed reporting and analytics, providing operators with valuable insights into the performance and utilization of their charging infrastructure.

Quick Start Guide for EMobility OCPI API

This API is secured by OAuth 2.0. It uses the 'Client Credentials' Grant Type to allow the API consumer to access data. The process is details with the diagram below.

Base URLs

Auth API

EMobility OCPI API

1. Request Client ID and Secret

Contact Shell API Team in order to request access to OAuth authentication.

2. Generate and provide Client ID and Secret

Shell API team will generate the credentials and you will be intimated via email with all the details.

3. Request Access Token

Once you receive the credentials next step is to call the /token.oauth2 endpoint to authenticate. Below are the key parameters.

Key request parameters

Sample request

curl --location --request POST 'https://api-test.shell.com/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**************' \
--data-urlencode 'client_secret=**************' \
--data-urlencode 'grant_type=client_credentials'

4. Get an access token

On receiving the request Shell Authorizaton system will verify all the parameters in the request and, if everything checks out, it will generate your access token and return it in the response.

Key response parameters

The response will contain the following parameters:

Sample response

{
  "access_token": "**************",
  "expires_in": "899",
  "token_type": "Bearer"
}

Note: Make a note that the expires_in is always in seconds.

5. Call the Functional API

While calling Shell API’s include the following in the header of the request. Note the space after Bearer.

Authorization: "Bearer " + access_token

Note: This endpoint doesn't return refresh token. Hence in case the bearer token expires the same endpoint should be called to retrieve new bearer token

Troubleshooting authentication

The following table lists common authentication errors and possible causes:

All error scenarios are returned with a response body and identifier. Few examples below for

Example 1 : HTTP 400 - Bad Request

{
  "ErrorCode": "invalid_request",
  "Error": "Unsupported grant type : client_credential"
}

Example 2 : HTTP 401 - Unauthorized

{
  "ErrorCode": "invalid_client",
  "Error": "ClientId is Invalid"
}

Fundamentals

Requests

The EMobility OCPI API provides a set of endpoints, each with its unique path. It is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format. List of verbs in EMobility OCPI API:

• GET - Retrieve data.

Responses

The responses always include a JSON object. Check the API documentation to find descriptions of common responses for each endpoint.

Response Status Codes

The EMobility OCPI API uses the following response status codes defined in RFC 2616 and RFC 6585.

• 200 - The request has succeeded. The Partner application can read the result of the request in the body and the headers of the response.
• 400 - Bad request. Due to malformed syntax, the server could not understand the request. The body will contain more information.
• 401 - Unauthorized. The request requires user authentication, and it has been refused for those credentials.
• 403 - Forbidden. The server understood the request but is refusing to fulfill it.
• 404 - Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
• 422 - Unprocessable content. The server understood the request but is unable to process it.
• 500 - Internal Server Error. This error should not happen but if you receive it, something went wrong, please report it to us.

Client Status Codes

Requests that reach the endpoints should return an OCPI response message with a status_code field as defined below.

• 1xxx - The request has succeeded.
• 2xxx - Client errors – The data sent by the client can not be processed by the server.
• 3xxx - Server errors – The server encountered an internal error.
• 4xxx - Hub errors – For errors that a Hub encounters while routing messages, the following OCPI status codes shall be used.

1xxx: Success

• 1000 - Generic success code.
• 19xx - Reserved range for custom success status codes (1900-1999).

2xxx: Client errors

• 2000 - Generic client error.
• 2001 - Invalid or missing parameters.
• 2002 - Not enough information, for example: Authorization request with too little information.
• 2003 - Unknown Location, for example: Command: START_SESSION with unknown location.
• 2004 - Unknown Token, for example: 'real-time' authorization of an unknown Token.
• 29xx - Reserved range for custom client error status codes (2900-2999).

3xxx: Server errors

• 3000 - Generic server error.
• 3001 - Unable to use the client’s API. For example during the credentials registration: When the initializing party requests data from the other party during the open POST call to its credentials endpoint. If one of the GETs can not be processed, the party should return this error in the POST response.
• 3002 - Unsupported version.
• 3003 - No matching endpoints or expected endpoints missing between parties. Used during the registration process if the two parties do not have any mutual modules or endpoints available, or the minimum expected by the other party implementation.
• 39xx - Reserved range for custom server error status codes (3900-3999).

4xxx: Hub errors

• 4000 - Generic error.
• 4001 - Unknown receiver (TO address is unknown).
• 4002 - Timeout on forwarded request (message is forwarded, but request times out).
• 4003 -Connection problem (receiving party is not connected).
• 49xx - Reserved range for custom hub error status codes (4900-4999).

Response Schemas

All success scenarios are returned with the same response body structure:

{
  "data": [{}],
  "status_code": 0,
  "status_message": "string",
  "timestamp": "2024-07-16T16:54:24.063Z"
}

Response Error Schemas

All error scenarios are returned with the same response body structure:

{
  "status_code": 0,
  "status_message": "string",
  "timestamp": "2024-07-16T16:54:24.063Z"
}

Versioning

Your API version controls the API behavior you see (what properties you see in responses, what parameters you're allowed to send in requests, and so on). Your version is set in the URL. When a breaking change is introduced to the EMobility OCPI API, an updated version is released. The current version is v1. This is the only version available at this moment.

Backwards-compatible changes

We consider the following changes to be backward-compatible:

• Adding new API resources.
• Adding new optional request parameters to existing API endpoints.
• Adding new properties to existing API responses.
• Changing the order of properties in existing API responses.
• Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.

Pagination

All GET methods that return a list of objects have pagination, this allows a client and server to control the amount of objects returned in the response to a GET request, while still enabling the client to retrieve all objects by doing multiple request with different parameters. Without pagination the server had to return all objects in one response that could potentially contain millions of objects. To enable pagination of the returned list of objects, additional URL parameters are allowed for the GET request.

Pagination request

Example: With offset=0 and limit=10 the server shall return the first 10 records (if 10 objects match the request). Then next page starts with offset=10.

Pagination response

HTTP headers that have to be added to any paginated GET response.

Cardinality

Security

The EMobility OCPI API forces HTTPS for all services using TLS (SSL).

The EMobility OCPI API does not require client side certificates for authentication, only server side certificates in order to setup a secure SSL connection.

Types

List endpoints and resource name

• Get all Locations
• Get a particular Location
• Get a particular EVSE
• Get a particular Connector
• Get all Tariffs
• Get a particular Tariff
• Get all Sessions
• Get a particular Session
• Get all CDRs
• Get a particular CDR
• Send a command

Get all Locations

Introduction

This API, will return the private charging locations.

The API also provide further search options to filter the result set.

• Based on the last updated date between two given dates.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/locations/?date_from=xxx&date_to=yyy' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a array of JSON objects with:

Sample Response

[
  {
    "id": "LOC1",
    "type": "ON_STREET",
    "name": "Gent Zuid",
    "address": "F.Rooseveltlaan 3A",
    "city": "Gent",
    "postal_code": "9000",
    "country": "BEL",
    "coordinates": {
      "latitude": "51.04759",
      "longitude": "3.72994"
    },
    "evses": [
      {
        "uid": "3256",
        "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",
        "id": "BE-BEC-E041503002",
        "status": "RESERVED",
        "capabilities": ["RESERVABLE"],
        "connectors": [
          {
            "id": "1",
            "status": "RESERVED",
            "standard": "IEC_62196_T2",
            "format": "SOCKET",
            "power_type": "AC_3_PHASE",
            "voltage": 220,
            "amperage": 16,
            "tariff_id": "12"
          }
        ],
        "physical_reference": "2",
        "floor_level": "-2",
        "last_updated": "2015-06-29T20:39:09Z"
      }
    ],
    "operator": {
      "name": "BeCharged"
    },
    "last_updated": "2015-06-29T20:39:09Z"
  }
]

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get a particular Location

Introduction

This API, will return a private charging location.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/locations/LOC1' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a JSON object with:

Sample Response

{
  "id": "LOC1",
  "type": "ON_STREET",
  "name": "Gent Zuid",
  "address": "F.Rooseveltlaan 3A",
  "city": "Gent",
  "postal_code": "9000",
  "country": "BEL",
  "coordinates": {
    "latitude": "51.04759",
    "longitude": "3.72994"
  },
  "evses": [
    {
      "uid": "3256",
      "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",
      "id": "BE-BEC-E041503002",
      "status": "RESERVED",
      "capabilities": ["RESERVABLE"],
      "connectors": [
        {
          "id": "1",
          "status": "RESERVED",
          "standard": "IEC_62196_T2",
          "format": "SOCKET",
          "power_type": "AC_3_PHASE",
          "voltage": 220,
          "amperage": 16,
          "tariff_id": "12"
        }
      ],
      "physical_reference": "2",
      "floor_level": "-2",
      "last_updated": "2015-06-29T20:39:09Z"
    }
  ],
  "operator": {
    "name": "BeCharged"
  },
  "last_updated": "2015-06-29T20:39:09Z"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get a particular EVSE

Introduction

This API, will return a EVSE from private charging location.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/locations/LOC1/3256' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a JSON object with:

Sample Response

{
  "uid": "3256",
  "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"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get a particular Connector

Introduction

This API, will return a EVSE's Connector from private charging location.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/locations/LOC1/3256/1' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a JSON object with:

Sample Response

{
  "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"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get all Tariffs

This API, will return the private charging tariffs.

The API also provide further search options to filter the result set.

• Based on the last updated date between two given dates.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/tariffs/?date_from=xxx&date_to=yyy' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a array of JSON object with:

Sample Response

[
  {
    "country_code": "DE",
    "party_id": "ALL",
    "id": "20",
    "currency": "EUR",
    "min_price": {
      "excl_vat": 0.5,
      "incl_vat": 0.55
    },
    "elements": [
      {
        "price_components": [
          {
            "type": "ENERGY",
            "price": 0.25,
            "vat": 10.0,
            "step_size": 1
          }
        ]
      }
    ],
    "last_updated": "2018-12-17T16:45:21Z"
  },
  {
    "country_code": "DE",
    "party_id": "ALL",
    "id": "14",
    "currency": "EUR",
    "type": "REGULAR",
    "tariff_alt_url": "https://company.com/tariffs/14",
    "elements": [
      {
        "price_components": [
          {
            "type": "FLAT",
            "price": 2.5,
            "vat": 15.0,
            "step_size": 1
          }
        ]
      },
      {
        "price_components": [
          {
            "type": "TIME",
            "price": 1.0,
            "vat": 20.0,
            "step_size": 900
          }
        ],
        "restrictions": {
          "max_current": 32.0
        }
      },
      {
        "price_components": [
          {
            "type": "TIME",
            "price": 2.0,
            "vat": 20.0,
            "step_size": 600
          }
        ],
        "restrictions": {
          "min_current": 32.0,
          "day_of_week": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY",
            "THURSDAY",
            "FRIDAY"
          ]
        }
      },
      {
        "price_components": [
          {
            "type": "TIME",
            "price": 1.25,
            "vat": 20.0,
            "step_size": 600
          }
        ],
        "restrictions": {
          "min_current": 32.0,
          "day_of_week": ["SATURDAY", "SUNDAY"]
        }
      },
      {
        "price_components": [
          {
            "type": "PARKING_TIME",
            "price": 5.0,
            "vat": 10.0,
            "step_size": 300
          }
        ],
        "restrictions": {
          "start_time": "09:00",
          "end_time": "18:00",
          "day_of_week": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY",
            "THURSDAY",
            "FRIDAY"
          ]
        }
      },
      {
        "price_components": [
          {
            "type": "PARKING_TIME",
            "price": 6.0,
            "vat": 10.0,
            "step_size": 300
          }
        ],
        "restrictions": {
          "start_time": "10:00",
          "end_time": "17:00",
          "day_of_week": ["SATURDAY"]
        }
      }
    ],
    "last_updated": "2015-06-29T20:39:09Z"
  }
]

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get a particular Tariff

This API, will return the private charging particular tariff.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/tariffs/{tariff_id}' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a JSON object with:

Sample Response

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "14",
  "currency": "EUR",
  "type": "REGULAR",
  "tariff_alt_url": "https://company.com/tariffs/14",
  "elements": [
    {
      "price_components": [
        {
          "type": "FLAT",
          "price": 2.5,
          "vat": 15.0,
          "step_size": 1
        }
      ]
    },
    {
      "price_components": [
        {
          "type": "TIME",
          "price": 1.0,
          "vat": 20.0,
          "step_size": 900
        }
      ],
      "restrictions": {
        "max_current": 32.0
      }
    },
    {
      "price_components": [
        {
          "type": "TIME",
          "price": 2.0,
          "vat": 20.0,
          "step_size": 600
        }
      ],
      "restrictions": {
        "min_current": 32.0,
        "day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
      }
    },
    {
      "price_components": [
        {
          "type": "TIME",
          "price": 1.25,
          "vat": 20.0,
          "step_size": 600
        }
      ],
      "restrictions": {
        "min_current": 32.0,
        "day_of_week": ["SATURDAY", "SUNDAY"]
      }
    },
    {
      "price_components": [
        {
          "type": "PARKING_TIME",
          "price": 5.0,
          "vat": 10.0,
          "step_size": 300
        }
      ],
      "restrictions": {
        "start_time": "09:00",
        "end_time": "18:00",
        "day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
      }
    },
    {
      "price_components": [
        {
          "type": "PARKING_TIME",
          "price": 6.0,
          "vat": 10.0,
          "step_size": 300
        }
      ],
      "restrictions": {
        "start_time": "10:00",
        "end_time": "17:00",
        "day_of_week": ["SATURDAY"]
      }
    }
  ],
  "last_updated": "2015-06-29T20:39:09Z"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get all Sessions

This API, will return the private charging sessions.

The API also provide further search options to filter the result set.

• Based on the last updated date between two given dates.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/sessions/?date_from=xxx&date_to=yyy' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a array of JSON object with:

Sample Response

[
  {
    "country_code": "NL",
    "party_id": "STK",
    "id": "101",
    "start_date_time": "2020-03-09T10:17:09Z",
    "kwh": 0.0,
    "cdr_token": {
      "uid": "123abc",
      "type": "RFID",
      "contract_id": "NL-TST-C12345678-S"
    },
    "auth_method": "WHITELIST",
    "location_id": "LOC1",
    "evse_uid": "3256",
    "connector_id": "1",
    "currency": "EUR",
    "total_cost": {
      "excl_vat": 2.5
    },
    "status": "PENDING",
    "last_updated": "2020-03-09T10:17:09Z"
  },
  {
    "country_code": "BE",
    "party_id": "BEC",
    "id": "101",
    "start_date_time": "2015-06-29T22:39:09Z",
    "end_date_time": "2015-06-29T23:50:16Z",
    "kwh": 41.0,
    "cdr_token": {
      "uid": "123abc",
      "type": "RFID",
      "contract_id": "NL-TST-C12345678-S"
    },
    "auth_method": "WHITELIST",
    "location_id": "LOC1",
    "evse_uid": "3256",
    "connector_id": "1",
    "currency": "EUR",
    "charging_periods": [
      {
        "start_date_time": "2015-06-29T22:39:09Z",
        "dimensions": [
          {
            "type": "ENERGY",
            "volume": 120
          },
          {
            "type": "MAX_CURRENT",
            "volume": 30
          }
        ]
      },
      {
        "start_date_time": "2015-06-29T22:40:54Z",
        "dimensions": [
          {
            "type": "ENERGY",
            "volume": 41000
          },
          {
            "type": "MIN_CURRENT",
            "volume": 34
          }
        ]
      },
      {
        "start_date_time": "2015-06-29T23:07:09Z",
        "dimensions": [
          {
            "type": "PARKING_TIME",
            "volume": 0.718
          }
        ],
        "tariff_id": "12"
      }
    ],
    "total_cost": {
      "excl_vat": 8.5,
      "incl_vat": 9.35
    },
    "status": "COMPLETED",
    "last_updated": "2015-06-29T23:50:17Z"
  }
]

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get a particular Session

This API, will return the private charging particular session.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/sessions/{session_id}' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a JSON object with:

Sample Response

{
  "country_code": "BE",
  "party_id": "BEC",
  "id": "101",
  "start_date_time": "2015-06-29T22:39:09Z",
  "end_date_time": "2015-06-29T23:50:16Z",
  "kwh": 41.0,
  "cdr_token": {
    "uid": "123abc",
    "type": "RFID",
    "contract_id": "NL-TST-C12345678-S"
  },
  "auth_method": "WHITELIST",
  "location_id": "LOC1",
  "evse_uid": "3256",
  "connector_id": "1",
  "currency": "EUR",
  "charging_periods": [
    {
      "start_date_time": "2015-06-29T22:39:09Z",
      "dimensions": [
        {
          "type": "ENERGY",
          "volume": 120
        },
        {
          "type": "MAX_CURRENT",
          "volume": 30
        }
      ]
    },
    {
      "start_date_time": "2015-06-29T22:40:54Z",
      "dimensions": [
        {
          "type": "ENERGY",
          "volume": 41000
        },
        {
          "type": "MIN_CURRENT",
          "volume": 34
        }
      ]
    },
    {
      "start_date_time": "2015-06-29T23:07:09Z",
      "dimensions": [
        {
          "type": "PARKING_TIME",
          "volume": 0.718
        }
      ],
      "tariff_id": "12"
    }
  ],
  "total_cost": {
    "excl_vat": 8.5,
    "incl_vat": 9.35
  },
  "status": "COMPLETED",
  "last_updated": "2015-06-29T23:50:17Z"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get all CDRs

This API, will return the private charging CDRs.

The API also provide further search options to filter the result set.

• Based on the last updated date between two given dates.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/cdrs/?date_from=xxx&date_to=yyy' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a array of JSON object with:

Sample Response

[
  {
    "country_code": "BE",
    "party_id": "BEC",
    "id": "12345",
    "start_date_time": "2015-06-29T21:39:09Z",
    "end_date_time": "2015-06-29T23:37:32Z",
    "cdr_token": {
      "uid": "012345678",
      "type": "RFID",
      "contract_id": "DE8ACC12E46L89"
    },
    "auth_method": "WHITELIST",
    "cdr_location": {
      "id": "LOC1",
      "name": "Gent Zuid",
      "address": "F.Rooseveltlaan 3A",
      "city": "Gent",
      "postal_code": "9000",
      "country": "BEL",
      "coordinates": {
        "latitude": "3.729944",
        "longitude": "51.047599"
      },
      "evse_uid": "3256",
      "evse_id": "BE*BEC*E041503003",
      "connector_id": "1",
      "connector_standard": "IEC_62196_T2",
      "connector_format": "SOCKET",
      "connector_power_type": "AC_1_PHASE"
    },
    "currency": "EUR",
    "tariffs": [
      {
        "country_code": "BE",
        "party_id": "BEC",
        "id": "12",
        "currency": "EUR",
        "elements": [
          {
            "price_components": [
              {
                "type": "TIME",
                "price": 2.0,
                "vat": 10.0,
                "step_size": 300
              }
            ]
          }
        ],
        "last_updated": "2015-02-02T14:15:01Z"
      }
    ],
    "charging_periods": [
      {
        "start_date_time": "2015-06-29T21:39:09Z",
        "dimensions": [
          {
            "type": "TIME",
            "volume": 1.973
          }
        ],
        "tariff_id": "12"
      }
    ],
    "total_cost": {
      "excl_vat": 4.0,
      "incl_vat": 4.4
    },
    "total_energy": 15.342,
    "total_time": 1.973,
    "total_time_cost": {
      "excl_vat": 4.0,
      "incl_vat": 4.4
    },
    "last_updated": "2015-06-29T22:01:13Z"
  }
]

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Get a particular CDR

This API, will return the private charging particular CDR.

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request query parameters

Sample Request

curl --location '{{url}}/v1/cdrs/{cdr_id}' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a JSON object with:

Sample Response

{
  "country_code": "BE",
  "party_id": "BEC",
  "id": "12345",
  "start_date_time": "2015-06-29T21:39:09Z",
  "end_date_time": "2015-06-29T23:37:32Z",
  "cdr_token": {
    "uid": "012345678",
    "type": "RFID",
    "contract_id": "DE8ACC12E46L89"
  },
  "auth_method": "WHITELIST",
  "cdr_location": {
    "id": "LOC1",
    "name": "Gent Zuid",
    "address": "F.Rooseveltlaan 3A",
    "city": "Gent",
    "postal_code": "9000",
    "country": "BEL",
    "coordinates": {
      "latitude": "3.729944",
      "longitude": "51.047599"
    },
    "evse_uid": "3256",
    "evse_id": "BE*BEC*E041503003",
    "connector_id": "1",
    "connector_standard": "IEC_62196_T2",
    "connector_format": "SOCKET",
    "connector_power_type": "AC_1_PHASE"
  },
  "currency": "EUR",
  "tariffs": [
    {
      "country_code": "BE",
      "party_id": "BEC",
      "id": "12",
      "currency": "EUR",
      "elements": [
        {
          "price_components": [
            {
              "type": "TIME",
              "price": 2.0,
              "vat": 10.0,
              "step_size": 300
            }
          ]
        }
      ],
      "last_updated": "2015-02-02T14:15:01Z"
    }
  ],
  "charging_periods": [
    {
      "start_date_time": "2015-06-29T21:39:09Z",
      "dimensions": [
        {
          "type": "TIME",
          "volume": 1.973
        }
      ],
      "tariff_id": "12"
    }
  ],
  "total_cost": {
    "excl_vat": 4.0,
    "incl_vat": 4.4
  },
  "total_energy": 15.342,
  "total_time": 1.973,
  "total_time_cost": {
    "excl_vat": 4.0,
    "incl_vat": 4.4
  },
  "last_updated": "2015-06-29T22:01:13Z"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.

Send a command

Introduction

This API, will enable remote commands to be sent to a Location/EVSE.

The following commands are supported:

• CANCEL_RESERVATION
• RESERVE_NOW
• START_SESSION
• STOP_SESSION
• UNLOCK_CONNECTOR

The complete list of query parameters and its details are provided in the OAS specification which can be used to filter down the search result based on the user journey.

Headers parameters

Request path parameters

Request body parameters

Depending on the command the body could be one of the following options:

CANCEL_RESERVATION

RESERVE_NOW

START_SESSION

STOP_SESSION

UNLOCK_CONNECTOR

Sample Request

curl --location '{{url}}/v1/commands/{path parameter} \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "response_url": "https://example.com/your-response-url",
  "session_id": "your-session-id"}'

Response

On success the response will have a 200 OK status and the data property from body of the response will contain a array of JSON objects with:

Sample Response

{
  "result": "REJECTED",
  "message": [
    {
      "language": "en",
      "text": "The reservation has been rejected due to an invalid session ID."
    },
    {
      "language": "es",
      "text": "La reserva ha sido rechazada debido a un ID de sesión inválido."
    }
  ]
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section.