Overview

Introduction

The Locus Energy v3 API endpoint prefix is https://api.locusenergy.com/v3.

The API provides programmatic access to much of the data found in SolarNOC. It deals with a few types objects and associated data:

• Clients: a client is a container for sites. It contains information about client name, timezone, and other metadata found in SolarNOC. Clients are often also referred to as ‘projects.’

• Sites: a site primarily provides holds location information, as well as site-level metadata such as size and installer. A client can have multiple sites. A site also has timeseries data associated with it.

• Components: a component represents a physical device installed on the site. A site can have multiple child components, and components can have multiple children components. A component also is associated with timeseries data.

Data is returned in JSON.

The source of this documentation is available publicly on Github. Feel free to contribute by submitting a pull request.

Getting started

Before you begin, you should already have the items below. If you don’t, please get in touch with your Locus Energy account manager.

• API credentials. This includes a client_id and client_secret.
• SolarOS username and password
• Your partner ID

Once you have these, check out the common workflows for some examples of how to interact with the API.

Postman

Postman is a tool for interacting with APIs. Download the tool from their website to more easily interact with the Locus Energy API. Once you have the application installed, click the button below to interact with the Locus Energy API using Postman. This button will open the Postman app with a configured Collection and Environment. For everything to work properly, be sure to update the Locus Energy External API.template Postman Environment with your own API credentials. To do this, make sure Locus Energy External API.template is selected in the dropdown in the upper-right hand corner of Postman. Then, click the eye button to the right of it, then choose edit. Fill in the values for each variable with your own information. You do not need to fill out refresh_token and access_token – those will be automatically filled as you interact with the API via the Locus Energy API Collection in Postman.

Errors

Locus Energy uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with Locus Energy’s servers.

Common Errors

400 Bad Request: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

401 Unauthorized: Authentication failed. Check that your authentication credentials are correct.

403 Forbidden: The request you are making is valid, but you do not have permission to access the entity requested. Authenticating will make no difference. Double check the entity ID that you are requesting.

404 Not Found: The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

429 Too Many Requests: The user has sent too many requests in a given amount of time. See information regarding rate limiting.

5xx Server Error: Please contact our support team with details about the error received.

Rate limiting

Requests are rate limited by default to 1 request at a time. A rate limited request will return an HTTP 429 error in the format shown on the right. If you’d like higher rates of concurrency, please contact your account manager.

{
    "message": "Too many requests",
    "statusCode": 429
}

Versioning

The v3 API is globally versioned for all endpoints. With this version, you can trust that we will never remove or change the existing structure of requests and responses. However, we may add new fields and query parameters. In addition, we may change the values that are returned while maintaining the response structure.

Examples of possible changes within a version are shown on the right.

Example 1

We may add a new field to an existing response. For example, we may add a new field to the component object.

The current object is:

{
  "id": 54369,
  "siteId": 3393714,
  "clientId": 419010,
  "parentId": 3393714,
  "parentType": "SITE",
  "nodeId": "OB.001EC1111DC9.1",
  "name": "PV Meter",
  "nodeType": "METER",
  "application": "GENERATION",
  "generationType": "SOLAR",
  "oem": "Locus Energy",
  "model": "LGate 120",
  "isConceptualNode": false,
  "serialNumber": "ABC123",
  "description": "This is a revenue grade meter"
}

A valid change would be:

{
  "id": 54369,
  "siteId": 3393714,
  "clientId": 419010,
  "parentId": 3393714,
  "parentType": "SITE",
  "nodeId": "OB.001EC1111DC9.1",
  "name": "PV Meter",
  "nodeType": "METER",
  "application": "GENERATION",
  "generationType": "SOLAR",
  "oem": "Locus Energy",
  "model": "LGate 120",
  "isConceptualNode": false,
  "serialNumber": "ABC123",
  "description": "This is a revenue grade meter",
  "exampleNewField": "hello everyone!"
}

Example 2

We may change that values that are returned while maintaining the response structure. For example, consider the dataavailable call.

For a site, a possible response is:

