Genability API PHP Library and Examples

We’ve added a PHP Library for our Genability APIs to Github. You can check it out right now at: https://github.com/Genability/Genability-PHP-Library. It works right out of the box and includes methods to use most of our api calls. It even includes our newest calculate method so you can start playing around with the calculator. More on that later.

getTariff()


The library comes with a couple of examples so you can see how it works. First up is getTariff. A PHP example was previously added to Github and this one basically removes all the code which communicated with our api and uses the library instead. To initialize the library, you just need to include the php file and create a new instance of the genability object by replacing ‘your-app-id-here’ and ‘your-app-key-here’ with your app id and key which you can get from https://developer.genability.com/admin/applications.

 

// set your app id and app key
$gen = new genability(array(
'app_id'  => 'your-app-id-here',    // Your Unique Genability Application ID <https://developer.genability.com/admin/applications>
'app_key' => 'your-app-key-here',   // Your Unique Genability Application Key <https://developer.genability.com/admin/applications>
//'debug'   => true,                // Debug mode echos API Url if set to true (Optional)
));

Tariff Information returned from getTariff

To make the getTarriff call, you just pass in the parameters as an array. The only required field for the library is masterTariffId. (populateRates is required by the api but the library defaults it to false if it isn’t set by the user). See how useful this library is already!? 🙂

getPrice()

 


Want to know the price of a tariff right now? Well now you can easily use the getPrice method and find out! The set up is exactly the same as getTariff. However, this time the parameter array must include a start date time in ISO 8601 format along with the masterTariffId. You can optionally also send in an end date time, territory id, consumption amount and/or demand amount. The included example has defaults for all of those that you can play around with.

 

// make the getPrice call
$output = $gen->getPrice(array(
  'masterTariffId'    => $TARIFF_ID,           // Unique Genability ID (primary key) for this tariff
  'fromDateTime'      => $FROM_DATE_TIME,      // Date and time of the requested start of the Price. In ISO 8601 format. (Required)
  'toDateTime'        => $TO_DATE_TIME,        // Date and time of the requested start of the Price. In ISO 8601 format. (Optional)
  'territoryId'       => $TERRITORY_ID,        // When specified, rate changes returned will be for the specified Territory. (Optional)
  'consumptionAmount' => $CONSUMPTION_AMOUNT,  // A monthly consumption in kWh. (Optional)
  'demandAmount'      => $DEMAND_AMOUNT,       // A monthly demand in kW. (Optional)
));

Example of vardump and array of price changes returned

This screenshot shows the vardump which is all the information returned by the api for the call. The vardump can be toggled on each example page to help you debug and understand the data structure that is returned. If you’re not even getting a useful vardump, you can set the debug flag to true in the initial genability call to echo each api call to see what data you’re sending to us.

calculate()


Now this one gets a little tricky. You want to calculate someone’s bill but don’t even know the information to ask for. You could just ask for their monthly energy data but that’s not very detailed. With the calculate method, if you just send in the masterTariffId without any tariffInputs, we’ll return the inputs that are applicable for that tariff.  It may be time of use intervals, specific LSE parameters, whatever. The image on the left is an example of this. Once you return the information, however detailed or generic it may be, we’ll do our best to break it up in an educated way to return the most specific cost possible. An example of that is on the right.

 

This is the Metadata that we would expect for the specified Tariff

—————————————>

Returned Cost

// if tariffInputs are sent through POST, make the calculate call
// otherwise, get the metadata parameters
if ($_POST['tariffInputs']) {
	$output = $gen->getCalculation(array(
	  'masterTariffId'=> $TARIFF_ID,               // Unique Genability ID (primary key) for this tariff
	  'fromDateTime'  => $FROM_DATE_TIME,          // Starting date and time for this Calculate request. (Required)
	  'toDateTime'    => $TO_DATE_TIME,            // End date and time for this Calculate request. (Required)
	  'territoryId'   => $_POST['territoryId'],    // The territory ID of where the usage consumption occurred. (Optional)
	  'tariffInputs'  => $_POST['tariffInputs'],   // The input values to use when running the calculation. (Array)

	));
} elseif ($_POST['tariff']) {
	$output = $gen->getCalculateInputs(array(
	  'masterTariffId'=> $TARIFF_ID,              // Unique Genability ID (primary key) for this tariff
	  'fromDateTime'  => $FROM_DATE_TIME,         // Starting date and time for this Calculate request. (Required)
	  'toDateTime'    => $TO_DATE_TIME,           // End date and time for this Calculate request. (Required)
	  'territoryId'   => $_POST['territoryId'],   // The territory ID of where the usage consumption occurred. (Optional)
	));
}

What’s Next?


We’ll be updating this library as we update our API with more calls. If you have any questions feel free to email our dev team at devnet@genability.com, talk on our forums at the Genability Developer Network or ping us on Twitter at @genabilityapi.

 

Want other libraries? What language(s) are you coding in?

This entry was posted in API, Developers, Info, News and tagged , , , , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

Post a Comment

Your email is never published nor shared. Required fields are marked *

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*
*

*

  • Categories

  • Archives