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.
Updated 12 days ago