Circuits represent circuits within a circuit panel. They contain information about their names, breakers, tags, and panel information.

Example Circuit

{
  // primary key of circuit
  "id": 1765,

  // name of circuit
  "name": "NASA Ames Building 19 Room 1001",

  // state of circuit
  "active": true,

  // tags associated to the circuit
  "tag_names": [
      "Office"
  ],

  // breaker associated to the circuit
  "breaker_id": 169
}

GET /api/v3/circuits
List circuits

Returns details about all accessible circuits.

Example Request

$ curl https://app.verdigris.co/api/v3/circuits -H "Authorization: Token token=<access_token>"

Examples

{
  "circuits": [
    {
        "id": 1765,
        "name": "NASA Ames Building 19 Room 1001",
        "active": true,
        "tag_names": [
            "Office"
        ],
        "breaker_id": 169
    },
    {
        "id": 1766,
        "name": "NASA Ames Building 19 Room 1002",
        "active": true,
        "tag_names": [
            "Kitchen"
        ],
        "breaker_id": 169
    }
  ]
}

GET /api/v3/circuits/:id
Show a circuit

Returns details about requested circuit.

Example Request

$ curl https://app.verdigris.co/api/v3/circuits/1765 -H "Authorization: Token token=<access_token>"

Examples

{
  "id": 1765,
  "name": "NASA Ames Building 19 Room 1001",
  "active": true,
  "tag_names": [
      "Office"
  ],
  "breaker_id": 169
}

Params

Param name Description
id
required

circuit id


Value:

Must be String


GET /api/v3/circuits/energy
Energy data for circuits

Returns the energy data in Watt-hours for the requested circuits.

If energy is null, there is missing data for that time interval.

Example Request

$ curl -G \
"https://app.verdigris.co/api/v3/circuits/energy?\
ids=1,2&\
start_time=2017-06-20T23:55:00Z&\
end_time=2017-06-20T23:57:00Z&\
interval=minutely&\
timestamp_format=iso8601" \
--data-urlencode "timezone=Pacific Time (US & Canada)" \
-H "Authorization: Token token=<access_token>"

Examples

# RESPONSE
# result is in the format:
# {
#     circuit_id0: {
#         "timestamps": [
#             timestamp0,
#             timestamp1
#         ],
#         "energy": [
#             energy0,
#             energy1
#         ]
#     },
#     "circuit_id2": {
#         "timestamps": [
#             timestamp0,
#             timestamp1
#         ],
#         "energy": [
#             energy0,
#             energy1
#         ]
#     }
# }
# energy is in units of Watt-hours
{
    "1": {
        "timestamps": [
            "2017-06-20T16:55:00-07:00",
            "2017-06-20T16:56:00-07:00"
        ],
        "energy": [
            1337,
            1338
        ]
    },
    "2": {
        "timestamps": [
            "2017-06-20T16:55:00-07:00",
            "2017-06-20T16:56:00-07:00"
        ],
        "energy": [
            1337,
            1338
        ]
    }
}

Params

Param name Description
ids
required

comma separated circuit ids (e.g. 1,2)


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

interval
required

time between each data point


Value:

Must be one of: minutely, 15-minutely, hourly, daily.

timestamp_format
optional

specify how timestamps are returned in the response (default: unix epoch seconds)


Value:

Must be one of: iso8601.

timezone
optional

timezone used to account for hour and day boundaries, and daylight savings (default: UTC)


Value:

