Properties

Use Properties to retrieve metadata keys used by tariffs, calculations, applicability rules, and lookup-backed values.

Property keys describe inputs that can affect tariff eligibility or calculation behavior. They are frequently used to determine applicability for a set of rates within a tariff. For example, the cityLimits property is used when a tariff has different rates based on whether the customer lives inside or outside city limits.

Property keys with a dataType of LOOKUP have corresponding Lookups values that you can retrieve separately. Use Lookups after you identify a lookup-backed property key and need its date-ranged values or summary statistics.

Get Properties

Retrieve property keys by data type, family, keyspace, or entity ownership.

Get One Property

Retrieve one property key by keyName.

Lookups

Retrieve date-ranged values and summary statistics for lookup-backed property keys.

Data definitions

Property Key

The PropertyKey object 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` (Lookups), or `DEMAND`.
quantityUnit	String	E	The unit that applies to this property, such as `"kWh"`, `"Inches"`, or `"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.

See Get One Property for examples of different PropertyKey types and their associated fields.

Get Properties

Retrieve property keys and sub-property keys, such as ISO zones, that match search criteria. The result set is an array of PropertyKey objects in the standard response format.

Resource URI

GET /rest/public/properties

Request parameters

Name	Type	Description
dataType	String	Return only properties with the specified `dataType`. Optional.
family	String	Return properties in a family, such as `"billing"`, `"metering"`, or `"connection"`. Optional.
keySpace	String	Return properties in a keyspace. Possible values include `"electricity"` and `"solarPv"`. Optional.
entityId	Long	Return properties that belong to this `entityId`. Requires `entityType`; otherwise ignored. Optional.
entityType	String	Return properties that belong to this `entityType`. Requires `entityId`; otherwise 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

Specify entityType=LSE and entityId to retrieve PropertyKey objects that belong to a specific LSE. The abbreviated response below shows one matching PropertyKey.

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",
            "dataType": "INTEGER",
            "entityId": 734,
            "entityType": "LSE"
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

Example 2 - Keys for Market-Based Prices

This request returns PropertyKey objects that correspond to market-based pricing.

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

Market prices have dataType=LOOKUP and exist in the market keyspace. You can also retrieve their values with Lookups. The abbreviated response below shows one matching PropertyKey.

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

To select a specific choice from a LOOKUP PropertyKey, use Lookups and pass the desired choice as the subKeyName parameter.

Frequently changing property keys

Some PropertyKey values have many corresponding values or change frequently over time. Examples include wholesale energy price indexes that change hourly, specialty variable-rate plans with hourly pricing, and tariffs where electricity rates can vary daily.

Non-market hourly rates can be found in the tariff keyspace and hourly family. Daily rates can be found in the tariff keyspace and daily family.

Get One Property

Retrieve one property key and its sub-property keys, such as ISO zones, by keyName. This is useful when using Account Cost Calculation, because calculations may require you to specify applicability values before running the calculation.

Resource URI

GET /rest/public/properties/{keyName}

Request parameters

There are no additional query parameters. Use the keyName path parameter.

Example 3 - Choice Property Key

Some PropertyKey objects have a fixed set of possible values. These values are returned in 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 Property Key

This example shows a FORMULA property that takes the number of billing days and divides it 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 Property Key

A DEMAND type PropertyKey can contain a formula or be part of another formula. This example 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"
        }
    ]
}

You can inspect one of those PropertyKey objects to see that offPeakBillingDemand1517 is the peak 15-minute kW demand across one 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"
        }
    ]
}