Skip to content
SPARK

Adding resources

Introduction

This guide will help you get started with adding your resources the Energy Coordination API.

The base URL for the API is https://api.sandbox.voluespark.com/energy-coordination/v1

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:

Terminal window
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:

Terminal window
Authorization: Bearer <access_token>

The token is valid for 60 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:

  1. Go to the Variables tab in the Collection
  2. Set the client_id and client_secret variables to your client ID and secret
  3. Click the Get New Access Token button under the Authorization tab of the collection.

1. Register a User

The User object represents a user or a customer of your service.

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": "3880a832-f483-4b6a-998d-6109d3a54b06"
}

2. Register a Location

We require that you provide either meterPointIds or coordinates for the Location. At least one meterpoint id is required to enable compensation for the user.

You can register locations via POST /users/:userId/locations:

{
  "locationId": "1365caf1-fa04-40b1-98ff-1618860f77d0",
  "locationType": "Residential",
  "meterPointIds": [
    "707057500012345678"
  ],
  "coordinates": null
}

3. (Sandbox only) Register a Location in the testing area

We have created designated testing areas in sandbox. Registering Locations in these areas using the coordinates listed below will ensure that users become eligible and price curve events are sent everyday to associated resources.

Area 1 (Svalbard)

Centerpoint coordinates

{
  "latitude": 79.51913682860402,
  "longitude": 15.97611317258921
}

Polygon (PostGIS syntax)

