SolarIn API

The SolarIn API provides methods for nodes to post data they've collected into SolarNetwork. All paths are relative to a /solarin prefix. All dates and times are represented in the Gregorian calendar system. Unless noted, all requests must provide a valid X.509 client certificate (and thus, use TLS) -- typically issued as part of the SolarNode+SolarNetwork association process when nodes are first deployed. This certificate determines what node is managed by the API calls.

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

Endpoints

Verb	Endpoint	Description
POST	/bulkCollector.do	Upload JSON encoded datum in bulk.
GET	/identity.do	Verify the identity of SolarNetwork and a SolarNode invitation.
GET	/priceLocationLookup.do	Lookup the location ID of a price location based on search criteria.
GET	/weatherLocationLookup.do	Lookup the location ID of a weather location based on search criteria.
POST	/api/v1/sec/cert/renew	Renew a node's X.509 client certificate.
GET	/api/v1/sec/datum/meta/{nodeId}/{sourceId}	Get metadata for a node datum source.
POST	/api/v1/sec/datum/meta/{nodeId}/{sourceId}	Add metadata to a node datum source.
GET	/api/v1/sec/datum/meta/{objectId}/stream/{sourceId}	Get metadata for a datum stream.
GET	/api/v1/sec/location	Search for locations.
GET	/api/v1/sec/location/{locationId}	Get a location.
POST	/api/v1/sec/location/update	Update a node's own location.
GET	/api/v1/sec/location/view	View a node's own location.
GET	/api/v1/sec/nodes/meta	Get metadata for the node.
POST	/api/v1/sec/nodes/meta	Add metadata for the node.

Bulk upload JSON datum

This endpoint accepts a simple JSON array payload of JSON objects representing individual datum. Each datum type supports specific attributes representative of that type.

Note this endpoint accepts gzip compressed body content. Just add a Content-Encoding: gzip HTTP header and then compress the JSON with the gzip compression encoding.

Request

POST	/bulkCollector.do
Content-Type	application/json
Content-Encoding	Optional; supports gzip.

An example JSON document is:

[
{"__type__":"PowerDatum", "created":1410064397000, "sourceId":"Solar", "watts":862, "wattHourReading":109298309 },
{"__type__":"ConsumptionDatum", "created":1410064398000, "sourceId":"Main", "watts": 862, "wattHourReading": 109298309 },
{"__type__":"InstructionStatus", "created":1410064399000, "instructionId":34982379, "status":"Completed" },
{"created":1410064399289,"sourceId":"Main","samples":{"i":{"watts":244},"s":{"ploc":2502287},"t":["consumption"]}},
{"created":1410064399289,"sourceId":"Office Temp","samples":{"i":{"temp":22.0},"t":["indoor"]}}
]

Note this example contains a mix of legacy typed node datum objects (the first two with "__type__":"PowerDatum" and "__type__":"ConsumptionDatum" and general node datum objects (the last two with the samples properties). Support for the legacy format is deprecated and will be removed at some point. Note that only the node-specific ConsumptionDatum, PowerDatum, and HardwareControlDatum are considered legacy. Location-specific datum such as DayDatum, PriceDatum, and WeatherDatum are still valid.

For a description of the properties supported by the legacy typed node datum objects, see the Bulk upload XML datum section later on.

Response

The JSON response is in this general form:

{
"success" : true,
"data" : {
"datum" : [ ... ],
"instructions": [ ... ]
}
}

The data.datum array will contain objects with a minimum of an id property that represents a server-assigned unique ID for the uploaded datum. There will be one object for every datum object uploaded, and the order will be the same as the order of the posted datum. Depending on the datum type, additional properties may be provided in the response.

The optional data.instructions array will contain Instruction objects for the node to execute.

For example, here is a response document after uploading one general datum object, where an instruction is also provided:

{
"success" : true,
"data" : {
"datum" : [ {
"nodeId" : 251,
"created" : "2017-08-08 22:13:50.321Z",
"sourceId" : "InverterA",
"id" : "2cb35d7ea8f9b1ee00c5591750a61e4d0f428f55"
} ],
"instructions" : [ {
"id" : 11537011,
"created" : "2017-08-08 21:59:11.084Z",
"topic" : "SetControlParameter",
"instructionDate" : "2017-08-08 21:59:11.084Z",
"state" : "Queued",
"parameters" : [ {
"name" : "/power/switch/1",
"value" : "1"
} ]
} ]
}
}

Datum types

The following datum objects are supported by SolarIn.

General node datum

The general node datum is a generic object that represents some form of data sampled by a node, specific to that node.

created	number	The datum date, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC).
sourceId	string	The node-unique ID of the datum. This represents some logical type associated with the sample, such as a name of the sensor the data was read from. This should be short and easily recognizable, such as "PV", "Mains", "Office", etcetera. The string can be at most 32 characters long.
samples	object	The sampled data values. See the table below for detailed information on the supported properties.

