Skip to content

SolarQuery API

Jump to bottom Edit New page
Matt Magoffin edited this page May 30, 2018 · 98 revisions

The SolarQuery API provides methods to query the data collected by SolarNodes. All paths are relative to a /solarquery prefix. 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}/{sourceId} Get metadata for node datum sources.
POST /datum/meta/{nodeId}/{sourceId} Add metadata a node datum source.
PUT /datum/meta/{nodeId}/{sourceId} Store metadata a node datum source.
DELETE /datum/meta/{nodeId}/{sourceId} Delete metadata a node datum source.
GET /datum/mostRecent Get the most recently posted data by source.
GET /location Find locations by name.
GET /location/datum/list Query raw or aggregate location data by time, source, and location.
GET /nodes Get the available node IDs for the authenticated token.
GET /nodes/meta Get metadata for a set of nodes.
GET /nodes/meta/{nodeId} Get metadata for a single node.
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.

Refresh token request

GET /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 object

key string A hexadecimal-encoded signing key.

Refresh token example response

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

Reportable interval

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

Request

GET /api/v1/{pub,sec}/range/interval
nodeId The ID of the SolarNode
sourceId An optional source ID value to limit the result to. If not provided the returned interval represents all available node data.
types List of datum types to query for the range, separated by commas. If more than one type is specified, the returned interval represents the union of all individual type's intervals. This parameter is deprecated in favor of the sourceId parameter and will be removed at some point. If this parameter is provided, the sourceId parameter is ignored.

Example response

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

Response object

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.
startDate string The starting date of the time span, in YYYY-MM-dd HH:mm format, in the node's time zone.
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.
endDateMillis number The start date of the time span, in the number of milliseconds since the epoch, in GMT.
startDateMillis number The end date of the time span, in the number of milliseconds since the epoch, in GMT.

Reportable sources

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

Reportable sources request

GET /api/v1/{pub,sec}/range/sources
nodeId The ID of the SolarNode
nodeIds A list of node IDs. This parameter may be provided multiple times to filter the results to multiple node IDs.
type The datum type to query for the available source IDs. This parameter is deprecated and will be removed at some point.
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 recent 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.
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.

Reportable sources example response

If sources for a single node ID are found, the result will be an array of strings, like this:

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

If sources for multiple node IDs are found, 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/?

might only return results like this:

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

Reportable sources response object

The response is an array of strings, each value representing a single source ID. They are not returned in any particular order.

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.

Note that archived node IDs are not returned in the results.

Note this endpoint is similar to the SolarUser /nodes endpoint, but works with data security tokens.

Reportable nodes request

GET /api/v1/sec/nodes

Reportable nodes response object

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

Reportable nodes example response

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

Most recent datum

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

Most recent datum request

GET /api/v1/{pub,sec}/datum/mostRecent
nodeId The ID of the SolarNode
sourceIds An optional list of source ID values to limit the returned results to. This parameter may be provided multiple times to filter the results to multiple source IDs. Additionally, a single wildcard pattern can be provided to restrict source IDs to only those that match the pattern. If not provided, the most recently available data for all sources will be returned.
type The datum type to query for the most recent data. This parameter is deprecated in favor of the sourceIds parameter and will be removed at some point. If this parameter is provided, the sourceIds parameter is ignored.

Most recent datum example response

{
  "success": true,
  "data": [
    {
      "id": 12845075,
      "created": "2013-09-22 23:07:41.746Z",
      "nodeId": 1,
      "sourceId": "Main",
      "posted": "2013-09-22 23:07:42.151Z",
      "locationId": 2502287,
      "watts": 386,
      "wattHourReading": 4580494
    }
  ]
}

Most recent datum response object

The response will contain an array of objects, one for each available source ID. All response objects have the following properties:

id number A unique ID assigned to the data.
created string The date the data was captured, as reported by the node, in YYYY-MM-DD HH:mm:ss.SSSZ format in GMT.
nodeId number The ID of the SolarNode (will be the same as the nodeId request parameter).
sourceId string The source ID for the datum, as assigned by the node.

General node datum response object

The samples object properties a, i, and s will have their values directly returned on the response object. The t array will be returned as a tags property. For example:

{
	"created": "2014-02-02 21:06:22.122Z",
	"nodeId": 30,
	"sourceId": "Main",
	"localDate": "2014-02-03",
	"localTime": "08:06",
	"watts": 1065.228,
	"wattHours": 12775.876,
	"tags": [
	  "consumption"
	]
}

Consumption response object

This type of object is only returned if the deprecated type=Consumption parameter is provided. The following additional properties will be returned:

watts number The instantaneous watts.
wattHourReading number An accumulative watt hour reading. Not all nodes capture this value, so it might not be present in the response.