Must be one of: International Date Line West, Midway Island, American Samoa, Hawaii, Alaska, Pacific Time (US & Canada), Tijuana, Mountain Time (US & Canada), Arizona, Chihuahua, Mazatlan, Central Time (US & Canada), Saskatchewan, Guadalajara, Mexico City, Monterrey, Central America, Eastern Time (US & Canada), Indiana (East), Bogota, Lima, Quito, Atlantic Time (Canada), Caracas, La Paz, Santiago, Newfoundland, Brasilia, Buenos Aires, Montevideo, Georgetown, Greenland, Mid-Atlantic, Azores, Cape Verde Is., Dublin, Edinburgh, Lisbon, London, Casablanca, Monrovia, UTC, Belgrade, Bratislava, Budapest, Ljubljana, Prague, Sarajevo, Skopje, Warsaw, Zagreb, Brussels, Copenhagen, Madrid, Paris, Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna, West Central Africa, Bucharest, Cairo, Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius, Athens, Istanbul, Minsk, Jerusalem, Harare, Pretoria, Kaliningrad, Moscow, St. Petersburg, Volgograd, Samara, Kuwait, Riyadh, Nairobi, Baghdad, Tehran, Abu Dhabi, Muscat, Baku, Tbilisi, Yerevan, Kabul, Ekaterinburg, Islamabad, Karachi, Tashkent, Chennai, Kolkata, Mumbai, New Delhi, Kathmandu, Astana, Dhaka, Sri Jayawardenepura, Almaty, Novosibirsk, Rangoon, Bangkok, Hanoi, Jakarta, Krasnoyarsk, Beijing, Chongqing, Hong Kong, Urumqi, Kuala Lumpur, Singapore, Taipei, Perth, Irkutsk, Ulaanbaatar, Seoul, Osaka, Sapporo, Tokyo, Yakutsk, Darwin, Adelaide, Canberra, Melbourne, Sydney, Brisbane, Hobart, Vladivostok, Guam, Port Moresby, Magadan, Srednekolymsk, Solomon Is., New Caledonia, Fiji, Kamchatka, Marshall Is., Auckland, Wellington, Nuku’alofa, Tokelau Is., Chatham Is., Samoa, Pacific/Midway, Pacific/Midway, Pacific/Pago_Pago, Pacific/Honolulu, America/Juneau, America/Los_Angeles, America/Tijuana, America/Denver, America/Phoenix, America/Chihuahua, America/Mazatlan, America/Chicago, America/Regina, America/Mexico_City, America/Mexico_City, America/Monterrey, America/Guatemala, America/New_York, America/Indiana/Indianapolis, America/Bogota, America/Lima, America/Lima, America/Halifax, America/Caracas, America/La_Paz, America/Santiago, America/St_Johns, America/Sao_Paulo, America/Argentina/Buenos_Aires, America/Montevideo, America/Guyana, America/Godthab, Atlantic/South_Georgia, Atlantic/Azores, Atlantic/Cape_Verde, Europe/Dublin, Europe/London, Europe/Lisbon, Europe/London, Africa/Casablanca, Africa/Monrovia, Etc/UTC, Europe/Belgrade, Europe/Bratislava, Europe/Budapest, Europe/Ljubljana, Europe/Prague, Europe/Sarajevo, Europe/Skopje, Europe/Warsaw, Europe/Zagreb, Europe/Brussels, Europe/Copenhagen, Europe/Madrid, Europe/Paris, Europe/Amsterdam, Europe/Berlin, Europe/Berlin, Europe/Rome, Europe/Stockholm, Europe/Vienna, Africa/Algiers, Europe/Bucharest, Africa/Cairo, Europe/Helsinki, Europe/Kiev, Europe/Riga, Europe/Sofia, Europe/Tallinn, Europe/Vilnius, Europe/Athens, Europe/Istanbul, Europe/Minsk, Asia/Jerusalem, Africa/Harare, Africa/Johannesburg, Europe/Kaliningrad, Europe/Moscow, Europe/Moscow, Europe/Volgograd, Europe/Samara, Asia/Kuwait, Asia/Riyadh, Africa/Nairobi, Asia/Baghdad, Asia/Tehran, Asia/Muscat, Asia/Muscat, Asia/Baku, Asia/Tbilisi, Asia/Yerevan, Asia/Kabul, Asia/Yekaterinburg, Asia/Karachi, Asia/Karachi, Asia/Tashkent, Asia/Kolkata, Asia/Kolkata, Asia/Kolkata, Asia/Kolkata, Asia/Kathmandu, Asia/Dhaka, Asia/Dhaka, Asia/Colombo, Asia/Almaty, Asia/Novosibirsk, Asia/Rangoon, Asia/Bangkok, Asia/Bangkok, Asia/Jakarta, Asia/Krasnoyarsk, Asia/Shanghai, Asia/Chongqing, Asia/Hong_Kong, Asia/Urumqi, Asia/Kuala_Lumpur, Asia/Singapore, Asia/Taipei, Australia/Perth, Asia/Irkutsk, Asia/Ulaanbaatar, Asia/Seoul, Asia/Tokyo, Asia/Tokyo, Asia/Tokyo, Asia/Yakutsk, Australia/Darwin, Australia/Adelaide, Australia/Melbourne, Australia/Melbourne, Australia/Sydney, Australia/Brisbane, Australia/Hobart, Asia/Vladivostok, Pacific/Guam, Pacific/Port_Moresby, Asia/Magadan, Asia/Srednekolymsk, Pacific/Guadalcanal, Pacific/Noumea, Pacific/Fiji, Asia/Kamchatka, Pacific/Majuro, Pacific/Auckland, Pacific/Auckland, Pacific/Tongatapu, Pacific/Fakaofo, Pacific/Chatham, Pacific/Apia.


