Lookups

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 itdataType field has a value of LOOKUP. The endpoints defined on this page allow you to query the values in their lookup tables directly in several useful ways. We also have an endpoint that summarizes the counts, averages, and 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
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	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 Arcadia 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/{propertyKey}/lookups

Request Parameters

Name	Type	Description
propertyKey	String	Property key name
subPropertyKey	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 PropertyKey

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 a Specific Sub-keys lookup values for a PropertyKey

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

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/{propertyKey}/stats

Request Parameters

Name	Type	Description
propertyKey	String	Property key name.

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
	}]
}