{
    "statusCode": 200,
    "baseFields": [
        {
            "baseField": "W",
            "longName": "AC Power",
            "source": "Measured",
            "unit": "W",
            "aggregations": [
                {
                    "shortName": "W_avg",
                    "aggregation": "avg"
                },
                {
                    "shortName": "W_max",
                    "aggregation": "max"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "Wh",
            "longName": "AC Energy",
            "source": "Measured",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "Wh_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        }
    ]
}

We may add a new data type that is available for this site. The response would then become:

{
    "statusCode": 200,
    "baseFields": [
        {
            "baseField": "W",
            "longName": "AC Power",
            "source": "Measured",
            "unit": "W",
            "aggregations": [
                {
                    "shortName": "W_avg",
                    "aggregation": "avg"
                },
                {
                    "shortName": "W_max",
                    "aggregation": "max"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "Wh",
            "longName": "AC Energy",
            "source": "Measured",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "Wh_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "NewBaseField",
            "longName": "I'm a new data type!",
            "source": "Measured",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "NewBaseField_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        }
    ]
}

Compression

Responses are compressed if Accept-Encoding: gzip is sent as a request header. Compression can significantly reduce the size of the response, saving bandwidth and reducing time spent transmitting the response from the server to the client.

Example compression request

GET https://api.locusenergy.com/v3/sites/123/alerts?tz=UTC HTTP/1.1
Accept: application/json
Accept-Encoding: gzip
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/alerts?tz=UTC
  -X GET
  -H "Accept: application/json"
  -H "Accept-Encoding: gzip"
  -H "Authorization: Bearer ACCESS_TOKEN"

The response will be compressed with gzip encoding. Decompressing the response will yield valid JSON.

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 456,
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T12:00:00-00:00",
            "updated": "2015-11-22T12:03:00-00:00"
        },
        {
            "id": 78,
            "componentId": 90,
            "alertType": "Device Fault",
            "priority": "Medium",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T15:00:00-00:00",
            "updated": "2015-11-24T12:05:00-00:00",
            "descriptionShort": "VDC high",
            "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
        }
    ]
}

Changelog

2018-06-07

• GHI_m from Irradiance Global Horizontal to VI - Irradiance Global Horizontal
• GHIh_m from Insolation Global Horizontal to VI - Insolation Global Horizontal
• GHIhp_m from Insolation Global Horizontal (prorated) to VI - Insolation Global Horizontal (prorated)

2018-03-13

• 5min and 15min granularity data time period limit extended from 7 to 31 days

2017-09-11

• Added additional filter options on alerts, including alertType and status

2017-07-20

• Added documentation to use Postman
• Added componentName, siteId and siteName to the alerts object

2017-05-15

• Added the latest granularity to Component level Data Available and Data calls

2017-04-20

• Added the read-only field locationTimezone to site objects

2016-11-11

• Added the ability to get data for all sites in one request

2016-09-30

• Added 1min as a valid granularity for data requests

Common workflows

Getting data for a component

Step 1: Get the componentId

GET https://api.locusenergy.com/v3/partners/123/components?nodeId=ABC.123 HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/123/components?nodeId=ABC.123
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "components": [
        {
            "id": 54369,
            "siteId": 3393714,
            "clientId": 419010,
            "parentId": 3393714,
            "parentType": "SITE",
            "nodeId": "ABC.123",
            "name": "PV Meter",
            "nodeType": "METER",
            "application": "GENERATION",
            "generationType": "SOLAR",
            "oem": "Locus Energy",
            "model": "LGate 120",
            "isConceptualNode": false
        }
    ]
}

Step 2: Get component data available

GET https://api.locusenergy.com/v3/components/54369/dataavailable HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/54369/dataavailable
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "baseFields": [
        {
            "baseField": "W",
            "longName": "AC Power",
            "source": "Measured",
            "unit": "W",
            "aggregations": [
                {
                    "shortName": "W_avg",
                    "aggregation": "avg"
                },
                {
                    "shortName": "W_max",
                    "aggregation": "max"
                },
                {
                    "shortName": "W_min",
                    "aggregation": "min"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "Wh",
            "longName": "AC Energy",
            "source": "Measured",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "Wh_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        }
    ]
}

Step 3: Get component data

GET https://api.locusenergy.com/v3/components/54369/data?start=2014-01-01T00:00:00&end=2014-03-01T00:00:00&tz=US/Pacific&gran=monthly&fields=W_avg,Wh_sum HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/54369/data?start=2014-01-01T00:00:00&end=2014-03-01T00:00:00&tz=US/Pacific&gran=monthly&fields=W_avg,Wh_sum
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "data": [
        {
            "id": 54369,
            "ts": "2014-01-01T00:00:00-07:00",
            "Wh_sum": 1234.5,
            "W_avg": 567
        },
        {
            "id": 54369,
            "ts": "2014-02-01T00:00:00-07:00",
            "Wh_sum": 1252.4,
            "W_avg": 684.756
        }
    ]
}

One of the most common use cases of our API is obtaining data for a component for which you know the node ID. It’s a three step process to get data that is described below. Example requests and responses are provided to the right.

1. Get the component ID (Locus API identifier) for the node ID (also known as the MAC ID) using the get components for a partner endpoint. For example, if your partner ID is 123 and the node ID of the component in question is ABC.123, you would do a GET https://api.locusenergy.com/v3/partners/123/components?nodeId=ABC.123.

2. Once you have the component ID, then you can ask what data is available for that component. This is important because different types of components have different types of data. For example, a meter might have energy and power data, while a weather station might have irradiance and ambient temperature. Assuming that the componentId resulting from the previous call was 54369, the call would like like GET https://api.locusenergy.com/v3/components/54369/dataavailable.

3. For your node ID, you now know the component ID and the data available that you can ask for. You’re now ready to ask for that data, supplying a comma-separated list of fields from the dataavailable baseField shortNames. Following this example, a possible data call could be GET https://api.locusenergy.com/v3/components/54369/data?start=2014-01-01T00:00:00&end=2014-03-01T00:00:00&tz=US/Pacific&gran=monthly&fields=W_avg,Wh_sum.

Getting lifetime energy for a component

GET https://api.locusenergy.com/v3/components/54369/data?start=2000-01-01T00:00:00&end=2030-01-01T00:00:00&tz=UTC&gran=yearly&fields=Wh_sum HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/54369/data?start=2000-01-01T00:00:00&end=2030-01-01T00:00:00&tz=UTC&gran=yearly&fields=Wh_sum
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "data": [
        {
            "id": 54369,
            "ts": "2000-01-01T00:00:00+00:00"
        },
        {
            "id": 54369,
            "ts": "2001-01-01T00:00:00+00:00"
        },
        ...
        {
            "id": 54369,
            "ts": "2014-01-01T00:00:00+00:00",
            "Wh_sum": 1234123.5
        },
        {
            "id": 54369,
            "ts": "2015-01-01T00:00:00+00:00",
            "Wh_sum": 124234.2
        },
        {
            "id": 54369,
            "ts": "2016-01-01T00:00:00+00:00"
        },
        ...
    ]
}

Sometimes you’d like to know how much energy a certain meter has produced in its lifetime. That’s easy with our data API. First, read through steps 1 and 2 of the Getting data for a component workflow.

• start: choose a very early start date, one that would be early enough to be before any PV system you are interested in came online. In general, 2000-01-01T00:00:00 is a safe choice unless you have some pretty old PV systems.

• end: choose something very far in the future. Let’s go with 2030-01-01T00:00:00. If you want to be a bit more clever, you can use the current timestamp of whenever you make the API call.

• tz: choose the timezone for which you’d like timestamps to be in. To avoid snubbing anyone, let’s go with UTC in this example.

• gran: this is an important one. Choose yearly. It will be much faster than any other option because less data will be transferred.

• fields: if you are looking for energy, go with Wh_sum. Make sure that Wh_sum is a valid field for this specific component using the dataavailable call.

The resulting call will look something like the example on the right. Note that for demonstration purposes, ’…’ is used to represent many timestamp blocks without any energy data.

Traversing the hierarchy to get data

Step 1: Get a list of sites

GET https://api.locusenergy.com/v3/partners/123/sites HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/123/sites
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "sites": [
        {
            "statusCode": 200,
            "id": 123,
            "clientId": 456,
            "name": "Test Site",
            "address1": "657 Mission St",
            "address2": "",
            "locale3": "San Francisco",
            "locale1": "California",
            "localeCode1": "CA",
            "postalCode": "94105",
            "countryCode": "US",
            "locationTimezone": "America/Los_Angeles"
        },
        {
            "statusCode": 200,
            "id": 789,
            "clientId": 456,
            "name": "Test Site 2",
            "address1": "2 Hudson Place",
            "address2": "",
            "locale3": "Hoboken",
            "locale1": "New Jersey",
            "localeCode1": "NJ",
            "postalCode": "07030",
            "countryCode": "US",
            "locationTimezone": "America/New_York"
        }
    ]
}

Step 2: Get components for a site

GET https://api.locusenergy.com/v3/sites/789/components HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/789/components
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "components": [
        {
            "id": 54369,
            "siteId": 789,
            "clientId": 419010,
            "parentId": 789,
            "parentType": "SITE",
            "nodeId": "OB.001EC1111DC9.1",
            "name": "PV Meter",
            "nodeType": "METER",
            "application": "GENERATION",
            "generationType": "SOLAR",
            "oem": "Locus Energy",
            "model": "LGate 120",
            "isConceptualNode": false
        },
        {
            "id": 54369,
            "siteId": 789,
            "clientId": 419010,
            "parentId": 54369,
            "parentType": "COMPONENT",
            "nodeId": "OB.TESTNODE.44",
            "name": "AE Inverter E1",
            "nodeType": "INVERTER",
            "application": "GENERATION",
            "generationType": "SOLAR",
            "oem": "Advanced Energy",
            "model": "AE 500NX 480V",
            "isConceptualNode": false
        }
    ]
}

Step 3: Get component data available

