The SolarQuery API provides methods to query the data collected via SolarNodes or Cloud Integrations. All dates and times are represented in the Gregorian calendar system. API methods are usually offered under both /pub and /sec paths, the former is for SolarNodes which publicly share their data, and the later is for SolarNodes that require a secure authentication token to access their data. When you see a path like /api/v1/{pub,sec} that should use either /pub or /sec for the URL. See SolarNet API authentication for information on how to use /sec paths.

Some legacy API endpoints are still available, but should be transitioned to the supported methods outlined here.

SolarQuery supports different response data formats, which are based on the Accept HTTP header used in the request. The supported formats, and their associated Accept header values, are:

• CBOR - application/cbor
• JSON - application/json
• XML - text/xml
• CSV - text/csv

This method allows you to refresh the signing key of an authentication token, for when you have been given a token ID and a signing key, but not the original token secret key. A signing key is only valid for a limited time. Calling this method with a properly authenticated token will return a new signing key for that token, good for another window of time. See Signing key for more information on tokens.

Note that only tokens that specifically allow refreshing will work.

An example response looks like:

{
    "success": true,
    "data": {
        "key": "22dd38b0a4c4bfc66968dd2bc153174fc1a58a03dd7d5957a9c8702d2e790ade"
    }
}

This method returns information about the span of time data is available for a particular node.

An example response looks like:

{
    "success": true,
    "data": {
        "timeZone": "Pacific/Auckland",
        "endDate": "2013-09-22 16:39",
        "startDate": "2009-07-27 16:25",
        "yearCount": 5,
        "monthCount": 51,
        "dayCount": 1519,
        "endDateMillis": 1379824746781,
        "startDateMillis": 1248668709972
    }
}

This method returns the available source ID values for a given node, or all source ID values matching a datum metadata filter.

🔥 Note this method is similar to the /nodes/sources method. However, this method requires node IDs to be specified and does not support as many search criteria.

The response takes one of two forms:

• an array of strings, each value representing a single source ID
• an array of objects with nodeId and sourceId properties, only if a metadataFilter is provided and multiple node IDs are found, or if withNodeIds=true is specified

The results are not returned in any particular order.

By default the result will be an array of strings, like this:

{
  "success": true,
  "data": [
    "Main2",
    "Main1",
    "Main"
  ]
}

When searching with a metadataFilter and multiple node IDs are found, or withNodesIds is true, the result will be an array of objects with nodeId and sourceId properties, like this:

{
  "success": true,
  "data": [
    {"nodeId":1, "sourceId":"Main"},
    {"nodeId":2, "sourceId":"Main"},
    {"nodeId":2, "sourceId":"Main1"}
  ]
}

A wildcard pattern can be used to search for source IDs matching a wildcard pattern. For example a URL like this would restrict the results to just those starting with /power:

