Quick Start

Get your Arcadia credentials, make an authenticated request, and retrieve utility data with your first Arcadia Signal API calls.

Before You Begin

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

A successful response returns status: "success" and two test strings in the results array:

{
    "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 REST APIs return JavaScript Object Notation (JSON) in a standard response envelope. The endpoint-specific data appears in results, with standard fields around it that describe the response.

Key fields include:

status: whether the request succeeded
count: how many items matched the request
type: the structure returned in results, when applicable
results: the response data for the endpoint

You can see all 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:

curl -u APP_ID:APP_KEY "https://api.genability.com/rest/public/lses?zipCode=94105&residentialServiceTypes=ELECTRICITY&sortOn=totalCustomers&sortOrder=DESC&fields=ext"

Optional: Understand the Request Parameters

This request combines the endpoint path with query parameters that filter, sort, and shape the response.

Part	What it does	Learn more
`https://`	Sends the request over HTTPS.
`api.genability.com`	Uses Arcadia's production API environment.
`/rest`	Routes the request to the REST APIs.
`/public`	Selects the API version. Versions are typically `v1` or `public`.	Versioning details
`/lses`	Calls the Load Serving Entities endpoint.	Introduction
`zipCode=94105`	Returns LSEs active in ZIP code `94105`.
`residentialServiceTypes=ELECTRICITY`	Filters to utilities that provide electricity to residential customers.
`sortOn=totalCustomers&sortOrder=DESC`	Sorts the results by `totalCustomers`, from highest to lowest.	Sorting details
`fields=ext`	Returns the extended field set instead of the default standard field set.	Fields details

Learn all about our standard REST parameters on the REST Requests page.

Optional: Example Response for ZIP 94105

A successful response returns one or more utilities in the results array, sorted by customer count:

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

This response includes three residential electricity utilities. The populated type field tells you that each item in results uses the LoadServingEntity structure, which can be reused across multiple endpoints.

Get Data About a Single Utility

Arcadia's REST endpoints use a consistent pattern:

To get a list of objects, make a GET request to the root of that object's service. For example, to get every LSE, make a GET request to /rest/v1/lses.
To get one object, add that object's unique ID to the request path.

Get the data for PG&E by adding its lseId to the request path:

curl -u APP_ID:APP_KEY https://api.genability.com/rest/public/lses/734

The 734 path parameter is PG&E's unique LSE record ID, which came from the previous response. A successful response returns one LoadServingEntity summary.

This call does not include fields=ext, so the response does not include the extended fields:

{
    "status": "success",
    "count": 1,
    "type": "LoadServingEntity",
    "results": [
        {
            "lseId": 734,
            "name": "Pacific Gas & Electric Co",
            "code": "14328",
            "websiteHome": "http://www.pge.com/"
        }
    ]
}

What You Accomplished

You authenticated with the Arcadia Signal API, searched for residential electric utilities by ZIP code, and retrieved details for a single utility.

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

Test requests locally: Use Postman for quick API testing
Practice error handling: Use the Echo APIs
Contact support: Send us an email at [email protected]