-
Notifications
You must be signed in to change notification settings - Fork 6
API Documentation
Once you have received an access token using OAuth, use your OAuth library to call the API you are interested in. The format of API URLs is:
https://secure.powershop.co.nz/external_api/v2/apiname.format
where apiname is one of the API calls listed in this document such as accounts, products, or purchase where format is one of js or xml. If you use format js, the response will be a JSON string. If you use format xml, the reponse will be in XML.
Parameters supplied to the calls should be passed URL-encoded. For example, a request to find meter readings for ICP 0123456789 between the 1st and 30th of September 2009, with a JSON response requested, would look like:
https://secure.powershop.co.nz/external_api/v2/meter_readings.js?icp_number=0123456789& start_date=2009-09-01&end_date=2009-09-30
Your OAuth library will add OAuth token information and a signature before passing it to the Powershop server.
See below for details about each of the different API calls. Note that calls that get information require you use an HTTP GET, and calls that update information require you use an HTTP POST.
A successful call to the API will return an HTTP 200 status code, and either JSON or XML-encoded data.
An unsuccessful call will return HTTP status codes 400, 401 or 503, depending on the error. A single line of text describing the error will also be returned. Error messages common to all API calls are:
[E900] Invalid OAuth signature or consumer key
[E901] Unknown OAuth signature method
[E902] The application has exceeded the request rate limit for this hour
[E903] Invalid OAuth token
[E904] OAuth consumer is disabled
[E905] Expired request token
[E906] Invalid verifier
[E907] oauth_token not found
[E908] oauth_callback must be supplied
As the text of error messages may change, please use the [Exxx] error number to detect a particular error message.
Returns information about the accounts and properties the currently authenticated user has access to.
Returns readings for a consumers ICP (Installation Control Point).
Allows users to enter a reading for the specified ICP.
Returns pre-calculated data about the user's usage, ready to plot on a graph.
It is the same data that is shown on the Powershop web site graphs.
Returns the products available for purchase from the specified property,
and the per unit price of the products.
Makes a purchase of power for the given consumer and property.
Posts some feedback to Powershop tailored to the user.
Returns all active referral promotions. The user can use one of these promotions to
refer Powershop to a friend.
Allows a user to refer a friend to Powershop.