Skip to content

SolarUser Cloud Integrations API

Jump to bottom Edit New page
Matt Magoffin edited this page Nov 21, 2024 · 36 revisions

The SolarUser Cloud Integrations API provides methods to manage integrations with external cloud services. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens.

For general information about Cloud Integrations support in SolarNetwork see the Cloud Integrations guide.

API Endpoints

The following endpoint paths are all relative to the base path /solaruser/api/v1/sec/user/c2c.

API group Description
/services Information about the available integration services
/settings Account-wide integration preferences
/integrations Integration service configuration
/integrations/*/data-values Cloud data hierarchy exploration
/datum-stream-mappings Maps a group of cloud data values to SolarNetwork datum properties
/datum-stream-mappings/*/properties Map a single cloud data value to a SolarNetwork datum property
/datum-streams Maps cloud data values to a SolarNetwork datum stream
/datum-streams/*/settings Cloud datum stream-specific preferences
/datum-streams/*/datum Query cloud data values as SolarNetwork datum
/datum-stream-poll-tasks Scheduled jobs to poll for cloud data values into SolarNetwork datum streams

Service discovery endpoints

The Services group of endpoints provide details on the types of cloud integration services SolarNetwork supports.

Verb Endpoint Description
GET /services/integrations List integration services
GET /services/datum-streams List datum stream services
GET /services/datum-streams/data-filters List the data filters available for a given datum stream service

Settings endpoints

The Settings group of endpoints allow account-wide settings to be configured. The values configured here serve as default values for other more specific settings, such as Cloud Datum Stream Settings.

Verb Endpoint Description
GET /settings View account settings
PUT /settings Save account settings
DELETE /settings Delete account settings

Cloud Integration entity endpoints

The Cloud Integration entity represents a connection to an external cloud service.

Verb Endpoint Description
POST /integrations Create integration
GET /integrations List integrations
GET /integrations/{integrationId} View integration
PUT /integrations/{integrationId} Update integration
DELETE /integrations/{integrationId} Delete integration
POST /integrations/{integrationId}/enabled/{enabled} Update integration enabled status
GET /integrations/{integrationId}/validate Validate integration connectivity

Cloud Integration data values endpoint

The Cloud Integration data values endpoint exposes the Data Value hierarchy supported by a configured Cloud Integration entity.

Verb Endpoint Description
GET /integrations/{integrationId}/data-values List data values

Cloud Datum Stream Mapping entity endpoints

The Cloud Datum Stream Mapping entity represents a group of Cloud Datum Stream Mapping Property entities that map a set of cloud data values to a complete SolarNetwork datum stream.

Verb Endpoint Description
POST /datum-stream-mappings Create datum stream mapping
GET /datum-stream-mappings List datum stream mappings
GET /datum-stream-mappings/{datumStreamMappingId} View datum stream mapping
PUT /datum-stream-mappings/{datumStreamMappingId} Update datum stream mapping
DELETE /datum-stream-mappings/{datumStreamMappingId} Delete datum stream mapping

Cloud Datum Stream Mapping Property entity endpoints

The Cloud Datum Stream Mapping Property entity represents a mapping of a single cloud data value to a SolarNetwork datum stream property.

Verb Endpoint Description
POST /datum-stream-mappings/{datumStreamMappingId}/properties Create datum stream mapping properties
GET /datum-stream-mappings/{datumStreamMappingId}/properties List datum stream mapping properties
PUT /datum-stream-mappings/{datumStreamMappingId}/properties/{index} Save datum stream mapping property
DELETE /datum-stream-mappings/{datumStreamMappingId}/properties/{index} Delete datum stream mapping property
POST /datum-stream-mappings/{datumStreamMappingId}/properties/{index}/enabled/{enabled} Update datum stream mapping property enabled status

Cloud Datum Stream entity endpoints

The Cloud Datum Stream entity represents a mapping of cloud data values to a SolarNetwork datum stream. The serviceIdentifier property is configured with the identifier of a supported Cloud Datum Stream Service. The supported services can be listed with the Datum Stream Services list endpoint.

Verb Endpoint Description
POST /datum-streams Create datum stream
GET /datum-streams List datum streams
GET /datum-streams/{datumStreamId} View datum stream
PUT /datum-streams/{datumStreamId} Update datum stream
DELETE /datum-streams/{datumStreamId} Delete datum stream
POST /datum-streams/{datumStreamId}/enabled/{enabled} Update datum stream enabled status

Cloud Datum Stream Settings endpoints

The Cloud Datum Stream Settings group of endpoints allow datum stream-specific settings to be configured. The values configured here override the same properties configured on the account-wide Settings entity.

Verb Endpoint Description
GET /datum-streams/default-settings View datum stream default settings
GET /datum-streams/settings List datum stream settings
GET /datum-streams/{datumStreamId}/settings View datum stream settings
PUT /datum-streams/{datumStreamId}/settings Save datum stream settings
DELETE /datum-streams/{datumStreamId}/settings Delete datum stream settings

Cloud Datum Stream datum endpoints

These endpoints provide ways to query for cloud data, converted to SolarNetwork datum with a specific Cloud Datum Stream configuration.

Verb Endpoint Description
GET /datum-streams/{datumStreamId}/datum List datum matching a search criteria
GET /datum-streams/{datumStreamId}/latest-datum View the "most recent" datum available

Cloud Datum Stream Poll Task entity endpoints

The Cloud Datum Stream Poll Task entity represents the runtime state of a datum stream poll task, specific to a Cloud Datum Stream.

Verb Endpoint Description
GET /datum-stream-poll-tasks List datum streams
PUT /datum-stream-poll-tasks/{datumStreamId} Save datum stream poll task
DELETE /datum-stream-poll-tasks/{datumStreamId} Delete datum stream poll task
POST /datum-stream-poll-tasks/{datumStreamId}/state Update datum stream poll task state (start/stop)

Services

The following endpoints provide details on the types of cloud integration services SolarNetwork supports.

Integration Services list

This method will list the Cloud Integration services supported by SolarNetwork, and the configurable service properties that are supported for those services.

