Load Serving Entity

  • signal
  • explorer
Switch product users. Your developer documentation has moved over to the switchsolar.io website.

Load Serving Entity (LSE) is the industry term for what most people would call a utility, or an electric company. Since there are different types of electric company, we use the term LSE in our APIs. This is a company or other organization that supplies load (electricity) to a customer. In many cases this is the same company that distributes the electricity too, but in some cases customers can have one company that they buy the load from, and another that operates the distribution system (runs the line to the house, manages the meters etc). Some characteristics and uses:

  • LSEs have one or more territories that they operate in.
  • LSEs have tariffs (rate plans) and are central to many of our data structures.

Data Definitions

Load Serving Entity

The Load Serving Entity has the following data structure.

Name Type Fields Description
lseId Long M Unique Genability ID (primary key) for each LSE
name String M Published name of the company
code String M Short code (an alternate key). For US companies this is the EIA ID
websiteHome String M The URL to the home page of the LSE website
offeringType String E Utility classification based on the type of service they offer. Possible values:
Bundled - The utility provides all the electricity services bundled into one, including the transportation (transmission and distribution) and the generation (energy) portion
Delivery - Responsible for the transportation ( transmission and distribution) of power only.
Energy - Provides only the generation (energy) portion of the service. Energy Suppliers are sometimes referred to as Retail Energy Providers.
ownership String E Ownership structure. Most common values are
INVESTOR - Investor-owned utility managed as private enterprise.
COOP - Member owned utility which is managed on a non-profit basis.
MUNI - Publicly owned utilities subject to local public control and regulation.
Others include "FEDERAL", "POLITICAL_SUBDIVISION", "RETAIL_ENERGY_MARKETER", "WHOLESALE_ENERGY_MARKETER", "TRANSMISSION", "STATE", "UNREGULATED".
serviceTypes String E Service types offered to any customer. Current values include "ELECTRICITY" and "SOLAR_PV".
totalRevenues Integer E Annual total revenue in thousands of local currency (e.g. USD).
totalSales Integer E Annual total sales in MWh.
totalCustomers Integer E Total customer count.
residentialServiceTypes String E Service types offered to residential customers. Current values include "ELECTRICITY" and "SOLAR_PV". Blank means not offered
residentialRevenues Integer E Annual residential revenue in thousands of local currency (e.g. USD).
residentialSales Integer E Annual residential sales in MWh.
residentialCustomers Integer E Residential customer count.
commercialServiceTypes String E Service types offered to commercial customers. Current values include "ELECTRICITY" and "SOLAR_PV". Blank means not offered
commercialRevenues Integer E Annual commercial revenue in thousands of local currency (e.g. USD).
commercialSales Integer E Annual commercial sales in MWh.
commercialCustomers Integer E Commercial customer count.
industrialServiceTypes String E Service types offered to industrial customers. Current values include "ELECTRICITY" and "SOLAR_PV". Blank means not offered
industrialRevenues Integer E Annual industrial revenue in thousands of local currency (e.g. USD).
industrialSales Integer E Annual industrial sales in MWh.
industrialCustomers Integer E Industrial customer count.
transportationServiceTypes String E Service types offered to transportation customers (such as municipal bus services, regional mass transit etc). Current values include "ELECTRICITY" and "SOLAR_PV". Blank means not offered.
transportationRevenues Integer E Annual transportation revenue in thousands of local currency (e.g. USD).
transportationSales Integer E Annual transportation sales in MWh.
transportationCustomers Integer E Transportation customer count.
billingPeriodRepresentation BillingPeriodRepresentation E Details about how the LSE represents billing periods.

Example

Here’s an example in JSON of an LSE:

1
2
3
4
5
6

{
    "lseId": 2756,
    "name":"Georgia Power Co",
    "code":"7140",
    "websiteHome":"http://www.georgiapower.com/"
}

And here is an example of the results coming back for an LSE with its extended fields included:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

