The disaggregation API allows you to query for device information per circuit. Counts over time are returned for each device.

There will be 1 device per circuit that has a name of “Baseload,” representing the minimum level of demand on the circuit.

Time series data is given at minutely intervals.

Limits

Queries are limited to a time range of 1 hour or less. Example error message:

HTTP/1.1 400 Bad Request
{
  "error":
  "Invalid parameter 'start_time, end_time' value ["2017-09-05T00:00:00Z", "2017-09-06T00:05:00Z"]: request time range must be less than or equal to 1 hour"
}

Up to 20 devices can be discovered per circuit.

It will take 2 weeks from initial installation to device discovery.

Our goal with Disaggregation API is to provide highly accessible, best in class virtual metering data to Verdigris customers. Part of meeting that objective requires the continuous and active development of these features to improve accuracy, reliability, and correctness. These changes may or may not be announced in advance. For that reason, this service is provided on an ‘as is’ and ‘as available’ basis with no warranties. If you encounter unexpected behavior, we welcome your feedback. For more information please see verdigris.co/terms or reach out to us at data@verdigris.co.

Example Request

$ curl -G \
"https://app.verdigris.co/api/v3/circuits/1/disag?\
start_time=2017-06-20T23:55:00Z&\
end_time=2017-06-20T23:57:00Z" \
-H "Authorization: Token token=<access_token>"

Examples

# RESPONSE
# result is in the format:
# {
#   "circuit_id": 1,
#   "devices": [
#     {
#       "id": device_id0,
#       "name": device0_name,
#       "real_power": device0_real_power,
#       "timestamps": [],
#       "counts": []
#     },
#     {
#       "id": device_id1,
#       "name": device1_name,
#       "real_power": device1_real_power,
#       "timestamps": [
#         timestamp0,
#         timestamp1,
#         timestamp2
#       ],
#       "counts": [
#         count0,
#         count1,
#         count2
#       ]
#     },
#     {
#       "id": device_id2,
#       "name": device2_name,
#       "real_power": device2_real_power,
#       "timestamps": [
#         timestamp0,
#         timestamp1,
#         timestamp2
#       ],
#       "counts": [
#         count0,
#         count1,
#         count2
#       ]
#     }
#   ]
# }
# real_power is Watts
# timestamp is unix epoch seconds
# count represents number of device
{
  "id": 1,
  "devices": [
    {
      "id": 1000,
      "name": "baseload",
      "real_power": 20,
      "timestamps": [],
      "counts": []
    },
    {
      "id": 1001,
      "name": null,
      "real_power": 10,
      "timestamps": [
        0,
        60,
        120
      ],
      "counts": [
        0.0,  # the device is off for the time interval 0 - 60
        0.5, # the device is off for half the minute
        1.2  # ~1 of this device is on for the time interval 120 - 180
      ]
    },
    {
      "id": 1002,
      "name": "phone charger",
      "real_power": 10,
      "timestamps": [
        0,
        60,
        180
      ],
      "counts": [
        0.1,
        1.5,
        2.7
      ]
    }
  ]
}

Params

Param name Description
circuit_id
required

circuit id


Value:

Must be String

start_time
required

start time in ISO 8601 combined date and time format (e.g. 2016-09-01T00:00:00.000Z), response will be inclusive of start time


Value:

Must be String

end_time
required

end time in ISO 8601 combined date and time format (e.g. 2016-10-01T00:00:00.000Z), response will be exclusive of end time


Value:

Must be String