Smart Price

The Smart Price (or Price for short) endpoint return marginal pricing to electricity end users and devices. They can be used this information for behavior changes (such as displaying to a home user that prices are currently high), or for automation (such as scheduling the running of a major appliance).

The endpoint tells you what rates (prices) are over a given time frame, typically the next 24 to 48 hours. Price is designed for shorter term load management and customer engagement applications so don’t call it for longer periods than, say, a week. All of the changes in the price within that specified range are returned. You can ask for the changes as they occur, or get prices split into hours. We also tell you the mean and standard deviation which can help simplify display, computation and scheduling.

Note that Price is quite similar to, and a logical replacement for, the retired Tariff Rate Summary endpoint. However, Price lets you know actual marginal pricing, whereas the Tariff Rate Summary gave you a summary of rates as of a particular point. The difference really comes down to computation and smarter defaults.

Part of the reason we call this a “smart” price is because this API endpoint gives you, the Provider, some additional flexibility as to the actual tariff rate plan that is used for a call. With our help, you can set up Smart Tariffs so that you can provide a signal for any specific intended behavior, such as sparing the grid during high load times or saving you or your customers money. This can be based on an actual tariff (like the most variable rate plan available to the customers whether they are on it or not), or even a custom (not public) tariff. We have, for instance, modeled a tariff to match a DOE Energy Star connected appliance specification. Talk to us to learn more.

Data Definitions

One Price object is returned for each request. The Price object then contains an array of PriceChange objects. By default there is one for each actual change in price during the requested date range, or you can ask for prices grouped by "HOUR", "DAY", "MONTH" and "YEAR" (although anything smaller than an hour doesn’t make much practical sense).

Price

The Price object has the following data structure.

Name	Type	Description
description	String	Description of the actual or Smart Tariff
masterTariffId	Long	Unique Genability ID (primary key) for this tariff
fromDateTime	DateTime	The starting date and time for this price summary.
toDateTime	DateTime	The ending date and time for this price summary.
detailLevel	String	The level of granularity that the price is returned in. For Smart Price this is Quantity Key.
currency	String	The ISO currency code for which the prices are returned (e.g. USD).
rateMean	Decimal	The mean value of the rate within the specified time period.
rateStandardDeviation	Decimal	The standard deviation of all the prices within the specified time period.
priceChanges	Array of PriceChange	An array containing details of all of the price changes within the specified time period.

Price Change

The PriceChange object has the following data structure.

Name	Type	Description
name	String	Name of this change. Usually something like the time of use period. For display purposes.
fromDateTime	DateTime	Date and Time when this change begins.
toDateTime	DateTime	Date and Time when this change ends.
rateAmount	Decimal	The actual charge amount for this price change
rateMeanDelta	Decimal	The mean delta of this price change compared to the overall mean across all price changes. Good for understanding if this is a high or low price relative to the rest of the period.

Here’s an example in JSON of a fully populated Price response containing price changes for our DOE Energy Star Smart Tariff for the next 48 hours.

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
{
   "status":"success",
   "count":1,
   "type":"Price",
   "results":[
      {
         "description":"Energy Star - Residential Refrigerators",
         "masterTariffId":3156186,
         "fromDateTime":"2013-02-15T18:04:16+00:00",
         "toDateTime":"2013-02-18T18:04:16+00:00",
         "detailLevel":"QUANTITY_KEY",
         "currency":"USD",
         "rateMean":0.083300,
         "rateStandardDeviation":0.039975,
         "priceChanges":[
            {
               "name":"Winter Off-Peak consumption charges",
               "fromDateTime":"2013-02-15T18:04:16+00:00",
               "toDateTime":"2013-02-16T06:00:00+00:00",
               "rateAmount":0.071400,
               "rateMeanDelta":-0.011900
            },
            
			/* edited for length */
			
            {
               "name":"Winter Off-Peak consumption charges",
               "fromDateTime":"2013-02-18T10:00:00+00:00",
               "toDateTime":"2013-02-18T18:04:16+00:00",
               "rateAmount":0.071400,
               "rateMeanDelta":-0.011900
            }
         ]
      }
   ]
}

Get the Smart Price

This returns the smart price for a given location, or a given tariff. Using the location or tariff we determine what you the provider have configured in terms of smart tariff rules, and use that to find the applicable smart tariff to send the price signal for.

Resource URI

GET /rest/v1/prices/smart

Request Parameters

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

Name	Type	Description
fromDateTime	DateTime	Start date and time to get prices for. (Optional, Defaults to `"now"`.)
toDateTime	DateTime	End date and time to get prices for. (Optional, Defaults to `fromDateTime` plus 3 days.)
masterTariffId	Long	You can use this rather than a location (`addressString` or `zipCode`) and customer class. We will use the tariffs information to return its price, or in the case of a smart price request, its applicable Smart Tariffs price (Optional)
zipCode or postCode	String	Recommended way to pass a location. Make sure it’s just the ZIP code or post code though. (Optional)
country	String	Use when passing in a `postCode` or `zipCode`. Set to the ISO Country Code you require (Optional)
addressString	String	An alternate to using `postCode` or `zipCode` and can be an address of any kind. Ideally this will contain a ZIP code or post code. (Optional)
customerClass	String	Denotes the type of customer and is used to determine the appropriate tariff or smart tariff. (Optional) Defaults to `"RESIDENTIAL"`
endUse	String - actual values from PropertyKey	Primarily used for smart tariffs. You can use this denote what end use (e.g. appliance, EV, whole home, thermostat etc) the price signal is for. (Optional). You can get the actual values that you can pass in from the property keys `residentialEndUse` and `commercialEndUse`
groupBy	String	Use to specify the intervals you want the price changes back in. (Optional) When not passed in you get a change record for each actual change in price. Passing in `"HOUR"` will give hourly prices, even if the price doesn’t change.
territoryId	Long	Rarely needed. This is the for when a tariff has different rates for different territories (so its not for a utility companies service area territory). Only needed when you want to override the default territory. (Optional)
consumptionAmount	Decimal	A monthly consumption in kWh. This is used for banded consumption to determine which pricing to use for the request. By default, the rate amount calculation assumes the highest banded level of consumption. (Optional)
demandAmount	Decimal	A monthly demand in kW. This is used for banded demand to determine which pricing to use for the request. By default, the rate amount calculation assumes the highest banded level of demand. (Optional)

Example 1

GET /rest/v1/prices/smart?masterTariffId=522

This is the most common way to call the endpoint. To find the masterTariffId that is appropriate for your customer, see the Which Tariff? Tutorial.

Example 2

GET /rest/v1/prices/smart?zipCode=94105

The results that come back look just like the JSON above. Note that for smart tariffs, the description and the masterTariffId that are returned are for the smart tariff that was used. If you are passing in a masterTariffId in the request (which really means you are asking for the smart tariff for a customer who is on a particular tariff), then the masterTariffId returned might be different.