POLYGON ((15.966604840082892 79.52009154420543, 15.96350723186006 79.52020678046054, 15.963450973156792 79.52021535498822, 15.961340685273045 79.52078875825326, 15.961295196485812 79.52080602477362, 15.961253913705665 79.52083177539599, 15.961218400633484 79.52086503474345, 15.961190002426308 79.52090454302508, 15.961169794745745 79.52094880375412, 15.961158543014273 79.52099614043154, 15.961156673422726 79.52104476004813, 15.961164256787118 79.52109282099977, 15.961181005866289 79.52113850284339, 15.961206286241973 79.52118007525124, 15.961653687515815 79.521776210591, 15.961682358685565 79.5218082532796, 15.961716096388654 79.52183490918435, 15.961753902653104 79.52185538981512, 15.96179465915759 79.52186908934831, 15.96220281160736 79.52196817784463, 15.962271854146591 79.52197503215727, 15.96315687279771 79.52193938143087, 15.970904289961888 79.5216272964264, 15.973715196479553 79.52151406620341, 15.98063293241149 79.52123540279811, 15.984445146332126 79.52108183745197, 15.984489209323716 79.52107611059573, 15.984531562519239 79.52106267367127, 15.984570868002184 79.52104195114438, 15.984605884131769 79.52101459762945, 15.984833202127355 79.52080191969394, 15.984871887309971 79.5207558020258, 15.984898427758221 79.52070177437292, 15.985203694475912 79.51982750105985, 15.985214198917447 79.51978659539925, 15.985217667910621 79.51974450522883, 15.985214002457791 79.51970243171202, 15.985164305186109 79.51941544251261, 15.985150706327348 79.51936680656726, 15.985127610449844 79.51932189593843, 15.985095960007353 79.5192825432558, 15.985057046532459 79.5192503543507, 15.98501245793411 79.5192266427283, 15.983366499816949 79.51855472050957, 15.983321219931192 79.51854106781026, 15.983274179102553 79.51853618675571, 15.983227060763667 79.5185402520224, 15.983194317296906 79.51854950898162, 15.98307989979041 79.51845149515542, 15.983047493380365 79.51842795918195, 15.983011744358198 79.51840990025414, 15.982581850864637 79.51823440673034, 15.982533285413153 79.51822011728824, 15.982307217816889 79.51817787337002, 15.982242049267002 79.51817436170089, 15.982147584441291 79.5181816561559, 15.982083727569046 79.51819513100584, 15.981824534761904 79.51828648625576, 15.981694867057799 79.51822305950976, 15.981633000231453 79.51820228049363, 15.981540015667324 79.51818409579664, 15.981474878896849 79.51818003712121, 15.981130411591364 79.51820372897654, 15.981139241027751 79.51818395793458, 15.981157847494288 79.51812140338944, 15.981172774846733 79.51802784064836, 15.981174557005659 79.51796260188976, 15.981157183827625 79.5177954896322, 15.981145870929971 79.51774281405028, 15.981123534885068 79.51769378549041, 15.981091213049806 79.51765068099469, 15.981050406552919 79.51761550247288, 15.981003010577776 79.5175898837273, 15.977928560948992 79.51633481472255, 15.977876356946648 79.51631987316756, 15.977822158214453 79.5163165557356, 15.977768521638668 79.5163250189303, 15.97678990531988 79.51659092662788, 15.976569824809332 79.5166507264705, 15.976523504185515 79.51666840730299, 15.976481583695156 79.5166948815266, 15.976445712129511 79.51672910787327, 15.976417300367206 79.51676974017312, 15.976397465882416 79.51681518030121, 15.976386988793044 79.51686364103404, 15.976271580475148 79.51787521665642, 15.976262087774991 79.51787951774291, 15.976254692359738 79.51788301551385, 15.97625140615091 79.5178846360927, 15.976244129139285 79.51788837396198, 15.976233565932699 79.51789402011354, 15.976226415117047 79.51789799407862, 15.976221442560243 79.51790086498563, 15.97621442559779 79.51790507079106, 15.97620425428385 79.5179113957205, 15.976197378688255 79.51791582886281, 15.976194332121391 79.5179178645137, 15.976187605255348 79.51792252024568, 15.976177869388884 79.51792949686892, 15.976171298455764 79.51793437020505, 15.976167935585334 79.5179369506263, 15.97616152762149 79.51794203634807, 15.976152268893326 79.51794963478991, 15.976146030760585 79.5179549274514, 15.976143275963283 79.5179573433438, 15.976137214341552 79.5179628372775, 15.976128472399004 79.5179710250002, 15.976122593779284 79.517976714323, 15.976077517346482 79.5180217907558, 15.972809680840905 79.51809775467342, 15.972577704835414 79.51786577866793, 15.97253694055077 79.51783279210584, 15.972490192067854 79.51780903459068, 15.972439516200374 79.5177955513924, 15.972387142556919 79.5177929357372, 15.972335375443873 79.51780130270726, 15.969226197738536 79.5186461223461, 15.969177627229133 79.5186649432284, 15.969134011164144 79.51869342056798, 15.969097243053026 79.51873031807467, 15.969068919114196 79.51877403391258, 15.969056828738085 79.51880556352187, 15.968911820735885 79.51876670874478, 15.968868613255424 79.5187591161824, 15.968824743819214 79.5187591932402, 15.96878156327836 79.51876693754538, 15.96746160897582 79.51912559292724, 15.967406187535511 79.5191480642808, 15.967390032792537 79.51915699697322, 15.967360657382258 79.51917604091366, 15.967319802030683 79.51920679421657, 15.96729337488222 79.51922975488324, 15.966761035839893 79.51976209392556, 15.966749852583321 79.51977403416709, 15.966734066418768 79.51979203483782, 15.966723688035543 79.51980468093437, 15.966718017001236 79.51981207157017, 15.966708487933257 79.51982536936914, 15.966695186380552 79.51984527654957, 15.96668654743266 79.51985916910786, 15.966681121099564 79.51986856779249, 15.966673409265134 79.51988299561992, 15.96666281991752 79.51990446869269, 15.966656068219775 79.51991937000714, 15.966652503258581 79.51992797658481, 15.966646740609328 79.51994328757661, 15.966639044653476 79.51996595913148, 15.966634295729294 79.51998161423649, 15.966604840082892 79.52009154420543, 15.966604840082892 79.52009154420543))
Area 2 (Longyearbyen, Svalbard)

Example address: Vei 221.1 Longyearbyen 9171, Svalbard & Jan Mayen