GET /solaruser/api/v1/sec/user/c2c/services/integrations

Integration Services list response

The response will be a list of localized service description objects:

Property Type Description
id String The integration service identifier.
locale String The locale of the response information.
settingSpecifiers SettingSpecifier[] List of setting specifier objects that define the available service properties for the integration service.
localizedName String A localized name for the integration service.
localizedInfoMessages Map Localized messages for all setting specifiers.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "s10k.c2c.i9n.locus",
      "locale": "en-US",
      "settingSpecifiers": [
        {
          "key": "oauthClientId",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "oauthClientSecret",
          "markup": false,
          "secureTextEntry": true,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "username",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "password",
          "markup": false,
          "secureTextEntry": true,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "partnerId",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "baseUrl",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        }
      ],
      "localizedName": "Locus Energy",
      "localizedInfoMessages": {
        "title": "Locus Energy",
        "oauthClientId.key": "OAuth Client ID",
        "oauthClientId.desc": "The OAuth client identifier.",
        "oauthClientSecret.key": "OAuth Client Secret",
        "oauthClientSecret.desc": "The OAuth client secret.",
        "username.key": "Username",
        "username.desc": "The user login name.",
        "password.key": "Password",
        "password.desc": "The user login password.",
        "partnerId.key": "Partner ID",
        "partnerId.desc": "The partner identifier.",
        "baseUrl.key": "Base URL",
        "baseUrl.desc": "An alternate URL to use to access the cloud service."
      }
    }
  ]
}

Cloud Integration services

SolarNetwork supports the following integration services:

Service Description
eGauge Integrate with the eGauge API.
Locus Energy (AlsoEnergy) Integrate with the Locus Energy API.
SolarEdge Integrate with the SolarEdge API.
SolrenView Integrate with the SolrenView API.

Each service can support one or more Cloud Datum Stream Service.

Datum Stream Services list

This method will list the Cloud Datum Stream services supported by a given Cloud Integration Service, and the configurable service properties that are supported for those services.

GET /solaruser/api/v1/sec/user/c2c/services/datum-streams
identifier The id of the Cloud Integration Service to list the datum stream services for

Datum Stream Services list response

The response will be a list of localized service description objects:

Property Type Description
id String The datum stream service identifier.
locale String The locale of the response information.
settingSpecifiers SettingSpecifier[] List of setting specifier objects that define the available service properties for the integration service.
localizedName String A localized name for the integration service.
localizedInfoMessages Map Localized messages for all setting specifiers.
requiresPolling Boolean true if the service requires polling for data
dataValuesRequireDatumStream Boolean true if the service requires a Cloud Datum Stream ID for the /data-values method to function.
arbitraryDateRangesSupported Boolean true if the /datum endpoint supports arbitrary date range filter parameters
supportedPlaceholders String[] List of supported placeholder keys for use in Cloud Datum Stream Mapping Property valueReference values
supportedDataValueWildcardIdentifierLevels Number[] List of 0-based Data Value identifiers offsets that support the * wildcard in Cloud Datum Stream Mapping Property valueReference values
dataValueIdentifierLevelsSourceIdRange Object For services that support wildcard identifiers, a 0-based Data Value identifiers offset range that can be used to uniquely identify a SolarNetwork source ID.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "s10k.c2c.ds.locus",
      "locale": "en-US",
      "requiresPolling": true,
      "dataValuesRequireDatumStream": false,
      "arbitraryDateRangesSupported": true,
      "supportedPlaceholders": [
        "siteId"
      ],
      "supportedDataValueWildcardIdentifierLevels": [
        2
      ],
      "dataValueIdentifierLevelsSourceIdRange": {
        "min": 0,
        "max": 2,
        "singleton": false
      },
      "settingSpecifiers": [
        {
          "key": "granularity",
          "defaultValue": "latest",
          "valueTitles": {
            "latest": "latest",
            "1min": "1min",
            "5min": "5min",
            "15min": "15min",
            "hourly": "hourly",
            "daily": "daily",
            "monthly": "monthly",
            "yearly": "yearly"
          },
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.MultiValueSettingSpecifier"
        }
      ],
      "localizedName": "Locus Energy Datum Stream",
      "localizedInfoMessages": {
        "title": "Locus Energy Datum Stream",
        "granularity.key": "Granularity",
        "granularity.desc": "The resolution of the data to request.",
        "granularity.latest.key": "Latest",
        "granularity.1min.key": "1 minute",
        "granularity.5min.key": "5 minute",
        "granularity.15min.key": "15 minute",
        "granularity.hourly.key": "Hourly",
        "granularity.daily.key": "Daily",
        "granularity.monthly.key": "Monthly",
        "granularity.yearly.key": "Yearly"
      }
    }
  ]
}

Datum Stream Services wildcard identifier support

Some cloud services return data for multiple devices at once, and a Cloud Datum Stream Service can support mapping the data into multiple SolarNetwork source IDs. The service can then support a service property to map unique cloud device identifiers to SolarNetwork source IDs. The supportedDataValueWildcardIdentifierLevels and dataValueIdentifierLevelsSourceIdRange values define which Data Value identifiers can be specified as a * wildcard and the identifiers range that is required when mapping a data value to a source ID.

The the previous service example, those properties had these values:

{
  "supportedDataValueWildcardIdentifierLevels": [
    2
  ],
  "dataValueIdentifierLevelsSourceIdRange": {
    "min": 0,
    "max": 2
  }
}

Imagine a Data Value was given like this:

{
  "name": "AC Power",
  "reference": "/1122334/inv/5555566/W",
  "identifiers": [
    "1122334",
	"inv",
    "5555566",
    "W"
  ]
}

That means that when configuring the valueReference on a Cloud Datum Stream Mapping Property entity you can specify a wildcard for the 3rd identifier component (index 2), like this:

