SolarQuery API

The SolarQuery API provides methods to query the data collected by SolarNodes. 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.

Response formats

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:

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

Endpoints

Verb	Endpoint	Description
GET	/auth-tokens/refresh/v2	Refresh an authentication token.
GET	/datum/list	Query raw or aggregate data by time, source, and node.
GET	/datum/meta/{nodeId}	List metadata for all node datum sources.
GET	/datum/meta/{nodeId}/{sourceId}	Get metadata for a node datum source.
GET	/datum/mostRecent	Get the most recently posted data by source.
GET	/datum/reading	Get data at specific dates or the difference between two dates.
GET	/datum/stream/meta/node	Find metadata for a node datum stream.
GET	/datum/stream/meta/node/ids	Find metadata IDs for a node datum stream.
GET	/location	Find locations by name.
GET	/location/datum/list	Query raw or aggregate location data by time, source, and location.
GET	/location/datum/meta	Find location datum metadata, or locations via metadata.
GET	/location/datum/meta/{locationId}	Get all location datum metadata for a location.
GET	/location/datum/meta/{locationId}/{sourceId}	Get location datum metadata for a location and source.
GET	/location/datum/mostRecent	Get the most recently posted location data by source.
GET	/location/datum/interval	Get the available date range for location data sets.
GET	/location/datum/sources	Get the available source IDs for a set of location IDs.
GET	/nodes	Get the available node IDs for the authenticated token.
GET	/nodes/meta	Get metadata for one or more nodes.
GET	/nodes/meta/{nodeId}	Get metadata for a single node.
GET	/nodes/sources	Get the available node and source IDs for the authenticated token.
GET	/range/interval	Get the available date range for data sets.
GET	/range/sources	Get the available source IDs for a set of node IDs.
GET	/users/meta/{userId}	Get metadata for a single user.

Refresh token

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.

GET	/solarquery/api/v1/sec/auth-tokens/refresh/v2
date	The desired signing date to use, using the syntax YYYY-MM-DD. The UTC time zone is assumed. Typically the current date will be used, which will result in the maximum allowable time before the signing key expires. Use a date in the past if a shorter time span is desired.

Refresh token response

Property	Type	Description
key	string	A hexadecimal-encoded signing key.

An example response looks like:

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

Reportable interval

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

GET	/solarquery/api/v1/{pub,sec}/range/interval
nodeId	The node ID to get the interval for.
sourceId	An optional source ID value to limit the result to. If not provided the returned interval represents all available node data.

Reportable interval response

Property	Type	Description
timeZone	string	The time zone the node is in.
endDate	string	The ending date of the time span, in YYYY-MM-dd HH:mm format, in the node's time zone.
endDateMillis	number	The ending date of the time span, as the number of milliseconds since the epoch, in GMT.
startDate	string	The starting date of the time span, in YYYY-MM-dd HH:mm format, in the node's time zone.
startDateMillis	number	The starting date of the time span, as the number of milliseconds since the epoch, in GMT.
yearCount	number	The number of years represented by the time span.
monthCount	number	The number of months represented by the time span.
dayCount	number	The number of days represented by the time span.

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
    }
}

Reportable sources

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.

GET	/solarquery/api/v1/{pub,sec}/range/sources
nodeId	The node ID to get the sources for.
nodeIds	A comma-delimited list of node IDs, or multiple parameters, to get the sources for.
sourceId	An optional source ID wildcard pattern to limit the results to. This pattern restricts the resulting source IDs to only those that match the pattern.
withNodeIds	If true then always return node ID and source ID objects in the response. With false (or not specified) then only source ID values are returned. See the response section for more info.
startDate	An optional start date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, to restrict the query range to. If omitted, the first available data for the SolarNode will be used as the start date. The date must be provided in the UTC time zone.
endDate	An optional end date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, to restrict the query range to. If omitted, the most recently available data for the SolarNode will be used as the end date. The date must be provided in the UTC time zone.
metadataFilter	An optional metadata filter to limit the results to. If provided, the startDate and endDate dates are ignored. Additionally, multiple node IDs may be specified using a nodeIds parameter with a comma-delimited list of node IDs to search for.

Reportable sources response

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"
  ]
}