{
    status: "success",
    count: 1,
    type: "LoadServingEntity",
    results: [
    {
        lseId: 734,
        name: "Pacific Gas & Electric Co",
        code: "14328",
        websiteHome: "http://www.pge.com/",
        offeringType: "Bundle",
        ownership: "INVESTOR",
        serviceTypes: "ELECTRICITY",
        totalRevenues: 11582000,
        totalSales: 83902268,
        totalCustomers: 5213528,
        residentialServiceTypes: "ELECTRICITY",
        residentialRevenues: 4729295,
        residentialSales: 30871669,
        residentialCustomers: 4574094,
        commercialServiceTypes: "ELECTRICITY",
        commercialRevenues: 5486004,
        commercialSales: 38534089,
        commercialCustomers: 638387,
        industrialServiceTypes: "ELECTRICITY",
        industrialRevenues: 1366701,
        industrialSales: 14496510,
        industrialCustomers: 1047,
        transportationServiceTypes: null,
        transportationRevenues: 0,
        transportationSales: 0,
        transportationCustomers: 0,
        billingPeriodRepresentation: {
          fromDateOffset: 0,
          toDateOffset: -1,
          style: "InclusiveToDate"
        }
    }]
}

Billing Period Representation

There is more than one way to represent a billing period. The Billing Period Representation object encapsulates how a billing period is represented for a given LSE.

We represent date ranges in what we call “Genability-style”, which matches ISO 8601’s “start/end” representation of time intervals.

The Billing Period Representation has the following data structure.

Name Type Fields Description
fromDateOffset Integer M The number of days to add to a Genability-style fromDate to obtain the LSE’s start of a billing period.
toDateOffset Integer M The number of days to add to a Genability-style toDate to obtain the LSE’s end of a billing period.
style String M Our name for this particular style of a Billing Period Representation.

The different styles

A Genability-style billing period is represented by two dates: the very first date of the billing period, and the date after the last day in the billing period. For instance, January 2015 would be represented as 2015-01-01 through 2015-02-01. The style for this is GenabilityStyle. Most utilities use this style, and it matches the style of our API. SCE (Southern California Edison) uses this style.

Another common style is what we call InclusiveToDate and this may seem more intuitive. In this style, the toDate is included in the billing period. So, for example, January 2015 would be represented as 2015-01-01 through 2015-01-31. PG&E (Pacific Gas & Electric) uses this style.

An unusual style that SDG&E (San Diego Gas & Electric) uses we call ExclusiveFromDateAndInclusiveToDate; the toDate is included in the billing period but the fromDate is not. So, for example, January 2015 would be represented as 2014-12-31 through 2015-01-31. As far as we know, no other LSE uses this style.

The other style you’ll see is Unknown, which means that we have not confirmed what style the LSE uses. If the style is Unknown, we assume that it is Genability-style.

Example

If you request the information for an LSE with its extended fields included, you will see this field at the end:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
    status: "success",
    count: 1,
    type: "LoadServingEntity",
    results: [
    {
        lseId: 734,
        name: "Pacific Gas & Electric Co",
        lseCode: "PGE",
        ...
        billingPeriodRepresentation: {
          fromDateOffset: 0,
          toDateOffset: -1,
          style: "InclusiveToDate"
        }
    }]
}

In this example, the toDateOffset is -1, which means that you must add this value to (ie subtract one day from) a Genability-style date to obtain the PG&E toDate. Conversely, you must subtract that value from (ie add one day to) the end date of a PG&E billing period to obtain the Genability-style toDate. For instance, if you have a PG&E bill from March 8th, 2015 through April 7th, 2015 (31 days), the equivalent Genability-style date range is 2015-03-08 through 2015-04-08.

Get a List of Load Serving Entities

This allows you to search for a set of LSE’s and get them back as a list of LoadServingEntity objects in the standard response format. Use the searchString parameter to specify the full or partial name of the LSE you want to retrieve. By default this does a “contains” search. Use the startsWith and endsWith boolean parameters to add more filters to the results.

Resource URI

GET /rest/public/lses

Request Parameters

Along with the standard pagination parameters, searching and sorting parameters, and the required security parameters, the following parameters are available as part of the request:

