Operator API - motown-io/motown GitHub Wiki
Functional Overview
The Operator API is a JSON based REST API.
Through this API you can manage your Charging Stations, and keep track of Transactions.
Versioning
API versioning is done using vendor media MIME types. These are used in the Accept (all HTTP methods) and Content-Type (POST and PUT only) HTTP headers.
The Operator API version 1 MIME type is application/vnd.io.motown.operator-api-v1+json.
Resources
| URL | HTTP method | Description | Links |
|---|---|---|---|
| /operator-api/charging-stations/ | GET | Retrieves a paginated set of charging stations, including the ones that are not accepted or configured | Sample |
| /operator-api/transactions/ | GET | Retrieves a paginated set of transactions | Sample |
Pagination
The API has built in pagination. When retrieving resources, the response contains 'previous', 'next', 'first' and 'last' URL's to navigate through the set of resources.
ChargingStation
Example response
[
{
"href": "/operator-api/charging-stations/?offset=0&limit=10",
"previous": {
"href": ""
},
"next": {
"href": "/operator-api/charging-stations/?offset=10&limit=10"
},
"first": {
"href": "/operator-api/charging-stations/?offset=0&limit=10"
},
"last": {
"href": "/operator-api/charging-stations/?offset=40&limit=10"
},
"elements": [
{
"accepted": true,
"accessibility": "PUBLIC",
"addressLine1": "Helmondseweg 2",
"addressLine2": "",
"attributes": {
"anAttribute": true,
"anotherAttribute": "This is a string!"
},
"availability": "OPERATIVE",
"city": "Deurne",
"configurationItems": {
"HeartBeatInterval": 900,
"ResetRetries": 3
},
"configured": true,
"country": "The Netherlands",
"evses": [
{
"availability": "OPERATIVE",
"connectors": [
{
"chargingProtocol": "MODE3",
"current": "AC",
"maxAmp": 11,
"phase": 3,
"type": "C_TYPE_2",
"voltage": 1
},
{
"chargingProtocol": "MODE3",
"current": "AC",
"maxAmp": 11,
"phase": 3,
"type": "TESLA",
"voltage": 1
}
],
"id": "1",
"status": "AVAILABLE"
},
{
"availability": "OPERATIVE",
"connectors": [
{
"chargingProtocol": "MODE3",
"current": "AC",
"maxAmp": 11,
"phase": 3,
"type": "C_TYPE_2",
"voltage": 1
},
{
"chargingProtocol": "MODE3",
"current": "AC",
"maxAmp": 11,
"phase": 3,
"type": "TESLA",
"voltage": 1
}
],
"id": "2",
"status": "OCCUPIED"
}
],
"id": "MOTOWN001",
"latitude": 51.464055,
"longitude": 5.794529,
"openingTimes": [
{
"day": "MONDAY",
"timeStart": "09:00",
"timeStop": "17:00"
},
{
"day": "TUESDAY",
"timeStart": "09:00",
"timeStop": "17:00"
}
],
"postalCode": "",
"protocol": "OCPPS15",
"region": "",
"reservable": false,
"status": "AVAILABLE"
}
]
}
]
Transaction
Example response
[
{
"href": "/operator-api/charging-stations/?offset=0&limit=10",
"previous": {
"href": ""
},
"next": {
"href": "/operator-api/charging-stations/?offset=10&limit=10"
},
"first": {
"href": "/operator-api/charging-stations/?offset=0&limit=10"
},
"last": {
"href": "/operator-api/charging-stations/?offset=40&limit=10"
},
"elements": [
{
"chargingStationId": "MOTOWN003",
"evseId": "1",
"id": "MOTOWN003_OCPPS15_1",
"idTag": "12345AF",
"meterStart": 1,
"meterValues": [
{
"timestamp": "2014-04-14T12:00:52:000Z",
"wattHour": 1
},
{
"timestamp": "2014-04-14T12:01:52:000Z",
"wattHour": 10
}
],
"started": "2014-04-14T12:00:52:000Z"
},
{
"chargingStationId": "MOTOWN004",
"evseId": "1",
"id": "MOTOWN003_OCPPS15_2",
"idTag": "54321AF",
"meterStart": 1,
"meterStop": 400,
"meterValues": [
{
"timestamp": "2014-04-14T12:00:52:000Z",
"wattHour": 1
},
{
"timestamp": "2014-04-14T12:01:52:000Z",
"wattHour": 10
},
{
"timestamp": "2014-04-14T12:02:52:000Z",
"wattHour": 20
},
{
"timestamp": "2014-04-14T12:03:52:000Z",
"wattHour": 30
},
{
"timestamp": "2014-04-14T12:04:52:000Z",
"wattHour": 40
},
{
"timestamp": "2014-04-14T12:05:52:000Z",
"wattHour": 50
}
],
"started": "2014-04-14T12:00:52:000Z",
"stopped": "2014-04-14T11:58:59:000Z"
}
]
}
]
Commands
| URL | HTTP method | Description | Links |
|---|---|---|---|
| /operator-api/charging-stations/<chargingStationId>/commands | POST | Executes the given command on the charging station with the given chargingStationId that is enclosed in the URL | Sample commands |
AddChargingStationOpeningTimes
Adds opening times to a Charging Station. See SetChargingStationOpeningTimes to replace the entire set of opening times.
Example request
[
"AddChargingStationOpeningTimes",
{
"openingTimes": [
{
"day": "friday",
"timeStart": "12:00",
"timeStop": "15:00"
},
{
"day": "friday",
"timeStart": "20:00",
"timeStop": "22:00"
}
]
}
]
RequestChangeConfigurationItem
Changes a single configuration key.
Example request
[
"RequestChangeConfigurationItem",
{
"key": "key",
"value": "value"
}
]
RequestDataTransfer
Tranfers free format data to the charging station.
Example request
[
"RequestDataTransfer",
{
"data": "data",
"messageId": "messageId",
"vendorId": "vendorId"
}
]
GrantPermission
Grants the specified command-execution permission to a user. See RevokePermission for revocation of permissions.
Example
[
"GrantPermission",
{
"commandClass": "io.motown.domain.api.chargingstation.AddChargingStationOpeningTimesCommand",
"userIdentity": "testUser"
}
]
ImproveChargingStationLocation
Improves the location information of an existing Charging Station.
Example request
[
"ImproveChargingStationLocation",
{
"accessibility": "Paying",
"address": {
"addressLine1": "Markt 8",
"addressLine2": "",
"city": "Amsterdam",
"country": "The Netherlands",
"postalCode": "5751 BE",
"region": ""
},
"coordinates": {
"latitude": 51.464055,
"longitude": 5.794529
}
}
]
MoveChargingStation
Modifies the charging station accessibility, address and coordinates upon relocating a Charging Station.
Example request
[
"MoveChargingStation",
{
"accessibility": "Private",
"address": {
"addressLine1": "Groeneweg 2",
"addressLine2": "",
"city": "Amsterdam",
"country": "The Netherlands",
"postalCode": "",
"region": ""
},
"coordinates": {
"latitude": 51.463976,
"longitude": 5.793803
}
}
]
PlaceChargingStation
Specifies the accessibility, address and coordinates upon initial placement of the Charging Station.
Example request
[
"PlaceChargingStation",
{
"accessibility": "public",
"address": {
"addressLine1": "Markt 8",
"addressLine2": "",
"city": "Amsterdam",
"country": "The Netherlands",
"postalCode": "5751 BE",
"region": ""
},
"coordinates": {
"latitude": 51.464055,
"longitude": 5.794529
}
}
]
AcceptChargingStation
Creates and accepts a Charging Station. In case the specified Charging Station does not exist yet, it will be created, registered and accepted.
Example request
[
"AcceptChargingStation",
{}
]
RequestAuthorizationListVersion
Requests the version of the local authorization list at the Charging Station.
Example request
[
"RequestAuthorizationListVersion",
{}
]
RequestCancelReservation
Requests the cancellation of a reservation.
Example request
[
"RequestCancelReservation",
{
"reservationId": "res1234"
}
]
RequestChangeAvailability
Sets the availability of a specific EVSE at the Charging Station (operative, inoperative)
Example request
[
"RequestChangeAvailability",
{
"availability": "inoperative",
"evseId": 1
}
]
RequestClearCache
Requests a clearing of the Charging Station's local authorization list
Example request
[
"RequestClearCache",
{}
]
RequestDiagnostics
Requests the charging station to send diagnostics information to the specified target location.
Example request
[
"RequestDiagnostics",
{
"targetLocation": "ftp://somewhere.com"
}
]
RequestConfigurationItems
Requests the Charging Station's configuration information. In case no keys are provided, all configuration key value pairs will be returned.
Example request
[
"RequestConfigurationItems",
{}
]
RequestReserveNow
Requests a reservation for the time up to the given expiry date.
Example
[
"RequestReserveNow",
{
"evseId": 1,
"expiryDate": "2014-03-21T09:30:00Z",
"identifyingToken": "token1"
}
]
RequestResetChargingStation
Requests a soft or hard reset of the Charging Station.
Example
[
"RequestResetChargingStation",
{
"type": "hard"
}
]
RequestStartTransaction
Requests a remote start transaction.
Example
[
"RequestStartTransaction",
{
"evseId": 1,
"identifyingToken": {
"token": "TOKEN"
}
}
]
RequestStopTransaction
Requests a remote stop transaction
Example
[
"RequestStopTransaction",
{
"id": "transId1234"
}
]
RevokePermission
Revokes a user permission.
Example
[
"RevokePermission",
{
"commandClass": "io.motown.domain.api.chargingstation.AddChargingStationOpeningTimesCommand",
"userIdentity": "testUser"
}
]
RequestSendAuthorizationList
Sends a differential or full list of authorization tokens that the Charging Station should store in it's local authorization list.
Example
[
"RequestSendAuthorizationList",
{
"items": [
{
"status": "ACCEPTED",
"token": "token1"
},
{
"status": "BLOCKED",
"token": "token2"
},
{
"status": "EXPIRED",
"token": "token3"
}
],
"listVersion": 1,
"updateType": "FULL"
}
]
SetChargingStationOpeningTimes
Replaces the set of opening times.
Example
[
"SetChargingStationOpeningTimes",
{
"openingTimes": [
{
"day": "monday",
"timeStart": "12:00",
"timeStop": "15:00"
},
{
"day": "monday",
"timeStart": "20:00",
"timeStop": "22:00"
}
]
}
]
RequestUnlockEvse
Requests the unlocking of an EVSE.
Example
[
"RequestUnlockEvse",
{
"evseId": 1,
"identifyingToken": {
"token": "TOKEN"
}
}
]
UpdateChargingStationReservable
Updates the indicator that marks a Charging Station reservable or not.
Example
[
"UpdateChargingStationReservable",
{
"reservable": false
}
]
RequestFirmwareUpdate
Updates the firmware.
Example
[
"RequestFirmwareUpdate",
{
"location": "http://somewhere.com",
"retrieveDate": "2014-06-01T09:30:00Z",
"numRetries": 3,
"retryInterval": 60
}
]