Smart Price

Overview

The Smart Price (or Price for short) endpoints return pricing signals to energy end users and devices. They can be used 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). There are 2 major flavors of price signals we provide, 1) Smart Prices and 2) Tariff Rate Prices.

  • Tariff Rate Price - this give you the price based on an actual retail tariff, such as the customers actual tariff rate plan.
  • Smart Price - this gives you lots of flexibility so that you, the Provider, can configure a price signal to meet your needs. You can set up Smart Tariffs so that you can provide a signal any specific intended behavior, such as sparing the grid 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, modelled a tariff to match a DOE Energy Star connected appliance specification.

Each 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 that, 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 computation and scheduling.

Note that Price is quite similar to the Tariff Rate Summary endpoints available in the Tariff APIs. However, Price lets you know actual marginal pricing, whereas the Tariff Rate Summary gives you a summary of rates as of a particular point. The difference really comes down to computation.

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

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. In ISO 8601 format.
toDateTime DateTime Date and Time when this change ends. In ISO 8601 format.
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.

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

Operations

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. Note that you can also use this endpoint to get the smart price for an account (if you are using accounts). To do that pass in Genability's accountId or your own providerAccountId to get the smart srice based on the account's settings.

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 Date and time of the requested start of the price. In ISO 8601 format. (Optional) Defaults to "now".
toDateTime DateTime Date and time of the requested start of the price. In ISO 8601 format. (Optional) Defaults to fromDateTime plus 3 days.
addressString String An address of any kind. Ideally this will contain a ZIP code or post code. (Optional)
zipCode or postCode String An alternate to using addressString. Make sure it's just the ZIP code or post code though. (Optional)
country String An alternate to using addressString. Use when passing in a postCode. Set to the ISO Country Code you require (Optional)
customerClass String Denotes the type of customer and is used to determine the appropriate tariff or smart tariff. (Optional) Defaults to "RESIDENTIAL"
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)
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.
accountId String Only if using accounts. The Genability ID for an account. Use this or the providerAccountId parameter. You can use accounts to store applicability values as well as usage profiles, territories and other properties that can help in deriving a very accurate price. Read more about accounts here. Note, settings in the account are used for things like tariff and consumption, but you can override them in the request (Optional)
providerAccountId String Alternative to accountId.
profileId String Only if using accounts. The Genability ID for an account's profile. Use this if you don't want to use the account's default profile. Instead of passing in consumptionAmount or demandAmount, you can pass in this profileId to use. Read more about profiles here. (Optional)
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

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.

Get the Price

This endpoint returns the actual retail price for a given location. Use this method when you don't know the actual masterTariffId of your customer, but you do know their ZIP code. We will use the location you pass in to determine the customers most likely tariff and return to you the prices for that tariff. In other words, we don't look up the smart tariff. Note that you can also use this endpoint if you are using accounts. Pass in Genability's accountId or your providerAccountId to get the price based on the account's actual tariff.

Resource URI

GET /rest/v1/prices

Request Parameters

This endpoint has the same parameters as the Smart Price endpoint

Examples

GET /rest/prices?zipCode=94105
GET /rest/prices?accountId=9f4d10b0-671d-469a-b1e8-d1619393f2da
GET /rest/prices?providerAccountId=mycustomerId123

Note that when you have a masterTariffId you usually use the Get Price of a Specific Tariff endpoint below, but you can actually pass it into this endpoint as a query string.

Get the Price of a Specific Tariff

This returns the price for the specific tariff requested. In other words it is not switched out for the smart tariff. Use this method when you what to understand pricing for a particular retail tariff and you know its masterTariffId.

Resource URI

GET /rest/v1/prices/{masterTariffId}

Request Parameters

Along with the standard pagination parameters, and the required security parameters, all the parameters noted above are available for this endpoint too.

Example - Get hourly Pricing for a given tariff for a customer who typically uses 1,100 kWh per month

GET /rest/prices/522?consumptionAmount=1100&groupBy=HOUR

Note that the masterTariffId is not needed on the query string because we get it from the URL.

History

  • Update - 3/6/2015 - Formatting updates
  • Update - 2/15/2013 - Fleshed out the documentation of the smart price endpoints
  • Update - 5/30/2012 - Updated examples; added more details on calling with accountId
  • Update - 6/9/2011 - Initial Version