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 territories that they operate in. Sometimes they operate in more than 1.
  • 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 Whether the offerings are bundled or one of energy or delivery.
ownership String E Ownership structure. Most common values are "INVESTOR", "COOP", "MUNI". Other 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 local currency (e.g. USD).
totalSales Integer E Annual total sales for the appropriate unit of quantity (e.g. 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 local currency (e.g. USD).
residentialSales Integer E Annual residential sales for the appropriate unit of quantity (e.g. 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 local currency (e.g. USD).
commercialSales Integer E Annual commercial sales for the appropriate unit of quantity (e.g. 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 local currency (e.g. USD).
industrialSales Integer E Annual industrial sales for the appropriate unit of quantity (e.g. 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 local currency (e.g. USD).
transportationSales Integer E Annual transportation sales for the appropriate unit of quantity (e.g. MWh).
transportationCustomers Integer E Transportation customer count.
billingPeriodRepresentation BillingPeriodRepresentation E Details about how the LSE represents billing periods.

Here’s an example in JSON of an LSE.

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

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

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

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
{
   "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
{
   "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
{
  "status": "success",
  "count": 1,
  "type": "LoadServingEntity",
  "results": [{
    "lseId": 2756,
    "name": "Georgia Power Co",
    "code": "7140",
    "websiteHome": "http://www.georgiapower.com/"}]
}