Reportable nodes

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.

GET	/solarquery/api/v1/sec/nodes
metadataFilter	An optional metadata filter to limit the results to.

Reportable nodes response

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
  ]
}

Reportable node sources

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.

GET	/solarquery/api/v1/sec/nodes/sources
nodeId	The node ID to match.
nodeIds	A comma-delimited list of node IDs, or multiple parameters, to limit the results to.
sourceId	A source ID wildcard pattern to limit the results to.
sourceIds	A comma-delimited list of source ID patterns, or multiple parameters, to limit the results to.
startDate	A minimum date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, that a source must have associated datum available after. The date must be provided in the UTC time zone.
endDate	A maximum date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, that a source must have associated datum available before. The date must be provided in the UTC time zone.
localStartDate	A minimum date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, that a source must have associated datum available after. The time zone will be specific to the node associated with the source.
localEndDate	A maximum date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, that a source must have associated datum available before. The time zone will be specific to the node associated with the source.
metadataFilter	A datum stream metadata filter to limit the results to.
propertyName	A datum property name that a source must include (instantaneous, accumulating, or status).
propertyNames	A comma-delimited list of datum property names that a source must include at least one of (instantaneous, accumulating, or status).
instantaneousPropertyName	A datum instantaneous property name that a source must include.
instantaneousPropertyNames	A comma-delimited list of datum instantaneous property names that a source must include.
accumulatingPropertyName	A datum accumulating property name that a source must include.
accumulatingPropertyNames	A comma-delimited list of datum accumulating property names that a source must include.
statusPropertyName	A datum status property name that a source must include.
statusPropertyNames	A comma-delimited list of datum status property names that a source must include.

Reportable node sources response

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"}
  ]
}

Reportable node sources examples

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)

Most recent datum

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

GET	/solarquery/api/v1/{pub,sec}/datum/mostRecent
nodeId	The ID of a single node.
nodeIds	A comma-delimited list of node IDs. This parameter may also be provided multiple times.
sourceId	The ID of a single source to restrict the results to. A wildcard pattern can be used to restrict the results to only source IDs that match the pattern. Also, read more about how source IDs resolve with security policy restrictions.
sourceIds	A comma-delimited list of source ID values to limit the returned results to. This parameter may also be provided multiple times. If not provided, the most recently available data for all sources will be returned.
aggregation	An optional aggregation type which will return the most recent aggregate datum for the given level, instead of the raw datum. See the SolarNet aggregation guide for more info.
startDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
localStartDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
localEndDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.

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.

Most recent datum response

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

Property	Type	Description
created	string	The datum creation date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
nodeId	number	The node ID.
sourceId	string	The source ID.
localDate	string	The date of the datum, in a YYYY-MM-dd pattern in the node's local time zone.
localTime	string	The time of the datum, in a HH:mm pattern in the node's local time zone.
tags	array	An array of associated tag string values.
sample properties	varies	The general node datum samples a, i, and s objects will have their properties returned directly on the response object.

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"
        ]
      }
    ]
  }
}

Datum list

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.