The samples property is a JSON object that contains the following properties, all of which are optional:

Property	JSON type	Description
a	Object	Holds accumulating sample data. All values in this object must be JSON numbers. SolarNet will aggregate these values over time by computing their differences.
i	Object	Holds instantaneous sample data. All values in this object must be JSON numbers. SolarNet will aggregate these values over time by computing their averages.
s	Object	Holds status or static sample data. The values may be any JSON type. SolarNet will not aggregate these values over time.
t	Array	Holds an array of tags. The tags must be JSON strings.

The keys within each of the a, i, and s objects can be any valid JSON identifier, however there are many standardized keys you should use when possible.

Example general node datum object

{
"created": 1410064399289,
"sourceId": "Office Temp",
"samples": {
"i": {
"temp": 22.0
},
"t": [
"indoor"
]
}
}

General location datum

The general location datum is a generic object that represents some form of data sampled by a node, specific to a SolarNet location.

created	number	The datum date, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC).
locationId	number	The SolarNet-unique ID of the location associated with this datum.
sourceId	string	The node-unique ID of the datum. This represents some logical type associated with the sample, such as a name of the sensor the data was read from. This should be short and easily recognizable, such as "PV", "Mains", "Office", etcetera. The string can be at most 32 characters long.
samples	object	The sampled data values. See the general node datum table above for detailed information on the supported properties.

Example general location datum object

{
"created" : 1502229600000,
"locationId" : 11536819,
"sourceId" : "NZ MetService",
"samples" : {
"i" : {
"temp" : 13.0,
"humidity" : 95,
"atm" : 100700
},
"s" : {
"sky" : "Windy"
}
}
}

InstructionStatus

A InstructionStatus object represents the status of an instruction previously requested by SolarNet. When a node receives an Instruction object in the response from this endpoint, it is expected to post updates on the status of handling that instruction back to SolarNet. The node does that by posting one of these datum objects.

__type__	string	Must be the constant InstructionStatus.
created	number	The datum date, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC).
instructionId	integer	The unique ID of the instruction (as originally provided by SolarNet).
status	string	The instruction status, one of Received, Executing, Completed, or Declined.

Example object

{
"__type__": "InstructionStatus",
"created": 1410064399000,
"instructionId": 34982379,
"status": "Completed"
}

Legacy datum types

The following datum objects are legacy types still supported by SolarIn, but that will be removed at some point in the future.

Day datum (legacy)

A DayDatum object represents daily conditions such as sunrise and sunset. The locationId attribute is required.

__type__	string	Must be the constant DayDatum.
created	number	The datum date, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC).
locationId	number	The SolarNet weather location ID to associate this datum with.
sunrise	number	The time of sunrise, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC). Note that only the time portion of this date is used.
sunset	number	The time of sunset, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC). Note that only the time portion of this date is used.

Example object

{"__type__":"DayDatum", "created":1410004800000, "locationId":4298974, "sunrise":-19380000, "sunset":21720000}

Node control info (legacy)

A NodeControlInfo object represents the status of a device a node is monitoring or controlling, such as a switch. The supported properties of this object are:

__type__	string	Must be the constant NodeControlInfo.
created	number	The datum date, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC).
controlId	string	The node-unique ID of the control. By convention these use path-like values, such as /power/switch/1. The string can be at most 32 characters long.
value	string	The value of the control.
type	string	One of Boolean, Float, Integer, or Percent.

Example object

{"__type__":"NodeControlInfo", "created":1410064399000, "controlId":"/power/switch/1", "value":"true", "type":"Boolean"}

Price datum (legacy)

A PriceDatum object represents a monetary cost. The locationId attribute is required and represents a specific price location registered with SolarNetwork. The supported attributes are:

price	number	The price, for the associated price location.

Example element

{"__type__":"PriceDatum", "created":1410064399000, "price":12.57}

Weather datum (legacy)

A WeatherDatum object represents weather conditions. The locationId attribute is required.

