Quick Start Guide

Create credentials, authenticate, make your first Switch API request, and inspect a standard API response.

Sign up for a user account

Every request to the Arcadia Switch APIs must be authenticated. Authentication identifies who is making the call and keeps your data private. If you don't have an account yet, create an Arcadia user account.

Create or join an organization

Once you have your user account, either join an existing organization or create a new one. An organization represents your team or company, often called an "Org" for short. Each API call to Arcadia is associated with one Org. 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.

Log in to Dash and navigate to the Org Settings page. From there, create a new Org and invite team members, or request membership in an existing Org that matches your email domain. Your user account can belong to more than one Org. 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.

The 14-day free trial is for Arcadia Signal. It is not Arcadia Switch and does not include permission to make Switch API calls. We grant Switch trials to qualified leads. Contact our sales team to get permission.

Create an API application

The credentials you use when making an Arcadia Switch API call belong to an Application, or App for short. This App belongs to the Org from above. Customers often 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 Dash. 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 and 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 should be kept private and changed periodically. Both values are automatically generated by Arcadia, and together they authenticate every API request. To pass these two values to us, use HTTP Basic Auth. This process is described in detail on our API Security page.

Make your first request

Make an API call from the command line, replacing APP_ID and APP_KEY with your own credentials:

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

The response should look like this:

{"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, continue with the Quick Start.

Normally, you create the authentication HTTP header programmatically. However, if you paste the 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 receive a JSON response.

Understand the response

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

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, and related response metadata. 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 the customer’s electric utility

Now that you've made your first request, 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. 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

The response includes matching utilities:

{
  "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
}

The response includes a list with three residential electricity utilities, each with details populated in the results list. The type property is also populated in this call. It tells us that the results JSON conforms to the LoadServingEntity structure. In many cases, types 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.

Next steps

Now that you've made your first API calls, review the guides that match your use case or continue exploring the API reference.