SolarQuery API global objects

This page lists objects used throughout the SolarQuery API.

Paged results object

Many API methods can return large sets of data, but SolarQuery will break up the results into smaller paged response objects that contain just a subset of the overall data. The response object contains details on the total number of available results along with the starting offset of the returned results:

{
  "success": true,
  "data": {
    "results": [...],
    "totalResults": 2384790,
    "startingOffset": 0,
    "returnedResultCount": 250
  }
}

In the preceding example, 2384790 results are available, but only the first 250 results have been returned in the data array. To get the next set, or page, of results you'd call the same method again but provide a 0-based starting offset for the desired first result. In this case, an offset of 250 would return the next page, which would result in a response like:

{
  "success": true,
  "data": {
    "results": [...],
    "totalResults": 2384790,
    "startingOffset": 250,
    "returnedResultCount": 250
  }
}

Paged query parameters

For API methods that return paged results objects, the following query parameters are used to specify the page attributes:

max	A positive integer for the maximum number of results to return in the response. SolarQuery might limit the number of returned results and ignore this value if it is too large.
offset	A non-negative integer for the starting offset of the results to return in the response. When combined with the max parameter you can get individual _pages_ of results from the overall result set.

Example

An example URL query string to return page 2 of a result set using 100 results per page:

?max=100&offset=100

Sort query parameters

For API methods that support sorting the result, an array of sort descriptors can be provided on the sorts query parameter. Array parameters must be specified as sort[x].y where x is a 0-based index that specifies the order of the sort descriptor and y is the sort descriptor property as detailed here:

sortKey	The name of the property to sort the results by. Typically this will correspond to the name of an attribute in the returned result objects. For example to sort a location search by name, a query parameter like sorts[0].sortKey=locationName might be appropriate. Consult the documentation for individual API methods for details on the supported sortKey values.
descending	A boolean indicating the sort should be in descending (true) or ascending (false) order. By default this value is false so sorts will be applied in ascending order if this is not specified.

Example

An example URL query string to sort by creation in descending order:

?sorts%5B0%5D.sortKey=created&sorts%5B0%5D.descending=true

Virtual ID queries

Virtual ID queries are queries where real node or source ID values are combined into results using a virtual ID. Imagine you had several PV inverters on a large solar array, each reporting their energy output on source IDs /pv/1, /pv/2, and /pv/3. You'd like to know the total energy output of all these inverters together. You could query for all 3 source IDs and then add up the results yourself, like this (date parameters omitted):

?nodeId=123&sourceIds=/pv/1,/pv/2,/pv/3&aggregation=Hour

which might return results like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"/pv/3", "wattHours":1000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"/pv/3", "wattHours":1000}
]

Virtual IDs provide a way to let SolarQuery sum them for you, by mapping the three source IDs into a single virtual ID PV. To do this, you would provide query parameters like this (in addition to those shown before):

?combiningType=Sum&sourceIdMaps=PV:/pv/1,/pv/2,/pv/3

This query will return a single result for those three real source IDs, like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "sourceId":"PV", "wattHours":3000},
  {"created":"2018-05-01 13:00:00.000Z", "sourceId":"PV", "wattHours":3000}
]

Node IDs can also be combined into virtual IDs. Imagine a query like this (date parameters omitted):

?nodeIds=123,345&sourceIds=/pv/1,/pv/2,/pv/3&aggregation=Hour

that returned results like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":123, "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":123, "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":123, "sourceId":"/pv/3", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":345, "sourceId":"/pv/1", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":345, "sourceId":"/pv/2", "wattHours":1000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":345, "sourceId":"/pv/3", "wattHours":1000}
]

These can be combined into a single -100 virtual ID with query parameters like this (in addition to those shown before):

?combiningType=Sum&nodeIdMaps=-100:123,345

that returned results like this:

[
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"/pv/1", "wattHours":2000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"/pv/2", "wattHours":2000},
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"/pv/3", "wattHours":2000}
]

Both node IDs and source IDs can be combined at once, so for example you could combine all results into a single virtual source ID PV and node ID -100 with query parameters like:

?combiningType=Sum&nodeIdMaps=-100:123,345&sourceIdMaps=PV:/pv/1,/pv/2,/pv/3

which would result in:

[
  {"created":"2018-05-01 12:00:00.000Z", "nodeId":-100, "sourceId":"PV", "wattHours":6000},
]

You can even provide multiple virtual ID mappings, for example to return virtual node IDs -100 and -200 and virtual source IDs PV and LOAD you might have these query parameters:

?combiningType=Sum&nodeIdMaps=-100:123,345&nodeIdMaps=-200:456,678&sourceIdMaps=PV:/pv/1,/pv/2,/pv/3&sourceIdMaps=LOAD:/meter/1,/meter/2