GET https://api.locusenergy.com/v3/components/54369/dataavailable HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/54369/dataavailable
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "baseFields": [
        {
            "baseField": "W",
            "longName": "AC Power",
            "source": "Measured",
            "unit": "W",
            "aggregations": [
                {
                    "shortName": "W_avg",
                    "aggregation": "avg"
                },
                {
                    "shortName": "W_max",
                    "aggregation": "max"
                },
                {
                    "shortName": "W_min",
                    "aggregation": "min"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "Wh",
            "longName": "AC Energy",
            "source": "Measured",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "Wh_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        }
    ]
}

Step 4: Get component data

GET https://api.locusenergy.com/v3/components/54369/data?start=2014-01-01T00:00:00&end=2014-03-01T00:00:00&tz=US/Pacific&gran=monthly&fields=W_avg,Wh_sum HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/54369/data?start=2014-01-01T00:00:00&end=2014-03-01T00:00:00&tz=US/Pacific&gran=monthly&fields=W_avg,Wh_sum
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "data": [
        {
            "id": 54369,
            "ts": "2014-01-01T00:00:00-07:00",
            "Wh_sum": 1234.5,
            "W_avg": 567
        },
        {
            "id": 54369,
            "ts": "2014-02-01T00:00:00-07:00",
            "Wh_sum": 1252.4,
            "W_avg": 684.756
        }
    ]
}

Each user has access to a list of sites and each site has a list of children components. You can traverse this hierarchy through the API in order to get the data you need.

1. Get the list of sites for your partner. Your partner ID was given to you by your account manager. For more info on the partner ID, please see the getting started section. If your partner ID is 123, for example, this call would be GET https://api.locusenergy.com/v3/partners/123/components.
2. Choose a site from the result of step 1 and use that site ID to get a list of children components. If the desired site ID was 789, this call would be GET https://api.locusenergy.com/v3/sites/789/components.
3. Select the component ID from the results of step 2. Once you have the component ID, then you can ask what data is available for that component. This is important because different types of components have different types of data. For example, a meter might have energy and power data, while a weather station might have irradiance and ambient temperature. Assuming that the component ID resulting from the previous call was 54369, the call would look like GET https://api.locusenergy.com/v3/components/54369/dataavailable.
4. For your node ID, you now know the component ID and the data available that you can ask for. You’re now ready to ask for that data, supplying a comma-separated list of fields from the dataavailable baseField shortNames. Following this example, a possible data call could be GET https://api.locusenergy.com/v3/components/54369/data?start=2014-01-01T00:00:00&end=2014-03-01T00:00:00&tz=US/Pacific&gran=monthly&fields=W_avg,Wh_sum.

Authentication

The authentication mechanism is based off of the OAuth 2 guidelines. Once an access_token is received, it must be used with all subsequent non-authentication API requests.

Authentication object

Example response:

{
    "access_token": "41e818b29780637494d9026760d40b51",
    "issued_at": 1430347010,
    "token_type": "bearer",
    "refresh_token": "c27720f61b77245731c2e3ce4647ddad",
    "expires_in": 3600
}

Attributes

Attribute	Type	Description	Always returned?
access_token	String	Randomly generated string to serve as authentication token for subsequent requests	yes
issued_at	Integer	Unix timestamp for when access_token was issued	yes
expires_in	Integer	Seconds until the access_token expires	yes
token_type	String	The type of the token being returned	yes
refresh_token	String	Randomly generated string. This can be used to obtain more access tokens instead of supplying a username and password	no. Only returned for password grant type.

Resource Owner Password

Example request:

POST https://api.locusenergy.com/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=password&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&username=USERNAME&password=PASSWORD

curl https://api.locusenergy.com/oauth/token 
  -X POST
  -H "Content-Type: application/x-www-form-urlencoded"
  -d 'grant_type=password&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&username=USERNAME&password=PASSWORD'

Make sure to replace CLIENT_ID and CLIENT_SECRET with your API credentials. USERNAME and PASSWORD are needed for the user on who’s behalf the application is making the request.

Example response:

{
    "access_token": "41e818b29780637494d9026760d40b51",
    "issued_at": 1430347010,
    "token_type": "bearer",
    "refresh_token": "c27720f61b77245731c2e3ce4647ddad",
    "expires_in": 3600
}

The API uses the OAuth 2 Resource Owner Password Credentials flow. If successful, an access_token is returned with an accompanying refresh_token. Once the access_token expires, you can refresh it by using the refresh_token.

Most API credentials for customers use this flow. If your credentials don’t work for this flow, please try Client Credentials. If you continue to experience trouble authenticating, please contact support.

Definition

POST /oauth/token

Arguments

Parameter	Required?	Default	Description
grant_type	yes		The string “password”. This defines the OAuth 2.0 flow.
client_id	yes		The client_id for your application. Obtain this from your account manager.
client_secret	yes		The client_secret for your application. Obtain this from your account manager.
username	yes		The user’s SolarNOC username.
password	yes		The user’s SolarNOC password.

Refreshing an Access Token

Example request:

POST https://api.locusenergy.com/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN

curl https://api.locusenergy.com/oauth/token 
  -X POST
  -H "Content-Type: application/x-www-form-urlencoded"
  -d 'grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN'

Make sure to replace CLIENT_ID and CLIENT_SECRET with your API credentials. You should have a REFRESH_TOKEN from a previously successful authentication attempt via the Resource Owner Password flow

Example response:

{
    "access_token": "41e818b29780637494d9026760d40b51",
    "issued_at": 1430347010,
    "token_type": "bearer",
    "expires_in": 3600
}

The API uses the OAuth 2 guidelines for refreshing an access token. If successful, an access_token is returned with an accompanying refresh_token. Once the access_token expires, you can refresh it by using the refresh_token.

Definition

POST /oauth/token

Arguments

Parameter	Required?	Default	Description
grant_type	yes		The string “refresh_token”. This defines the OAuth 2.0 flow.
client_id	yes		The client_id for your application. Obtain this from your account manager.
client_secret	yes		The client_secret for your application. Obtain this from your account manager.
refresh_token	yes		The refresh_token from a previously successful authentication attempt.

Client Credentials

Example request:

POST https://api.locusenergy.com/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

curl https://api.locusenergy.com/oauth/token 
  -X POST
  -H "Content-Type: application/x-www-form-urlencoded"
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

Make sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your API credentials.

Example response:

{
    "access_token": "ef4ace9dc2574925b8708d05fbb9da7z",
    "issued_at": 1425672574,
    "expires_in": 3600
}

For some special use cases, the API uses the OAuth 2 Client Credentials flow. If successful, an access_token is returned with a 1 hour lifetime. Once the access_token expires, you will need to authenticate again to get a new one.

If your credentials don’t work for this flow, please try Resource Owner Password flow. If you continue to experience trouble authenticating, please contact support.

Definition

POST /oauth/token

Arguments

Parameter	Required?	Default	Description
grant_type	yes		The string “client_credentials”. This defines the OAuth 2.0 flow.
client_id	yes		The client_id for your application. Obtain this from your account manager.
client_secret	yes		The client_secret for your application. Obtain this from your account manager.

Components

Component object

{
  "id": 54369,
  "siteId": 3393714,
  "clientId": 419010,
  "parentId": 3393714,
  "parentType": "SITE",
  "nodeId": "OB.001EC1111DC9.1",
  "name": "PV Meter",
  "nodeType": "METER",
  "application": "GENERATION",
  "generationType": "SOLAR",
  "oem": "Locus Energy",
  "model": "LGate 120",
  "isConceptualNode": false,
  "serialNumber": "ABC123",
  "description": "This is a revenue grade meter"
}

Attributes

Attribute	Type	Description	Always returned?
id	Integer	Unique identifier for the component	yes
siteId	Integer	Identifier for the parent site	yes
clientId	Integer	Identifier for the grandparent client	yes
parentId	Integer	Identifier for the parent. This could be the ID of a component or site depending upon the site hierarchy.	yes
parentType	String	Type of parent. This can be SITE or COMPONENT.	yes
nodeID	String	Unique MAC address of the physical device that this component represents.	yes
name	String	Component name	yes
nodeType	String	Type of component	yes
application	String	Use of component. Options are: GENERATION or NET-GRID	yes
generationType	String	Type of generation. Options are: SOLAR, WIND, THERMAL, OTHER, NET-GRID or EVSE	yes
oem	String	Original Equipment Manufacturer of the component	yes
model	String	Model name of the component	yes
isConceptualNode	boolean	Conceptual means non-monitored. If this component actually collects data, it is not conceptual.	yes
serialNumber	String	Text field for serial number	no
description	String	Text field for description	no

Get component

Example request:

GET https://api.locusenergy.com/v3/components/54369 HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/54369
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "id": 54369,
  "siteId": 3393714,
  "clientId": 419010,
  "parentId": 3393714,
  "parentType": "SITE",
  "nodeId": "OB.001EC1111DC9.1",
  "name": "PV Meter",
  "nodeType": "METER",
  "application": "GENERATION",
  "generationType": "SOLAR",
  "oem": "Locus Energy",
  "model": "LGate 120",
  "isConceptualNode": false
}

This endpoint retrieves a component object.

Definition

GET /v3/components/{componentId}

Arguments

Argument	Description	Required?	Default
componentId	Unique identifier for the component	yes

Returns

Returns a component object.

Get components for a site

Example request:

GET https://api.locusenergy.com/v3/sites/3393714/components HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/3393714/components
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "components": [
    {
      "id": 54369,
      "siteId": 3393714,
      "clientId": 419010,
      "parentId": 3393714,
      "parentType": "SITE",
      "nodeId": "OB.001EC1111DC9.1",
      "name": "PV Meter",
      "nodeType": "METER",
      "application": "GENERATION",
      "generationType": "SOLAR",
      "oem": "Locus Energy",
      "model": "LGate 120",
      "isConceptualNode": false
    },
    {
      "id": 54369,
      "siteId": 3393714,
      "clientId": 419010,
      "parentId": 2050424,
      "parentType": "COMPONENT",
      "nodeId": "OB.TESTNODE.44",
      "name": "AE Inverter E1",
      "nodeType": "INVERTER",
      "application": "GENERATION",
      "generationType": "SOLAR",
      "oem": "Advanced Energy",
      "model": "AE 500NX 480V",
      "isConceptualNode": false
    }
  ]
}

This endpoint retrieves components for a site.

Definition

GET /v3/sites/{siteId}/components

Arguments

Argument	Description	Required?	Default
siteId	Unique identifier for the site	yes

Returns

Returns an array of component objects.

Get components for a client

Example request:

GET https://api.locusenergy.com/v3/clients/419010/components HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/clients/419010/components
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "components": [
    {
      "id": 54369,
      "siteId": 3393714,
      "clientId": 419010,
      "parentId": 3393714,
      "parentType": "SITE",
      "nodeId": "OB.001EC1111DC9.1",
      "name": "PV Meter",
      "nodeType": "METER",
      "application": "GENERATION",
      "generationType": "SOLAR",
      "oem": "Locus Energy",
      "model": "LGate 120",
      "isConceptualNode": false
    },
    {
      "id": 54369,
      "siteId": 3393714,
      "clientId": 419010,
      "parentId": 2050424,
      "parentType": "COMPONENT",
      "nodeId": "OB.TESTNODE.44",
      "name": "AE Inverter E1",
      "nodeType": "INVERTER",
      "application": "GENERATION",
      "generationType": "SOLAR",
      "oem": "Advanced Energy",
      "model": "AE 500NX 480V",
      "isConceptualNode": false
    }
  ]
}

This endpoint retrieves components for a client.

Definition

GET /v3/clients/{clientId}/components

Arguments

Argument	Description	Required?	Default
clientId	Unique identifier for the client	yes