Power response object

This type of object is only returned if the deprecated type=Power parameter is provided. The following additional properties will be returned:

watts number The instantaneous watts.
wattHourReading number An accumulative watt hour reading. Not all nodes capture this value, so it might not be present in the response.

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.

Datum list request

GET /api/v1/{pub,sec}/datum/list
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. Not all types are supported for all data types. If not provided, then non-aggregated data will be returned.
nodeId The ID of a single node.
nodeIds A list of node IDs. This parameter may be provided multiple times to filter the results to multiple node IDs.
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 list of source IDs to restrict the results to. This parameter may be provided multiple times to filter the results to multiple source IDs. If omitted, data for all available sources will be returned.
dataPath An optional JavaScript-like object access path to limit the returned data to. Some aggregate levels require this, such as the HourOfDay and DayOfWeek levels. For example, pass i.watts to return just the watts data value in the result JSON.
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. See Virtual IDs for more information.

Datum list queries support the following sort query parameter keys:

  • created
  • node
  • source

Datum list response

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

created string The datum creation date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
nodeId number The SolarNode 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.
sample properties varies The general node datum samples a, i, and s objects will have their properties returned directly on the response object.
tags array An array of associated tag string values.

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

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.

Location lookup request

GET /api/v1/{pub,sec}/location
id A specific unique ID for the location.
source A name of the source associated with the location. A source is an entity providing one or more locations, e.g. a utility that offers many different price schemes or a weather service.
tags An array of tag string values, e.g. day, price, or weather.
location.name A name for the price location.
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 example response

{
  "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 lookup response object

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

id number The unique ID of the price location.
locationName string The name of the price location.
country string The 2-character country code of the location.
region string The region of the location.
locality string The locality of the location.
postalCode string The postal code of the location.
timeZoneId string The time zone of the location, e.g. Pacific/Auckland.

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.

Location datum list request common parameters

GET /api/v1/{pub,sec}/location/datum/list
locationId The ID of the location to return data for. You can look up available IDs via
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. Not all types are supported for all data types. If not provided, then non-aggregated data will be returned.

Location datum list request sort parameters

Location datum queries support the following sort query parameter keys:

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

Location datum list response object

The following additional properties will be returned:

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.
samples varies The general node datum samples a, i, and s objects will have their properties returned directly on the response object.
tags array An array of associated tag string values.

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 list example day location response

{
    "success": true,
    "data": {
        "results": [{
            "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"
        }],
        "totalResults": 133,
        "startingOffset": 0,
        "returnedResultCount": 1
    }
}

Location datum list example weather location response

{
    "success": true,
    "data": {
        "results": [{
            "created": "2016-05-29 00:30:00.000Z",
            "locationId": 11536819,
            "sourceId": "NZ MetService",
            "localDate": "2016-05-29",
            "localTime": "12:30",
            "temp": 15,
            "humidity": 64,
            "atm": 99400,
            "sky": "Partly cloudy"
        },
        ],
        "totalResults": 1,
        "startingOffset": 0,
        "returnedResultCount": 1
    }
}

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.

Find node datum metadata

This endpoint returns a list of node metadata for multiple nodes.

GET /api/v1/{pub,sec}/datum/meta/{nodeId}/{sourceId}
nodeId The node ID to get metadata for.
sourceId The source ID to get metadata for. If not specified, then all available sources for the associated node ID will be returned. The source ID may alternatively be specified as a query parameter, e.g. datum/meta/123?sourceId=Foo.

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

Add node datum metadata

This endpoint allows updating existing node datum metadata by adding new values (or replacing existing values). The request body should be a metadata document with values you want to merge into any existing values. If no metadata exists, it will be created.

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

Store node datum metadata

This endpoint allows storing complete node datum metadata documents, replacing any existing metadata for the given node and source ID. The request body should be the complete metadata document to store.

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

Delete node datum metadata

This endpoint allows deleting entire node datum metadata documents.

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

Node metadata

Node metadata may be queried using the following endpoints. All returned metadata objects will include a nodeId property for the ID of the node the metadata is associated with.

Find node metadata

This endpoint returns a list of node metadata for multiple nodes.

GET /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.

Find node metadata example 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
	}
}

Get node metadata

This endpoint returns a single node metadata.

GET /api/v1/{pub,sec}/nodes/meta/{nodeId}

Fet node metadata example 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

User metadata may be queried using the following endpoints. 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.

Get user metadata

This endpoint returns a single user metadata.

GET /api/v1/sec/users/meta/{userId}

Get user metadata example 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"
			}
		}
	}
}
Add a custom footer
Clone this wiki locally