Property Key

  • signal
Switch product users. Your developer documentation has moved over to the switchsolar.io website.

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