Name Type Description
searchOn String This is from the standard searching and sorting parameters. You can search within one or more of the attributes within the LSE object (see above). When search is specified but searchOn is not specified, the default field is name. (Optional)
zipCode String (Optional but Recommended) zip or post code where you would like to see a list of LSEs for (e.g. 5 digit ZIP code for USA). Most countries have regional, not national, Utility Service Areas. When populating this field you should also populate country too.
postCode String Alias for zipCode, you can use either.
country ISO Country Code Use this when passing in a zipCode or postCode, and set it to the ISO Country Code of your zipCode or postCode since some countries use the same format (Optional)
ownerships Comma Separated String Filter results by the type of ownership structure for the LSE. Values include "INVESTOR", "COOP", "MUNI", but see ownership field above for complete list. (Optional).
serviceTypes Comma Separated String Filter results to LSEs that just offer this service type to a customer class. Valid values include "ELECTRICITY" and "SOLAR_PV" (Optional).
residentialServiceTypes Comma Separated String Filter results to LSEs that just offer this service type to their residential customers. Valid values include "ELECTRICITY" and "SOLAR_PV" (Optional).
commercialServiceTypes Comma Separated String Filter results to LSEs that just offer this service type to their commercial (business) customers. Valid values include "ELECTRICITY" and "SOLAR_PV" (Optional).
industrialServiceTypes Comma Separated String Filter results to LSEs that just offer this service type to their industrial customers. Valid values include "ELECTRICITY" and "SOLAR_PV" (Optional).
transportationServiceTypes Comma Separated String Filter results to LSEs that just offer this service type to their transportation customers. Valid values include "ELECTRICITY" and "SOLAR_PV" (Optional).

Example 1 : Find residential electricity utilities for a zipcode

GET /rest/public/lses?zipCode=94105&country=US&residentialServiceTypes=ELECTRICITY&fields=ext

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
   "status": "success",
   "count": 1,
   "type": "LoadServingEntity",
   "results": [
      {
         "lseId": 734,
         "name": "Pacific Gas & Electric Co",
         "code": "14328",
         "websiteHome": "http://www.pge.com/",
         "offeringType": "Bundle",
         "ownership": "INVESTOR",
         "serviceTypes": "ELECTRICITY",
         "totalRevenues": 11582000,
         "totalSales": 83902268,
         "totalCustomers": 5213528,
         "residentialServiceTypes": "ELECTRICITY",
         "residentialRevenues": 4729295,
         "residentialSales": 30871669,
         "residentialCustomers": 4574094,
         "commercialServiceTypes": "ELECTRICITY",
         "commercialRevenues": 5486004,
         "commercialSales": 38534089,
         "commercialCustomers": 638387,
         "industrialServiceTypes": "ELECTRICITY",
         "industrialRevenues": 1366701,
         "industrialSales": 14496510,
         "industrialCustomers": 1047,
         "transportationServiceTypes": null,
         "transportationRevenues": 0,
         "transportationSales": 0,
         "transportationCustomers": 0
      }
   ]
}

Example 2 : Find based on wildcard

This is good for a type-ahead scenario.

GET /rest/public/lses?&search=Pacific

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{
   "status":"success",
   "count":4,
   "type":"LoadServingEntity",
   "results":[
      {
         "lseId":734,
         "name":"Pacific Gas & Electric Co",
         "code":"14328",
         "websiteHome":"http://www.pge.com/"
      },
      {
         "lseId":1164,
         "name":"Sierra Pacific Industries Inc",
         "code":"17164",
         "websiteHome":null
      },
      {
         "lseId":1165,
         "name":"Sierra Pacific Power Co",
         "code":"17166",
         "websiteHome":"http://www.nvenergy.com/"
      },
      {
         "lseId":3142,
         "name":"Pacific Power",
         "code":"14354",
         "websiteHome":"http://www.rockymountainpower.net/index.html"
      }
   ]
}

Get One Load Serving Entity

This allows you to retrieve one LSE.

Resource URI

GET /rest/public/lses/{lseId}

Example

GET /rest/public/lses/2756

1
2
3
4
5
6
7
8
9
10

{
  "status": "success",
  "count": 1,
  "type": "LoadServingEntity",
  "results": [{
    "lseId": 2756,
    "name": "Georgia Power Co",
    "code": "7140",
    "websiteHome": "http://www.georgiapower.com/"}]
}