GET /api/v3/circuits/power_factor
Power factor data for circuits

Returns power factor for the requested circuits.

Power factor is the ratio of the real power used to do work to the apparent power that is supplied.

If power factor is null, there is missing data for that time interval.

Example Request

$ curl -G \
"https://app.verdigris.co/api/v3/circuits/power_factor?\
ids=1,2&\
start_time=2017-06-20T23:55:00Z&\
end_time=2017-06-20T23:57:00Z&\
interval=minutely&\
timestamp_format=iso8601" \
--data-urlencode "timezone=Pacific Time (US & Canada)" \
-H "Authorization: Token token=<access_token>"

Examples

# RESPONSE
# result is in the format:
# {
#     circuit_id0: {
#         "timestamps": [
#             timestamp0,
#             timestamp1
#         ],
#         "power_factor": [
#             power_factor0,
#             power_factor1
#         ]
#     },
#     "circuit_id2": {
#         "timestamps": [
#             timestamp0,
#             timestamp1
#         ],
#         "power_factor": [
#             power_factor0,
#             power_factor1
#         ]
#     }
# }
{
    "1": {
        "timestamps": [
            "2017-06-20T16:55:00-07:00",
            "2017-06-20T16:56:00-07:00"
        ],
        "power_factor": [
            1337,
            1338
        ]
    },
    "2": {
        "timestamps": [
            "2017-06-20T16:55:00-07:00",
            "2017-06-20T16:56:00-07:00"
        ],
        "power_factor": [
            1337,
            1338
        ]
    }
}

Params

Param name Description
ids
required

comma separated circuit ids (e.g. 1,2)


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

interval
required

time between each data point


Value:

Must be one of: minutely, 15-minutely, hourly, daily.

timestamp_format
optional

specify how timestamps are returned in the response (default: unix epoch seconds)


Value:

Must be one of: iso8601.

timezone
optional

timezone used to account for hour and day boundaries, and daylight savings (default: UTC)


Value:

