Virtual Mode

To enable you to begin integrating with and testing our API as quickly as possible, Derapi provides a 'virtual mode', in which you can exercise full programatic control over virtual DERs, using the same base URI as you would for interacting with real DERs. You can create, destroy, and modify virtual device configurations freely in this mode, without needing to track down real test devices to work with.

Virtual mode credentials are distinct from production mode credentials, and can only access virtual devices. Similarly, virtual devices are not accessible using production mode credentials. You can provision virtual mode credentials by signing up here.

Creating a virtual site

First, use the the POST /virtual/sites endpoint to create a virtual site:

$ curl -X POST \
  -H "Authorization: Bearer $DERAPI_TOKEN" \
  -H "content-type: application/json" \
  https://api.derapi.com/virtual/sites -d '{}' | jq .
{
  "name": "Site 1",
  "location": {
    "lat": 55.8,
    "lon": -4.3,
    "timezone": "Europe/Berlin",
    "currentUTCOffset": 1.0
  },
  "locationUTCOffset": 1,
  "operationalSince": "2023-01-01T23:59:00+00:00",
  "id": "site-jcf6kaafwgbqjjxg",
  "vendor": "virtual",
  "batteries": [],
  "solarInverters": []
}

You can now use the returned Site ID with the (non-virtual) /sites or /sites/{siteID} endpoints:

$ curl -H "Authorization: Bearer $DERAPI_TOKEN" \
  https://api.derapi.com/sites/site-jcf6kaafwgbqjjxg | jq .
{
  "name": "Site 1",
  "location": {
    "lat": 55.8,
    "lon": -4.3,
    "timezone": "Europe/Berlin",
    "currentUTCOffset": 1.0
  },
  "locationUTCOffset": 1,
  "operationalSince": "2023-01-01T23:59:00+00:00",
  "id": "site-jcf6kaafwgbqjjxg",
  "vendor": "virtual",
  "batteries": [],
  "solarInverters": [],
  "vendorID": "679816bb9dbd2597c5e4f6ae"
}

Attaching devices

Specific devices such as https://api.derapi.com/virtual/batteries and https://api.derapi.com/virtual/solar-inverters can be created and associated with virtual sites you create.

Here's an example showing how to attach a solar inverter to the site created above:

$ curl -X POST \
  -H "Authorization: Bearer $DERAPI_TOKEN" \
  -H "content-type: application/json" \
  https://api.derapi.com/virtual/solar-inverters \
  -d '{"siteID":"site-jcf6kaafwgbqjjxg"}'

Requesting interval data

Interval data requests to virtual sites and devices return appropriately-shaped test data. For example:

$ curl -H "Authorization: Bearer $DERAPI_TOKEN" 'https://api.derapi.com/solar-inverters/solr-24nmnscr6aycm5ln/intervals?start=2025-01-01T00:00:00Z&end=2025-01-05T00:00:00Z&summaryLevel=day' | jq .
{
  "id": "solr-24nmnscr6aycm5ln",
  "summaryLevel": "day",
  "intervals": [
    {
      "kwh": 55.425312537626745,
      "start": "2024-12-31T23:00:00+00:00",
      "end": "2025-01-01T23:00:00+00:00"
    },
    {
      "kwh": 55.04193651032593,
      "start": "2025-01-01T23:00:00+00:00",
      "end": "2025-01-02T23:00:00+00:00"
    },
    ...
  ]
}

Deleting devices

Unlike real devices, each virtual resource can be deleted. This supports the common use case to programmatically creating and adjusting sets of devices for different testing scenarios.

Quotas

Up to 100 of each virtual resource type can exist within your account at a time.