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 Fields 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 Fields 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/
{
  "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
{
  "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
}