GET	/solarquery/api/v1/{pub,sec}/datum/list
localStartDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
localEndDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
startDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
mostRecent	If true then no date range is required, and the most recently posted datum for all matching nodes/sources will be returned. This can also be combined with the aggregation parameter to return the most recent calculated aggregate values instead of raw datum (only the Hour, Day, and Month types are supported). Date parameters may be included to restrict the results to the most recently available datum within the given date range.
aggregation	An optional aggregation type. If not provided, then non-aggregated data will be returned. See the SolarNet aggregation guide for more info. ⚠️ Note the *Minute types enforce a maximum date range of 5 weeks.
partialAggregation	An optional aggregation type for partial aggregation results to be included. See the partial aggregation guide for more info.
nodeId	The ID of a single node.
nodeIds	A comma-delimited list of node IDs. This parameter may be also provided multiple times.
sourceId	The ID of a single source to restrict the results to. A wildcard pattern can be used to restrict the results to only source IDs that match the pattern. Also, read more about how source IDs resolve with security policy restrictions.
sourceIds	A comma-delimited list of source IDs to restrict the results to. This parameter may also be provided multiple times.
withoutTotalResultsCount	If true then the results will not contain a totalResults value. This allows the query to execute faster. When iterating over the result data pages, you then iterate until less than the requested page size is returned.
combiningType	An optional combining type to combine raw results into virtual ones. Specifying a type here requires some combintation of nodeIdMaps and sourceIdMaps parameters also be provided. See Virtual IDs for more information.
nodeIdMaps	Return combined node IDs as virtual node IDs using the specified combiningType. The format of this parameter is VID:IDLIST where VID is a virtual node ID (integer) and IDLIST is a comma-delimited list of real node IDs. Multiple virtual IDs can be assigned by providing multiple nodeIdMaps query parameters. See Virtual IDs for more information.
sourceIdMaps	Return combined source IDs as virtual source IDs using the specified combiningType. The format of this parameter is VID:IDLIST where VID is a virtual source ID and IDLIST is a comma-delimited list of real source IDs. Multiple virtual IDs can be assigned by providing multiple sourceIdMaps query parameters. This parameter requires the withoutTotalResultsCount also be set to true. See Virtual IDs for more information.

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.

Datum list response

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

Property	Type	Description
created	string	The datum creation date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
nodeId	number	The node ID.
sourceId	string	The source ID.
localDate	string	The date of the datum, in a YYYY-MM-dd pattern in the node's local time zone.
localTime	string	The time of the datum, in a HH:mm pattern in the node's local time zone.
tags	array	An array of associated tag string values.
sample properties	varies	The general node datum samples a, i, and s objects will have their properties returned directly on the response object.

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"
  ]
}

Datum reading

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.

GET	/solarquery/api/v1/{pub,sec}/datum/reading
readingType	The type of reading to perform. See Datum reading types for possible values.
localStartDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
localEndDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
startDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
aggregation	An optional aggregation type. If provided, then individual aggregate results covering the time range between the start/end dates will be returned, instead of just one result for the overall range. Only Hour, Day, and Month values are supported. Only the Difference reading type is supported. See the SolarNet aggregation guide for more info.
nodeId	The ID of a single node.
nodeIds	A comma-delimited list of node IDs. This parameter may be also provided multiple times.
sourceId	The ID of a single source to restrict the results to. A wildcard pattern can be used to restrict the results to only source IDs that match the pattern. Also, read more about how source IDs resolve with security policy restrictions.
sourceIds	A comma-delimited list of source IDs to restrict the results to. This parameter may also be provided multiple times.
tolerance	An optional time duration to restrict how far in time the query is allowed to look for matching raw datum. This duration is applied to both the start and end dates. The syntax is ISO 8601 and defaults to P1M (one month). Generally the shorter the duration, the faster the query can execute.

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.

Datum reading response

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.

Property	Type	Description
endDate	string	The date of the raw datum used for the end of the time range, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
localEndDate	string	The date of the raw datum used for the end of the time range, in yyyy-MM-dd HH:mm:ss.SSS format in the time zone returned by the timeZone property.
timeZone	string	The time zone associated with the node associated with this datum, e.g. Pacific/Auckland.

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 lookup

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.

GET	/api/v1/{pub,sec}/location
location.name	A location name.
location.country	A 2-character country code for the country the location represents.
location.region	A region name the location represents.
location.stateOrProvince	A state or province name the location represents.
location.postalCode	A postal code for the place the location represents.
location.timeZoneId	A time zone name for the weather location, e.g. Pacific/Auckland.

Location lookup request sort parameters

This method supports the following sort query parameter keys:

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

Location lookup response

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

Property	Type	Description
id	number	The unique ID of the location.
created	timestamp	The date the location was created.
country	string	The 2-character country code of the location.
region	string	The region of the location.
locality	string	The locality/city of the location.
postalCode	string	The postal code of the location.
timeZoneId	string	The time zone of the location, e.g. Pacific/Auckland.

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
  }
}

Location datum most recent

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

