Repository navigation
Operator API
The Operator API is a JSON based REST API.
Through this API you can manage your Charging Stations, and keep track of Transactions.
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.
| 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 |
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.
[
{
"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"
}
]
}
][
{
"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"
}
]
}
]| 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 |
Adds opening times to a Charging Station. See SetChargingStationOpeningTimes to replace the entire set of opening times.
[
"AddChargingStationOpeningTimes",
{
"openingTimes": [
{
"day": "friday",
"timeStart": "12:00",
"timeStop": "15:00"
},
{
"day": "friday",
"timeStart": "20:00",
"timeStop": "22:00"
}
]
}
]Changes a single configuration key.
[
"RequestChangeConfigurationItem",
{
"key": "key",
"value": "value"
}
]Tranfers free format data to the charging station.
[
"RequestDataTransfer",
{
"data": "data",
"messageId": "messageId",
"vendorId": "vendorId"
}
]Grants the specified command-execution permission to a user. See RevokePermission for revocation of permissions.
[
"GrantPermission",
{
"commandClass": "io.motown.domain.api.chargingstation.AddChargingStationOpeningTimesCommand",
"userIdentity": "testUser"
}
]Improves the location information of an existing Charging Station.
[
"ImproveChargingStationLocation",
{
"accessibility": "Paying",
"address": {
"addressLine1": "Markt 8",
"addressLine2": "",
"city": "Amsterdam",
"country": "The Netherlands",
"postalCode": "5751 BE",
"region": ""
},
"coordinates": {
"latitude": 51.464055,
"longitude": 5.794529
}
}
]Modifies the charging station accessibility, address and coordinates upon relocating a Charging Station.
[
"MoveChargingStation",
{
"accessibility": "Private",
"address": {
"addressLine1": "Groeneweg 2",
"addressLine2": "",
"city": "Amsterdam",
"country": "The Netherlands",
"postalCode": "",
"region": ""
},
"coordinates": {
"latitude": 51.463976,
"longitude": 5.793803
}
}
]Specifies the accessibility, address and coordinates upon initial placement of the Charging Station.
[
"PlaceChargingStation",
{
"accessibility": "public",
"address": {
"addressLine1": "Markt 8",
"addressLine2": "",
"city": "Amsterdam",
"country": "The Netherlands",
"postalCode": "5751 BE",
"region": ""
},
"coordinates": {
"latitude": 51.464055,
"longitude": 5.794529
}
}
]Creates and accepts a Charging Station. In case the specified Charging Station does not exist yet, it will be created, registered and accepted.
[
"AcceptChargingStation",
{}
]Requests the version of the local authorization list at the Charging Station.
[
"RequestAuthorizationListVersion",
{}
]Requests the cancellation of a reservation.
[
"RequestCancelReservation",
{
"reservationId": "res1234"
}
]Sets the availability of a specific EVSE at the Charging Station (operative, inoperative)
[
"RequestChangeAvailability",
{
"availability": "inoperative",
"evseId": 1
}
]Requests a clearing of the Charging Station's local authorization list
[
"RequestClearCache",
{}
]Requests the charging station to send diagnostics information to the specified target location.
[
"RequestDiagnostics",
{
"targetLocation": "ftp://somewhere.com"
}
]Requests the Charging Station's configuration information. In case no keys are provided, all configuration key value pairs will be returned.
[
"RequestConfigurationItems",
{}
]Requests a reservation for the time up to the given expiry date.
[
"RequestReserveNow",
{
"evseId": 1,
"expiryDate": "2014-03-21T09:30:00Z",
"identifyingToken": "token1"
}
]Requests a soft or hard reset of the Charging Station.
[
"RequestResetChargingStation",
{
"type": "hard"
}
]Requests a remote start transaction.
[
"RequestStartTransaction",
{
"evseId": 1,
"identifyingToken": {
"token": "TOKEN"
}
}
]Requests a remote stop transaction
[
"RequestStopTransaction",
{
"id": "transId1234"
}
]Revokes a user permission.
[
"RevokePermission",
{
"commandClass": "io.motown.domain.api.chargingstation.AddChargingStationOpeningTimesCommand",
"userIdentity": "testUser"
}
]Sends a differential or full list of authorization tokens that the Charging Station should store in it's local authorization list.
[
"RequestSendAuthorizationList",
{
"items": [
{
"status": "ACCEPTED",
"token": "token1"
},
{
"status": "BLOCKED",
"token": "token2"
},
{
"status": "EXPIRED",
"token": "token3"
}
],
"listVersion": 1,
"updateType": "FULL"
}
]Replaces the set of opening times.
[
"SetChargingStationOpeningTimes",
{
"openingTimes": [
{
"day": "monday",
"timeStart": "12:00",
"timeStop": "15:00"
},
{
"day": "monday",
"timeStart": "20:00",
"timeStop": "22:00"
}
]
}
]Requests the unlocking of an EVSE.
[
"RequestUnlockEvse",
{
"evseId": 1,
"identifyingToken": {
"token": "TOKEN"
}
}
]Updates the indicator that marks a Charging Station reservable or not.
[
"UpdateChargingStationReservable",
{
"reservable": false
}
]Updates the firmware.
[
"RequestFirmwareUpdate",
{
"location": "http://somewhere.com",
"retrieveDate": "2014-06-01T09:30:00Z",
"numRetries": 3,
"retryInterval": 60
}
]