Centerpoint coordinates

{
  "latitude": 78.21661621129984,
  "longitude": 15.63509153386616
}

Polygon (PostGIS syntax)

POLYGON ((15.628599943969219 78.21408023622156, 15.628591492632914 78.21406213308997, 15.62856188866033 78.2140220686282, 15.628524928839735 78.21398866910798, 15.628482080657127 78.21396326065394, 15.628435045395342 78.21394685210623, 15.628385690584775 78.2139400949646, 15.621310659305431 78.2136833883656, 15.621261747855403 78.21368641988975, 15.621214367482036 78.21369893469308, 15.62117033874402 78.21372045190274, 15.621131353415736 78.21375014473455, 15.621098909481958 78.21378687226161, 15.621074253578827 78.21382922325361, 15.621058333092687 78.21387557040244, 15.621051759757412 78.21392413285032, 15.62105478614895 78.2139730446182, 15.621067295980257 78.21402042630457, 15.62108880856956 78.2140644573003, 15.621118497310212 78.21410344574424, 15.621155221432502 78.2141358935319, 15.621197569836957 78.21416055387908, 15.629470937586174 78.21794638877087, 15.629510734916524 78.21796066776112, 15.639716153620787 78.22067358874767, 15.639778812387625 78.22068197492482, 15.639880849467431 78.22068261510654, 15.639933552310465 78.2206773347098, 15.639983959856544 78.220661069669, 15.640029809434116 78.2206345500821, 15.640069042967696 78.2205989663485, 15.645098631788407 78.21495623768921, 15.645126502672962 78.21491831061564, 15.645146770967411 78.21487583185207, 15.645158718282614 78.21483030701516, 15.6451619211581 78.21478334968663, 15.645156266071195 78.21473662422133, 15.645141953460723 78.214691786756, 15.645119490622642 78.21465042650915, 15.64508967372947 78.21461400945276, 15.645053559610744 78.21458382635245, 15.645012428294779 78.21456094701763, 15.644967737639353 78.2145461823831, 15.644921071659429 78.21454005576636, 15.640201539687775 78.21436881482714, 15.640148170897778 78.21437260741317, 15.640096831304971 78.21438766920804, 15.64004987235426 78.21441331035471, 15.640009444849326 78.21444835644293, 15.639230056399022 78.2152860338288, 15.638448848752358 78.2150303444665, 15.638384704231006 78.21501831317003, 15.635145832469675 78.21484158236017, 15.635035731217126 78.21478507948487, 15.63499537411233 78.2147686376186, 15.634952775022525 78.21475945347895, 15.634909228299497 78.21475780612133, 15.634536213337238 78.21477626856898, 15.630596490272975 78.21402321743916, 15.630558619110994 78.21401893632512, 15.629824120569339 78.21399228617827, 15.629796838245936 78.21399278641195, 15.628599943969219 78.21408023622156, 15.628599943969219 78.21408023622156))
Move Locations

You can update a Location’s coordinates at any point to move it in our out of the testing area.

Example using PATCH /users/{userId}/locations/{locationId}:

{
  "coordinates": {
    "latitude": 79.51913682860402,
    "longitude": 15.97611317258921
  }
}

4. Register a Resource

The Resource represents an energy resource unit that your user owns, e.g. a hot water tank or charger. Besides vehicles, most resources will always be connected to a specific meterpoint id.

Use POST /users/:userId/locations/:locationId/resources to register such resources. The payload should identify a unique resource:

{
  "resourceId": "23202835-7843-4a90-b6d9-235fdf0e5844",
  "resourceType": "HotWaterTank"
}

To register vehicles, use POST /users/:userId/vehicles:

{
  "resourceId": "4b146c67-9e59-4cfb-863c-8c175659e8ba",
  "resourceType": "Vehicle"
}

5. Utilize batching

If you need to register many users and/or locations at once, please use our batch endpoints:

  • Batch users: POST /users/batch
  • Batch locations: POST /users/locations/batch