GET	/solarquery/api/v1/{pub,sec}/location/datum/mostRecent
locationId	The ID of a single location.
locationIds	A comma-delimited list of location IDs. This parameter may also be provided multiple times.
sourceId	The ID of a single source. A single wildcard pattern can be used to restrict source IDs to only those that match the pattern.
sourceIds	A comma-delimited list of source ID values to limit the returned results to. This parameter may also be provided multiple times. If not provided, the most recently available data for all sources will be returned.
aggregation	An optional aggregation type which will return the most recent aggregate datum for the given level, instead of the raw datum. See the SolarNet aggregation guide for more info.
startDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
localStartDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
localEndDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.

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.

Location datum most recent response

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

Property	Type	Description
created	string	The datum creation date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
locationId	number	The location ID.
sourceId	string	The source ID.
localDate	string	The date of the datum, in a YYYY-MM-dd pattern in the node's local time zone.
localTime	string	The time of the datum, in a HH:mm pattern in the node's local time zone.
tags	array	An array of associated tag string values.
sample properties	varies	The general location datum samples a, i, and s objects will have their properties returned directly on the response object.

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":
}

Location datum list

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.

GET	/solarquery/api/v1/{pub,sec}/location/datum/list
locationId	The ID of a single location. The ID of the location to return data for. You can look up available IDs via Location lookup.
locationIds	A comma-delimited list of location IDs. This parameter may also be provided multiple times.
sourceId	The ID of a single source. A single wildcard pattern can be used to restrict source IDs to only those that match the pattern.
sourceIds	A comma-delimited list of source ID values to limit the returned results to. This parameter may also be provided multiple times. If not provided, the most recently available data for all sources will be returned.
localStartDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
localEndDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date will be interpreted in the time zone of the node associated with each datum.
startDate	An inclusive starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate	An exclusive ending date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
mostRecent	If true then no date range is required, and the most recently posted datum for all matching nodes/sources will be returned. This can also be combined with the aggregation parameter to return the most recent calculated aggregate values instead of raw datum (only the Hour, Day, and Month types are supported). Date parameters may be included to restrict the results to the most recently available datum within the given date range.
aggregation	An optional aggregation type. If not provided, then non-aggregated data will be returned. See the SolarNet aggregation guide for more info. ⚠️ Note the *Minute types enforce a maximum date range of 5 weeks.
withoutTotalResultsCount	If true then the results will not contain a totalResults value. This allows the query to execute faster. When iterating over the result data pages, you then iterate until less than the requested page size is returned.

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.

Location datum list response

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

Property	Type	Description
created	string	The datum creation date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
locationId	number	The location ID.
sourceId	string	The source ID.
localDate	string	The date of the datum, in a YYYY-MM-dd pattern in the node's local time zone.
localTime	string	The time of the datum, in a HH:mm pattern in the node's local time zone.
tags	array	An array of associated tag string values.
sample properties	varies	The general location datum samples a, i, and s objects will have their properties returned directly on the response object.

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

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.

Find location datum metadata

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.

GET	/solarquery/api/v1/{pub,sec}/location/meta
query	An optional general text-based query to search for.
sourceId	The ID of a single source to restrict the results to.
sourceIds	A comma-delimited list of sources to restrict the results to.
tags	A comma-delimited list of tag values to restrict the results to, e.g. day, price, weather.
location.country	The 2-character country code for the country of the location.
location.region	The region name of the location.
location.stateOrProvince	The state or province name of the location.
location.postalCode	The postal code of the location.
location.timeZoneId	The time zone name of the location, e.g. Pacific/Auckland.

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

Find location metadata response

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:

Property	Type	Description
created	timestamp	The creation date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
updated	timestamp	The last update date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
locationId	number	The unique ID of the location associated with the metadata.
sourceId	string	The unique source ID of the metadata.
location	object	The location object associated with the metadata.

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"
        ]
      }
    ]
  }
}

List location datum metadata

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

GET	/solarquery/api/v1/{pub,sec}/location/datum/meta/{locationId}
locationId	The location ID to get metadata for.

Get location datum metadata

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

GET	/solarquery/api/v1/{pub,sec}/location/datum/meta/{locationId}/{sourceId}
locationId	The location ID to get metadata for.
sourceId	The source ID to get metadata for. The source ID may alternatively be specified as a query parameter, e.g. location/datum/meta/123?sourceId=Foo.

Location reportable interval

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