Returns

Returns an array of component objects.

Get components for a partner

Example request:

GET https://api.locusenergy.com/v3/partners/123/components HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/123/components
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "components": [
    {
      "id": 54369,
      "siteId": 3393714,
      "clientId": 419010,
      "parentId": 3393714,
      "parentType": "SITE",
      "nodeId": "OB.001EC1111DC9.1",
      "name": "PV Meter",
      "nodeType": "METER",
      "application": "GENERATION",
      "generationType": "SOLAR",
      "oem": "Locus Energy",
      "model": "LGate 120",
      "isConceptualNode": false
    },
    {
      "id": 54369,
      "siteId": 3393714,
      "clientId": 419010,
      "parentId": 2050424,
      "parentType": "COMPONENT",
      "nodeId": "OB.TESTNODE.44",
      "name": "AE Inverter E1",
      "nodeType": "INVERTER",
      "application": "GENERATION",
      "generationType": "SOLAR",
      "oem": "Advanced Energy",
      "model": "AE 500NX 480V",
      "isConceptualNode": false
    }
  ]
}

This endpoint retrieves components for a partner.

Definition

GET /v3/partners/{partnerId}/components

Arguments

Argument	Description	Required?	Default
partnerId	Unique identifier for the partner	yes
nodeId	Node ID of component. A URL-encoded % will function as a wildcard in the search.	no
notes	Value of note fields to search on. A URL-encoded % will function as wildcard in the search.	no

Returns

Returns an array of component objects.

Sites

Site object

{
  "id": 123,
  "clientId": 456,
  "name": "Test Site",
  "address1": "657 Mission St",
  "address2": "",
  "locale3": "San Francisco",
  "locale1": "California",
  "localeCode1": "CA",
  "postalCode": "94105",
  "countryCode": "US",
  "locationTimezone": "America/Los_Angeles"
}

Attributes

Attribute	Type	Description	Always returned?
id	Integer	Unique identifier for the site	yes
clientId	Integer	Identifier for the parent client	yes
name	String	Name of the site	yes
address1	String	Address line 1	yes
address2	String	Address line 2	no
locale3	String	Within the US, city	yes
locale1	String	Within the US, state	yes
localeCode1	String	Within the US, state abbreviation	yes
postalCode	String	Within the US, zip code	yes
countryCode	String	Country name abbreviation	yes
latitude	Float	Latitude	no
longitude	Float	Longitude	no
locationTimezone	String	Timezone	no

Get site

Example request:

GET https://api.locusenergy.com/v3/sites/123 HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "id": 123,
  "clientId": 456,
  "name": "Test Site",
  "address1": "657 Mission St",
  "address2": "",
  "locale3": "San Francisco",
  "locale1": "California",
  "localeCode1": "CA",
  "postalCode": "94105",
  "countryCode": "US",
  "locationTimezone": "America/Los_angeles"
}

This endpoint retrieves a site object.

Definition

GET /v3/sites/{siteId}

Arguments

Argument	Description	Required?	Default
siteId	Unique identifier for the site	yes

Returns

Returns a site object.

Get sites for a client

Example request:

GET https://api.locusenergy.com/v3/clients/456/sites HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/clients/456/sites
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "sites": [
    {
      "statusCode": 200,
      "id": 123,
      "clientId": 456,
      "name": "Test Site",
      "address1": "657 Mission St",
      "address2": "",
      "locale3": "San Francisco",
      "locale1": "California",
      "localeCode1": "CA",
      "postalCode": "94105",
      "countryCode": "US",
      "locationTimezone": "America/Los_Angeles"
    },
    {
      "statusCode": 200,
      "id": 789,
      "clientId": 456,
      "name": "Test Site 2",
      "address1": "2 Hudson Place",
      "address2": "",
      "locale3": "Hoboken",
      "locale1": "New Jersey",
      "localeCode1": "NJ",
      "postalCode": "07030",
      "countryCode": "US",
      "locationTimezone": "America/New_York"
    }
  ]
}

This endpoint retrieves sites for a client.

Definition

GET /v3/clients/{clientId}/sites

Arguments

Argument	Description	Required?	Default
clientId	Unique identifier for the client	yes

Returns

Returns a site object.

Get sites for a partner

Example request:

GET https://api.locusenergy.com/v3/partners/456/sites HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/456/sites
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "sites": [
    {
      "statusCode": 200,
      "id": 123,
      "clientId": 456,
      "name": "Test Site",
      "address1": "657 Mission St",
      "address2": "",
      "locale3": "San Francisco",
      "locale1": "California",
      "localeCode1": "CA",
      "postalCode": "94105",
      "countryCode": "US",
      "locationTimezone": "America/Los_Angeles"
    },
    {
      "statusCode": 200,
      "id": 789,
      "clientId": 456,
      "name": "Test Site 2",
      "address1": "2 Hudson Place",
      "address2": "",
      "locale3": "Hoboken",
      "locale1": "New Jersey",
      "localeCode1": "NJ",
      "postalCode": "07030",
      "countryCode": "US",
      "locationTimezone": "America/New_York"
    }
  ]
}

This endpoint retrieves sites for a partner.

Definition

GET /v3/partners/{partnerId}/sites

Arguments

Argument	Description	Required?	Default
partnerId	Unique identifier for the partner	yes

Returns

Returns a site object.

Get install info

Example request:

GET https://api.locusenergy.com/v3/sites/123/installinfo HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/installinfo
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "installer": "ABC Solar",
  "installDate": "2014-05-08",
  "ptoDate": "2014-05-14",
  "startupDate": "2014-05-14",
  "uninstallDate": "2014-06-01"
}

This endpoint retrieves a site installinfo object.

Definition

GET /v3/sites/{siteId}/installinfo

Arguments

Argument	Description	Required?	Default
siteId	Unique identifier for the site	yes

Returns

Returns a site installinfo object.

Attribute	Type	Description	Always returned?
installer	String	Installer of the site	no
installCrew	String	Install crew of the site	no
installDate	String (yyyy-mm-dd)	Install date of the site	no
ptoDate	String (yyyy-mm-dd)	Permission to operate date of the site	no
startupDate	String (yyyy-mm-dd)	Startup date of the site	no
uninstallCrew	String	Uninstall crew of the site	no
uninstallDate	String (yyyy-mm-dd)	Uninstall date of the site	no

Get model settings

Example request:

GET https://api.locusenergy.com/v3/sites/123/modelsettings HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/modelsettings
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "size": 1023.4,
  "mismatch": 98,
  "diodesAndConnections": 99,
  "dcWiring": 98,
  "soiling": 95,
  "sunTracking": 100,
  "nameplate": 100,
  "acWiring": 99,
  "transformer": 100,
  "tmy3Id": 724095
}

This endpoint retrieves a site modelsettings object.

Definition

GET /v3/sites/{siteId}/modelsettings

Arguments

Argument	Description	Required?	Default
siteId	Unique identifier for the site	yes

Returns

Returns a site modelsettings object.

Attribute	Type	Description	Always returned?
size	Float	Installed system size (kw DC)	no
mismatch	Integer	PV model parameter	yes
diodesAndConnections	Integer	PV model parameter	yes
dcWiring	Integer	PV model parameter	yes
soiling	Integer	PV model parameter	yes
sunTracking	Integer	PV model parameter	yes
nameplate	Integer	PV model parameter	yes
acWiring	Integer	PV model parameter	yes
transformer	Integer	PV model parameter	yes
tmy3Id	Integer	PV model parameter	no

Clients

Client object

{
  "id": 123,
  "partnerId": 456,
  "tz": "US/Eastern",
  "firstName": "Test",
  "lastName": "System",
  "email": "test@aol.com"
}

Attributes

Attribute	Type	Description	Always returned?
id	Integer	Unique identifier for the client	yes
partnerId	Integer	Identifier for the parent partner	yes
tz	String	Timezone default for the client home user	yes
firstName	String	First name of the client	yes
lastName	String	Last name of the client	yes
email	String	email address of the client	yes

Get client

Example request:

GET https://api.locusenergy.com/v3/clients/123 HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/clients/123
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "id": 123,
  "partnerId": 456,
  "tz": "US/Eastern",
  "firstName": "Test",
  "lastName": "System",
  "email": "test@aol.com"
}

This endpoint retrieves a client object.

Definition

GET /v3/clients/{clientId}

Arguments

Argument	Description	Required?	Default
clientId	Unique identifier for the client	yes

Returns

Returns a client object.

Get clients for partner

Example request:

