Use Lookups to retrieve date-ranged values for LOOKUP property keys, such as market prices and fuel cost adjustment rates.
Use Lookups to retrieve date-ranged values for LOOKUP property keys, such as market prices and fuel cost adjustment rates.
Some Property Keys have many values, values tied to date ranges, or values that change frequently. Examples include wholesale energy price indexes that change hourly and monthly retail electricity fuel cost adjustment rates.
When Arcadia tracks this kind of data, the property key uses a lookup table. You can identify lookup-backed properties because the Property Key has dataType set to LOOKUP. Use Properties first to find lookup-backed property keys, then use these endpoints to retrieve lookup table values directly or to summarize counts, averages, and durations for lookup values.
Data definitions
Lookup Value
A lookup value has the resource type PropertyLookup and the following data structure.
| Name | Type | Fields | Description |
|---|---|---|---|
| lookupId | Integer | M | The unique ID for this lookup value entry in the lookup table. |
| propertyKey | String | M | The unique name for this property this lookup belongs to. |
| subPropertyKey | String | M | Sub-property this lookup value applies to (when needed, e.g. wholesale index node or zone). |
| fromDateTime | DateTime | M | Start date and time for this value. |
| toDateTime | DateTime | M | End date and 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 Arcadia for the property key for the date range based on previous values. |
| forecastAccuracy | Decimal | M | Reserved for future use. |
Get Property Lookup Values
Retrieve lookup table values for a specific Property Key. If a date range is not specified, the request defaults to the last 72 hours.
Resource URI
GET /rest/public/properties/{keyName}/lookups
Request parameters
| Name | Type | Description |
|---|---|---|
| keyName | String | Property key name. Required. |
| subKeyName | String | Sub-property key name. Optional. |
| fromDateTime | DateTime | Start date and time. Optional. |
| toDateTime | DateTime | End date and time. Optional. |
Example 1 - Get all lookup table values for a property key
GET /rest/public/properties/hourlyPricingRealTimeERCOT/lookups
{
"status": "success",
"count": 384,
"type": "PropertyLookup",
"results": [
{
"lookupId": 19890442,
"propertyKey": "hourlyPricingDayAheadERCOT",
"subPropertyKey": "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,
"propertyKey": "hourlyPricingDayAheadERCOT",
"subPropertyKey": "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,
"propertyKey": "hourlyPricingDayAheadERCOT",
"subPropertyKey": "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 specific sub-key lookup values for a property key
GET /rest/public/properties/hourlyPricingDayAheadERCOT/lookups?subKeyName=CPS
{
"status": "success",
"count": 48,
"type": "PropertyLookup",
"results": [
{
"lookupId": 19932084,
"propertyKey": "hourlyPricingDayAheadERCOT",
"subPropertyKey": "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,
"propertyKey": "hourlyPricingDayAheadERCOT",
"subPropertyKey": "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,
"propertyKey": "hourlyPricingDayAheadERCOT",
"subPropertyKey": "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
}
Get Property Lookup Stats
Retrieve summary statistics for a lookup-backed property key. Only property keys with dataType=LOOKUP are relevant for this endpoint.
The response includes statistics such as minFromDateTime, maxToDateTime, lookupCount, meanValue, totalDuration, and lastUpdatedDate.
Resource URI
GET /rest/public/properties/{propertyKey}/stats
Request parameters
| Name | Type | Description |
|---|---|---|
| propertyKey | String | Property key name. Required. |
Example 3 - Get lookup stats
GET /rest/public/properties/hourlyPricingRealTimeERCOT/stats
{
"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
}]
}