GET	/solarquery/api/v1/{pub,sec}/location/datum/interval
locationId	The node ID to get the interval for.
sourceId	An optional source ID value to limit the result to. If not provided the returned interval represents all available location data.

Location reportable interval response

Property	Type	Description
timeZone	string	The time zone the node is in.
endDate	string	The ending date of the time span, in YYYY-MM-dd HH:mm format, in the node's time zone.
endDateMillis	number	The ending date of the time span, as the number of milliseconds since the epoch, in GMT.
startDate	string	The starting date of the time span, in YYYY-MM-dd HH:mm format, in the node's time zone.
startDateMillis	number	The starting date of the time span, as the number of milliseconds since the epoch, in GMT.
yearCount	number	The number of years represented by the time span.
monthCount	number	The number of months represented by the time span.
dayCount	number	The number of days represented by the time span.

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
    }
}

Location reportable sources

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

GET	/solarquery/api/v1/{pub,sec}/location/datum/sources
locationId	The location ID to get the sources for.
locationIds	A comma-delimited list of location IDs, or multiple parameters, to get the sources for.
sourceId	An optional source ID wildcard pattern to limit the results to. This pattern restricts the resulting source IDs to only those that match the pattern.
startDate	An optional start date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, to restrict the query range to. If omitted, the first available data for the SolarNode will be used as the start date. The date must be provided in the UTC time zone.
endDate	An optional end date, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns, to restrict the query range to. If omitted, the most recently available data for the SolarNode will be used as the end date. The date must be provided in the UTC time zone.

Location reportable sources response

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

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.

List node datum metadata

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

GET	/solarquery/api/v1/{pub,sec}/datum/meta/{nodeId}
nodeId	The node ID to get metadata for.

List node datum metadata example response

{
  "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
  },
}

Get node datum metadata

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

GET	/solarquery/api/v1/{pub,sec}/datum/meta/{nodeId}/{sourceId}
nodeId	The node ID to get metadata for.
sourceId	The source ID to get metadata for. The source ID may alternatively be specified as a query parameter, e.g. datum/meta/123?sourceId=Foo.

Get node datum metadata example response

{
  "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
  },
}

Datum stream metadata list

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.

GET	/solarquery/api/v1/sec/datum/stream/meta/node
nodeId	The ID of a single node to restrict the results to.
nodeIds	A comma-delimited list of node IDs to restrict the results to.
streamId	The ID of a single stream to restrict the results to.
streamIds	A comma-delimited list of stream IDs to restrict the results to.
sourceId	The ID of a single source to restrict the results to. A wildcard pattern can be used.
sourceIds	A comma-delimited list of source IDs to restrict the results to. Wildcard patterns can be used.

Datum stream metadata list response

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"
      ]
    }
  ]
}

Datum stream metadata ID list

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.

GET	/solarquery/api/v1/sec/datum/stream/meta/node/ids
nodeId	The ID of a single node to restrict the results to.
nodeIds	A comma-delimited list of node IDs to restrict the results to.
streamId	The ID of a single stream to restrict the results to.
streamIds	A comma-delimited list of stream IDs to restrict the results to.
sourceId	The ID of a single source to restrict the results to. A wildcard pattern can be used.
sourceIds	A comma-delimited list of source IDs to restrict the results to. Wildcard patterns can be used.

Datum stream metadata list response

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 list

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.

GET	/solarquery/api/v1/{pub,sec}/nodes/meta
nodeIds	A comma-delimited list of node IDs to get metadata for. If not specified, then metadata for all nodes the current request is authorized to access will be returned.
metadataFilter	An optional metadata filter to limit the results to.

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

• created
• node
• updated

Node metadata list response

{
  "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
  }
}

Node metadata view

This endpoint returns node metadata for a specific node.

GET	/solarquery/api/v1/{pub,sec}/nodes/meta/{nodeId}
nodeId	The node ID to get metadata for.

Node metadata view response

{
  "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 view

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.

GET	/solarquery/api/v1/sec/users/meta/{userId}
userId	The user ID to get metadata for. If not provided, then the user ID of the owner of the authenticated token is assumed.

User metadata view response

{
  "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"
      }
    }
  }
}