GET https://api.locusenergy.com/v3/partners/456/clients HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/456/clients
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "clients": [
    {
      "id": 123,
      "partnerId": 456,
      "tz": "US/Eastern",
      "firstName": "Test",
      "lastName": "System",
      "email": "test@locusenergy.com"
    },
    {
      "id": 789,
      "partnerId": 456,
      "tz": "US/Pacific",
      "firstName": "Another",
      "lastName": "System",
      "email": "another@locusenergy.com"
    }
  ]
}

This endpoint retrieves clients for a partner.

Definition

GET /v3/partners/{partnerId}/clients

Arguments

Argument	Description	Required?	Default
partnerId	Unique identifier for the partner	yes

Returns

Returns an array of client objects.

Data Available

Base Field object

{
    "baseField": "W_m",
    "longName": "AC Power",
    "source": "Modeled",
    "unit": "W",
    "aggregations": [
        {
            "shortName": "W_m_avg",
            "aggregation": "avg"
        }
    ],
    "fieldParameters": [
        {
            "param": "modelType",
            "values": [
                "simple"
            ]
        },
        {
            "param": "irradianceSource",
            "values": [
                "weatherStation"
            ]
        },
        {
            "param": "inverterClipping",
            "values": [
                "true",
                "false"
            ]
        }
    ],
    "granularities": [
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
    ]
}

Attributes

Attribute	Type	Description	Always returned?
baseField	String	Unique identifier of this base field	yes
longName	String	Human-readable name of this base field	yes
source	String	Type of data. This can be Measured, Modeled or Expected	yes
unit	String	Unit of this data type	yes
aggregations	Array	Array of aggregations	yes
fieldParameters	Array	Array of field parameters	yes
granularities	Array of Strings	Array of granularities allowed	yes

Aggregations

Attribute	Type	Description	Always returned?
shortName	String	Base field with the aggregation appended. This fully defines the field to be used in the data call	yes
aggregation	String	Aggregation for this short name. Options are min, max, avg and sum.	yes

Field Parameters

Attribute	Type	Description	Always returned?
param	String	Type of parameter	yes
values	Array of Strings	Allowed values for this parameter	yes

Get data available for component

Example request:

