API release – Calculation Assumptions & USD Rates

We’ve released a number of upgrades to the API’s and we’d like to highlight a few key ones:

Tariff Rate Amounts in USD

Historically, when you ran a calculation or asked for a price, any currency returned was in the same denomination. However, the tariff rate amounts that you got back from the tariff end point are in dollars for fixed charges (like meter charges) and cents for consumption, demand and other rates. Why, you ask? Good question. Doesn’t make any sense, so we have moved to be consistent across all API methods.

To get all rates in dollars, you can now pass in betaStandardCurrency=true when requesting a tariff’s rates or a price, and what you get back will be in dollars.  Why the “beta” prefix? We don’t want to pull the rug out on anyone by changing the default behavior unannounced, so by default the end point will return rates as it previously did. However, on 1/31/2012 we will change the default to be consistently dollars, and won’t support the old approach. So you should remove any “x100” logic in your apps and set is flag sometime between now and then. (Note: the flag will not be necessary from the 31st, but won’t hurt anything should you leave it in the URL for a while).

Read more about this flag on the Get Tariffs or Get Price documentation.

Understanding what Calculation Assumptions were used

You don’t always know the accurate consumption amount, or whether a customer is on option A or B, when you run a calculation. With that in mind we built our rate engine to be flexible enough to always handle incomplete data. Today, we are starting to make that capability visible to you via the API. When calling a calculation, the results contain a new field called accuracy. This is a decimal number between 0 and 1. A value of 1 means completely accurate, and anything < 1 means some assumption was made. In the current version the magnitude of this value does not indicate a confidence, but over time it will.

So you ran a calculation and saw its accuracy is < 1? Why? To answer that question, set the new input parameter betaPopulateAssumption to true (by default its false). The results will then include a new assumptions property that’s a collection of the assumptions the calculator made. In this release we are concentrating on effective tariffs. To illustrate, consider this situation:

  • You run a calculation for Jan and Feb
  • We only have an effective tariff from Feb, so a tariff for Jan is missing
  • When you run the calculation, we’d determine the best tariff to substitute in for the Jan period (in this case Feb is the nearest one).
  • When we return the results, it will have a an accuracy of < 1 and will include an assumption record for Jan saving the accuracy is < 1, and another for Feb saying its accuracy is 1

A note on tariff coverage. For most major markets, we have tariff data from the beginning of 2011. So if you wish to run a calculation for 2010, this capability is very useful.

Let us know what you think.

This entry was posted in API, Developers, News, Products and tagged , , , , , . Bookmark the permalink. Both comments and trackbacks are currently closed.
  • Categories

  • Archives