created	number	The datum date, represented as the number of milliseconds since the Unix epoch (midnight 1 Jan 1970 UTC).
temperatureCelsius	number	The air temperature, in Celsius.
humidity	number	The relative humidity, as an integer percentage (0 - 100).
barometricPressure	number	The barometric pressure, in millibars.
barometerDelta	number	The barometric pressure, in millibars.
skyConditions	string	The sky conditions, using general text. For example clear or rain.
condition	string	The sky condition for the day, using normalized weather condition values.
dewPoint	number	The dew point.
uvIndex	integer	The UV index.
visibility	number	The visibility, in kilometers.

Example object

{"__type__":"WeatherDatum", "created":1410064399000, "skyConditions":"partly cloudy", "temperatureCelsius":19.2}

Identity

This method is used in the SolarNode setup process to associate the node with SolarNetwork via an invitation from SolarNetwork. A client X.509 certificate is not required for this method, and it does not need to be called using TLS when the username and key parameters are omitted. Calling in that form will respond only with basic public details on the SolarNetwork service at the requested host. When the username and key parameters are included, TLS should be used as in this case the user's email and security phrase are included in the response.

GET	/identity.do
username	When checking an invitation, the SolarNetwork account email from the SolarNode invitation.
key	When checking an invitation, the SolarNode invitation confirmation key, as generated by SolarNetwork (the confirmationKey value from the invitation).

Identity response

The response will be XML and includes the following properties:

Property	Type	Description
host	string	The DNS name or IP address to use for SolarIn.
port	number	The network port to use for SolarIn.
forceTLS	boolean	If true then TLS is required, even if the port is not the standard port of 443.
identityKey	string	Some information about the SolarIn service that can be manually verified during the SolarNode association process.
termsOfService	string	The terms of service for SolarNetwork.
networkServiceURLs	object	A mapping of SolarNetwork service keys to associated URLs.
networkServiceURLs/entry/@key	string	A SolarNetwork service key.
networkServiceURLs/entry/value/@value	string	A SolarNetwork service URL.

Here's an example XML response when no username/key are provided:

<BasicNetworkIdentityhost="in.solarnetwork.net"port="443"forceTLS="true"identityKey="Server in.solarnetwork.net ..."termsOfService="SolarNetwork is ...">
<networkServiceURLs>
<entrykey="solaruser">
<valuetype="String"value="https://data.solarnetwork.net/solaruser" />
</entry>
<entrykey="solarquery">
<valuetype="String"value="https://data.solarnetwork.net/solarquery" />
</entry>
<entrykey="solarin-mqtt">
<valuetype="String"value="mqtts://queue.solarnetwork.net:8883" />
</entry>
</networkServiceURLs>
</BasicNetworkIdentity>

Here's an example XML response is when a valid username/key are provided:

<BasicNetworkIdentity
forceTLS="true"
host="in.solarnetwork.net"
port="11444"
identityKey="..."
termsOfService="..."
confirmationKey="11908udhjlsi3093y7039u3"
securityPhrase="It's hard to see the forest when the trees block the view."
username="foo@localhost">
</BasicNetworkIdentity>

Identity service keys

The networkServiceURLs SolarNetwork service keys can include:

Key	Description
solaruser	The SolarUser API base URL.
solarquery	The SolarQuery API base URL.
solarin-mqtt	A SolarIn MQTT URL, if supported.

Price location lookup

This method is used to look up a price location ID based on a search criteria. The price location ID can then be used to associate that location with PriceDatum posted to SolarIn. A client X.509 certificate is not required for this method, and it does not need to be called using TLS. All query parameters are joined together using a logical and operand.

Request

GET	/priceLocationLookup.do
sourceName	A weather source to filter the results by.
locationName	The location name to filter the results by.

An example XML response is:

<?xml version="1.0" encoding="UTF-8"?>
<PriceLocationcreated="2011-02-21T08:44:15Z"currency="NZD"id="2502287"locationId="2502287"
locationName="HAY2201"name="HAY2201"sourceName="electricityinfo.co.nz"
timeZoneId="Pacific/Auckland"unit="MWh">
<PriceSourcecreated="2011-02-21T08:44:15Z"id="2502285"name="electricityinfo.co.nz"/>
</PriceLocation>

Weather location lookup

This method is used to look up a weather location ID based on a search criteria. The weather location ID can then be used to associate that location with WeatherDatum posted to SolarIn. A client X.509 certificate is not required for this method, and it does not need to be called using TLS. All query parameters are joined together using a logical and operand.

Request