/api/v1/pub/range/sources?nodeId=123&sourceId=/power/**

which might return results like this:

{
  "success": true,
  "data": [
    "/power/switch/1",
    "/power/switch/2",
    "/power/switch/3",
    "/power/switch/grid"
  ]
}

while

/api/v1/pub/range/sources?nodeId=123&sourceId=/power/switch/%3F

might only return results like this:

{
  "success": true,
  "data": [
    "/power/switch/1",
    "/power/switch/2",
    "/power/switch/3"
  ]
}

This method returns the available node ID values for the active user. When accessed with a user security token, all node IDs owned by that user are returned. When accessed with a data security token, only the node IDs in the security policy attached to the token that are owned by the issuer of the data token are return. If the security policy does not have any node ID restrictions, then all node IDs owned by the issuer of the data token are returned.

Notes:

• Archived node IDs are not returned in the results.
• This endpoint is similar to the SolarUser /nodes endpoint, but works with data security tokens.

The response is an array of numbers, each value representing a single node ID. They are returned in ascending order.

An example response looks like:

{
  "success": true,
  "data": [
    123,
    234,
    345
  ]
}

This method returns the available node ID and source ID combinations matching various search criteria. All criteria are optional, and all provided criteria must match for a value to be returned.

🔥 Note this method is similar to the /range/sources?withNodeIds=true method. However, this method supports more search criteria options and does not require any node IDs be specified.

The response consists of an array of objects with nodeId and sourceId properties, for example:

{
  "success": true,
  "data": [
    {"nodeId":1, "sourceId":"Main"},
    {"nodeId":2, "sourceId":"Main"},
    {"nodeId":2, "sourceId":"Main1"}
  ]
}

Here are some example search criteria for various scenarios:

• Sources matching solar inverters /**/INV/*: sourceId=%2F**%2FINV%2F*
• Sources that posted datum in a specific week: startDate=2024-01-01&endDate=2024-01-07
• Sources with watts and wattHours properties: instantaneousPropertyName=watts&accumulatingPropertyName=wattHours
• Sources from devices manufactured by Accuenergy: metadataFilter=(%2Fpm%2FdeviceInfo%2Fmanufacturer%3DACCUENERGY)

This method returns the most recently posted datum, by source, for a given node or set of nodes.

Notes:

• Supported aggregation values are limited to:
  • Hour
  • Day
  • Month
• If date criteria are included, the results will be the most recent available within the date range constraints.
• If no startDate or localStartDate criteria are included, an implicit startDate value equal to 90 days before the query execution date will be assumed. Essentially the query will be limited to showing sources that have posted within the past 90 days.

The response contains a paged results object of datum objects, one for each matching source ID. All response objects have the following properties:

An example response looks like (notice the inline sample properties):

{
  "success": true,
  "data": {
    "totalResults": 1,
    "startingOffset": 0,
    "returnedResultCount": 1,
    "results": [
      {
        "created": "2011-10-05 11:00:00.000Z",
        "nodeId": 30,
        "sourceId": "Main",
        "localDate": "2011-10-06",
        "localTime": "00:00",
        "watts": 1065.228,
        "wattHours": 12775.876,
        "tags": [
          "consumption"
        ]
      }
    ]
  }
}

This method returns datum values, either raw data or aggregated if the aggregation parameter is provided.

This method supports paged query parameters. In addition, each datum type supports filtering and sorting the results based on the properties of the datum being queried.

Datum list queries support the following sort query parameter keys:

• created
• node
• source

Notes:

• Use either the local*Date or *Date parameters; do not mix the two styles. For example, providing localStartDate and endDate parameters is not supported.

The response contains a paged results object with the following properties returned for each result datum:

An example response object looks like this:

{
  "created": "2011-10-05 11:00:00.000Z",
  "nodeId": 30,
  "sourceId": "Main",
  "localDate": "2011-10-06",
  "localTime": "00:00",
  "watts": 1065.228,
  "wattHours": 12775.876,
  "tags": [
    "consumption"
  ]
}

This method returns datum values, either "virtual" raw values derived from actual raw data across time, or aggregated as a difference between raw data at two points in time. This endpoint is helpful for "meter reading" style applications that need to know how much of something was measured over time, for example how much energy a power meter measured over time.

The calculations used by this endpoint are not the same as those used by the /datum/list endpoint. That endpoint calculates aggregate values for individual hourly time slots, even for larger aggregates, and will ignore differences in data if the difference in time between two raw datum is too large. This endpoint will look for datum as close as possible to the requested dates, and then produce a result based on just those found datum. This is akin to taking a meter reading at the start and end of a billing cycle, where the charge for the bill is the difference between the two readings. See the SolarNet aggregation guide for more info.

This method will use any Reset type datum auxiliary records that match the given search criteria, and calculate the overall difference taking those into account. The datum stream example helps visualize how the Reset records are used to calculate the reading differences in the same way used by this method.

The following sort query parameter keys are supported:

• created
• node
• source

Notes:

• Use either the local*Date or *Date parameters; do not mix the two styles. For example, providing localStartDate and endDate parameters is not supported.
• When aggregation is provided, results for the specified aggregation are returned. For example, if the date range is specified as 2000-01-01 to 2001-01-01 and Month aggregation is used, 12 results will be returned per node and source combination, one for each month. Each month's results shows the reading values for just that month.
• If no datum exists before a given start date, either because there simply isn't any data or there isn't any data within the tolerance range of the start date, the queries will include the first available datum within the given start/end dates. This can happen if datum are posted infrequently or at the very start of a datum stream, for example when querying for datum in the month the stream started and the stream starts in the middle of the month.

The response contains a list of datum with the same basic properties as returned by the /datum/list endpoint, with some additions as shown below. Note that the Difference reading type queries only support returning the accumulating datum properties of the datum, as those are only ones suitable for those queries.

In addition to the above properties, all accumulating properties will have two additional properties added, named after the property and one a _start suffix and one with an _end suffix. These represent the value of the associated property in the found raw datum for the start and end of the time range.

Here's an example response object (note the wattHours_end and wattHours_start properties associated with the calculated wattHours difference):

{
	"created": "2018-07-01 03:59:42.014Z",
	"nodeId": 18,
	"sourceId": "/GEN/1",
	"localDate": "2018-06-30",
	"localTime": "23:59",
	"wattHours": 10320000,
	"wattHours_end": 805703000,
	"wattHours_start": 795383000,
	"endDate": "2018-08-01 03:58:42.014Z",
	"timeZone": "America/New_York",
	"localEndDate": "2018-07-31 23:58:42.014"
}

This result shows that SolarNetwork found a starting datum at 2018-07-01 03:59:42.014Z with a wattHour reading of 795383000 and an ending datum at 2018-08-01 03:58:42.014Z with a wattHour reading of 805703000 and calculated the difference as 10320000.

Location data is not associated with a specific node, so many SolarNodes can share the same data. This method allows you to look up the unique ID for a location based on its name and other attributes. When querying, at least one location.* filter must be provided.

This method supports paged query parameters.

This method supports the following sort query parameter keys:

• source
• location.name
• location.country
• location.region
• location.stateOrProvince
• location.postalCode
• location.timeZoneId

The response contains a paged results object with an array of location objects. All location objects contain the following properties:

An example response looks like this:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": 301025,
        "created": "2009-09-14 00:48:03.014Z",
        "country": "NZ",
        "region": "Auckland",
        "locality": "Auckland",
        "timeZoneId": "Pacific/Auckland"
      }
    ],
    "totalResults": 1,
    "startingOffset": 0,
    "returnedResultCount": 1
  }
}

This method returns the most recently posted location datum, by source, for a given node or set of locations.

Notes:

• Supported aggregation values are limited to:
  • Hour
  • Day
  • Month
• If date criteria are included, the results will be the most recent available within the date range constraints.

The response contains a paged results object of datum objects, one for each matching source ID. All response objects have the following properties:

An example response looks like (notice the inline sample properties):

{
  "success": true,
  "data": {
    "totalResults": 1,
    "startingOffset": 0,
    "returnedResultCount": 1,
    "results": [
      {
        "created": "2021-10-19 00:00:00Z",
        "locationId": 11536828,
        "sourceId": "Yr",
        "localDate": "2021-10-19",
        "localTime": "13:00:00",
        "atm": 101750,
        "rain": 0,
        "temp": 15,
        "wdir": 321,
        "wspeed": 9.4,
        "sky": "Partly cloudy",
        "validTo": "2021-10-19T01:00:00Z",
        "symbolVar": "03d",
        "tags": [
          "forecast"
        ]
      }
    ]
  }
  "data":
}

This method returns location datum values, either raw data or aggregated if the aggregation parameter is provided. Location data is not node-specific, so it can be shared across any number of nodes. The structure is similar to the datum list API, with a location ID property associated with each datum instead of a node ID.

This method supports paged query parameters. In addition, each datum type supports filtering and sorting the results based on the properties of the datum being queried.

Location datum queries support the following sort query parameter keys:

• created
• source
• location.name
• location.country
• location.region
• location.stateOrProvince
• location.postalCode

Notes:

• Use either the local*Date or *Date parameters; do not mix the two styles. For example, providing localStartDate and endDate parameters is not supported.

The response contains a paged results object with the following properties returned for each result datum:

An example response object looks like this:

{
	"created": "2016-05-29 12:00:00.000Z",
	"locationId": 11536819,
	"sourceId": "NZ MetService Day",
	"localDate": "2016-05-30",
	"localTime": "00:00",
	"sunrise": "07:33",
	"sunset": "17:04",
	"moonrise": "00:02",
	"moonset": "13:18",
	"sky": "Partly cloudy"
}

Location datum metadata is metadata associated with a specific source ID of a specific location ID. It may be queried using the following endpoints. All returned metadata objects will include locationId and sourceId properties for the ID of the location and source the metadata is associated with.

Location datum metadata is used for things like identifying locations with weather data. This method allows you to look up locations based on that metadata, returning both the matching metadata and associated location details. At least one query parameter must be used, and multiple parameters are logically AND-ed together.

This method supports paged query parameters.

This method supports the following sort query parameter keys:

• created - the metadata creation time
• location - the location ID
• source - the source ID
• updated the metadata update time

The response contains a paged results object with an array of location metadata objects. Location metadata objects contain all available metadata properties (such as m, pm, and t) along with the following properties:

An example response looks like this:

{
  "success": true,
  "data": {
    "totalResults": 1,
    "startingOffset": 0,
    "returnedResultCount": 1,
    "results": [
      {
        "created": "2018-09-17 22:26:13.777Z",
        "updated": "2018-09-17 22:26:13.777Z",
        "locationId": 11537068,
        "sourceId": "OpenWeatherMap",
        "location": {
          "id": 7068,
          "created": "2018-05-08 18:29:16.630Z",
          "country": "US",
          "stateOrProvince": "DE",
          "locality": "Wilmington",
          "timeZoneId": "America/New_York"
        },
        "m": {
          "name": "Wilmington"
        },
        "t": [
          "weather"
        ]
      }
    ]
  }
}

This endpoint returns a list of metadata for all location datum sources of a specific location.

This endpoint returns the location datum metadata for a specific location and source.

This method returns information about the span of time data is available for a particular location.

An example response looks like:

{
    "success": true,
    "data": {
        "timeZone": "Pacific/Auckland",
        "endDate": "2013-09-22 16:39",
        "startDate": "2009-07-27 16:25",
        "yearCount": 5,
        "monthCount": 51,
        "dayCount": 1519,
        "endDateMillis": 1379824746781,
        "startDateMillis": 1248668709972
    }
}

This method returns the available source ID values for a given location, or all source ID values matching a location datum metadata filter.

The response returns an array of strings, each value representing a single source ID. The results are not returned in any particular order. An example response looks like this:

{
  "success": true,
  "data": [
    "Main2",
    "Main1",
    "Main"
  ]
}

A wildcard pattern can be used to search for source IDs matching a wildcard pattern. For example a URL like this would restrict the results to just those starting with /power:

/api/v1/pub/location/datum/sources?locationId=123&sourceId=/power/**

which might return results like this:

{
  "success": true,
  "data": [
    "/power/switch/1",
    "/power/switch/2",
    "/power/switch/3",
    "/power/switch/grid"
  ]
}

while

/api/v1/pub/location/datum/sources?locationId=123&sourceId=/power/switch/%3F

might only return results like this:

{
  "success": true,
  "data": [
    "/power/switch/1",
    "/power/switch/2",
    "/power/switch/3"
  ]
}

Node datum metadata is metadata associated with a specific source ID of a specific node ID. It may be queried using the following endpoints. All returned metadata objects will include nodeId and sourceId properties for the ID of the node and source the metadata is associated with.

This endpoint returns a list of metadata for all node datum sources.

{
  "success": true,
  "data": {
    "results": [
      {
        "created": "2017-02-27 04:41:17.510Z",
        "updated": "2017-02-27 05:01:32.198Z",
        "nodeId": 250,
        "sourceId": "MockMeterA",
        "m": {
          "num": 12
        },
        "pm": {
          "room": {
            "foo": "bar"
          }
        },
        "t": [
          "green",
          "yellow"
        ],
      }
    ],
    "returnedResultCount": 1,
    "startingOffset": 0,
    "totalResults": 1
  },
}

This endpoint returns the node datum metadata for a specific node and source.

{
  "success": true,
  "data": {
    "results": [
      {
        "created": "2017-02-27 04:41:17.510Z",
        "updated": "2017-02-27 05:01:32.198Z",
        "nodeId": 250,
        "sourceId": "MockMeterA",
        "m": {
          "num": 12
        },
        "pm": {
          "room": {
            "foo": "bar"
          }
        },
        "t": [
          "green",
          "yellow"
        ],
      }
    ],
    "returnedResultCount": 1,
    "startingOffset": 0,
    "totalResults": 1
  },
}

Query for node datum stream metadata. This can be used to list the stream metadata for a given set of stream IDs, or list the metadata matching a set of node IDs and/or source IDs.

The response contains a list of datum stream metadata objects.

Here's an example response with 2 results:

{
  "success": true,
  "data": [
    {
      "streamId": "9458020e-789b-49d5-8a29-d9b53fde622f",
      "zone": "Pacific/Auckland",
      "kind": "n",
      "objectId": 123,
      "sourceId": "/test/power/meter/1",
      "i": [
        "watts",
        "current",
        "voltage",
        "frequency",
        "realPower",
        "powerFactor",
        "phaseVoltage",
        "apparentPower",
        "reactivePower"
      ],
      "a": [
        "wattHours"
      ]
    },
    {
      "streamId": "0168b2cd-3489-494f-9881-007189ac1526",
      "zone": "Pacific/Auckland",
      "kind": "n",
      "objectId": 123,
      "sourceId": "/gps/1",
      "i": [
        "alt",
        "lat",
        "lon",
        "alt_ep",
        "lon_ep",
        "latError",
        "lat_ep"
      ]
    }
  ]
}

Query for node datum stream metadata IDs. This can be used to list the stream metadata for a given set of stream IDs, or list the metadata IDs matching a set of node IDs and/or source IDs. This endpoint is similar to Datum stream metadata list but it omits the datum property names, and executes more quickly and returns a smaller amount of information in the response, omitting all non-identifying properties.

The response contains a list of datum stream metadata objects with only the streamId, kind, objectId, and sourceId properties.

Here's an example response with 2 results:

{
  "success": true,
  "data": [
    {
      "streamId": "9458020e-789b-49d5-8a29-d9b53fde622f",
      "kind": "n",
      "objectId": 123,
      "sourceId": "/test/power/meter/1"
    },
    {
      "streamId": "0168b2cd-3489-494f-9881-007189ac1526",
      "kind": "n",
      "objectId": 123,
      "sourceId": "/gps/1"
    }
  ]
}

Node metadata is metadata associated with a specific node ID and no source ID. All returned metadata objects will include a nodeId property for the ID of the node the metadata is associated with.

This method returns node metadata for one or more nodes. This method supports paged query parameters.

Node metadata list queries support the following sort query parameter keys:

• created
• node
• updated

{
  "success": true,
  "data": {
  "results": [
    {
      "nodeId": 1,
      "created": "2016-11-11 08:06:10.866Z",
      "updated": "2016-11-13 21:40:08.015Z",
      "m": {
        "a": "1",
        "b": "2"
      },
      "pm": {
        "A": {
          "a": "3",
          "b": "4"
        }
      },
      "t": [
        "test",
        "fun"
      ]
    }
  ],
  "totalResults": 1,
  "startingOffset": 0,
  "returnedResultCount": 1
  }
}

This endpoint returns node metadata for a specific node.

{
  "success": true,
  "data": {
    "nodeId": 1,
    "created": "2016-11-11 08:06:10.866Z",
    "updated": "2016-11-13 21:40:08.015Z",
    "m": {
      "a": "1",
      "b": "2"
    },
    "pm": {
      "A": {
        "a": "3",
        "b": "4"
      }
    },
    "t": [
      "test",
      "fun"
    ]
  }
}

User metadata is metadata associated with a SolarNetwork user account. All returned metadata objects will include a userId property for the ID of the user the metadata is associated with.

Note that by default user metadata is not accessible. It can only be accessed with an appropriate user security token or a data security token with a userMetadataPaths security policy specified.

This endpoint returns a single user metadata.

{
  "success": true,
  "data": {
    "userId": 2,
    "created": "2016-11-11 08:06:10.866Z",
    "updated": "2016-11-13 21:40:08.015Z",
    "m": {
      "a": "6",
      "b": "7"
    },
    "pm": {
      "A": {
        "a": "8",
        "b": "9"
      }
    }
  }
}