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).


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.

         "description":"Energy Star - Residential Refrigerators",
               "name":"Winter Off-Peak consumption charges",
			/* edited for length */
               "name":"Winter Off-Peak consumption charges",

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.