API Reference
Support

Batch circuit energy

get
https://api.verdigris.co/data/v4/energy/circuits

Gets energy data for multiple circuits in a single batch request. Units are in watt-hour (SI unit: Wh) if type query parameter is real, volt-ampere-hour (SI unit: VAh) if type query parameter is apparent.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
ids
array of integers
required
length ≥ 1

An array of circuit IDs separated by commas.

ids*
string
enum
required

Interval between each data points. Affects the validity of start_time, end_time query parameters, time resolution and aggregation of results.

For example, given the time range query parameters, start_time=2020-01-01T12:30:00Z&end_time=2020-01-01T13:00:00Z:

  • interval=1m: returns 30 data points at minutely resolution.
  • interval=15m: returns 2 data points at 15-minutesly/quarter-hourly resolution.

The ordering of timestamps is not guaranteed.

Allowed:
date-time
required

Start of the query time range. Value must be in ISO 8601 format.

Note that validity of start_time changes depending on the interval query parameter.

For example:

  • VALID: start_time=2020-01-01T12:34:00Z&interval=1m
  • VALID: start_time=2020-01-01T12:45:00Z&interval=15m
  • VALID: start_time=2020-01-01T13:00:00Z&interval=1h
  • VALID (if building’s timezone is in Pacific Standard Time):
    • start_time=2020-01-01T08:00:00Z&interval=1d (UTC)
    • start_time=2020-01-01T00:00:00+08:00&interval=1d (PST)
  • NOT VALID: start_time=2020-01-01T12:34:00Z&interval=15m
  • NOT VALID: start_time=2020-01-01T12:59:00Z&interval=1h
  • NOT VALID (if building’s timezone is in Pacific Standard Time):
    • start_time=2020-01-01T00:00:00Z&interval=1d
    • start_time=2020-01-01T04:00:00+08:00&interval=1d
date-time
required

End of the query time range. Value must be in ISO 8601 format.

Note that validity of end_time changes depending on the interval query parameter.

For example:

  • VALID: end_time=2020-12-31T12:34:00Z&interval=1m
  • VALID: end_time=2020-12-31T12:45:00Z&interval=15m
  • VALID: end_time=2020-12-31T13:00:00Z&interval=1h
  • VALID (if building’s timezone is in Pacific Standard Time):
    • end_time=2020-12-31T08:00:00Z&interval=1d (UTC)
    • end_time=2020-12-31T00:00:00+08:00&interval=1d (PST)
  • NOT VALID: end_time=2020-12-31T12:34:00Z&interval=15m
  • NOT VALID: end_time=2020-12-31T12:59:00Z&interval=1h
  • NOT VALID (if building’s timezone is in Pacific Standard Time):
    • end_time=2020-12-31T00:00:00Z&interval=1d
    • end_time=2020-12-31T04:00:00+08:00&interval=1d
string | null
enum

Format timestamps in the data. If set to ISO8601 (case-insensitive), the timestamp is returned as a string formatted in ISO 8601 format. If omitted, the timestamp is returned as an integer representing UNIX epoch.

Allowed:
string
Defaults to UTC

When used in conjunction with timestamp_format query parameter that is set to ISO8601 format, specifying the zone ID of IANA Time Zone Database returns the timestamp in the time zone offset.

Setting the timezone when timestamp_format is not specified has no affect on the UNIX epoch timestamp.

Note

This query parameter meant to be a convenience feature that only affects the display format of the timestamps in the result. It has no affect on the building’s timezone.

string | null
enum
Defaults to real

Type of energy:

  • real: Energy calculated from real (true) power over given time interval. Returns energy in watt-hour (SI unit: Wh).
  • apparent: Energy calculated from apparent power over given time interval. Returns energy in volt-ampere-hour (SI unit: VAh). Apparent energy is not supported for daily interval.
Allowed:
string
enum

Warning

This query parameter is intended for advanced users troubleshooting potentially incorrect data. Incorrect use of this query parameter can lead to erroneous data.

Overrides the configured phase for this circuit and returns the data as if the circuit was on the specified phase.

When omitted, the circuit will reference the phase based on the current panel configuration.

Allowed:
string
enum

Warning

This query parameter is intended for advanced users troubleshooting potentially incorrect data. Incorrect use of this query parameter can lead to erroneous data.

Overrides the configured sensor orientation to return circuit data as if the CT was clamped upside down and flip positive values to negative and vice versa.

When omitted, the API will compute the data by referencing the sensor orientation based on the current panel configuration.

Allowed:
Headers
string
enum
Defaults to application/json

Specify a MIME type to indicate the content type the client would like to receive the data in. If omitted, defaults to application/json.

Currently, the supported formats are:

  • application/json
  • text/csv
Allowed:
Responses

Updated 2 months ago

Language
Credentials
OAuth2
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
text/csv

Updated 2 months ago