/1122334/inv/*/W

When configuring a source ID mapping service property on a Cloud Datum Stream entity you must include the 1st, 2nd, and 3rd components. For example this would map this data to a INV/1 source ID:

/1122334/inv/5555566 = INV/1

Datum Stream Data Filters list

This method will list the data filters supported by a given Cloud Datum Stream service. The data filters are used to discover the possible data mappings a given cloud integration supports, and work like a hierarchical query filter to "drill down" into the data exposed by the cloud service.

GET /solaruser/api/v1/sec/user/c2c/services/datum-streams/data-filters
identifier The id of the Cloud Datum Stream to list the data filters for.
any Any additional id key (as returned by this API) and associated filter value to narrow the results to.

Datum Stream Data Filters response

The response will be a list of localized service information objects:

Property Type Description
id String The data filter identifier. This defines a possible additional query parameter that can be provided to this API to "drill down" into the data hierarchy of the cloud service.
locale String The locale of the response information.
localizedName String A localized name for the data filter.
localizedDescription String Localized description of the data filter.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "siteId",
      "locale": "en-US",
      "localizedName": "Site ID",
      "localizedDescription": "The site identifier to restrict the results to."
    },
    {
      "id": "componentId",
      "locale": "en-US",
      "localizedName": "Component ID",
      "localizedDescription": "The component identifier to restrict the results to."
    }
  ]
}

Settings

The Settings group of endpoints allow account-wide settings to be configured. The values configured here serve as default values for other more specific settings, such as Cloud Datum Stream Settings.

Settings view

This method returns the Settings entity for the active user.

GET /solaruser/api/v1/sec/user/c2c/settings

Settings view response

The response will be a Settings object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity
created String The creation date.
modified String The modification date.
publishToSolarIn Boolean true to publish datum to SolarIn for services that collect datum, unless overridden in a more specific setting
publishToSolarFlux Boolean true to publish datum to SolarFlux for services that collect datum, unless overridden in a more specific setting

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "created": "2024-10-28 03:18:08.083032Z",
    "modified": "2024-10-28 03:18:08.083032Z",
    "publishToSolarIn": true,
    "publishToSolarFlux": true
  }
}

Settings defaults

If no Settings entity exists for an account, the following default property values are assumed by SolarNetwork:

Property Default value
publishToSolarIn true
publishToSolarFlux false

Settings save

This method creates or updates the Settings entity for the active user. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/settings

The request body accepts a Settings JSON object with the following properties:

Property Type Description
publishToSolarIn Boolean true to publish datum to SolarIn for services that collect datum, unless overridden in a more specific setting
publishToSolarFlux Boolean true to publish datum to SolarFlux for services that collect datum, unless overridden in a more specific setting

For example:

{
  "publishToSolarIn": true,
  "publishToSolarFlux": true
}

Settings delete

This method deletes the Settings entity for the active user.

DELETE /solaruser/api/v1/sec/user/c2c/settings

The response will be a simple success or failure message.

Cloud Integration data values

This API provides a way to discover the "data values" that are supported by a cloud integration, that can be mapped onto a SolarNetwork datum stream. The Datum Stream Data Filters list API will provide you with the list of possible data filters you can use to "drill down" into the data hierarchy supported by the cloud integration.

GET /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}/data-values
integrationId The configId of the Cloud Integration to list the data values for
datumStreamServiceIdentifier The serviceIdentifier of the Cloud Datum Stream Service to use. Can omit to use the first-available service supported by the Cloud Integration Service configured on the given Cloud Integration
any Any additional id key as returned by the Datum Stream Data Filters list API and associated filter value to narrow the results to

👉 Some datum stream services require a Cloud Datum Stream ID to function. For those that do, it can be provided on a datumStreamId parameter. If a service requires this, the /services/datum-streams result will have a dataValuesRequireDatumStream set to true.

Cloud Integration data values response

The response will be a list of Data Value objects, which conceptually exist as a tree structure that reflects the hierarchy of data presented by the cloud service. The leaf nodes within the tree represent data points that can be mapped onto SolarNetwork datum stream properties by including their reference property value on Coud Datum Stream Mapping Property entities.

Each Data Value object has the following properties:

Property Type Description
name String A display name for the value.
reference String A unique identifier that, for leaf nodes, can be included on Coud Datum Stream Mapping Property entities.
identifiers String[] A list of data value hiearchy identifiers used to uniquely identify the value.
metadata Map<String, any> Cloud service-specific metadata to help identify the value. Some standard keys are defined.

An example response looks like this:

{
  "success": true,
  "data": [
    {
      "name": "Acme Solar Plant",
      "identifiers": [
        "1122334"
      ],
      "metadata": {
        "street": "123 Main Street",
        "l": "Anytown",
        "st": "California",
        "postalCode": "90731",
        "c": "US",
        "tz": "America/Los_Angeles"
      }
    }
  ]
}

Datum Stream data value metadata

The metadata property on Data Value objects holds extra details provided by the cloud service that can be helpful for locating the values you want to map onto SolarNetwork datum streams. The example response shown in the previous section hints at the type of information that might be included.

Although the exact metadata provided depends on the cloud service, SolarNetwork defines the following standard keys that cloud integrations will provide if possible:

Key Description
c A postal location country name or code, for example US.
l A postal location locality (city) name or code, for example Anytown.
manufacturer A device manufacturer name.
model A device model name.
postalCode A postal code, for example 90731.
serial A device serial number.
st A postal location state or province name, for example California.
street A postal location street address, for example 123 Main Street.
tz A time zone identifier, for example America/Los_Angeles.
unit A unit of measure name.

Note that the keys listed here may or may not be provided, and other cloud service-specific values may be provided. See the docuemntation on a given Cloud Integration Service for more details.

Cloud Integration data values API usage

To use this API, first make a request with just the integrationId path variable and no query parameters, to discover what top-level data values are available. You can use the identifiers provided in that response to then make additional requests that provide specific identifiers as additional query parameters, until you reach the "bottom" of the hierarchy where specific cloud data values are available for mapping into a SolarNetwork datum stream.

For example, imagine GET /services/datum-streams/data-filters returned the example shown above, which means the following filters are available:

  • siteId - a site identifier
  • componentId - a component identifier

The initial request would be without any query parameters:

/integrations/1/data-values

This will return the available "sites" with their site identifiers. For example:

{
  "success": true,
  "data": [
    {
      "name": "Acme Solar Plant",
      "identifiers": [
        "1122334"
      ],
      "metadata": {
        "street": "123 Main Street",
        "l": "Anytown",
        "st": "California",
        "postalCode": "90731",
        "c": "US",
        "tz": "America/Los_Angeles"
      }
    }
  ]
}

Here there was one site named Acme Solar Plant with the identifier 1122334. Given that initial response, you can "drill down" into Acme Solar Plant by calling the API again, but with a siteId=1122334 query parameter, this is:

/integrations/1/data-values?siteId=1122334

This will return the next layer in the data hierarchy: a list of "components" for the given site. Imagine that returned the following:

{
  "success": true,
  "data": [
    {
      "name": "Elkor RGM",
      "identifiers": [
        "1122334",
        "5555566"
      ],
      "metadata": {
        "manufacturer": "Elkor",
        "model": "WattsOn - Mark II",
        "nodeId": "OB.001EC111111.11",
        "nodeType": "METER",
        "application": "GENERATION",
        "generationType": "SOLAR"
      }
    },
    {
      "name": "Inverter 01",
      "identifiers": [
        "1122334",
        "6677777"
      ],
      "metadata": {
        "manufacturer": "Ginlong",
        "model": "Solis-60K-US",
        "nodeId": "OB.001EC1111111.22",
        "nodeType": "INVERTER",
        "application": "GENERATION",
        "generationType": "SOLAR"
      }
    }
  ]
}

The response includes two components, an Elkor WattsOn meter and a Ginlong Solis solar inverter. You can drill down into the Elkor meter by adding a componentId=5555566 to the API, like this:

/integrations/1/data-values?siteId=1122334&componentId=5555566

This will return the next layer in the data hierarchy: a list of values for the given site and component. For example:

{
  "success": true,
  "data": [
    {
      "name": "AC Power",
      "reference": "/1122334/5555566/W",
      "identifiers": [
        "1122334",
        "5555566",
        "W"
      ],
      "metadata": {
        "source": "Measured",
        "unit": "W"
      },
      "children": [
        {
          "name": "AC Power avg",
          "reference": "/1122334/5555566/W/W_avg",
          "identifiers": [
            "1122334",
            "5555566",
            "W",
            "W_avg"
          ],
          "metadata": {
            "aggregation": "avg"
          }
        },
        {
          "name": "AC Power max",
          "reference": "/1122334/5555566/W/W_max",
          "identifiers": [
            "1122334",
            "5555566",
            "W",
            "W_max"
          ],
          "metadata": {
            "aggregation": "max"
          }
        }
      ]
    }
  ]
}

Notice that this response includes two more levels in the hierarchy, as the first AC Power object has a children property with AC Power avg, AC Power max, and AC Power min objects included. These children objects are leaf nodes so their reference value can be used as a valueReference on a Coud Datum Stream Mapping Property.

Note that even though the AC Power Data Value has a reference property it can not be used as a valueReference property of a Coud Datum Stream Mapping Property, because AC Power has a children property and is thus not a leaf node in the data values hierarchy.

Cloud Integration

The Cloud Integration entity represents a connection to an external cloud service. Use these endpoints to manage integration entities.

Cloud Integration create

This method creates a new Cloud Integration entity. An application/json request body must be provided with the integration details to create.

POST /solaruser/api/v1/sec/user/c2c/integrations

The request body accepts a Cloud Integration JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.
name String A display name.
serviceIdentifier String The Service ID of the Cloud Integration Service to use.
serviceProperties Object Cloud Integration Service-specific settings to use.

For example:

{
  "enabled": true,
  "name": "Locus Energy Meter Example",
  "serviceIdentifier": "s10k.c2c.i9n.locus",
  "serviceProperties": {
    "username": "foo",
    "password": "bar",
    "oauthClientId": "abc",
    "oauthClientSecret": "02ffffffff3333333777777777777777",
    "partnerId": 12345
  }
}

The response will be a Cloud Integration entity object that provides the ID assigned. See Cloud Integration view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/c2c/integrations/1

⚠️ Note that sensitive service property values like password will be encrypted by SolarNetwork using an internal key, and will not be returned in a decipherable way in any API response. See View response for an example.

Cloud Integration list

This method returns a list of Cloud Integration entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/integrations

The URL accepts the following search filter query parameters:

Property Type Description
integrationId Number The ID of an integration to match.
integrationIds Number[] A comma-delimited list of integration IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Cloud Integration entity objects. See the Cloud Integration view response for details.

Cloud Integration view

This method returns a Cloud Integration entity.

GET /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}
integrationId The ID of the Cloud Integration to view.

Cloud Integration view response

The response will be a Cloud Integration entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity
configId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator.
name String The display name.
serviceIdentifier String The Service ID of the Cloud Integration Service to use.
serviceProperties Object Cloud Integration Service-specific settings to use.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "configId": 4,
    "created": "2024-10-12 03:50:55.90895Z",
    "modified": "2024-10-12 03:51:20.525542Z",
    "enabled": true,
    "name": "Locus Energy Meter Example",
    "serviceIdentifier": "s10k.c2c.i9n.locus",
    "serviceProperties": {
      "password": "{AES}ABCD_XmAofK0b-scoU",
      "username": "foo",
      "partnerId": "12345",
      "oauthClientId": "02ffffffff3333333777777777777777",
      "oauthClientSecret": "{AES}abcd_ceNmf1sVp08U3XCN3w"
    }
  }
}

☝️ Note that sensitive service property values like password will have been encrypted by SolarNetwork using an internal key, and not decipherable. The encrypted form is provided only to indicate that a value for that property has been configured.

Cloud Integration update

This method updates an existing Cloud Integration entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}
integrationId The ID of the Cloud Integration to update.

The request body accepts a Cloud Integration JSON object as specified in the Cloud Integration create method. The response will be the updated entity as specified in the Cloud Integration view method.

Cloud Integration delete

This method deletes a Cloud Integration entity. ⚠️ All entities associated with the entity will be deleted as well.

DELETE /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}
integrationId The ID of the Cloud Integration to delete.

The response will be a simple success or failure message.

Cloud Integration update enabled

This method updates the enabled status of a Cloud Integration entity.

POST /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}/enabled/{enabled}
integrationId The ID of the Cloud Integration to update.
enabled The desired enabled state to set.

The response will be a simple success or failure message.

Cloud Integration validate

This method validates the connectivity between SolarNetwork and the cloud service, for example using the configured credentials.

GET /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}/validate
integrationId The ID of the Cloud Integration to validate.

The response will be a simple success or failure message.

Cloud Datum Stream Mapping

The Cloud Datum Stream Mapping entity represents a group of Cloud Datum Stream Mapping Property entities that map a set of cloud data values to a complete SolarNetwork datum stream.

Cloud Datum Stream Mapping create

This method creates a new Cloud Datum Stream Mapping entity. An application/json request body must be provided with the details to create.

POST /solaruser/api/v1/sec/user/c2c/datum-stream-mappings

The request body accepts a Cloud Datum Stream Mapping JSON object with the following properties:

Property Type Description
name String A display name.
integrationId Number The ID of the Cloud Integration entity to use.

For example:

{
  "name": "Locus Energy Meter",
  "integrationId": 1
}

The response will be a Cloud Datum Stream Mapping entity object that provides the ID assigned. See Cloud Datum Stream Mapping view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/1

Cloud Datum Stream Mapping list

This method returns a list of Cloud Datum Stream Mapping entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/datum-stream-mappings

The URL accepts the following search filter query parameters:

Property Type Description
datumStreamMappingId Number The ID of a datum stream mapping to match.
datumStreamMappingIds Number[] A comma-delimited list of datum stream mapping IDs to match (logical OR).
integrationId Number The ID of an integration to match.
integrationIds Number[] A comma-delimited list of integration IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Cloud Datum Stream Mapping entity objects. See the Cloud Datum Stream Mapping view response for details.

Cloud Datum Stream Mapping view

This method returns a Cloud Datum Stream Mapping entity.

GET /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping to view.

Cloud Datum Stream Mapping view response

The response will be a Cloud Datum Stream Mapping entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity
configId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
name String The display name.
integrationId Number The ID of the associated Cloud Integration entity.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "configId": 1,
    "created": "2024-10-15 22:35:52.39096Z",
    "modified": "2024-10-15 22:40:58.17154Z",
    "name": "Locus Energy Meter",
    "integrationId": 1
  }
}

Cloud Datum Stream Mapping update

This method updates an existing Cloud Datum Stream Mapping entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping to update.

The request body accepts a Cloud Datum Stream Mapping JSON object as specified in the Cloud Datum Stream Mapping create method. The response will be the updated entity as specified in the Cloud Datum Stream Mapping view method.

Cloud Datum Stream Mapping delete

This method deletes a Cloud Datum Stream Mapping entity. ⚠️ All associated Cloud Datum Stream Mapping Property entities will be deleted as well.

DELETE /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping to delete.

The response will be a simple success or failure message.

Cloud Datum Stream Mapping Property

The Cloud Datum Stream Mapping Property entity represents a mapping of a single cloud data value to a SolarNetwork datum stream property.

Cloud Datum Stream Mapping Property create

This method creates a set of Cloud Datum Stream Mapping Property entities. An application/json request body must be provided with the details to create.

POST /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties

The request body accepts a JSON array of Cloud Datum Stream Mapping Property JSON objects, each with the following properties:

Property Type Description
enabled Boolean Enabled status indicator.
multiplier Number An optional number to multiply the cloud service data values by when saving to the SolarNetwork datum stream.
propertyType String The SolarNetwork datum property classification, one of i, a, or s for instantaneous, accumulating, or status.
propertyName String The SolarNetwork datum property name.
scale Number An optional number of decimal places to round the cloud service data value to. Can omit or specify as -1 for no rounding.
valueType String The value reference, one of r or s for reference or Spel Expression. Defaults to r. See the Cloud Integrations Expressions for more information on the expression syntax.
valueReference String The value reference, as discovered using the Data Values method. Datum Stream Service-specific placeholder values are supported, configured on the placeholder property of the Cloud Datum Stream associated with the mapping associated with this property. Some services also support a special * wildcard character. See the documentation for the Cloud Datum Stream Service for more information.

Here is an example that uses siteId and componentId placeholders, as well as an expression to derive a voltage property out of phase-specific voltage_* properties:

[
  {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "watts",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/W/W_avg"
  },
  {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage_a",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/PhVphA/PhVphA_avg"
  },
  {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage_b",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/PhVphB/PhVphB_avg"
  },
  {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage_c",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/PhVphC/PhVphC_avg"
  },
  {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage",
    "valueType": "s",
    "valueReference": "round(rms({voltage_a, voltage_b, voltage_c}), 1)"
  },
  {
    "enabled": true,
    "propertyType": "a",
    "propertyName": "wattHours",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/TotWhExp/TotWhExp_max"
  }
]

The response will be a list of Cloud Datum Stream Mapping Property entity objects. See Cloud Datum Stream Mapping Property list response for more information.

Cloud Datum Stream Mapping Property list

This method returns a list of Cloud Datum Stream Mapping Property entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties

The URL accepts the following search filter query parameters:

Property Type Description
index Number The index of a datum stream mapping property to match.
indexes Number[] A comma-delimited list of datum stream mapping property index values to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

Cloud Datum Stream Mapping Property list response

The response will be a paged results list of Cloud Datum Stream Mapping Property entity objects, as specified in the save method.

An example response looks like:

{
  "success": true,
  "data": {
    "totalResults": 17,
    "startingOffset": 0,
    "returnedResultCount": 17,
    "results": [
      {
        "userId": 123,
        "datumStreamMappingId": 1,
        "index": 0,
        "created": "2024-10-14 03:27:54.859495Z",
        "modified": "2024-10-14 03:27:54.859495Z",
        "enabled": true,
        "propertyType": "i",
        "propertyName": "watts",
        "valueType": "r",
        "valueReference": "/{siteId}/{componentId}/W/W_avg"
      },
      {
        "userId": 123,
        "datumStreamMappingId": 1,
        "index": 1,
        "created": "2024-10-14 03:27:54.859495Z",
        "modified": "2024-10-14 03:27:54.859495Z",
        "enabled": true,
        "propertyType": "a",
        "propertyName": "wattHours",
        "valueType": "r",
        "valueReference": "/{siteId}/{componentId}/TotWhExp/TotWhExp_max"
      }
    ]
  }
}

Cloud Datum Stream Mapping Property save

This method creates or updates a single Cloud Datum Stream Mapping Property entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties/{index}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping Property to save.
index The index of the Cloud Datum Stream Mapping Property to save.

The request body accepts a Cloud Datum Stream Mapping Property JSON object with the following properties:

Property Type Description
enabled Boolean Enabled status indicator.
multiplier Number An optional number to multiply the cloud service data values by when saving to the SolarNetwork datum stream.
propertyType String The SolarNetwork datum property classification, one of i, a, or s for instantaneous, accumulating, or status.
propertyName String The SolarNetwork datum property name.
scale Number An optional number of decimal places to round the cloud service data value to. Can omit or specify as -1 for no rounding.
valueType String The value reference, one of r or s for reference or Spel Expression. Defaults to r.
valueReference String The value reference, as discovered using the Data Values method. Datum Stream Service-specific placeholder values are supported, configured on the placeholder property of the Cloud Datum Stream associated with the mapping associated with this property. Some services also support a special * wildcard character. See the documentation for the Cloud Datum Stream Service for more information.

For example:

{
  "enabled": true,
  "propertyType": "i",
  "propertyName": "watts",
  "valueReference": "/{siteId}/{componentId}/mW/mW_avg",
  "multiplier": 0.001,
  "scale": 3
}

The response will be the saved Cloud Datum Stream Mapping Property entity.

Cloud Datum Stream Mapping Property delete

This method deletes a Cloud Datum Stream Mapping Property entity.

DELETE /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties/{index}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping Property to delete.
index The index of the Cloud Datum Stream Mapping Property to delete.

The response will be a simple success or failure message.

Cloud Datum Stream Mapping Property update enabled

This method updates the enabled status of a Cloud Datum Stream Mapping Property entity.

POST /solaruser/api/v1/sec/user/c2c/integrations/{datumStreamMappingId}/properties/{index}/enabled/{enabled}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping Property to update.
index The index of the Cloud Datum Stream Mapping Property to delete.
enabled The desired enabled state to set.

The response will be a simple success or failure message.

Cloud Datum Stream

The Cloud Datum Stream entity represents a mapping of cloud data values to a SolarNetwork datum stream. The serviceIdentifier property is configured with the identifier of a supported Cloud Datum Stream Service. The supported services can be listed with the Datum Stream Services list endpoint.

Cloud Datum Stream create

This method creates a new Cloud Datum Stream entity. An application/json request body must be provided with the details to create.

POST /solaruser/api/v1/sec/user/c2c/datum-streams

The request body accepts a Cloud Datum Stream JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.
name String A display name.
serviceIdentifier String The Service ID of the Cloud Datum Stream Service to use.
datumStreamMappingId Number The ID of the Cloud Datum Stream Mapping to use
schedule String An optional schedule to poll for data (for services that require polling), as either a cron schedule or a number of seconds. For example 0 0/15 * * * * or 900
kind String The SolarNetwork datum stream kind, one of n or l for node or location
objectId Number The SolarNetwork datum stream node or location ID
sourceId String The SolarNetwork datum stream source ID
serviceProperties Object Cloud Datum Stream Service-specific settings to use.

For example:

{
  "enabled": true,
  "name": "Locus Energy Meter Example",
  "serviceIdentifier": "s10k.c2c.ds.locus",
  "datumStreamMappingId": 1,
  "schedule": "300",
  "kind": "n",
  "objectId": "123",
  "sourceId": "INV/1",
  "serviceProperties": {
    "granularity": "5min"
  }
}

The response will be a Cloud Datum Stream entity object that provides the ID assigned. See Cloud Datum Stream view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/c2c/datum-streams/1

Cloud Datum Stream list

This method returns a list of Cloud Datum Stream entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/datum-streams

The URL accepts the following search filter query parameters:

Property Type Description
datumStreamId Number The ID of a datum stream to match.
datumStreamIds Number[] A comma-delimited list of datum stream IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Cloud Datum Stream entity objects. See the Cloud Datum Stream view response for details.

Cloud Datum Stream view

This method returns a Cloud Datum Stream entity.

GET /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}
datumStreamId The ID of the Cloud Datum Stream to view.

Cloud Datum Stream view response

The response will be a Cloud Datum Stream entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity
configId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator.
name String The display name.
serviceIdentifier String The Service ID of the Cloud Datum Stream Service to use.
datumStreamMappingId Number The ID of the Cloud Datum Stream Mapping to use
schedule String An optional schedule to poll for data (for services that require polling), as either a cron schedule or a number of seconds. For example 0 0/15 * * * * or 900
kind String The SolarNetwork datum stream kind, one of n or l for node or location
objectId Number The SolarNetwork datum stream node or location ID
sourceId String The SolarNetwork datum stream source ID
serviceProperties Object Cloud Datum Stream Service-specific settings to use.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "configId": 1,
    "created": "2024-10-12 03:50:55.90895Z",
    "modified": "2024-10-12 03:51:20.525542Z",
    "enabled": true,
    "name": "Locus Energy Meter Example",
    "serviceIdentifier": "s10k.c2c.ds.locus",
    "datumStreamMappingId": 1,
    "schedule": "300",
    "kind": "n",
    "objectId": "123",
    "sourceId": "INV/1",
    "serviceProperties": {
      "granularity": "5min"
    }
  }
}

Cloud Datum Stream update

This method updates an existing Cloud Datum Stream entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}
datumStreamId The ID of the Cloud Datum Stream to update.

The request body accepts a Cloud Datum Stream JSON object as specified in the Cloud Datum Stream create method. The response will be the updated entity as specified in the Cloud Datum Stream view method.

Cloud Datum Stream delete

This method deletes a Cloud Datum Stream entity. ⚠️ All associated Datum Stream Poll Task entities will be deleted as well.

DELETE /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}
datumStreamId The ID of the Cloud Datum Stream to delete.

The response will be a simple success or failure message.

Cloud Datum Stream update enabled

This method updates the enabled status of a Cloud Datum Stream entity.

POST /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}/enabled/{enabled}
datumStreamId The ID of the Cloud Datum Stream to update.
enabled The desired enabled state to set.

The response will be a simple success or failure message.

Cloud Datum Stream Settings

The Cloud Datum Stream Settings group of endpoints allow datum stream-specific settings to be configured. The values configured here override the same properties configured on the account-wide Settings entity.

Cloud Datum Stream Settings defaults view

This method returns the default Cloud Datum Stream Settings used if none is configured, and no account-wide Settings exist.

GET /solaruser/api/v1/sec/user/c2c/datum-streams/default-settings

Cloud Datum Stream Settings defaults view response

This method returns a Cloud Datum Stream Settings object with the following properties:

Property Type Description
publishToSolarIn Boolean true to publish datum to SolarIn for services that collect datum, unless overridden in a more specific setting
publishToSolarFlux Boolean true to publish datum to SolarFlux for services that collect datum, unless overridden in a more specific setting

An example response looks like:

{
  "success": true,
  "data": {
    "publishToSolarIn": true,
    "publishToSolarFlux": false
  }
}

Cloud Datum Stream Settings view

This method returns the Cloud Datum Stream Settings entity for a given datum stream.

GET /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}/settings
datumStreamId The ID of the Cloud Datum Stream to view the settings for

Cloud Datum Stream Settings view response

The response will be a Cloud Datum Stream Settings object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity
datumStreamId Number The datum stream ID associated with this entity
created String The creation date.
modified String The modification date.
publishToSolarIn Boolean true to publish datum to SolarIn for services that collect datum, unless overridden in a more specific setting
publishToSolarFlux Boolean true to publish datum to SolarFlux for services that collect datum, unless overridden in a more specific setting

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "datumStreamId": 1,
    "created": "2024-10-28 03:18:08.083032Z",
    "modified": "2024-10-28 03:18:08.083032Z",
    "publishToSolarIn": true,
    "publishToSolarFlux": true
  }
}

Cloud Datum Stream Settings list

This method returns a list of Cloud Datum Stream Settings entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/datum-streams/settings

The URL accepts the following search filter query parameters:

Property Type Description
datumStreamId Number The ID of a datum stream to match.
datumStreamIds Number[] A comma-delimited list of datum stream IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Cloud Datum Stream Setting entity objects. See the Cloud Datum Stream Settings view section for more information.

Cloud Datum Stream Settings save

This method creates or updates the Settings entity for the active user. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}/settings
datumStreamId The ID of the Cloud Datum Stream to save the settings for

The request body accepts a Cloud Datum Stream Settings JSON object with the following properties:

Property Type Description
publishToSolarIn Boolean true to publish datum to SolarIn for services that collect datum, unless overridden in a more specific setting
publishToSolarFlux Boolean true to publish datum to SolarFlux for services that collect datum, unless overridden in a more specific setting

For example:

{
  "publishToSolarIn": true,
  "publishToSolarFlux": true
}

Cloud Datum Stream Settings delete

This method deletes the Cloud Datum Stream Settings entity for a datum stream.

DELETE /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}/settings
datumStreamId The ID of the Cloud Datum Stream to save the settings for

The response will be a simple success or failure message.

Cloud Datum Stream datum list

This method queries a cloud service for cloud data values matching a search criteria, and converts the results to SolarNetwork datum values using a Cloud Datum Stream configuration. It is similar to the /datum/list endpoint, but for cloud service data.

GET /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}/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.

Cloud Datum Stream datum list response

The response contains a paged results object of datum objects. The following additional properties are returned:

Property Type Description
usedQueryFilter Map<String,String> The query filter parameters actually used, which may differ from what was provided. For example some cloud services impose time range restrictions.

See the Cloud Datum Stream datum view latest response for details on the properties returned for each result datum in the results array.

An example response for a node datum stream looks like this:

{
  "success": true,
  "data": {
    "returnedResultCount": 1,
    "usedQueryFilter": {
      "startDate": "2024-11-06 17:05:00Z",
      "endDate": "2024-11-06 18:05:00Z"
    },
    "results": [
      {
        "created": "2024-11-06 17:05:00Z",
        "nodeId": 123,
        "sourceId": "test/egauge",
        "i": {
          "voltage_a": 122.759,
          "voltage_b": 123.851,
          "voltage_c": 123.872,
          "voltage_ab": 213.839,
          "voltage_bc": 214.865,
          "voltage_ca": 212.996,
          "current_a": 356.421,
          "current_b": 357.119,
          "current_c": 396.193,
          "powerFactor": 0.879,
          "frequency": 60.090,
          "watts": 120632,
          "wattsReverse": 0,
          "current": 1109.734,
          "voltage": 123.494
        },
        "a": {
          "wattHours": 2824290738,
          "wattHourReverse": 630033
        }
      }
	]
  }
}

An example response for a location datum stream looks like this:

{
  "success": true,
  "data": {
    "returnedResultCount": 1,
    "results": [
      {
        "created": "2024-11-06 18:14:00Z",
        "locationId": 123123123,
        "sourceId": "OpenWeatherMap",
        "i": {
          "visibility": 10000,
          "temp": 12.61,
          "atm": 102200,
          "humidity": 92,
          "wdir": 20,
          "wspeed": 4.63,
          "cloudiness": 75
        },
        "s": {
          "sky": "Clouds",
          "iconId": "04d"
        }
      }
    ]
  }
}

Cloud Datum Stream datum view latest

This method queries a cloud service for cloud data values in the current time window associated with the Cloud Datum Stream, and converts the results to SolarNetwork datum values using a Cloud Datum Stream configuration. It is similar to the /datum/mostRecent endpoint, but for cloud service data.

💡 A "time window" is datum stream dependent, but generally is a short time range ending around the current time. You can think of it as similar to "what is happening right now". If the devices referenced by the Cloud Datum Stream do not happen to be available, then data for those devices will not be returned. For example some PV inverters shut down at night, and thus will not return data until they power up again the next morning.

GET /solaruser/api/v1/sec/user/c2c/datum-streams/{datumStreamId}/latest-datum

Cloud Datum Stream datum view latest response

The response contains a list of datum objects. The following properties are returned for each result datum in the results array:

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 (only for node datum streams)
locationId number The location ID (only for location datum streams)
sourceId string The source ID
a Map<String,Number> The accumulating datum properties
i Map<String,Number> The instantaneous datum properties
s Map<String,String> The status datum properties

☝️ Note that the datum samples properties a, i, and s are returned directly on the datum object.

An example response for a node datum stream looks like this:

{
  "success": true,
  "data": [
    {
      "created": "2024-11-06 18:00:00Z",
      "nodeId": 123,
      "sourceId": "test/egauge",
      "i": {
        "voltage_a": 122.142,
        "voltage_b": 123.855,
        "voltage_c": 123.441,
        "voltage_ab": 213.376,
        "voltage_bc": 214.739,
        "voltage_ca": 211.778,
        "current_a": 309.549,
        "current_b": 318.921,
        "current_c": 354.884,
        "powerFactor": 0.877,
        "frequency": 59.987,
        "watts": 106260,
        "wattsReverse": 0,
        "current": 983.355,
        "voltage": 123.146
      },
      "a": {
        "wattHours": 2824410283,
        "wattHourReverse": 630033
      }
    }
  ]
}

An example response for a location datum stream looks like this:

{
  "success": true,
  "data": [
    {
      "created": "2024-11-06 18:23:35Z",
      "locationId": 11536945,
      "sourceId": "OpenWeatherMap",
      "i": {
        "visibility": 10000,
        "temp": 11.99,
        "atm": 102200,
        "humidity": 94,
        "wdir": 20,
        "wspeed": 4.63,
        "cloudiness": 75
      },
      "s": {
        "sky": "Clouds",
        "iconId": "04d"
      }
    }
  ]
}

Cloud Datum Stream Poll Task

The Cloud Datum Stream Poll Task entity represents the runtime state of a datum stream poll task, specific to a Cloud Datum Stream.

Cloud Datum Stream Poll Task list

This method returns a list of Cloud Datum Stream Poll Task entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/datum-stream-poll-tasks

The URL accepts the following search filter query parameters:

Property Type Description
datumStreamId Number The ID of a datum stream to match.
datumStreamIds Number[] A comma-delimited list of datum stream IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a paged results list of Cloud Datum Stream Poll Task entity objects. Each entity contains the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity
datumStreamId Number The ID of the associated Cloud Datum Stream
state String Job execution state, one of q, e, c for queued, executing, or completed
executeAt String A timestamp of the next scheduled execution time
startAt String A timestamp of the next data query time
message String A message, such as an error reason.
serviceProperties Object Extra job properties, such as additional error information.

An example response looks like:

{
  "success": true,
  "data": {
    "totalResults": 2,
    "startingOffset": 0,
    "returnedResultCount": 2,
    "results": [
      {
        "userId": 123,
        "datumStreamId": 1,
        "state": "q",
        "executeAt": "2024-10-22 18:55:12Z",
        "startAt": "2024-10-22 18:34:00Z"
      },
      {
        "userId": 123,
        "datumStreamId": 2,
        "state": "c",
        "executeAt": "2024-10-22 18:55:12Z",
        "startAt": "2024-10-22 18:45:00Z",
		"message": "Authentication failed.",
		"serviceProperties": {
			"siteId": 1111
		}
      }
    ]
  }
}

Cloud Datum Stream Poll Task save

PUT /solaruser/api/v1/sec/user/c2c/datum-stream-poll-tasks/{datumStreamId}
datumStreamId The ID of a datum stream to save (create or update) the task for

The request body accepts a Cloud Datum Stream Poll Task JSON object with the following properties:

Property Type Description
state String Job execution state, one of q, c for queued, completed
executeAt String A timestamp of the next scheduled execution time
startAt String A timestamp of the next data query time
message String A message, such as an error reason.
serviceProperties Object Extra job properties, such as additional error information.
requiredStates String[] Optional list of states the task must be in in order to update, like an update if state is X restriction

For example, this would stop the task with an error message, only if the task was in the queued state q:

{
  "state": "c",
  "executeAt": "2024-10-11 05:00:00Z",
  "startAt": "2024-10-11 04:50:00Z",
  "message": "Manually stopped with state constraint",
  "serviceProperties": {
    "because": "of emergency"
  },
  "requiredStates": [
    "q"
  ]
}

Cloud Datum Stream Poll Task delete

This method deletes a Cloud Datum Stream Poll Task entity.

DELETE /solaruser/api/v1/sec/user/c2c/datum-stream-poll-tasks/{datumStreamId}
datumStreamId The ID of the Cloud Datum Stream to delete the poll task for

The response will be a simple success or failure message.

Cloud Datum Stream Poll Task update state

PUT /solaruser/api/v1/sec/user/c2c/datum-stream-poll-tasks/{datumStreamId}/state
datumStreamId The ID of a datum stream to update the task for

The request body accepts a JSON object with the following properties:

Property Type Description
state String Desired job execution state, one of q, c for queued, completed
requiredStates String[] Optional list of states the task must be in in order to update, like an update if state is X restriction

For example, this would stop the task, only if the task was in the queued state q:

{
  "state": "c",
  "requiredStates": [
    "q"
  ]
}
Add a custom footer
Clone this wiki locally