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 .

which responds with site details:

{
  "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": [],
  "chargers": []
}

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 .

to fetch the site details:

{
  "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": [],
  "chargers": [],
  "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"}' | jq .

which responds with the virtual inverter details:

{
  "reportedAt": "2023-01-01T23:59:00+00:00",
  "model": "Derapi Virtual Inverter",
  "serialNumber": "9900010",
  "name": "My Derapi Inverter",
  "recentProduction": {
    "kwh": 11.8,
    "start": "2023-01-01T00:00:00+00:00"
  },
  "lifetimeProduction": {
    "kwh": 999.8877,
    "start": "2022-01-01T00:00:00+00:00"
  },
  "siteID": "site-jcf6kaafwgbqjjxg",
  "id": "solr-vhby3csynjvnhfwe",
  "vendor": "virtual"
}

Similar to site details, you can also fetch the device details by id, for example:

$ curl -H "Authorization: Bearer $DERAPI_TOKEN" \
  https://api.derapi.com/solar-inverters/solr-vhby3csynjvnhfwe | jq .

which responds with our example device details:

{
  "reportedAt": "2023-01-01T23:59:00+00:00",
  "model": "Derapi Virtual Inverter",
  "serialNumber": "9900010",
  "name": "My Derapi Inverter",
  "recentProduction": {
    "kwh": 11.8,
    "start": "2023-01-01T00:00:00+00:00"
  },
  "lifetimeProduction": {
    "kwh": 999.8877,
    "start": "2022-01-01T00:00:00+00:00"
  },
  "siteID": "site-jcf6kaafwgbqjjxg",
  "id": "solr-vhby3csynjvnhfwe",
  "vendor": "virtual",
  "vendorID": "67d9df4478b8633451e69686"
}

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-vhby3csynjvnhfwe/intervals?start=2025-01-01T00:00:00Z&end=2025-01-05T00:00:00Z&summaryLevel=day' | jq .

which returns daily intervals between the provided start and end dates:

{
  "id": "solr-vhby3csynjvnhfwe",
  "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.

Using our example site from above:

$ curl -X DELETE -H "Authorization: Bearer $DERAPI_TOKEN" \
  https://api.derapi.com/virtual/sites/site-jcf6kaafwgbqjjxg

Quotas

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