Savings Analysis Watch (RETIRED)

Note that this API is deprecated.

With each Savings Analysis call, Genability runs a series of real-time data quality checks to examine if properties of the result are within an expected range. The Watch API may be used to view the results of the checks.

Data Definitions

Watch Result

An individual evaluation of a WatchDefinition against a Savings Analysis call.

Name	Type	Description
savingsAnalysisId	String	The unique ID of the Savings Analysis call. This can be retrieved by viewing the Savings Analysis History.
accountSnapshot	Account	A snapshot of the account at the time the Savings Analysis call was made. This will only be populated for searches, not for calls by `accountId` and `savingsAnalysisId`.
definition	WatchDefinition	The definition of the check being run.
passed	Boolean	`true` if the value was within the expected tolerance, `false` otherwise.
resultStatus	WatchResultStatus	A more granular status of the result, given the thresholds defined for the check. Possible values are `PASSED`, `FAILED_LOW` (the value was outside normal range, but within a more generous configured threshold of “normal” for your organization), `FAILED_MODERATE` (the value was outside of the normal range), and `FAILED_CRITICAL` (the value was outside normal range by the critical threshold, and a real-time alert was be sent).
percentOutsideRange	Double	The percentage the value was outside of the nearest bound. In the case that the value was lower than the minimum bound, this value will be negative.
actualValue	String	The actual value of the property being checked. In most cases this value will be a `Double`. Genability may add checks for non-numeric values in the future.
createdDate	DateTime	The ISO-8601 timestamp of the time that the check was run.

Watch Definition

The rule that is evaluated. It tells you what property is checked, (via the watchedProperty), such as netAvoidedRate for Avoided Cost of Power. It also has parameters that define the actual check logic, including the range of expected values for that property.

Name	Type	Description
id	Long	The unique ID of the watch definition.
description	String	A description of the purpose of the check.
watchedProperty	String	The name of the property in the Savings Analysis response being checked.
watchedPropertyDisplayName	String	A more user-friendly display of the `watchedProperty`.
min	Double	The minimum value for which the value is within the expected tolerance. This may not be defined for all types of Watch definition.
max	Double	The maximum value for which the value is within the expected tolerance. This may not be defined for all types of Watch definition.
unitsPrefix	String	The appropriate units for the given value. This will be populated for units which traditionally are displayed before a value.
unitsSuffix	String	The appropriate units for the given value. This will be populated for units which traditionally are displayed after a value.

Get all Watch results for a single Savings Analysis call:

Resource URIs

GET /rest/v1/accounts/{accountId}/analyses/{savingsAnalysisId}/watch/results/
GET /rest/v1/accounts/pid/{providerAccountId}/analyses/{savingsAnalysisId}/watch/results/

Request Parameters

Along with the standard pagination parameters, sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name	Type	Description
fromDateTime	DateTime	An ISO-8601 timestamp of the earliest Watch result to retrieve. Optional, defaults to include all Watch results.
toDateTime	DateTime	An ISO-8601 timestamp of the latest Watch result to retrieve. Optional, defaults to include all Watch results.
passed	Boolean	`true` to see only passing Watch results, or `false` to see only failing Watch results. Optional, defaults to include both passing and failed watch results.
resultStatus	String	Valid statuses are `PASSED`, `FAILED_LOW`, `FAILED_MODERATE` and `FAILED_CRITICAL`. Multiple statuses may be comma-separated. Optional, defaults to all.
watchDefinitionId	Long	Watch definition ID. Multiple Watch definition IDs may be comma-separated. Optional.
watchedProperty	String	The name of the property being checked. Multiple property names may be comma-separated. Optional.
sortOn	String	Valid fields to sort by are `country`, `state`, `watchDefinitionId`, `watchedProperty`, `createdDate`, `passed`, `resultStatus`, `absolutePercentOutsideRange`, `lseId`, `lseName`, `accountId`, `accountName`. Multiple sort fields may be comma-separated. Defaults to sort by createdDate.
sortOrder	String	`ASC` or `DESC`. Comma-separate multiple sort orders to correspond to the comma-separated fields in `sortOn`. Defaults to `DESC` if `sortOn` is `createdDate`, `ASC` otherwise.

Example

