Lookup
- signal
- explorer
Certain types of Property Key have a large set of corresponding values and/or values that change frequently over time. Examples of these are property keys that hold wholesale energy price indexes that change hourly, or for monthly retail electricity fuel cost adjustment rates. In some cases electricity rates can vary daily (New York) or even hourly (specialty variable rate plans). Whenever we need to track data that can have a large number of values, or values tied to a date range, or values that update at least monthly, we usually use a special type of Property Key that we call a “Lookup”. These Property Keys include a lookup table to hold their values (hence the name). You can tell when a Property Key has a lookup table attached because its dataType field has a value of LOOKUP. The endpoints defined in this page allow you to query the values in their lookup tables directly in a number of useful ways. We also have an endpoint that summarizes the counts, averages, durations of the lookup values.
Data Definitions
Lookup Value
A lookup value (resource type PropertyLookup) has the following data structure.
| Name | Type | Fields | Description |
|---|---|---|---|
| lookupId | Integer | M | The unique ID for this lookup value entry in the lookup table |
| keyName | String | M | The unique name for this property this lookup belongs to. |
| subKeyName | String | M | sub-property this lookup value applies to (when needed, e.g. wholesale index node or zone) |
| fromDateTime | DateTime | M | Date Range - from date time for this value |
| toDateTime | DateTime | M | Date Range - to date time for this value |
| bestValue | Decimal | M | Best kWh/kW price for the property key for the date range |
| bestAccuracy | Decimal | M | Reserved for future use |
| actualValue | Decimal | M | Actual kWh/kW price for the property key for the date range |
| lseForecastValue | Decimal | M | kWh/kW price forecasted by the utility for the property key for the date range |
| lseForecastAccuracy | Decimal | M | Reserved for future use |
| forecastValue | Decimal | M | kWh/kW price forecasted by Genability for the property key for the date range based on previous Values |
| forecastAccuracy | Decimal | M | Reserved for future use |
Get Property Lookup Values
Use the following call to get the lookup table values for a specific Property Key. If a date range is not specified, it is defaulted to last 72 hours.
Resource URI
GET /rest/public/properties/{keyName}/lookups
Request Parameters
| Name | Type | Description |
|---|---|---|
| keyName | String | Property key name (Required) |
| subKeyName | String | Subproperty Key Name (Optional). |
| fromDateTime | DateTime | Date range - from value (Optional). |
| toDateTime | DateTime | Date range - to value (Optional) |
Example 1 - Get All Lookup Table Values for a Property Key
GET /rest/public/properties/hourlyPricingRealTimeERCOT/lookups
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
{
"status": "success",
"count": 384,
"type": "PropertyLookup",
"results": [
{
"lookupId": 19890442,
"keyName": "hourlyPricingDayAheadERCOT",
"subKeyName": "AEN",
"fromDateTime": "2017-11-04T00:00:00",
"toDateTime": "2017-11-04T01:00:00",
"bestValue": 0.01783,
"bestAccuracy": 0,
"actualValue": 0.01783,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": null,
"forecastAccuracy": null
},
{
"lookupId": 19932102,
"keyName": "hourlyPricingDayAheadERCOT",
"subKeyName": "CPS",
"fromDateTime": "2017-11-06T18:00:00",
"toDateTime": "2017-11-06T19:00:00",
"bestValue": 0.04826,
"bestAccuracy": 0,
"actualValue": 0.04826,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": null,
"forecastAccuracy": null
},
{
"lookupId": 19932109,
"keyName": "hourlyPricingDayAheadERCOT",
"subKeyName": "HOUSTON",
"fromDateTime": "2017-11-06T01:00:00",
"toDateTime": "2017-11-06T02:00:00",
"bestValue": 0.01946,
"bestAccuracy": 0,
"actualValue": 0.01946,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": null,
"forecastAccuracy": null
}
],
"pageCount": 25,
"pageStart": 0
}
Example 2 - Get a Specific Sub-keys lookup values for a Property Key Name
GET /rest/public/properties/hourlyPricingDayAheadERCOT/lookups?subKeyName=CPS
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
{
"status": "success",
"count": 48,
"type": "PropertyLookup",
"results": [
{
"lookupId": 19932084,
"keyName": "hourlyPricingDayAheadERCOT",
"subKeyName": "CPS",
"fromDateTime": "2017-11-06T00:00:00",
"toDateTime": "2017-11-06T01:00:00",
"bestValue": 0.01799,
"bestAccuracy": 0,
"actualValue": 0.01799,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": null,
"forecastAccuracy": null
},
{
"lookupId": 19932085,
"keyName": "hourlyPricingDayAheadERCOT",
"subKeyName": "CPS",
"fromDateTime": "2017-11-06T01:00:00",
"toDateTime": "2017-11-06T02:00:00",
"bestValue": 0.01777,
"bestAccuracy": 0,
"actualValue": 0.01777,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": null,
"forecastAccuracy": null
},
{
"lookupId": 19932086,
"keyName": "hourlyPricingDayAheadERCOT",
"subKeyName": "CPS",
"fromDateTime": "2017-11-06T02:00:00",
"toDateTime": "2017-11-06T03:00:00",
"bestValue": 0.0176,
"bestAccuracy": 0,
"actualValue": 0.0176,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": null,
"forecastAccuracy": null
}
],
"pageCount": 25,
"pageStart": 0
}
(Deprecated) Get Lookup Values
Deprecated: Please use Get Property Lookup Values instead. These endpoints are functionally equivalent.
If no fromDateTime and toDateTime is provided, the result set will be limited to property lookups effective in the last 72 hours.
Resource URI
Deprecated: Please use Get Property Lookup Values instead. These endpoints are functionally equivalent.
GET /rest/public/properties/lookups
Request Parameters
| Name | Type | Description |
|---|---|---|
| keyName | String | Property key name (Required). |
| subKeyName | String | Subproperty key name (Optional). |
| fromDateTime | DateTime | Date range - from value (Optional). |
| toDateTime | DateTime | Date range - to value (Optional) |
Example 3 - Get All Lookups
Deprecated: Please use Get Property Lookup Values instead. These endpoints are functionally equivalent.
GET /rest/public/properties/lookups
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
{
"lookupId": 7808815,
"propertyKey": "2007SantaFeCountyUndergroundProjectsRiderSC3a3b",
"fromDateTime": "2017-02-25T00:00:00",
"toDateTime": "2018-02-25T00:00:00",
"bestValue": 0,
"bestAccuracy": null,
"actualValue": null,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": 0,
"forecastAccuracy": null
},
{
"lookupId": 7808816,
"propertyKey": "2007SantaFeCountyUndergroundProjectsRiderSC4B",
"fromDateTime": "2017-02-25T00:00:00",
"toDateTime": "2018-02-25T00:00:00",
"bestValue": 0,
"bestAccuracy": null,
"actualValue": null,
"lseForecastValue": null,
"lseForecastAccuracy": null,
"forecastValue": 0,
"forecastAccuracy": null
},
Get Property Lookup Stats
This endpoint gives summary stats for a given property key (only LOOKUP data type property keys are relevant here). It returns statistics like minFromDateTime, maxToDateTime, lookupCount, meanValue, totalDuration, lastUpdatedDate
Resource URI
GET /rest/public/properties/{keyName}/stats
Request Parameters
| Name | Type | Description |
|---|---|---|
| keyName | String | Property key name. |
Example 4 - Get Lookup Stats
GET /rest/public/properties/hourlyPricingRealTimeERCOT/stats
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"status": "success",
"count": 1,
"type": "PropertyKey",
"results": [
{
"keyName": "hourlyPricingRealTimeERCOT",
"minFromDateTime": 1293840000000,
"maxToDateTime": 1425945600000,
"lookupCount": 1172992,
"meanValue": 0.03465241,
"totalDuration": 17596800,
"meanDuration": 15,
"missingDuration": -15395040,
"lastUpdatedDate": 1426032000000
}]
}