Energy Coordination API Quickstart
Introduction
This guide will help you get started with the Energy Coordination API. It will walk you through the process of authenticating with the API, registering a user and some resources, subscribing to events, and sending a report.
Postman
We have a Postman Collection with all the endpoints from the API, as well as a folder that follows along with this guide. You can download the Postman Collection here.
Authentication
We use OAuth2 for authentication. If don't have a client ID and secret, you can create those in the Spark Portal.
Get an access token by sending a POST request to https://auth.identity.volue.com/connect/token
as follows:
curl --location 'https://auth.identity.volue.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your_client_id>' \
--data-urlencode 'client_secret=<your_client_secret>'
Then you can use the access token to authenticate with the API by sending it in the Authorization
header in subsequent requests to the Energy Coordination API:
Authorization: Bearer <access_token>
The token is valid for 30 minutes so you will need to refresh it periodically.
Postman Authentication
If you are using the Postman Collection, you can set up the authentication by following these steps:
- Go to the
Variables
tab in the Collection - Set the
client_id
andclient_secret
variables to your client ID and secret - Click the
Get New Access Token
button
1. Registering a User
The User
object represents a user or customer of your service. Use it to register Meters
and Resources
that your user owns to let us know who should get incentives based on your Reports
.
You can create users via POST /users
, the response is a userId
that you can use to refer to the user in subsequent requests.
{
"userId": "string"
}
2. Registering a Vehicle
The Vehicle
object represents a specific electric vehicle that your user owns.
You can create vehicles via POST /users/:userId/vehicles
, the payload should be information identifying a unique vehicle:
{
"vehicleId": "<string>",
"metadata": {
"resourceType": "Vehicle",
"brand": "Tesla",
"model": "Model 3",
"year": 2022,
"vin": "<string>"
}
}
3. Registering a Meter
The Meter
object represents a specific power meter that your user owns. This is the information we give to DSOs so they can correctly send out incentives to your users.
You can create meters via POST /users/:userId/meters
, the payload should be information identifying a unique power meter:
{
"address": {
"street": "string",
"city": "string",
"zipCode": "string"
},
"location": {
"latitude": 63.1,
"longitude": 10.7
},
"meterPointId": "string",
"meterNumber": "string",
"locationType": "Residential"
}
In response you will get a meterId
that you can use to refer to the meter in subsequent requests.
4. Registering a Resource
The Resource
object represents a specific resource that your user owns.
You can create resources via POST /users/:userId/resources
, the payload should be information identifying a unique resource:
{
"resourceId": "<string>",
"metadata": {
"resourceType": "HotWaterTank",
"brand": "Oso",
"model": "SuperTank",
"capacity": 500,
"heatingElements": [1750, 1250]
}
}