Get Sandbox Dispatches

This tutorial describes how to fetch dispatches from the Voltus REST API in the public sandbox. You will not require an API key.

We provide source code examples in-line. You can obtain this source code from Voltus API Examples.

Fetch dispatches

We'll use the public sandbox to illustrate how to fetch dispatches from Voltus. You will include a generic API key, and make a request to the Dispatches resource.

import json
import os
import urllib

import requests

VOLTUS_SANDBOX_API_URL = "https://sandbox.voltus.co"
VOLTUS_TEST_API_KEY = "secret"

s = requests.Session()
s.headers.update({"X-Voltus-API-Key": VOLTUS_TEST_API_KEY, "Accept": "application/json"}
)

url = urllib.parse.urljoin(VOLTUS_API_URL, "/2022-04-15/dispatches")
r = s.get(url)

print(json.dumps(r.json(), indent=4))

This code should produce the following output:

{
  "dispatches": [
    {
      "id": "asdf",
      "authorized": true,
      "test": false,
      "start_time": "2023-06-29T14:53:36.563070478Z",
      "end_time": "2023-06-29T15:53:36.563069928Z",
      "program": {
        "name": "MISO - Operating Reserves",
        "timezone": "US/Central",
        "market": "MISO",
        "program_type": "ancillary_services"
      },
      "sites": [
        {
          "name": "Site 1",
          "id": "asdf",
          "customer_location_id": "1",
          "commitment": 12
        },
        {
          "name": "Site 2",
          "id": "lkjh",
          "customer_location_id": "2",
          "commitment": 40
        }
      ]
    }
  ],
  "page": 0,
  "perPage": 0
}

The dispatches key in this payload contains an array of Dispatch objects. For an explanation of fields in each Dispatch, consult the API Reference.

Process dispatch data

Let's write a program that checks to see if a dispatch is ongoing, and sends curtailment signals to the applicable sites.

"""
Simplified polling processor which gets dispatches then waits to see if they're in progress

Precursor to the more sophisticated poller.py
"""

import datetime
import os
import time

import requests
import urllib
from dateutil import parser as date_parser


VOLTUS_API_URL = os.getenv("VOLTUS_API_URL", "https://sandbox.voltus.co")
VOLTUS_API_KEY = os.getenv("VOLTUS_API_KEY", "secret")

processed_dispatches = set()

s = requests.Session()
s.headers.update({"X-Voltus-API-Key": VOLTUS_API_KEY, "Accept": "application/json"})

url = urllib.parse.urljoin(VOLTUS_API_URL, "/2022-04-15/dispatches")
resp = s.get(url)
dispatches = resp.json()["dispatches"]


if __name__ == "__main__":
    while True:
        for dispatch_info in dispatches:
            if dispatch_info["id"] in processed_dispatches:
                continue
            start_time = date_parser.parse(dispatch_info["start_time"])
            end_time = (
                date_parser.parse(dispatch_info["end_time"])
                if dispatch_info.get("end_time")
                else None
            )
            now = datetime.datetime.now(datetime.timezone.utc)
            if start_time <= now:
                if end_time is None or end_time >= now:
                    processed_dispatches.add(dispatch_info["id"])
                    print("Dispatch {} is in progress".format(dispatch_info["id"]))
                    if dispatch_info["authorized"]:
                        for site in dispatch_info["sites"]:
                            print(
                                "- Customer location {} should curtail. Commitment: {} kW".format(
                                    site["customer_location_id"], site["commitment"]
                                )
                            )
                    else:
                        print("- Dispatch is not authorized or is cancelled, skipping")
                else:
                    print("Dispatch {} has ended".format(dispatch_info["id"]))

        time.sleep(1)

[get the code]

The above code should produce this output after a short delay:

Dispatch asdf is in progress
- Customer location 1 should curtail. Commitment: 12 kW
- Customer location 2 should curtail. Commitment: 40 kW

Next steps

Now you know how to fetch dispatches from Voltus in our sandbox environment. If you have your API keys, you're ready to create a REST dispatch integration.