Quick Start Guide

Sign Up for a User Account

Every request to the Arcadia Switch APIs must be authenticated—this is how we identify who is making the call and keep your data private. If you don't have one yet, your first step is to create your own Arcadia User Account. Please go ahead and do this now!

Create or Join an Organization

Once you have your User Account, you need to either join an existing Organization or create a new one. An Organization represents your team or company (we often call them "Orgs" for short). Each API call to Arcadia is associated with one Org. Additionally, APIs that store and share data do so at an Org level—only the Org that created the data can later view and manage it. We offer a 14-day free trial if your company or team isn't yet a paying customer or doesn't have an Org.

Let's give your User Account membership in an Org. Log in to Explorer and navigate to the Org Settings page. Here you can either create a brand new Org (including inviting other team members to it), or you can request membership in an existing Org that matches your email domain, where one already exists. Note that 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 in one. You'll receive 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 for our Arcadia Signal product. This is NOT Arcadia Switch, and therefore does not include permission to make Switch API calls. However, we do grant trials for our Switch product to qualified leads. Contact our sales team to get permission!

Create an API Application

The actual credentials you use when making an Arcadia Switch API call belong to an Application (or App for short). This App, in turn, belongs to the Org from above. Often our customers create multiple Apps—for example, for test vs. production environments or for mobile vs. web applications. You can have as many Apps as you want. You manage your Organization's Apps on the Org Applications page in Explorer. Either click the "Create Application" button or select one of the existing Apps for which you'd like to use credentials.

🗒️

If you are on a free trial, you will need to enter a valid credit card to create an Application and get an API Key. Just remember to cancel your subscription before the trial ends if you don't want to be billed.

API Credentials & Authentication

Each App has an appId and an appKey. The appId is equivalent to your application's username. The appKey is like its password and, as such, should be kept private and changed periodically. Both values are automatically generated by Arcadia, and together they are used to authenticate every API request. To pass these two values to us, you'll use HTTP Basic Auth. This process is described in detail on our API Security page.

Make Your First Request

OK, enough preparation! Let's make an API call. From the command line (substituting your own appId and appKey):

curl -u APP_ID:APP_KEY https://api.genability.com/rest/echo/hello

This should return the following:

{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

The above is an API call to our Echo API. This endpoint is useful for getting started, including ensuring your code handles validation and exception errors. We suggest returning to this API once you're deeper into integrating. For now, let's continue with the Quick Start!

Normally, you would create the authentication HTTP header programmatically. However, if you paste the above URL into your web browser's address bar, you can enter your appId and appKey in the username and password fields of the Basic Authentication dialog when it appears. If it works, you'll get JSON back!

Understanding the Response

All our REST APIs return JavaScript Object Notation (JSON). Additionally, all our REST APIs return a response in a standard "envelope" that contains the main results in the results property, in a structure specific to that endpoint (for example, a simple array with the string "Hello World" for this endpoint).

Surrounding that are standard fields that provide additional information about what you received back. For instance, the count tells you how many items matched, and the type gives you details about the structure in the results. Other fields help with pagination, status information, etc. You can see all the standard response fields on the REST Response page.

{
  "status": "success",
  "count": 1,
  "type": null,
  "results": [
    "Hello World",
    "Hello World!"
  ]
}

Find Your Home's Electric Utility

Now that we're up and running and have made our first request, let's do something 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 the residential electricity LSEs for your ZIP or postal code using the following request:

https://api.genability.com/rest/public/lses?zipCode=94105&residentialServiceTypes=ELECTRICITY&sortOn=totalCustomers&sortOrder=DESC&fields=ext

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 GET request to the root of that object's service. For example, to get every LSE you would make a GET request 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 to 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 we 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 that you've got some API calls under your belt, you're ready to move on and learn more about building energy applications. We suggest you now review our Tutorials and pick the one that best matches your use case.