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.
POST	/datum/meta/{nodeId}/{sourceId}	Add metadata to a node datum source.
PUT	/datum/meta/{nodeId}/{sourceId}	Store metadata for a node datum source.
DELETE	/datum/meta/{nodeId}/{sourceId}	Delete 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	/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	/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	/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.

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

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

Notes:

• Multiple node IDs (via the nodeIds parameter) cannot be combined with source IDs ( via either the sourceId or sourceIDs parameters). If any source ID is provided, only the first node ID will be used.
• Supported aggregation values are limited to:
  • Hour
  • Day
  • Month

Most recent datum response

The response will contain an array 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 watts and wattHours sample properties):

{
  "success": true,
  "data": [
    {
      "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
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 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 1 week.
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.
sourceIds	A comma-delimited list of source IDs to restrict the results to. This parameter may also be provided multiple times.
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 aggregate 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. 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

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 change 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 below 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.
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.

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.

Datum reading types

The readingType parameter controls the type of reading you'd like to perform, and accepts the following values:

Reading Type	Description
Difference	Find datum nearest to and not after the given start/end dates and compute the difference between them. Note the tolerance parameter is not used by this method, and the query can return datum far before the given start/end dates.
DifferenceWithin	Find datum nearest to and within the given start/end dates and compute the difference between them. Note the tolerance parameter is not used by this method, and the query will never return datum before the given start, or after the given end, dates.
NearestDifference	Find datum nearest to and not after the given start/end dates and compute the difference between them. Similar to the Difference type but the tolerance parameter is used to constrain the amount of distance in time from the start/end dates the query will consider.
CalculatedAt	Derive a reading from the datum nearest before and after the given start date.
CalcualtedAtDifference	Derive readings like CalculatedAt for the given start and end dates and compute the difference between them.

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.

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

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.

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

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	/solarquery/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	/solarquery/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	/solarquery/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 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/{pub,sec}/users/meta/{userId}
userId	The user ID to get metadata for.

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