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.

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

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.

Request

GET	/identity.do
username	When responding to an invitation, the email of the user inviting the node.
key	The invitation key, as generated on SolarNetwork.

An example XML response when no username/key are provided:

<BasicNetworkIdentity
	forceTLS="true"
	host="in.solarnetwork.net"
	port="11444"
	identityKey="..."
	termsOfService="..."/>

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

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"?>
<PriceLocation created="2011-02-21T08:44:15Z" currency="NZD" id="2502287" locationId="2502287"
		locationName="HAY2201" name="HAY2201" sourceName="electricityinfo.co.nz"
		timeZoneId="Pacific/Auckland" unit="MWh">
	<PriceSource created="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>
	<WeatherLocation created="2009-09-14T00:48:03Z" id="301026" sourceData="NZXX0049">
		<SolarLocation country="NZ" created="2009-09-14T00:48:03Z" id="301026" latitude="-41.2952" longitude="174.7895" name="Wellington" postalCode="6011" region="Wellington" timeZoneId="Pacific/Auckland"/>
		<WeatherSource created="2009-09-14T00:48:03Z" id="301023" name="weather.com"/>
	</WeatherLocation>
</result>