Must be one of: International Date Line West, Midway Island, American Samoa, Hawaii, Alaska, Pacific Time (US & Canada), Tijuana, Mountain Time (US & Canada), Arizona, Chihuahua, Mazatlan, Central Time (US & Canada), Saskatchewan, Guadalajara, Mexico City, Monterrey, Central America, Eastern Time (US & Canada), Indiana (East), Bogota, Lima, Quito, Atlantic Time (Canada), Caracas, La Paz, Santiago, Newfoundland, Brasilia, Buenos Aires, Montevideo, Georgetown, Greenland, Mid-Atlantic, Azores, Cape Verde Is., Dublin, Edinburgh, Lisbon, London, Casablanca, Monrovia, UTC, Belgrade, Bratislava, Budapest, Ljubljana, Prague, Sarajevo, Skopje, Warsaw, Zagreb, Brussels, Copenhagen, Madrid, Paris, Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna, West Central Africa, Bucharest, Cairo, Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius, Athens, Istanbul, Minsk, Jerusalem, Harare, Pretoria, Kaliningrad, Moscow, St. Petersburg, Volgograd, Samara, Kuwait, Riyadh, Nairobi, Baghdad, Tehran, Abu Dhabi, Muscat, Baku, Tbilisi, Yerevan, Kabul, Ekaterinburg, Islamabad, Karachi, Tashkent, Chennai, Kolkata, Mumbai, New Delhi, Kathmandu, Astana, Dhaka, Sri Jayawardenepura, Almaty, Novosibirsk, Rangoon, Bangkok, Hanoi, Jakarta, Krasnoyarsk, Beijing, Chongqing, Hong Kong, Urumqi, Kuala Lumpur, Singapore, Taipei, Perth, Irkutsk, Ulaanbaatar, Seoul, Osaka, Sapporo, Tokyo, Yakutsk, Darwin, Adelaide, Canberra, Melbourne, Sydney, Brisbane, Hobart, Vladivostok, Guam, Port Moresby, Magadan, Srednekolymsk, Solomon Is., New Caledonia, Fiji, Kamchatka, Marshall Is., Auckland, Wellington, Nuku’alofa, Tokelau Is., Chatham Is., Samoa, Pacific/Midway, Pacific/Midway, Pacific/Pago_Pago, Pacific/Honolulu, America/Juneau, America/Los_Angeles, America/Tijuana, America/Denver, America/Phoenix, America/Chihuahua, America/Mazatlan, America/Chicago, America/Regina, America/Mexico_City, America/Mexico_City, America/Monterrey, America/Guatemala, America/New_York, America/Indiana/Indianapolis, America/Bogota, America/Lima, America/Lima, America/Halifax, America/Caracas, America/La_Paz, America/Santiago, America/St_Johns, America/Sao_Paulo, America/Argentina/Buenos_Aires, America/Montevideo, America/Guyana, America/Godthab, Atlantic/South_Georgia, Atlantic/Azores, Atlantic/Cape_Verde, Europe/Dublin, Europe/London, Europe/Lisbon, Europe/London, Africa/Casablanca, Africa/Monrovia, Etc/UTC, Europe/Belgrade, Europe/Bratislava, Europe/Budapest, Europe/Ljubljana, Europe/Prague, Europe/Sarajevo, Europe/Skopje, Europe/Warsaw, Europe/Zagreb, Europe/Brussels, Europe/Copenhagen, Europe/Madrid, Europe/Paris, Europe/Amsterdam, Europe/Berlin, Europe/Berlin, Europe/Rome, Europe/Stockholm, Europe/Vienna, Africa/Algiers, Europe/Bucharest, Africa/Cairo, Europe/Helsinki, Europe/Kiev, Europe/Riga, Europe/Sofia, Europe/Tallinn, Europe/Vilnius, Europe/Athens, Europe/Istanbul, Europe/Minsk, Asia/Jerusalem, Africa/Harare, Africa/Johannesburg, Europe/Kaliningrad, Europe/Moscow, Europe/Moscow, Europe/Volgograd, Europe/Samara, Asia/Kuwait, Asia/Riyadh, Africa/Nairobi, Asia/Baghdad, Asia/Tehran, Asia/Muscat, Asia/Muscat, Asia/Baku, Asia/Tbilisi, Asia/Yerevan, Asia/Kabul, Asia/Yekaterinburg, Asia/Karachi, Asia/Karachi, Asia/Tashkent, Asia/Kolkata, Asia/Kolkata, Asia/Kolkata, Asia/Kolkata, Asia/Kathmandu, Asia/Dhaka, Asia/Dhaka, Asia/Colombo, Asia/Almaty, Asia/Novosibirsk, Asia/Rangoon, Asia/Bangkok, Asia/Bangkok, Asia/Jakarta, Asia/Krasnoyarsk, Asia/Shanghai, Asia/Chongqing, Asia/Hong_Kong, Asia/Urumqi, Asia/Kuala_Lumpur, Asia/Singapore, Asia/Taipei, Australia/Perth, Asia/Irkutsk, Asia/Ulaanbaatar, Asia/Seoul, Asia/Tokyo, Asia/Tokyo, Asia/Tokyo, Asia/Yakutsk, Australia/Darwin, Australia/Adelaide, Australia/Melbourne, Australia/Melbourne, Australia/Sydney, Australia/Brisbane, Australia/Hobart, Asia/Vladivostok, Pacific/Guam, Pacific/Port_Moresby, Asia/Magadan, Asia/Srednekolymsk, Pacific/Guadalcanal, Pacific/Noumea, Pacific/Fiji, Asia/Kamchatka, Pacific/Majuro, Pacific/Auckland, Pacific/Auckland, Pacific/Tongatapu, Pacific/Fakaofo, Pacific/Chatham, Pacific/Apia.


GET /api/v3/circuits/:circuit_id/disag
Show disaggregation data for a circuit

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