GET https://api.locusenergy.com/v3/components/123/dataavailable HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/123/dataavailable
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "baseFields": [
    {
      "baseField": "A",
      "longName": "AC Current",
      "source": "Measured",
      "unit": "A",
      "aggregations": [
        {
          "shortName": "A_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "A_max",
          "aggregation": "max"
        },
        {
          "shortName": "A_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "Hz",
      "longName": "AC Frequency",
      "source": "Measured",
      "unit": "Hz",
      "aggregations": [
        {
          "shortName": "Hz_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "Hz_max",
          "aggregation": "max"
        },
        {
          "shortName": "Hz_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "PF",
      "longName": "AC Power Factor",
      "source": "Measured",
      "unit": "",
      "aggregations": [
        {
          "shortName": "PF_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "PF_max",
          "aggregation": "max"
        },
        {
          "shortName": "PF_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "PI_m",
      "longName": "Performance Index",
      "source": "Modeled",
      "unit": "",
      "fieldParameters": [
        {
          "param": "modelType",
          "values": [
            "simple"
          ]
        },
        {
          "param": "irradianceSource",
          "values": [
            "weatherStation"
          ]
        },
        {
          "param": "inverterClipping",
          "values": [
            "true",
            "false"
          ]
        }
      ],
      "granularities": [
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "PPV",
      "longName": "AC Voltage L-L",
      "source": "Measured",
      "unit": "V",
      "aggregations": [
        {
          "shortName": "PPV_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "PPV_max",
          "aggregation": "max"
        },
        {
          "shortName": "PPV_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "PhV",
      "longName": "AC Voltage L-N",
      "source": "Measured",
      "unit": "V",
      "aggregations": [
        {
          "shortName": "PhV_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "PhV_max",
          "aggregation": "max"
        },
        {
          "shortName": "PhV_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "VA",
      "longName": "AC Apparent Power",
      "source": "Measured",
      "unit": "VA",
      "aggregations": [
        {
          "shortName": "VA_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "VA_max",
          "aggregation": "max"
        },
        {
          "shortName": "VA_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "VAR",
      "longName": "AC Reactive Power",
      "source": "Measured",
      "unit": "VAR",
      "aggregations": [
        {
          "shortName": "VAR_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "VAR_max",
          "aggregation": "max"
        },
        {
          "shortName": "VAR_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "W",
      "longName": "AC Power",
      "source": "Measured",
      "unit": "W",
      "aggregations": [
        {
          "shortName": "W_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "W_max",
          "aggregation": "max"
        },
        {
          "shortName": "W_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "W_m",
      "longName": "AC Power",
      "source": "Modeled",
      "unit": "W",
      "fieldParameters": [
        {
          "param": "modelType",
          "values": [
            "simple"
          ]
        },
        {
          "param": "irradianceSource",
          "values": [
            "weatherStation"
          ]
        },
        {
          "param": "inverterClipping",
          "values": [
            "true",
            "false"
          ]
        }
      ],
      "granularities": [
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "Wh",
      "longName": "AC Energy",
      "source": "Measured",
      "unit": "Wh",
      "aggregations": [
        {
          "shortName": "Wh_sum",
          "aggregation": "sum"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "Wh_m",
      "longName": "AC Energy",
      "source": "Modeled",
      "unit": "Wh",
      "fieldParameters": [
        {
          "param": "modelType",
          "values": [
            "simple"
          ]
        },
        {
          "param": "irradianceSource",
          "values": [
            "weatherStation"
          ]
        },
        {
          "param": "inverterClipping",
          "values": [
            "true",
            "false"
          ]
        }
      ],
      "granularities": [
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "WphA",
      "longName": "AC Power A",
      "source": "Measured",
      "unit": "W",
      "aggregations": [
        {
          "shortName": "WphA_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "WphA_max",
          "aggregation": "max"
        },
        {
          "shortName": "WphA_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "WphB",
      "longName": "AC Power B",
      "source": "Measured",
      "unit": "W",
      "aggregations": [
        {
          "shortName": "WphB_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "WphB_max",
          "aggregation": "max"
        },
        {
          "shortName": "WphB_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    },
    {
      "baseField": "WphC",
      "longName": "AC Power C",
      "source": "Measured",
      "unit": "W",
      "aggregations": [
        {
          "shortName": "WphC_avg",
          "aggregation": "avg"
        },
        {
          "shortName": "WphC_max",
          "aggregation": "max"
        },
        {
          "shortName": "WphC_min",
          "aggregation": "min"
        }
      ],
      "granularities": [
        "latest",
        "1min",
        "5min",
        "15min",
        "hourly",
        "daily",
        "monthly",
        "yearly"
      ]
    }
  ]
}

This endpoint retrieves a list of available data types for a component.

Definition

GET /v3/components/{componentId}/dataavailable

Arguments

Argument	Description	Required?	Default
componentId	Unique identifier for the component	yes

Returns

Returns an array of base field objects.

Get data available for site

Example request:

GET https://api.locusenergy.com/v3/sites/123/dataavailable HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/dataavailable
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "baseFields": [
        {
            "baseField": "GHI_m",
            "longName": "VI - Irradiance Global Horizontal",
            "source": "Modeled",
            "unit": "W/m²",
            "aggregations": [
                {
                    "shortName": "GHI_m_avg",
                    "aggregation": "avg"
                },
                {
                    "shortName": "GHI_m_max",
                    "aggregation": "max"
                },
                {
                    "shortName": "GHI_m_min",
                    "aggregation": "min"
                }
            ],
            "granularities": [
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "GHIh_m",
            "longName": "VI - Insolation Global Horizontal",
            "source": "Modeled",
            "unit": "Wh/m²",
            "aggregations": [
                {
                    "shortName": "GHIh_m_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "W",
            "longName": "AC Power",
            "source": "Measured",
            "unit": "W",
            "aggregations": [
                {
                    "shortName": "W_avg",
                    "aggregation": "avg"
                },
                {
                    "shortName": "W_max",
                    "aggregation": "max"
                }
            ],
            "granularities": [
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "W_m",
            "longName": "AC Power",
            "source": "Modeled",
            "unit": "W",
            "aggregations": [
                {
                    "shortName": "W_m_avg",
                    "aggregation": "avg"
                }
            ],
            "fieldParameters": [
                {
                    "param": "modelType",
                    "values": [
                        "simple"
                    ]
                },
                {
                    "param": "irradianceSource",
                    "values": [
                        "weatherStation"
                    ]
                },
                {
                    "param": "inverterClipping",
                    "values": [
                        "true",
                        "false"
                    ]
                }
            ],
            "granularities": [
                "1min",
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "Wh",
            "longName": "AC Energy",
            "source": "Measured",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "Wh_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "1min",
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "Wh_e",
            "longName": "AC Energy",
            "source": "Expected",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "Wh_e_sum",
                    "aggregation": "sum"
                }
            ],
            "granularities": [
                "daily",
                "monthly",
                "yearly"
            ]
        },
        {
            "baseField": "Wh_m",
            "longName": "AC Energy",
            "source": "Modeled",
            "unit": "Wh",
            "aggregations": [
                {
                    "shortName": "Wh_m_sum",
                    "aggregation": "sum"
                }
            ],
            "fieldParameters": [
                {
                    "param": "modelType",
                    "values": [
                        "simple"
                    ]
                },
                {
                    "param": "irradianceSource",
                    "values": [
                        "weatherStation"
                    ]
                },
                {
                    "param": "inverterClipping",
                    "values": [
                        "true",
                        "false"
                    ]
                }
            ],
            "granularities": [
                "1min",
                "5min",
                "15min",
                "hourly",
                "daily",
                "monthly",
                "yearly"
            ]
        }
    ]
}

This endpoint retrieves a list of available data types for a site.

Definition

GET /v3/sites/{siteId}/dataavailable

Arguments

Argument	Description	Required?	Default
siteId	Unique identifier for the site	yes

Returns

Returns an array of base field objects.

Get bulk dataavailable

Example request:

GET https://api.locusenergy.com/v3/partners/111/sites/dataavailable HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/111/sites/dataavailable
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "baseFields": [
    {
      "baseField": "Wh",
      "longName": "AC Energy",
      "source": "Measured",
      "unit": "Wh",
      "aggregations": [
        {
          "shortName": "Wh_sum",
          "aggregation": "sum"
        }
      ],
      "granularities": [
        "monthly"
      ]
    },
    {
      "baseField": "Whp",
      "longName": "AC Energy (prorated)",
      "source": "Measured",
      "unit": "Wh",
      "aggregations": [
        {
          "shortName": "Whp_sum",
          "aggregation": "sum"
        }
      ],
      "granularities": [
        "monthly"
      ]
    },
    {
      "baseField": "Wh_e",
      "longName": "AC Energy",
      "source": "Expected",
      "unit": "Wh",
      "aggregations": [
        {
          "shortName": "Wh_e_sum",
          "aggregation": "sum"
        }
      ],
      "granularities": [
        "monthly"
      ]
    },
    {
      "baseField": "GHIh_m",
      "longName": "VI - Insolation Global Horizontal",
      "source": "Modeled",
      "unit": "Wh/m²",
      "aggregations": [
        {
          "shortName": "GHIh_m_sum",
          "aggregation": "sum"
        }
      ],
      "granularities": [
        "monthly"
      ]
    },
    {
      "baseField": "GHIhp_m",
      "longName": "VI - Insolation Global Horizontal (prorated)",
      "source": "Modeled",
      "unit": "Wh/m²",
      "aggregations": [
        {
          "shortName": "GHIhp_m_sum",
          "aggregation": "sum"
        }
      ],
      "granularities": [
        "monthly"
      ]
    },
    {
      "baseField": "GHIh_t",
      "longName": "Insolation Global Horizontal",
      "source": "Expected",
      "unit": "Wh/m²",
      "aggregations": [
        {
          "shortName": "GHIh_t_sum",
          "aggregation": "sum"
        }
      ],
      "granularities": [
        "monthly"
      ]
    },
    {
      "baseField": "EER",
      "longName": "Energy Expectations Ratio",
      "source": "Modeled",
      "unit": "",
      "aggregations": [
        {
          "shortName": "EER_avg",
          "aggregation": "avg"
        }
      ],
      "granularities": [
        "monthly"
      ]
    },
    {
      "baseField": "GEER",
      "longName": "GHI-adjusted Energy Expectations Ratio",
      "source": "Modeled",
      "unit": "",
      "aggregations": [
        {
          "shortName": "GEER_avg",
          "aggregation": "avg"
        }
      ],
      "granularities": [
        "monthly"
      ]
    }
  ]
}

This endpoint retrieves a list of available data types when doing a bulk data request.

Definition

GET /v3/partners/{partnerId}/sites/dataavailable

Arguments

Argument	Description	Required?	Default
partnerId	Unique identifier for the partner	yes

Returns

Returns an array of base field objects.

Data

Overview

Timeseries data calls return interval, rather than accumulated values for the granularity chosen. For example, if you ask for energy from 2013-01-01T00:00:00 to 2014-01-01T00:00:00 at yearly granularity, you would receive the energy measured only during the calendar year of 2013. Timestamps in responses of data calls represent the beginning of that time interval. This is also known as a “leading” timestamp. The interval includes data up until just before the following timestamp in the data response. Using the same yearly example as above, the timestamp for data received would be 2013-01-01T00:00:00 and would include all energy where the timestamp is >= 2013-01-01T00:00:00 and < 2014-01-01T00:00:00.

For all data calls, the time period allowed depends upon the granularity chosen.

• latest: not applicable
• 1min: < 5 days
• 5min: < 31 days
• 15min: < 31 days
• hourly: < 31 days
• daily: < 1 year
• monthly: no limitations
• yearly: no limitations

Field Parameters

Field parameters describe additional query parameters that need to be provided in a data call in order to function properly. For example, in order to make a request for Modeled AC Power, the data request must use the field parameters provided in the dataavailable response. Based on the field parameters returned, an example data call could be: GET /data?fields=W_m_avg&start=2015-08-01T00:00:00&end=2015-08-02T00:00:00&tz=US/Pacific&gran=5min&modelType=singleDiode&irradianceSource=TMY&inverterClipping=true.

Depending upon the entity, available field parameters are explained below. All options for the field parameters are dictated by the results of the dataavailable call.

• modelType: there are two possible options for modelType – singleDiode and simple. The single diode model is a PV model that represents the physics of a PV cell. A detailed explanation can be found here. The simple model is based on PVWatts which is best explained here.
• irradianceSource: possible irradiance sources include TMY3 and weatherStation. TMY3 data is taken from the nearest TMY3 station to the geolocated address of the entity being modeled. Weather station data is obtained from a weather station in the site hierarchy in SolarNOC.
• inverterClipping: boolean toggle to determine whether the PV model should clip at the inverter maximum output power.

Data object

{
  "id": 123,
  "ts": "2014-04-01T12:00:00-07:00",
  "W_avg": 23.717,
  "Wh_sum": 5936
}

Attributes

Attribute	Type	Description	Always returned?
id	Integer	Corresponds to the entity ID for which this data was requested	yes
ts	String (YYYY-MM-DDThh:mm:ssZ)	Datetimestamp for this data point	yes

For each data object, any non-null data is returned with the field name. In this example, W_avg and Wh_sum were requested.

Get data for component

Example request:

GET https://api.locusenergy.com/v3/components/123/data?fields=W_avg,Wh_sum&start=2014-04-01T12:00:00&end=2014-04-01T13:00:00&tz=US/Pacific&gran=hourly HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/123/data?fields=W_avg,Wh_sum&start=2014-04-01T12:00:00&end=2014-04-01T13:00:00&tz=US/Pacific&gran=hourly
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "data": [
    {
      "id": 123,
      "ts": "2014-04-01T12:00:00-07:00",
      "W_avg": 23.717,
      "Wh_sum": 5936
    },
    {
      "id": 123,
      "ts": "2014-04-01T13:00:00-07:00",
      "W_avg": 10.373,
      "Wh_sum": 2372
    }
  ]
}

This endpoint retrieves data for the component, fields and time period requested.

Definition

GET /v3/components/{componentId}/data

Arguments

Argument	Description	Required?	Default
componentId	Unique identifier for the component	yes
fields	Comma-delimited list of valid shortNames	yes
start	Timestamp of start period of request	yes
end	Timestamp of end period of request	yes
tz	Timezone for data requested	yes
gran	Granularity for data requested. Options are latest, 1min, 5min, 15min, hourly, daily, monthly, yearly	yes

Note

With latest gran, start and end arguments are not used and can be excluded. Only the latest data point is returned in the response object

Returns

Returns an array of data objects.

Get data for site

Example request:

GET https://api.locusenergy.com/v3/sites/123/data?fields=W_avg,Wh_sum&start=2014-04-01T12:00:00&end=2014-04-01T13:01:00&tz=US/Pacific&gran=hourly HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/data?fields=W_avg,Wh_sum&start=2014-04-01T12:00:00&end=2014-04-01T13:01:00&tz=US/Pacific&gran=hourly
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "data": [
    {
      "id": 123,
      "ts": "2014-04-01T12:00:00-07:00",
      "W_avg": 23.717,
      "Wh_sum": 5936
    },
    {
      "id": 123,
      "ts": "2014-04-01T13:00:00-07:00",
      "W_avg": 10.373,
      "Wh_sum": 2372
    }
  ]
}

This endpoint retrieves data for the site, fields and time period requested.

Definition

GET /v3/sites/{siteId}/data

Arguments

Argument	Description	Required?	Default
siteId	Unique identifier for the site	yes
fields	Comma-delimited list of valid shortNames	yes
start	Timestamp of start period of request	yes
end	Timestamp of end period of request	yes
tz	Timezone for data requested	yes
gran	Granularity for data requested. Options are 1min, 5min, 15min, hourly, daily, monthly, yearly	yes

Returns

Returns an array of data objects.

Get bulk data for all sites

Example request:

GET https://api.locusenergy.com/v3/partners/111/sites/data?start=2014-04-01T00:00:00&end=2014-05-01T01:00:00&tz=US/Pacific&gran=monthly&fields=Wh_sum HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/111/sites/data?start=2014-04-01T00:00:00&end=2014-05-01T01:00:00&tz=US/Pacific&gran=monthly&fields=Wh_sum
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
  "statusCode": 200,
  "data": [
    {
      "id": 123,
      "ts": "2014-04-01T12:00:00-07:00",
      "Wh_sum": 5936
    },
    {
      "id": 123,
      "ts": "2014-05-01T13:00:00-07:00",
      "Wh_sum": 2372
    },
    {
      "id": 456,
      "ts": "2014-04-01T12:00:00-07:00",
      "Wh_sum": 21324
    },
    {
      "id": 456,
      "ts": "2014-05-01T13:00:00-07:00",
      "Wh_sum": 25234
    }
  ]
}

Bulk data allows users to obtain data for all sites with one API request. The advantages / differences with the data API are:

• Grab data for all sites in one call
• Site data only
• Monthly granularity only
• 1 year max data for a single call
• Limited number of supported fields

Definition

GET /v3/partners/{partnerId}/sites/data

Arguments

Argument	Description	Required?	Default
partnerId	Unique identifier for the partner	yes
fields	Comma-delimited list of valid shortNames	yes
start	Timestamp of start period of request	yes
end	Timestamp of end period of request. end can be a maximum of 1 year after start	yes
tz	Timezone for data requested	yes
gran	Granularity for data requested. Only valid option is monthly	yes

Returns

Returns an array of data objects.

Additional Notes

Prorating

In the Locus platform, a prorated value is defined as a value that is scaled based on time. When a site Startup Date is set, then prorated fields will return only the data on and after this date and nothing before it (see the SolarOS Support tab on how to configure a Startup Date). In the case of a Startup Date in the middle of the month, a partial value is returned for the month corresponding to the remaining monthly data on and after the Startup Date.

When a Startup Date is not set, then all energy (Wh_sum) values are returned; however, other fields will return data only for months on and after the time of the first measured energy value. Only whole month data values are returned (i.e. partial months are not returned based on the first day of energy).

Each field if prorated as follows:

• Wh_sum: Not prorated.
• Whp_sum: Prorated based on startup date.
• Wh_e_sum: Prorated based on startup date and the current date. If the startup date doesn’t exist, then the entire month and subsequent months are only returned for when the site first had a measured energy value. If there is no meter data or startup date then nothing is returned.
• GHIh_t_sum: Prorated based on startup date and the current date. If the startup date doesn’t exist, then the entire month and subsequent months are only returned for when the site first had a measured energy value. If there is no meter data or startup date then nothing is returned.
• EER_avg: All the prorating happens in the other fields.
• GHIh_m_sum: Not prorated based on startup date, but the entire month and subsequent months are only returned for when the site first had a measured energy value. If there is no meter data then nothing is returned.
• GHIhp_m_sum: Prorated based on startup date. If the startup date doesn’t exist, then the entire month and subsequent months are only returned for when the site first had a measured energy value. If there is no meter data or startup date then nothing is returned.
• GEER_avg: All the prorating happens in the other fields.

Timestamp Conventions

Just as with the data request, all timestamps returned are associated with the first timestamp of the granular period (1st day of the month at T00:00:00 for monthly granularity) and are >= start and < end. For example:

• start = 2015-03-15T00:00:00 and end = 2015-05-02T00:00:00 returns the following months:
  • 2015-04-01T00:00:00
  • 2015-05-01T00:00:00
• start = 2015-03-01T00:00:00 and end = 2015-05-01T00:00:00 returns the following months:
  • 2015-03-01T00:00:00
  • 2015-04-01T00:00:00

Null Values for Sites Without Certain Data Fields

With individual data requests, a thorough data available check is performed to make sure that the user isn’t being guided to ask for data that doesn’t exist for a given entity; however, for the Bulk Data API on the partner level, this check is complex. There will be cases where some sites would return no data or even an error for a given shortName when the data is fetched directly via the Data API. In these cases the Bulk Data API will return a null value for the shortName in question. For example, if a given site does not have a valid address it cannot be geolocated, and hence it cannot have a GHIh_t_sum. In this case the Data API would throw and error; however, the Bulk Data API will return a null value for this field.

Note: A site without any components will not return a data object.

Alerts

Overview

Alerts provide notifications for certain issues the can occur to a given component. Types of alerts include:

• System Disconnect: the device has not communicated with the server for a certain period of time
• Zero Generation: the device has not generated energy for a certain period of time when it was expected that it should be generating
• Performance Yield: measured performance is a certain threshold less than modeled performance
• Device Fault: the device has sent a message to indicate its status

Filters

Alerts can be filtered through the query parameters.

• updatedSince: allows you to get a list of alerts that have been updated since a certain timestamp. This is particularly useful for use cases where you would like to sync alerts into another platform, such as a ticketing system. By specifying updatedSince to the time of the last API call, you are getting only the new status changes of the alerts.
• openDuringMin and openDuringMax: “open during” is a concept that means the alert is open at any point within the given time period. The time period is defined between the openDuringMin and openDuringMax query parameters.
• alertType: valid types are Device Fault, Performance Index, Strings Performance, System Disconnect, and Zero Generation. You can provide one or more of these alert types as a comma-separated list to alertType. If no alertType is not provided, it defaults to all types.
• status: valid statuses are open and closed. open alerts have not yet closed. closed alerts are no longer open. If no status is provided, it defaults to all statuses.
• priority: valid priorities are high, medium, and low. One or more of these priorities can be provided as a comma-separated list. If no priority is provided, it defaults to all priorities.

Alert object

{
    "id": 78,
    "componentId": 90,
    "componentName": "Test Inverter",
    "siteId": 99,
    "siteName": "Test Site",
    "alertType": "Device Fault",
    "priority": "Medium",
    "start": "2015-11-01T12:00:00-00:00",
    "end": "2015-11-22T15:00:00-00:00",
    "updated": "2015-11-24T12:05:00-00:00",
    "descriptionShort": "VDC high",
    "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
}

Attributes

Attribute	Type	Description	Always returned?
id	Integer	The unique identifier for the alert	yes
componentId	Integer	The unique identifier for the component that has the alert	yes
componentName	String	The name of the component that has the alert	yes
siteId	Integer	The unique identifier for the site that the component belongs to	yes
siteName	String	The name of the site	yes
alertType	String	The type of alert. Valid types are: Device Fault, Performance Index, Strings Performance, System Disconnect, and Zero Generation	yes
priority	String	Priority of the alert. Valid priorities are: High, Medium and Low	yes
start	String (YYYY-MM-DDThh:mm:ssZ)	Start time of the alert. This should be in the timezone specified by the tz query param of the request.	yes
end	String (YYYY-MM-DDThh:mm:ssZ)	End time of the alert. This should be in the timezone specified by the tz query param of the request.	no
updated	String (YYYY-MM-DDThh:mm:ssZ)	Time when the alert was last updated. This should be in the timezone specified by the tz query param of the request.	yes
descriptionShort	String	A short description of the alert. This only appears for device faults.	no
descriptionLong	String	A longer, more verbose description of the alert. This only appears for device faults, and does not always appear for all device faults.	no

Get alerts for partner

Example updatedSince request (assume the current time is 2015-11-26T00:00:00):

GET https://api.locusenergy.com/v3/partners/123/alerts?updatedSince=2015-11-20T00:00:00&tz=UTC HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/123/alerts?updatedSince=2015-11-20T00:00:00&tz=UTC
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 456,
            "componentName": "Test Inverter 1",
            "siteId": 99,
            "siteName": "Test Site",
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T12:00:00-00:00",
            "updated": "2015-11-22T12:03:00-00:00"
        },
        {
            "id": 78,
            "componentId": 90,
            "componentName": "Test Inverter 2",
            "siteId": 99,
            "siteName": "Test Site",
            "alertType": "Device Fault",
            "priority": "Medium",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T15:00:00-00:00",
            "updated": "2015-11-24T12:05:00-00:00",
            "descriptionShort": "VDC high",
            "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
        }
    ]
}

Example openDuring request:

GET https://api.locusenergy.com/v3/partners/123/alerts?openDuringMin=2015-09-01T00:00:00&openDuringMax=2015-10-01T00:00:00&tz=US/Pacific HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/partners/123/alerts?openDuringMin=2015-09-01T00:00:00&openDuringMax=2015-10-01T00:00:00&tz=US/Pacific
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 456,
            "componentName": "Test Inverter 1",
            "siteId": 99,
            "siteName": "Test Site",
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2015-09-01T12:00:00-07:00",
            "end": "2015-09-02T12:00:00-07:00",
            "updated": "2015-09-02T12:00:00-07:00"
        },
        {
            "id": 78,
            "componentId": 90,
            "componentName": "Test Inverter 2",
            "siteId": 99,
            "siteName": "Test Site",
            "alertType": "Device Fault",
            "priority": "Medium",
            "start": "2015-09-01T12:00:00-07:00",
            "end": "2015-09-02T12:00:00-07:00",
            "updated": "2015-09-02T13:00:00-07:00",
            "descriptionShort": "VDC high",
            "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
        }
    ]
}

This endpoint retrieves alerts for the partner and filter params requested.

Definition

GET /v3/partners/{partnerId}/alerts

Arguments

Either updatedSince or both openDuringMin and openDuringMax are required.

Argument	Description	Required?
partnerId	Unique identifier for the partner	yes
tz	Timezone for data requested	yes
updatedSince	Timestamp since when the alerts have been updated. Limited to up to 7 days ago. Format YYYY-MM-DDThh:mm:ss.	no
openDuringMin	Timestamp at which the open during period starts. Open during time period is limited to 31 days. Format YYYY-MM-DDThh:mm:ss.	no
openDuringMax	Timestamp at which the open during period ends. Open during time period is limited to 31 days. Format YYYY-MM-DDThh:mm:ss.	no

Returns

Returns an array of alert objects.

Get alerts for site

Example request for all alerts:

GET https://api.locusenergy.com/v3/sites/123/alerts?tz=UTC HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/alerts?tz=UTC
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 456,
            "componentName": "Test Inverter 1",
            "siteId": 123,
            "siteName": "Test Site",
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T12:00:00-00:00",
            "updated": "2015-11-22T12:03:00-00:00"
        },
        {
            "id": 78,
            "componentId": 90,
            "componentName": "Test Inverter 2",
            "siteId": 123,
            "siteName": "Test Site",
            "alertType": "Device Fault",
            "priority": "Medium",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T15:00:00-00:00",
            "updated": "2015-11-24T12:05:00-00:00",
            "descriptionShort": "VDC high",
            "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
        }
    ]
}

Example updatedSince request:

GET https://api.locusenergy.com/v3/sites/123/alerts?updatedSince=2014-11-20T00:00:00&tz=UTC HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/alerts?updatedSince=2014-11-20T00:00:00&tz=UTC
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 456,
            "componentName": "Test Inverter 1",
            "siteId": 123,
            "siteName": "Test Site",
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2014-11-01T12:00:00-00:00",
            "end": "2014-11-22T12:00:00-00:00",
            "updated": "2014-11-22T12:03:00-00:00"
        },
        {
            "id": 78,
            "componentId": 90,
            "componentName": "Test Inverter 2",
            "siteId": 123,
            "siteName": "Test Site",
            "alertType": "Device Fault",
            "priority": "Medium",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T15:00:00-00:00",
            "updated": "2015-11-24T12:05:00-00:00",
            "descriptionShort": "VDC high",
            "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
        }
    ]
}

Example openDuring request:

GET https://api.locusenergy.com/v3/sites/123/alerts?openDuringMin=2014-09-01T00:00:00&openDuringMax=2015-10-01T00:00:00&tz=US/Pacific HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/sites/123/alerts?openDuringMin=2014-09-01T00:00:00&openDuringMax=2015-10-01T00:00:00&tz=US/Pacific
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 456,
            "componentName": "Test Inverter 1",
            "siteId": 123,
            "siteName": "Test Site",
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2014-09-01T12:00:00-07:00",
            "end": "2015-09-02T12:00:00-07:00",
            "updated": "2015-09-02T12:00:00-07:00"
        },
        {
            "id": 78,
            "componentId": 90,
            "componentName": "Test Inverter 2",
            "siteId": 123,
            "siteName": "Test Site",
            "alertType": "Device Fault",
            "priority": "Medium",
            "start": "2015-09-01T12:00:00-07:00",
            "end": "2015-09-02T12:00:00-07:00",
            "updated": "2015-09-02T13:00:00-07:00",
            "descriptionShort": "VDC high",
            "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
        }
    ]
}

This endpoint retrieves alerts for the site and filter params requested.

Definition

GET /v3/sites/{siteId}/alerts

Arguments

Argument	Description	Required?
siteId	Unique identifier for the site	yes
tz	Timezone for data requested	yes
updatedSince	Timestamp since when the alerts have been updated. Format YYYY-MM-DDThh:mm:ss.	no
openDuringMin	Timestamp at which the open during period starts. Format YYYY-MM-DDThh:mm:ss.	no
openDuringMax	Timestamp at which the open during period ends. Format YYYY-MM-DDThh:mm:ss.	no

Returns

Returns an array of alert objects.

Get alerts for component

Example request for all alerts:

GET https://api.locusenergy.com/v3/components/123/alerts?tz=UTC HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/123/alerts?tz=UTC
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 123,
            "componentName": "Test Inverter",
            "siteId": 99,
            "siteName": "Test Site",
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T12:00:00-00:00",
            "updated": "2015-11-22T12:03:00-00:00"
        }
    ]
}

Example updatedSince request:

GET https://api.locusenergy.com/v3/components/90/alerts?updatedSince=2014-11-20T00:00:00&tz=UTC HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/90/alerts?updatedSince=2014-11-20T00:00:00&tz=UTC
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 78,
            "componentId": 90,
            "componentName": "Test Inverter",
            "siteId": 99,
            "siteName": "Test Site",
            "alertType": "Device Fault",
            "priority": "Medium",
            "start": "2015-11-01T12:00:00-00:00",
            "end": "2015-11-22T15:00:00-00:00",
            "updated": "2015-11-24T12:05:00-00:00",
            "descriptionShort": "VDC high",
            "descriptionLong": "A voltage higher than 2100 V is present on the DC bus. (Resettable)"
        }
    ]
}

Example openDuring request:

GET https://api.locusenergy.com/v3/components/123/alerts?openDuringMin=2014-09-01T00:00:00&openDuringMax=2015-10-01T00:00:00&tz=US/Pacific HTTP/1.1
Accept: application/json
Authorization: Bearer ACCESS_TOKEN

curl https://api.locusenergy.com/v3/components/123/alerts?openDuringMin=2014-09-01T00:00:00&openDuringMax=2015-10-01T00:00:00&tz=US/Pacific
  -X GET
  -H "Accept: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"

Example response:

{
    "statusCode": 200,
    "alerts": [
        {
            "id": 999,
            "componentId": 123,
            "componentName": "Test Inverter",
            "siteId": 99,
            "siteName": "Test Site",
            "alertType": "System Disconnect",
            "priority": "High",
            "start": "2014-09-01T12:00:00-07:00",
            "end": "2015-09-02T12:00:00-07:00",
            "updated": "2015-09-02T12:00:00-07:00"
        }
    ]
}

This endpoint retrieves alerts for the site and filter params requested.

Definition

GET /v3/components/{componentId}/alerts

Arguments

Argument	Description	Required?
componentId	Unique identifier for the component	yes
tz	Timezone for data requested	yes
updatedSince	Timestamp since when the alerts have been updated. Format YYYY-MM-DDThh:mm:ss.	no
openDuringMin	Timestamp at which the open during period starts. Format YYYY-MM-DDThh:mm:ss.	no
openDuringMax	Timestamp at which the open during period ends. Format YYYY-MM-DDThh:mm:ss.	no

Returns

Returns an array of alert objects.