Property Key

Property Keys are used for a vast array of metadata associated with a tariff or calcuation. They are frequently used to determine applicability for a particular set of rates within a tariff. For example, the property cityLimits is used when a tariff has different rates based on whether the consumer lives inside or outside the city limits.

Note that Property Keys with the dataType of LOOKUP have a corresponding Lookup API that you can use to access their lookup tables values.

Data Definitions

Property Key

PropertyKey has the following data structure.

See examples below of different types of PropertyKey and their associated fields

Get a List of Property Keys

This returns a list of property keys and sub-property keys (e.g. ISO zones) if they exist, based on search criteria. The result set is an array of PropertyKey objects in the standard response format.

Resource URI

GET /rest/public/properties

Request Parameters

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

EXAMPLE 1 - KEYS FOR A SPECIFIC LSE

By specifying entityType=LSE and supplying an entityId you can get an array of PropertyKey objects that belong to a specific LSE. (Note: results below are truncated to maintain reasonable length).

GET /rest/public/properties?entityType=LSE&entityId=734

{
    "status": "success",
    "count": 316,
    "type": "PropertyKey",
    "results": [
        {
            "keyName": "airflowCorrection",
            "displayName": "Airflow Correction ",
            "family": "incentiveQuantityKeys",
            "keyspace": "tariff",
            "description": "Airflow Correction Rebate, to adjust, repair, and renovate ducts, and install new filters\r\n",
            "dataType": "INTEGER",
            "entityId": 734,
            "entityType": "LSE"
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

EXAMPLE 2 - KEYS FOR MARKET-BASED PRICES

Here is an example call that returns an array of PropertyKey objects that correspond to market-based pricing.

GET /rest/public/properties?dataType=LOOKUP&keySpace=market

All of our market prices are of type LOOKUP and exist in the "market" keyspace and can also be viewed using the lookup endpoint. (Note: results below are truncated to maintain reasonable length).

{
    "status": "success",
    "count": 13,
    "type": "PropertyKey",
    "results": [
        {
            "keyName": "hourlyPricingDayAheadERCOT",
            "displayName": "Hourly Pricing Day Ahead ERCOT",
            "family": "ercot",
            "keyspace": "market",
            "description": "Hourly Pricing Day Ahead ERCOT",
            "dataType": "LOOKUP",
            "choices": [
                {
                    "displayValue": "AEN",
                    "value": "AEN",
                    "dataValue": "AEN",
                    "likelihood": null
                },
                {
                    "displayValue": "CPS",
                    "value": "CPS",
                    "dataValue": "CPS",
                    "likelihood": null
                },
                {
                    "displayValue": "HOUSTON",
                    "value": "HOUSTON",
                    "dataValue": "HOUSTON",
                    "likelihood": null
                },
                {
                    "displayValue": "LCRA",
                    "value": "LCRA",
                    "dataValue": "LCRA",
                    "likelihood": null
                },
                {
                    "displayValue": "NORTH",
                    "value": "NORTH",
                    "dataValue": "NORTH",
                    "likelihood": null
                },
                {
                    "displayValue": "RAYBN",
                    "value": "RAYBN",
                    "dataValue": "RAYBN",
                    "likelihood": null
                },
                {
                    "displayValue": "SOUTH",
                    "value": "SOUTH",
                    "dataValue": "SOUTH",
                    "likelihood": null
                },
                {
                    "displayValue": "WEST",
                    "value": "WEST",
                    "dataValue": "WEST",
                    "likelihood": null
                }
            ]
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

Often we will need to select a specific choice from a LOOKUP PropertyKey. To do this use the lookup endpoint and pass in the desired choice as a subKeyName parameter.

Frequently Changing Property Keys

Certain types of PropertyKey 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, as in the example above. Other frequently changing property keys include specialty variable rate plans with hourly pricing (e.g. ComEd BESH in Illinois) and tariffs where electricity rates can vary daily (e.g. New York). Note that other, non-market hourly rates can be found in the "tariff" keyspace and "hourly" family, while daily rates are in the "tariff" keyspace and "daily" family.

Get One Property Key

This allows you to retrieve one property key and its subproperty keys (e.g. ISO zones) if present, using its keyname. This is particularly useful when using Calculate as it may require you to specify certain applicability values prior to making the calculation.

Resource URI

GET /rest/public/properties/{keyName}

Request Parameters

There are no additional query parameters; just use the keyName.

EXAMPLE 3 - CHOICE PROPERTYKEY

Some PropertyKey objects have a choice of value, we show all the possiblities under the "choices" field.

GET /rest/public/properties/additionalPole1203

{
    "status": "success",
    "count": 1,
    "type": "PropertyKey",
    "results": [
        {
            "keyName": "additionalPole1203",
            "displayName": "Overhead Floodlighting Additional Pole",
            "family": "fixture",
            "keyspace": "electricity",
            "description": "Overhead Floodlighting Additional Pole",
            "dataType": "CHOICE",
            "entityId": 1203,
            "entityType": "LSE",
            "choices": [
                {
                    "displayValue": "25'",
                    "value": "25'",
                    "dataValue": "25'",
                    "likelihood": null
                },
                {
                    "displayValue": "30'",
                    "value": "30'",
                    "dataValue": "30'",
                    "likelihood": null
                },
                {
                    "displayValue": "35'",
                    "value": "35'",
                    "dataValue": "35'",
                    "likelihood": null
                },
                {
                    "displayValue": "40'",
                    "value": "40'",
                    "dataValue": "40'",
                    "likelihood": null
                },
                {
                    "displayValue": "45'",
                    "value": "45'",
                    "dataValue": "45'",
                    "likelihood": null
                },
                {
                    "displayValue": "None",
                    "value": "None",
                    "dataValue": "None",
                    "likelihood": null
                }
            ]
        }
    ]
}

EXAMPLE 4 - SIMPLE FORMULA PROPERTYKEY

This is a simple example of a FORMULA that takes the number of billing days and divides them by 365.

GET /rest/public/properties/billingPeriodYearFactor

{
    "status": "success",
    "count": 1,
    "type": "PropertyKey",
    "results": [
        {
            "keyName": "billingPeriodYearFactor",
            "displayName": "Billing Period Factor",
            "family": "formula",
            "keyspace": "tariff",
            "description": "Total Billing Days divided by 365",
            "dataType": "FORMULA",
            "formulaDetail": "( #billingPeriod.days  / 365.00 )"
        }
    ]
}

EXAMPLE 5 - DEMAND PROPERTYKEY

A DEMAND type PropertyKey can contain a formula or be a part of another formula. Below we have an example that adds the results from two different PropertyKey objects to return a single result

GET /rest/public/properties/billing2Demand1517?fields=ext

{
    "status": "success",
    "count": 1,
    "type": "PropertyKey",
    "results": [
        {
            "keyName": "billing2Demand1517",
            "displayName": "Total Billing Demand",
            "family": "formula",
            "keyspace": "tariff",
            "description": "Total kW metered during the billing period",
            "dataType": "DEMAND",
            "formulaDetail": "#offPeakBillingDemand1517 + #onPeakBillingDemand1517",
            "lookbackPeriod": "",
            "entityId": 1517,
            "entityType": "LSE",
            "privacy": "PUBLIC"
        }
    ]
}

We can look at one of those PropertyKey objects and see that offPeakBillingDemand1517 is the peak 15 minute kW demand across 1 billing period during the off-peak time specified by timeOfUseId 975.

GET /rest/public/properties/offPeakBillingDemand1517?fields=ext

{
    "status": "success",
    "count": 1,
    "type": "PropertyKey",
    "results": [
        {
            "keyName": "offPeakBillingDemand1517",
            "displayName": "Off-Peak Billing Demand",
            "family": "peakDemand",
            "keyspace": "tariff",
            "description": "The peak 15 minute interval during the off-peak time of use period.",
            "dataType": "DEMAND",
            "quantityUnit": "kW",
            "lookbackIntervalQuantity": 15,
            "lookbackQuantity": 1,
            "lookbackPeriod": "BILLING_PERIOD",
            "lookbackTimeOfUseId": 975,
            "entityId": 1517,
            "entityType": "LSE",
            "privacy": "PUBLIC"
        }
    ]
}