Quick Start Guide
This quickstart guide is the place to begin if you are brand new to the Arcadia Switch APIs. Here we go over the basics of getting credentials, making a request, and getting some data back. So without further ado, let’s get started.
Sign up for a User Account
Every request to the Arcadia Switch APIs needs to be authenticated, which is how we know who is making the call and how we can keep your data private. If you don’t have one yet, your first step is to create your own Arcadia User Account. So please go do it now!
Create or Join an Org
Once you have your own User Account, you then need to either join an existing Organization or create a new one. An Organization is your team or company (we often call them "Org's" for short). Each API call to Arcadia is associated with one Org. Furthermore, the APIs that store and share data do so at an Org level; only the Org that created the data can later see and manage it. We have a 14-day free trial if your company or team is not yet a paying customer or does not yet have an Org.
So let's give your User Account membership to an Org. Log in to Explorer and navigate to the Org Settings page. Here you have the option of creating a brand new Org (including inviting other team members to it), or you can request membership to an existing Org that matches your email domain, where one already exists. Note your User Account can be a member of more than one Org if that makes sense for you. Go ahead and either create an Org or request membership of one. You will get a confirmation email when the Org's administrator approves your request.
Once you belong to an Org, you can move on to the next step.
We have a 14 day free trial to our Arcadia Signal product. This is NOT Arcadia Switch, and so does not include permission to make Switch API calls. We do, however, grant trials to our Switch product for qualified leads. Contact our sales team to get permission!
Create an API Application
The actual credentials you use when making a Arcadia Signal API call belong to an Application (or App for short). This App in turn belongs to the Org from above. Often our customers will create multiple Apps, say, for test vs production or for mobile vs web. You can have as many Apps as you want. You manage your Organization's Apps in the Org Applications page in Explorer. Either click on the "Create Application" button or select one of the existing Apps that you'd like to use credentials for.
If you are on a free trial, you will need to enter a valid credit card in order to create an Application and get an API Key. Just remember to cancel your subscription before the end of the trial if you do not want to be billed.
API Credentials & Authentication
Each App has an appId and and appKey. The appId is equivalent to your application's user name. The appKey is like its password, and as such should be kept private and should be changed from time to time. Both values are automatically generated by Arcadia and together they are used to authenticate every API request. To pass us these two values, you'll use HTTP Basic Auth. How to do this is described in detail on our API Security page.
Make your first request
OK, enough messing about! Let's make an API call. From the command line (swapping out your own appId and appKey) ...
curl -u APP_ID:APP_KEY https://api.genability.com/rest/echo/hello
... which should return the following ...
1
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}
The above is an API call to our Echo API. The endpoint is useful for getting going, including making sure your code handles validation and exception errors. We suggest coming back to this API once you are deeper into integrating. For now, on with the Quick Start!
Normally, you would create the authentication HTTP header programmatically. However, if you paste the above URL into your favorite web browser's address bar, you can put your appId and appKey in the username and password fields of the Basic Authentication dialog when it pops up. If it works, you get JSON back!
Understanding the response
All our REST APIs return Javascript Object Notation (JSON). In addition, all our REST APIs return a response in a standard "envelope" that has the main results in the results property, in a structure that is specific to that endpoint (for example a simple array with the string Hello World in it for this endpoint). Surrounding that are standard fields that tell you a few other things about what you got back. For instance the count tells you how many items matched, and the type gives you details of what the structure in the results is. Other fields help with pagination, what the status was etc. You can see all the standard response fields in the REST Response page.
{
"status": "success",
"count": 1,
"type": null,
"results": [
"Hello World",
"Hello World!"
]
}
Find your home's electric utility
Now we are up and running and have made our first request, let's do something a bit more meaningful. Let's use the Load Serving Entities API. A Load Serving Entity, or LSE, is a Utility or any other entity that services the load of a building (hence the name). Let's get a list of all of the residential electricity LSEs for your ZIP or postcode by using the following request:
https://api.genability.com/rest/public/lses?zipCode=94105&residentialServiceTypes=ELECTRICITY&sortOn=totalCustomers&sortOrder=DESC&fields=ext
What does this request mean? Broken down from left to right ...
| Request Section | Description | |
|---|---|---|
<https://> | We recommend using https for all API traffic. | |
api.genability.com | Our production API environment is at api.genability.com. You'll probably always make calls to this server. | |
/rest | If you look in the path of this request, you'll see it starts with /rest. Almost all of our APIs are RESTful in nature. | |
/public | this denotes the version. It's typically either v1 or public | Versioning details |
/lses | This part of the request path denotes the actual endpoint you are calling. In this case, Get LSEs. | API Reference |
zipCode=94105 | The call will only find LSEs that are active in the ZIP code 94105. | |
residentialServiceTypes=ELECTRICITY | Arcadia tracks different types of LSEs, including utilities that just provide service to businesses, those that just provide natural gas, rooftop, and community solar companies, agencies that provide incentives and rebates, and more. In our case, we just want utilities that provide electricity to residential customers. | |
sortOn=totalCustomers&sortOrder=DESC | Any API endpoint that can return more than one item in its response has the ability for the caller to request how the results are sorted. In this case, we wanted to put the most likely utility at the top of the list, and the least at the bottom. So we sorted on the totalCustomers field. | Sorting details. |
fields=ext | This tells the API to return the extended set of fields for this queries results, rather than the regular set. You can use this parameter in a lot of different places in order to get back additional information from the API. In fact, there are three different options for the amount of data that you want the API to return: standard, which is what gets returned by default, extended, and mininimum. You can read more about them, along with other standard request parameters. | Fields details. |
Learn all about our standard REST parameters on the REST Requests page.
Here's the response you get back when making the above call:
{
"status": "success",
"count": 3,
"type": "LoadServingEntity",
"results": [
{
"lseId": 734,
"name": "Pacific Gas & Electric Co",
"lseCode": "PGE",
"code": "14328",
"websiteHome": "http://www.pge.com/",
"offeringType": "Bundle",
"ownership": "INVESTOR",
"serviceTypes": "ELECTRICITY",
"totalRevenues": 12615980,
"totalSales": 72481825,
"totalCustomers": 5069189,
"residentialServiceTypes": "ELECTRICITY",
"residentialRevenues": 4969233,
"residentialSales": 27558981,
"residentialCustomers": 4453034,
"commercialServiceTypes": "ELECTRICITY",
"commercialRevenues": 5057946,
"commercialSales": 27109514,
"commercialCustomers": 526484,
"industrialServiceTypes": "ELECTRICITY",
"industrialRevenues": 2588801,
"industrialSales": 17813330,
"industrialCustomers": 89671,
"transportationServiceTypes": "ELECTRICITY",
"transportationRevenues": 0,
"transportationSales": 0,
"transportationCustomers": 0,
"billingPeriodRepresentation": {
"fromDateOffset": 0,
"toDateOffset": -1,
"style": "InclusiveToDate"
}
},
{
"lseId": 1074,
"name": "San Francisco City & County of",
"lseCode": "CCOSF",
"code": "16612",
"websiteHome": "http://www.sfgov.org/index.asp",
"offeringType": "Bundle",
"ownership": "MUNI",
"serviceTypes": "ELECTRICITY",
"totalRevenues": 101620,
"totalSales": 992877,
"totalCustomers": 2173,
"residentialServiceTypes": "ELECTRICITY",
"residentialRevenues": 12,
"residentialSales": 53,
"residentialCustomers": 21,
"commercialServiceTypes": "ELECTRICITY",
"commercialRevenues": 94177,
"commercialSales": 860564,
"commercialCustomers": 2150,
"industrialServiceTypes": "ELECTRICITY",
"industrialRevenues": 912,
"industrialSales": 28067,
"industrialCustomers": 1,
"transportationServiceTypes": "ELECTRICITY",
"transportationRevenues": 6519,
"transportationSales": 104193,
"transportationCustomers": 1,
"billingPeriodRepresentation": {
"fromDateOffset": 0,
"toDateOffset": 0,
"style": "Unknown"
}
},
{
"lseId": 100773,
"name": "CleanPowerSF",
"lseCode": "CPSF",
"code": "",
"websiteHome": "http://sfwater.org/index.aspx",
"offeringType": "Bundle",
"ownership": "COOP",
"serviceTypes": "ELECTRICITY",
"totalRevenues": 1,
"totalSales": 1,
"totalCustomers": 1,
"residentialServiceTypes": "ELECTRICITY",
"residentialRevenues": 1,
"residentialSales": 1,
"residentialCustomers": 1,
"commercialServiceTypes": "ELECTRICITY",
"commercialRevenues": 1,
"commercialSales": 1,
"commercialCustomers": 1,
"industrialServiceTypes": "ELECTRICITY",
"industrialRevenues": 1,
"industrialSales": 1,
"industrialCustomers": 1,
"transportationServiceTypes": null,
"transportationRevenues": 1,
"transportationSales": 1,
"transportationCustomers": 1,
"billingPeriodRepresentation": {
"fromDateOffset": 0,
"toDateOffset": -1,
"style": "InclusiveToDate"
}
}
],
"pageCount": 25,
"pageStart": 0
}
As you can see, we got back a list with three residential electricity utilities, each with their details populated in the results list. Also, the type property is populated in this call. It tells us that in the results we have JSON that conforms to the LoadServingEntity structure. In many cases, we have types that are reused across different endpoints.
Get Data About a Single Utility
Arcadia's API endpoints follow a pattern that should be familiar to people who have worked with REST APIs before. That pattern is:
- To get a list of every instance of a particular object, make a
GETrequest to the root of that object's service. For example, to get every LSE you would make aGETrequest to/rest/v1/lses. - To get a particular instance, add a URL parameter to your request that specifies which instance you're interested in. To get the data for PG&E, that request would look like this:
https://api.genability.com/rest/public/lses/734
Notice that we added the URL parameter 734 onto the end of our request. This is the unique ID of PG&E's LSE record, the lseId, which we got from the response to our last request. The LSE summary for PG&E looks like the following. Again, note that we reuse the LoadServingEntity type. However, for this call, we did not ask for fields=ext so did not get back the extended fields:
{
"status": "success",
"count": 1,
"type": "LoadServingEntity",
"results": [
{
"lseId": 734,
"name": "Pacific Gas & Electric Co",
"code": "14328",
"websiteHome": "http://www.pge.com/"
}]
}
Congratulations!You made it through the Quick Start!
Where to next?
Now you've got some API calls under your belt, you're ready to move on and learn more about building new energy applications. We suggest you now review our Tutorials, and pick the one that best matches your use case. Our Tutorials are step-by-step guides that tell you the common approach to a given problem.
Other Reading
- Dive right into our API Reference section and review all the APIs we have to offer.
- Get familiar with handling common error responses by using our Echo APIs method.
- Download Postman which is a handy REST client that you can use to quickly test out the request parameters and response formats for all of our endpoints.
- Need help? Send us an email at [email protected].
Updated 2 days ago