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.

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.

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.

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.

Example object

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

Day datum

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}

InstructionStatus

A InstructionStatus object represents the status of an instruction previously requested by SolarNet.

__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 ID of the instruction.
status	string	The instruction status, one of Received, Executing, Completed, or Declined.

Example object

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

NodeControlInfo

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

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

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}

Bulk upload XML datum

Note this endpoint is deprecated and will be removed at some point. The JSON variant should be used instead.

This endpoint accepts a simple XML payload using a root <bulkDatumUpload> element. Within that element can be any number of elements, each one representing a single supported datum type. Each data type element supports specific attributes representative of that type.

Request

POST	/bulkCollector.do
Content-Type	text/xml
Content-Encoding	Optional; supports gzip.

An example XML document is:

<bulkDatumUpload>
	<PowerDatum watts="862" wattHourReading="109298309"/>
	<ConsumptionDatum created="2013-01-01 13:01:22.233Z" watts="862" wattHourReading="109298309"/>
	<InstructionStatus created="2013-01-01 13:01:22.233Z" instructionId="34982379" status="Completed"/>
</bulkDatumUpload>

Common attributes

The following table contains the attributes that are common to all datum elements:

created	timestamp	The creation date of the datum, generally representing the time and date the reading was taken.
locationId	integer	The ID of a SolarNetwork location, used to associate the datum with a place. Not all datums support this attribute.
sourceId	string	A node-unique value used to distinguish two elements of the same type. This allows a single node to collect `PowerDatum` readings from more than one device.

Consumption datum

A <ConsumptionDatum> element represents electric power consumption. The supported attributes are:

watts	integer	An instantaneous watt reading.
wattHourReading	decimal	A total cumulative watt hour reading.

Example element

<ConsumptionDatum created="2013-01-01 13:01:22.233Z" watts="862" wattHourReading="109298309"/>

Day datum

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

day	date	The date, in YYYY-MM-dd pattern, in the node's local time zone.
sunrise	time	The time of sunrise, in HH:mm pattern, in the node's local time zone.
sunset	time	The time of sunrise, in HH:mm pattern, in the node's local time zone.

Example element

<DayDatum day="2013-01-01" sunrise="06:10" sunset="20:23"/>

HardwareControl datum

A <HardwareControlDatum> element represents the value of a control on the node. The sourceId value is required. See also NodeControlInfo, which is mapped into this object.

integerValue	integer	An integer value of the control.
floatValue	decimal	A decimal value of the control.

Example element

<HardwareControlDatum created="2013-01-01 13:01:22.233Z" integerValue="1"/>

InstructionStatus

A <InstructionStatus> element is a special datum that is used to relay the status of an instruction previously requested by SolarNetwork.

instructionId	integer	The ID of the instruction.
status	string	The instruction status, one of Received, Executing, Completed, or Declined.

Example element

<InstructionStatus created="2013-01-01 13:01:22.233Z" instructionId="34982379" status="Completed"/>

NodeControlInfo

A <NodeControlInfo> element is a special datum that gets mapped into a HardwareControlDatum object by SolarIn.

controlId	string	The ID of the control. By convention these use path-like values, such as /power/switch/1. This is mapped into the sourceId attribute.
propertyName	string	If provided, this is appended to the controlId value after a semicolon when mapped to the sourceId attribute.
value	string	The value of the control. Depending on the type type attribute this will be mapped to the integerValue or floatValue attribute.
type	string	One of Boolean, Float, Integer, or Percent. Boolean values are mapped to the integerValue attribute using 1 for true or yes and 0 for all other values. Integer values are mapped directly to the integerValue attribute. Float and Percent values are mapped directly to the floatValue attribute.

Example element

<NodeControlInfo created="2013-01-01 13:01:22.233Z" controlId="/power/switch/1" value="true" type="Boolean"/>

Power datum

A <PowerDatum> element represents electric power generation. The supported attributes are:

watts	integer	An instantaneous watt reading.
batteryVolts	decimal	An instantaneous battery volt reading.
batteryAmpHours	decimal	An instantaneous battery amp-hours reading, for the available energy in the battery.
wattHourReading	decimal	A total cumulative watt hour reading.
KWattHoursToday	decimal	A daily cumulative watt hour reading. This is expected to reset to zero each day, and is an alternative to the `wattHourReading` attribute.

Example element

<PowerDatum created="2013-01-01 13:01:22.233Z" watts="862" wattHourReading="109298309"/>

Price datum

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

price	decimal	The price, for the associated price location.

Example element

<PriceDatum created="2013-01-01 13:01:22.233Z" price="12.57"/>

Weather datum

A <WeatherDatum> element represents weather conditions. The locationId attribute is required.

infoDate	timestamp	The date the weather is current of. In many cases weather readings might be from sources that do not update their data as frequently as samples are taken, so this date is used to identify when the data is valid for.
temperatureCelsius	decimal	The air temperature, in Celsius.
humidity	decimal	The relative humidity, as an integer percentage (0 - 100).
barometricPressure	decimal	The barometric pressure, in millibars.
barometerDelta	decimal	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	decimal	The dew point.
uvIndex	integer	The UV index.
visibility	decimal	The visibility, in kilometers.

Example element

<WeatherDatum infoDate="2013-01-01 13:01:22.233Z" 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>