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.

Name	Type	Fields	Description
keyName	String	M	The unique name for this property.
subKeyName	String	M	Sub-property name for this property.
displayName	String	M	A string that can be used to display to users.
family	String	M	Second level of the categorization hierarchy, family groups `keyNames` together into logical areas, such as `"billing"`, `"generation"`, `"load"`, `"peakDemand"`, and `"ratchetDemand"`.
keyspace	String	M	The top level of the categorization hierarchy, keyspace defines major groups of `keyNames`, such as `"customer"`, `"electricity"`, `"market"`, “tariff”`, and "solarPV"`.
description	String	M	A user friendly detailed description of the purpose of this property.
dataType	String	M	The data type of this property. Possible values are `STRING`, `CHOICE`, `BOOLEAN`, `DATE`, `DECIMAL`, `INTEGER`, `FORMULA`, `LOOKUP` (see Lookup API), or `DEMAND`.
quantityUnit	String	E	The unit that applies to this property. e.g. `"kWh"`, `"Inches"`, `"HP"`
formulaDetail	String		For properties that specify a formula, this is the actual formula used.
lookbackIntervalQuantity	Integer	E	For properties of type `DEMAND`, this specifies the size of the interval in minutes.
lookbackQuantity	Integer	E	For properties of type `DEMAND`, this specifies the number of lookback periods.
lookbackPeriod	String	E	For properties of type `DEMAND`, this specifies the duration of a single lookback period.
lookbackTimeOfUseId	Integer	E	For properties of type `DEMAND`, this specifies the applicable timeOfUseId.
lookbackSeasonId	Integer	E	For properties of type `DEMAND`, this specifies the applicable seasonId .
entityId	Integer		The ID of the entity this property key belongs to. For example, for an LSE specific property, this will be the LSE ID. For general properties, this will be `null`.
entityType	String		The type of entity this property key belongs to. For example, for an LSE specific property this will be `"LSE"`. For general properties this will be `null`.
choices	Array of Choices		For properties of type `CHOICE` or `LOOKUP`, this contains the possible choices to choose from.

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 subproperty keys (e.g. ISO zones) if they exist, based on a 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:

Name	Type	Description
dataType	String	Filters the result set to only include properties that have the specified `dataType` (Optional)
family	String	Filters the result by the family. Examples of family include `"billing"`, `"metering"` and `"connection"`. Look at the properties to see more examples of the family (Optional).
keySpace	String	Filters the result by the key space. Possible values include `"electricity"` and `"solarPv"` (Optional)
entityId	Long	Filters the result set to only include properties that belong to this `entityId`. `entityType` must also be specified, otherwise this is ignored (Optional).
entityType	String	Filters the result set to only include properties that belong to this `entityType`. `entityId` must also be specified, otherwise this is ignored. Currently the only supported value is `"LSE"` (Optional)
excludeGlobal	Boolean	Filters the result set to only include entity specific properties.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "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).

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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
    "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

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
52
53
54
55
{
    "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "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"
        }
    ]
}