GET /rest/v1/accounts/pid/api-eg-01/analyses/1111-22-333-4444/watch/results/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
{
  "status": "success",
  "count": 3,
  "type": "WatchResult",
  "results": [
    {
      "savingsAnalysisId": "1111-22-333-4444",
      "definition": {
        "id": 1,
        "description": "ACP is expected to be between a minimum and maximum value for certain states.",
        "watchedProperty": "netAvoidedRate",
        "watchedPropertyDisplayName": "ACP",
        "min": 0.05,
        "max": 0.5,
        "unitsPrefix": "",
        "unitsSuffix": " $/kWh"
      },
      "passed": true,
      "resultStatus": "PASSED",
      "percentOutsideRange": 0,
      "actualValue": 0.350744,
      "createdDate": "2016-03-16T18:10:05+00:00"
    },
    {
      "savingsAnalysisId": "1111-22-333-4444",
      "definition": {
        "id": 143,
        "description": "ACP is outside of typical range for customers served by the utility company in this area.",
        "watchedProperty": "netAvoidedRate",
        "watchedPropertyDisplayName": "ACP",
        "min": 0.176,
        "max": 0.3,
        "unitsPrefix": "",
        "unitsSuffix": " $/kWh"
      },
      "passed": false,
      "resultStatus": "FAILED_MODERATE",
      "percentOutsideRange": 16.914667,
      "actualValue": 0.350744,
      "createdDate": "2016-03-16T18:10:05+00:00"
    },
    {
      "savingsAnalysisId": "1111-22-333-4444",
      "definition": {
        "id": 220,
        "description": "Solar system is expected to offset 70% to 95% of consumption.",
        "watchedProperty": "netAvoidedKWhPctOffset",
        "watchedPropertyDisplayName": "netAvoidedKWhPctOffset",
        "min": 70,
        "max": 95,
        "unitsPrefix": "",
        "unitsSuffix": "%"
      },
      "passed": false,
      "resultStatus": "FAILED_MODERATE",
      "percentOutsideRange": -28.571429,
      "actualValue": 50,
      "createdDate": "2016-03-16T18:10:05+00:00"
    }
  ],
  "pageStart": 0,
  "pageCount": 25
}

Search for Watch results

Resource URIs

GET /rest/v1/watch/results/

Request Parameters

Along with the standard pagination parameters, sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name	Type	Description
fromDateTime	DateTime	An ISO-8601 timestamp of the earliest Watch result to retrieve. When not passed, this will default to one day before `toDateTime`.
toDateTime	DateTime	An ISO-8601 timestamp of the latest Watch result to retrieve. When not passed, this will default to the current time.
passed	Boolean	`true` to see only passing Watch results, or `false` to see only failing Watch results. Optional, defaults to all.
resultStatus	String	Valid statuses are `PASSED`, `FAILED_LOW`, `FAILED_MODERATE` and `FAILED_CRITICAL`. Multiple statuses may be comma-separated. Optional, defaults to all.
watchDefinitionId	Long	Watch definition ID. Multiple Watch definition ids may be comma-separated. Optional, defaults to all.
watchedProperty	String	The name of the property being checked. Multiple property names may be comma-separated. Optional, defaults to all.
accountId	String	The uuid of an account. Multiple account IDs may be comma-separated. Optional, defaults to all.
providerAccountId	String	The provider ID of an account. Multiple provider account IDs may be comma-separated. Optional, defaults to all.
country	String	A two-character country code. Multiple country codes may be comma separated. Optional, defaults to all.
state	String	A two-character state code. Multiple state codes may be comma-separated. Optional, defaults to all.
lseId	Long	The ID of a Load Serving Entity. Multiple LSE IDs may be comma-separated. Optional, defaults to all.
sortOn	String	Valid fields to sort by are `country`, `state`, `watchDefinitionId`, `watchedProperty`, `createdDate`, `passed`, `resultStatus`, `absolutePercentOutsideRange`, `lseId`, `lseName`, `accountId`, `accountName`. Multiple sort fields may be comma-separated. Defaults to sort by `createdDate`.
sortOrder	String	`ASC` or `DESC`. Comma-separate multiple sort orders to correspond to the comma-separated fields in `sortOn`. Defaults to `DESC` if `sortOn` is `createdDate`, `ASC` otherwise.

Example

GET /rest/v1/watch/results?fromDateTime=2016-03-21T00:00:00-07:00&toDateTime=2016-03-28T00:00:00-07:00&passed=true&watchedProperty=netAvoidedRate&state=CA,NV,AZ

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "status": "success",
  "count": 5,
  "type": "WatchResult",
  "results": [
    {
      "savingsAnalysisId": "5c0281e9-dad9-429a-b398-12680b16620e",
      "accountSnapshot": {
        "accountId": "eeaa75f9-400c-4bc3-94cb-28749faa53b6",
        "providerAccountId": "api-eg-01",
        "accountName": "Example 1 API Home",
        "customerOrgId": null,
        "customerOrgName": null,
        "address": {
          "addressString": null,
          "address1": "221 Main St",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94105",
          "country": "US"
        },
        "status": null,
        "type": null,
        "accountManager": null,
        "assignee": null,
        "contacts": null,
        "properties": {
          "lseId": {
            "keyName": "lseId",
            "displayName": "PGE",
            "description": "Pacific Gas & Electric Co",
            "dataValue": "734"
          }
        },
        "tariffs": null,
        "projects": null
      },
      "definition": {
        "id": 1,
        "description": "ACP is expected to be between a minimum and maximum value for certain states.",
        "watchedProperty": "netAvoidedRate",
        "watchedPropertyDisplayName": "Avoided Cost",
        "min": 0.05,
        "max": 0.5,
        "unitsPrefix": "",
        "unitsSuffix": " $/kWh"
      },
      "passed": true,
      "resultStatus": "PASSED",
      "percentOutsideRange": 0,
      "actualValue": 0.328459,
      "createdDate": "2016-03-23T21:58:25+00:00"
    },...
  ],
  "pageCount": 25,
  "pageStart": 0
}