Quick Start

Getting Started Steps

Step 1: Sign Up for a User Account

Every request to the Arcadia Signal APIs must be authenticated. Create your own Arcadia User Account to continue.

Step 2: Create or Join an Organization

An Organization (Org) is the account scope for API access and shared data. Each API call is associated with one Org, and only the Org that created data can later view and manage it. If your team does not yet have an Org, you can start with a 14-day free trial.

Log in to Dash and open the Org Settings page. Create a new Org, invite teammates if needed, or request access to an existing Org that matches your email domain. Your User Account can belong to more than one Org. Once your access is approved, continue to the next step.

Step 3: Create an API Application

Your API credentials belong to an Application (App), and each App belongs to an Org. Many teams create separate Apps for test and production environments or for different platforms.

Open the Org Applications page, then create a new App or select an existing one to get your appId and appKey.

📘
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 end of the trial if you do not want to be billed.

Step 4: Authenticate Your Request

Each App has an appId and an appKey, which work like a username and password. Arcadia uses these values to authenticate every API request through HTTP Basic Authentication. Keep the appKey private and rotate it periodically. For more detail, see the API Security page.

Make Your First Request

Run the following command, replacing APP_ID and APP_KEY with your credentials:

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

...which should return the following:

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

This call uses the Echo API. It is useful for verifying authentication and testing how your code handles validation and exception errors. Keep this endpoint handy while you integrate.

You can also test the call in a browser by pasting the URL into the address bar and entering your appId and appKey in the Basic Authentication dialog. If the request succeeds, the browser returns JSON.

Optional: Understand the API 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, status information, etc. You can see all the standard response fields on the REST Response page.

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

Find Your Home's Electric Utility

After you confirm authentication, use the Load Serving Entities API. A Load Serving Entity (LSE) is a utility or another entity that services a building's load. Request the residential electricity LSEs for your ZIP or postal code with:

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

Optional: Understand the Request Parameters

What does this request mean? Broken down from left to right:

Request Section	Description	More Information
`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 at 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.	Introduction
`zipCode=94105`	The call will only find LSEs that are active in ZIP code `94105`.
`residentialServiceTypes=ELECTRICITY`	Arcadia tracks different types of LSEs, including utilities that only provide service to businesses, those that only provide natural gas, rooftop and community solar companies, agencies that provide incentives and rebates, and more. In our case, we only 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 likely 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 query's results, rather than the regular set. You can use this parameter in many different places to get 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), `ext`ended, and `min`imum. 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.

Optional: Example Response for ZIP 94105

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": "Energy",
          "ownership": "COMMUNITY_CHOICE_AGGREGATOR",
          "serviceTypes": "ELECTRICITY",
          "totalRevenues": 1,
          "totalSales": 1,
          "totalCustomers": 1,
          "residentialServiceTypes": "ELECTRICITY",
          "residentialRevenues": null,
          "residentialSales": null,
          "residentialCustomers": null,
          "commercialServiceTypes": "ELECTRICITY",
          "commercialRevenues": null,
          "commercialSales": null,
          "commercialCustomers": null,
          "industrialServiceTypes": "ELECTRICITY",
          "industrialRevenues": null,
          "industrialSales": null,
          "industrialCustomers": null,
          "transportationServiceTypes": "ELECTRICITY",
          "transportationRevenues": null,
          "transportationSales": null,
          "transportationCustomers": null,
          "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 array. 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/"
        }
    ]
}

Quick Start Complete

You’ve completed the quickstart.

Next Steps

Tutorials & Guides

Explore our step-by-step tutorials that match your specific use case

API Reference

Dive into our complete API documentation and explore all available endpoints

Echo APIs

Practice with our Echo APIs to handle validation and exception errors

Download Postman

Use a REST client to quickly test request parameters and response formats

Need Help?

Support & Resources

Testing Tool: Use Postman for quick API testing
Error Handling: Practice with our Echo APIs
Email Support: Send us an email at [email protected]