Setup an Account

When you want to do an analysis with the Arcadia API, the first thing that you have to do is create an Account. The second thing that you have to do is set a Tariff on that account. This How-To will show you how to do both.

Create an Account

An account is the basis for all analysis in the Arcadia API. It stores the data associated with a particular customer: their address, what tariff they're on, how much energy they're using, and more. It's important to make sure that you populate it with all of the data that you need. In particular, you want to specify where the customer is located and what kind of customer they are -- residential or commercial.

The Account Endpoint

Whether it's creating, modifying, or deleting an account, all operations happen through the Account endpoint:

https://api.genability.com/rest/v1/accounts

To create our account, we'll send a PUT request to that URL:

PUT /rest/v1/accounts

Along with the following JSON request body:

{  
    "providerAccountId":"example_account",  
    "accountName": "Example Account",  
    "address": {  
        "address1": "455 Market St",  
        "city" : "San Francisco",  
        "state" : "CA",  
        "zip" : "94105",  
        "country" : "US"  
    },  
    "properties": {  
        "customerClass": {  
            "keyName":"customerClass",  
            "dataValue":"1"  
        }  
    }  
}

Let's break this request down and examine each piece individually.

Why a PUT request?

There are two different options for creating an account: you can send either a POST or a PUT request. So why did we choose to do a PUT? Doing it this way lets us use the providerAccountId property on the account in order to set our own unique identifier. Why is that a good thing?

accountId versus providerAccountId

Each account that you create in the Arcadia API can have two unique identifiers: accountId and providerAccountId. accountId is a UUID that is generated by the API for each account. providerAccountId, on the other hand, is a unique identifier that you can generate in order to keep track of the accounts that you create within the API. This way, if you have an existing database of accounts, you can use the identifiers that you've already created rather than having to also store the new IDs generated by the API.

A providerAccountId does not have to be unique within the API. Specifically, as long as you haven't already used the ID, it will be available for you to assign to an account.

Setting an Address

Probably the most important property of an account is its address. This tells the API where your customer is located in the world, allowing it to use that data to do a lot of the account setup for you.

In the example, we're using the addressString property of the address, but that's not the only way to do it. You can see all of the different options in the Address definition on the Account page. The most important thing to include is a ZIP code, either as part of the addressString or in its separate zip field.

Setting the Customer Class

The last thing to point out is the properties map, which is a dictionary that maps strings to account properties. In this request, we've set the only property, customerClass, to a value of 1. This value tells the API that our customer is a residential customer. It's important to set this property when creating your account; you'll need it later when you're specifying our tariff. You can see the other options for the customerClass property in the table below.

Value	Meaning
1	A residential customer.
2	A "general" customer. Used to represent a commercial customer.
4	Special use. Not normally used.

Select a Tariff

When an account is created, the Arcadia API will try to guess the best tariff for your customer based on the address and customerClass. For the account that we created above, the tariff will be automatically set to Pacific Gas & Electric's "E-1 Residential" tariff, since that is the most common tariff for residential customers in the 94105 ZIP code.

However, sometimes your customer is not on the most popular tariff, or a particular ZIP code has service from multiple different utilities. In that case, there's still some work to be done in setting up the account. It's important to make sure that an account has the correct tariff set on it because the tariff determines how much money the customer pays to their utility for the energy that they use. That, in turn, determines the amount of money they could save by going solar.

To pick the correct tariff when the default doesn't work, we can use a data-driven approach with two steps:

Use the customer's address information to select the correct utility.
Based on that utility selection, pick the right tariff.

Choose the Correct LSE

For many customers, there is only one utility (also called a "load-serving entity" or "LSE" in the Arcadia API) that provides power in their area. Some customers, though, will have some choices. We'll use the Load Serving Entity endpoint to pick the right one.

The easiest way to see what utilities are available for your customer is to search by address or ZIP code. Continuing our example from before, you could use:

GET /rest/public/lses?zipCode=94105&country=USresidentialServiceTypes=ELECTRICITY

One important thing to take note of is the residentialServiceTypes=ELECTRICITY parameter on to the end of the URL. This parameter makes sure that you only get back LSEs that serve power to residential customers. Otherwise, you would get back solar providers and other LSEs in the database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively.

Either query will return the following list:

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

Since there's only one choice, you know that our customer is getting their power from PG&E. If there were more options, they would show up as additional entries in the results array. You can use the lseId field in the results to set the lseId property on the account:

PUT /rest/v1/accounts/pid/example_account/properties

{  
    "keyName":"lseId",  
    "dataValue":"734"  
}

Pick the Right Tariff

Now that you've created an account and chosen an LSE, you're ready to pick a tariff. For that, we'll use the Account Tariff endpoint. This endpoint uses the data that you've added to our account already in order to show a list of tariffs that are available. For example, if you had set up our account as a commercial account, the Account Tariff endpoint would only have commercial tariffs available.

To see what tariffs are available, make the following call:

GET /rest/v1/accounts/pid/example_account/tariffs

This will return a list of tariffs:

{  
    "status": "success",  
    "count": 21,  
    "type": "Tariff",  
    "results": \[  
    {  
        "tariffId": 3215865,  
        "masterTariffId": 522,  
        "tariffCode": "E-1",  
        "tariffName": "Residential",
      
         /* more tariff data */
}]
}

You can see that, given the data we've provided so far, there are 21 tariffs to choose from. That's a lot of tariffs! Luckily, Arcadia helps you choose. The tariffs that are returned from the account tariff endpoint are ordered by likelihood. That is, the tariffs that are most likely to be the correct tariff for your customer are at the top, and the tariffs that are least likely are at the bottom.

Once you selected the correct tariff from the list, you can set the masterTariffId property on the account just like we did for lseId earlier. Let's assume that our customer is on E-1:

POST /rest/v1/accounts/pid/example_account/properties

{  
    "keyName":"masterTariffId",  
    "dataValue":"522"  
}

tariffId versus masterTariffId

Why did we use masterTarffId to set our customer's tariff instead of tariffId? It's because tariff data changes periodically. E-1, for example, usually changes a few times per year. For each revision, we put a new tariff into the database with a unique tariffId. Logically, however, each of these new tariffs is actually just a different version of a single "master" tariff. This family of tariffs is tied together with the masterTariffId property. Each version of the tariff will have a different tariffId, but they all have the same masterTariffId.

Add a Tax Rate to an Account

The Arcadia database only has rates that appear in utility tariff books. That means that it does not have state, local, and other tax rates. To incorporate a tax (say, a Utility User's Tax or UUT) into a calculation on your account, you can include in that account's tariffs:

PUT /rest/v1/accounts/{accountId}/tariffs
PUT /rest/v1/accounts/pid/{providerAccountId}/tariffs

{  
   "masterTariffId":"522",  
   "serviceType":"ELECTRICITY",  
   "rates":\[  
      {  
         "chargeType":"TAX",  
         "rateName":"Utility Tax",  
         "rateBands":[  
            {  
               "rateAmount":0.085,  
               "rateUnit":"PERCENTAGE"  
            }  
         ]  
      }  
   ]  
}