Load Serving Entity

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/"}]
}