Welcome to the API v2 Quickstart! Our goal here is to get you using our API right away!
In order to use our API, you need include an api token in every request so that we can return the correct list of results that belong to you.
4e74da223908414fa171ae5fe19dcde1)
Next, we'll create an authorization form that you can send to a utility customer to request their utility data.
Use curl to create a new Form object
(copy your api token into where it says API_TOKEN_HERE).
curl -X POST \ -H 'Authorization: Bearer API_TOKEN_HERE' \ 'https://utilityapi.com/api/v2/forms'
Copy the uid from the response and head to Step 3!
{ "uid": "1234", // copy this string ... }
Normally, you would send or embed the
url
from the created Form to the utility customer from which you want to request
their utility data. However, we also offer the ability to simulate this
authorization for testing purposes. We'll do that here so you don't have to
track down a real utility customer.
Use curl to submit a demo authorization form via
/test-submit.
Replace FORM_UID_HERE with the uid
returned in Step 2.
curl -X POST \ -H 'Authorization: Bearer API_TOKEN_HERE' \ -d '{"utility": "DEMO", "scenario": "residential"}' \ 'https://utilityapi.com/api/v2/forms/FORM_UID_HERE/test-submit'
Copy the referral from the response and head to Step 4!
{ "referral": "2345" // copy this string }
Normally, you will get a referral code via a customer redirecting back to your site after submitting an authorization form, but in this quickstart we manually created a referral code via test-submit. You can use this referral code to look up the associated Authorizations and Meters via the /authorizations endpoint.
Use curl to get the Authorizations
and Meters created from the test-submit.
Replace REFERRAL_CODE_HERE with the referral
returned in Step 3.
curl -X GET \ -H 'Authorization: Bearer API_TOKEN_HERE' \ 'https://utilityapi.com/api/v2/authorizations?referrals=REFERRAL_CODE_HERE&include=meters'
Copy the Meter uid
from the "meters" list which was included in the
Authorization
object and head to Step 5!
{ "authorizations": [ { ... "meters": { "meters": [ { "uid": "3456", // copy this string ...
Once you have a list of Meters, you can activate them to go and collect the historical bill and interval data for those Meters. NOTE: Since this is a demo it will be free. However, if you activate real Meters it will be counted towards your subscription (i.e. it will cost money).
Use curl to get activate a Meter to get historical data.
Replace METER_UID_HERE with the uid
returned in Step 4.
curl -X POST \ -H 'Authorization: Bearer API_TOKEN_HERE' \ -d '{"meters": ["METER_UID_HERE"]}' \ 'https://utilityapi.com/api/v2/meters/historical-collection'
Verify a successful response and head to Step 6!
{ "success": true }
It takes a little time for us to go and collect the utility data from the utility
and we also simulate that in our demo utility, too. So, you can't download bills
right after activating. You need to check to see if bills have been collected before
you download them. You can do that by checking the bill_count on the
/meters/{uid} endpoint.
Use curl to get a Meter object.
Replace METER_UID_HERE with the uid
returned in Step 4.
curl -X GET \ -H 'Authorization: Bearer API_TOKEN_HERE' \ 'https://utilityapi.com/api/v2/meters/METER_UID_HERE'
Keep making the same request until you see the bill_count > 0
and status == "updated". Then head to Step 7!
{ ... "bill_count": 0, // poll until this is greater than zero ... "status": "pending", // poll until this is "updated" ... }
Now that the Meter is showing we have collected bills, you can download them via the /bills endpoint.
Use curl to get the bills for a Meter.
Replace METER_UID_HERE with the uid
returned in Step 4.
curl -X GET \ -H 'Authorization: Bearer API_TOKEN_HERE' \ 'https://utilityapi.com/api/v2/bills?meters=METER_UID_HERE'
Enjoy the utility bill data that's returned! Check out things like
bill_total_volume and service_tariff.
{ "bills": [ { ... "base": { ... "bill_total_volume": 837.0, ... "service_tariff": "E1 XB Residential Service", ...
Congratulations! You have successfully collected utility data via UtilityAPI!