GET	/weatherLocationLookup.do
sourceName	A weather source to filter the results by.
locationName	The location name to filter the results by.
location.country	An optional 2-character ISO 3166 country code to filter the results by.
location.region	An optional region name to filter the results by.
location.stateOrProvince	An optional state/province name to filter the results by.
location.postalCode	An optional postal code to filter the results by.

An example XML response is:

<?xml version="1.0" encoding="UTF-8"?>
<result>
<WeatherLocationcreated="2009-09-14T00:48:03Z"id="301026"sourceData="NZXX0049">
<SolarLocationcountry="NZ"created="2009-09-14T00:48:03Z"id="301026"latitude="-41.2952"longitude="174.7895"name="Wellington"postalCode="6011"region="Wellington"timeZoneId="Pacific/Auckland"/>
<WeatherSourcecreated="2009-09-14T00:48:03Z"id="301023"name="weather.com"/>
</WeatherLocation>
</result>

Renew node certificate

This method allows a node's X.509 client certificate to be renewed. This method can be called either as a normal form post, or as a multipart/form-data request. The renewal process is asynchronous, and this method will return before completing the renewal process. Once the certificate has been renewed, SolarNetwork will issue a RenewCertificate instruction for the node, which will contain the renewed certificate for SolarNode to install.

POST	/api/v1/sec/cert/renew
password	The PKCS12 certificate keystore password.
keystore	A PKCS12 keystore with the nodes active private key and signed certificate. This must be Base64 encoded when using a normal form post, or just the raw data when using a multipart request.

Node datum metadata view

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

GET	/solarin/api/v1/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.

Node datum metadata view 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
}
}

Node datum metadata add

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

POST	/solarin/api/v1/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.

Node metadata view

This endpoint returns the node metadata.

GET	/solarin/api/v1/sec/nodes/meta

Node metadata view example response

{
"success": true,
"data": {
"created": "2017-02-27 04:41:17.510Z",
"updated": "2017-02-27 05:01:32.198Z",
"nodeId": 250,
"m": {
"num": 12
},
"pm": {
"room": {
"foo": "bar"
}
}
}
}

Datum stream metadata view

GET	/solarin/api/v1/sec/datum/meta/{objectId}/stream/{sourceId}
objectId	The node or 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. datum/meta/123/stream?sourceId=Foo.
kind	An optional query parameter for the datum stream kind, one of Node or Location. If not provided then a Node kind will be looked up first, and if not found a Location kind will be assumed.

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

Datum stream metadata view example response

{
"success": true,
"data": {
"streamId": "a66e3344-3791-4113-afff-22b44eb3c833",
"objectId": 123,
"sourceId": "meter/a",
"zone": "Pacific/Auckland",
"kind": "n",
"location": {
"country": "NZ",
"region": "Wellington",
"locality": "Wellington",
"zone": "Pacific/Auckland"
},
"i": ["current","voltage","watts"],
"a": ["wattHours"]
}
}

Node metadata add

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

POST	/solarin/api/v1/sec/nodes/meta

Location query

This endpoint allows a node to query for locations so a location ID can be associated with location datum. For example a weather data source would need to provide the location ID associated with the weather data it collects.

GET	/api/v1/sec/location
query	A general full-text search value.
locationId	A specific location ID to filter by.
sourceId	A specific source ID to filter by.
tags	A tag, or comma-delimited list of tags, to filter by. Multiple tags parameters are also allowed.

The response contains a list of matching location metadata. See Location view for more details.

Location view

This endpoint allows a node to query for a specific location or all locations for a source.

GET	/api/v1/sec/location/{locationId}
sourceId	A specific source ID to filter by.

The response contains a list of matching location metadata with the following properties:

Property	Description
locationId	The unique identifier for the location.
sourceId	A source identifier.
location	A location object.

Node location update

This endpoint allows a node to update its own location details.

POST	/api/v1/sec/location/update

The request body must be a JSON location object with the location properties to update. Note that only the following properties are supported:

Name	Type	Description
latitude	number	A decimal latitude value.
longitude	number	A decimal longitude value.
elevation	number	An elevation, in meters.

An example request body looks like this:

{"latitude":51.178882,"longitude":-1.828409,"elevation":100}

Node location view

This endpoint allows a node to view its own location details.

GET	/api/v1/sec/location/view

The response will be a JSON location object with the location properties configured for the node.

An example response looks like this:

{
"success":true,
"data":{"latitude":51.178882,"longitude":-1.828409,"elevation":100}
}