Quick Start

Welcome to the Arcadia Signal APIs! This guide will walk you through the essential steps to get started, from setting up your account to making your first API calls.

Getting Started Steps

Create your Arcadia User Account to authenticate your API requests and keep your data private.

Create/Join Organization

Join an existing Organization or create a new one. Each API call is associated with one Org, with a 14-day free trial available.

Create API Application

Set up your App credentials on the Org Applications page to get your appId and appKey.

Make Your First Request

Test your setup with a simple API call using HTTP Basic Authentication.

Step 1: Sign Up for a User Account

Every request to the Arcadia Signal APIs must be authenticated—this is how we know who is making the call and how we 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 that now!

Step 2: Create or Join an Organization

Once you have your own User Account, you need to either join an existing Organization or create a new one. An Organization is your team or company (we often call them "Orgs" 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 offer a 14-day free trial if your company or team is not yet a paying customer or does not yet have an Org.

Let's give your User Account membership to an Org. Log in to Dash 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, if 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 of one. You will 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.

Step 3: Create an API Application

The actual credentials you use when making an 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 create multiple Apps—for example, for test vs. production or for mobile vs. web. You can have as many Apps as you want. You manage your organization apps on the Org Applications page in Dash. 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 end of the trial if you do not want to be billed.

API Credentials & Authentication

Each App has an appId and an appKey which in essence function like a username and password. These should be kept private and the appKey is something you can and should refresh periodically. 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

Okay, 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

...which should return the following:

{
    "status": "success",
    "count": 2,
    "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 making sure your code handles validation and exception errors. We suggest returning to this API once you are deeper into integrating. For now, let's continue with the QuickStart!

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 appears. If it works, you get JSON back!

Understanding 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": 1,
  "type": null,
  "results": [
    "Hello World",
    "Hello World!"
  ]
}

Find Your Home's Electric Utility

Now that 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 the residential electricity LSEs for your ZIP or postal code by using the following request:

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

Understanding the API 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.

Example Response: Electric Utilities in 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/"
        }
    ]
}

🎉 Congratulations!

You made it through the Quick Start!

Where to Next?

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

Get a handy 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]