Explore the latest updates and features in our new Signal Product Documentation and Switch Product Documentation.
Please note, this site’s retirement date will be announced soon, so make sure to update your bookmarks.
Find your customer’s utility
Find your customer’s utility
The first step we recommend is to determine your customer’s utility. Most homes and businesses know their utility even if they don’t know their tariff rate plan. We collect electricity utility and tariff data across the USA, Canada, and Mexico. These utilities include investor-owned utilities, municipalities, and cooperatives.
At Genability:
- We maintain data on which utilities operate in which locations using Territories that define utility service areas.
- We track all the tariff rate plans that a utility has, including how many customers are on that plan and whether it’s the default option or not. At last, we have tariffs for about 98% of the customers in the countries we cover
The easiest way to see what utilities are available for your customer, is by searching by postal code or zip code. Here’s an example for our office location:
GET /rest/public/lses?zipCode=94105&country=US&residentialServiceTypes=ELECTRICITY
Some key things to note about the request we are sending:
- Always pass in the ISO Country Code along with your customer’s zip code to ensure the results you get are relevant. Some countries have matching zip codes.
- The
residentialServiceTypes=ELECTRICITYparameter at the end of the URL makes sure you only get back Load Serving Entities or LSEs that serve power to residential customers. - Without
residentialServiceTypes=ELECTRICITY, you would retrieve solar providers and other non-electricity LSEs from the database. - The
commercialServiceTypesandindustrialServiceTypesparameters are available for commercial and industrial customers, respectively.
Sending this request returns the following response:
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
{
"status": "success",
"count": 3,
"type": "LoadServingEntity",
"results": [
{
"lseId": 1074,
"name": "San Francisco City & County of",
"code": "16612",
"websiteHome": "http://www.sfgov.org/index.asp"
},
{
"lseId": 734,
"name": "Pacific Gas & Electric Co",
"code": "14328",
"websiteHome": "http://www.pge.com/"
},
{
"lseId": 100773,
"name": "CleanPowerSF",
"code": "",
"websiteHome": "http://sfwater.org/index.aspx"
}
],
"pageCount": 25,
"pageStart": 0
}
Analyzing the response allows us to learn a few things:
- There are currently three different utilities being returned for zip code 94105, which is a zip code in San Francisco, California. This means customers in this area may have three utilities to choose from, as shown by the value of the
countfield. This can occur for the following reasons:- This zip code could be located on the border of 2 or more electricity service areas, and service area boundaries don’t map exactly to zip code boundaries. We work hard to make sure that our zip code to utility mapping is accurate and up-to-date.
- The location you provided might be a location where there is a choice of utilities, which is usually the case for deregulated markets or community choice aggregation markets.
The lseId is the primary field we are trying to find. It is a unique Genability ID (primary key) for each Load Serving Entity that is returned. Once you know the lseId for a utility, it can be used in a number of other APIs as a filter for records tied to that utility. We will be using this lseId in the next step in order to get matching tariffs for a certain utility.
What if a recognizable utility is not returned?
On some occasions, there will be no recognizable utilities returned by your zip code search. This may have happened because the zip code you provided is not a valid zip code, or the utilities name has changed. This is a rare occurrence, but one you must be aware of.
If your utility search using a zip code or address was unsuccessful, you have two options.
The first is to search by the utility code if this is known. To do this, provide the search and searchOn parameters.
GET /rest/public/lses?country=US&residentialServiceTypes=ELECTRICITY&search=16612&searchOn=code
Alternatively you can search by the name of the utility. If you know the utility name is likely to contain “San Francisco”, you can search for this like so:
GET /rest/public/lses?country=US&residentialServiceTypes=ELECTRICITY&search=San%20Francisco&searchOn=name
Note, we replaced the space in “San Francisco” with “%20” resulting in the final search parameter of “San%20Francisco”. This is called URL encoding.
Executing either of these requests will return the same response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"status": "success",
"count": 1,
"type": "LoadServingEntity",
"results": [
{
"lseId": 1074,
"name": "San Francisco City & County of",
"code": "16612",
"websiteHome": "http://www.sfgov.org/index.asp"
}
],
"pageCount": 25,
"pageStart": 0
}
If neither of these options provides the utility you expect to see, you can contact our support team.
Getting more details about the utility
Our API calls have an option to return a minimum, standard, or an extended set of data in the response. In the previous API call to get our local utilities, the standard response fields were sufficient to find our utility (and our customer) PG&E. However, if we had included the optional argument, fields=ext, an extended set of information about each utility would have been returned.
GET /rest/public/lses?zipCode=94105&country=US&residentialServiceTypes=ELECTRICITY&fields=ext
Executing this request generates the following response:
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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
{
"status": "success",
"count": 3,
"type": "LoadServingEntity",
"results": [
{
"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": 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": 100773,
"name": "CleanPowerSF",
"lseCode": "CPSF",
"code": "",
"websiteHome": "http://sfwater.org/index.aspx",
"offeringType": "Energy",
"ownership": "COOP",
"serviceTypes": "ELECTRICITY",
"totalRevenues": 1,
"totalSales": 1,
"totalCustomers": 1,
"residentialServiceTypes": "ELECTRICITY",
"residentialRevenues": 1,
"residentialSales": 1,
"residentialCustomers": 1,
"commercialServiceTypes": "ELECTRICITY",
"commercialRevenues": 1,
"commercialSales": 1,
"commercialCustomers": 1,
"industrialServiceTypes": "ELECTRICITY",
"industrialRevenues": 1,
"industrialSales": 1,
"industrialCustomers": 1,
"transportationServiceTypes": "ELECTRICITY",
"transportationRevenues": 1,
"transportationSales": 1,
"transportationCustomers": 1,
"billingPeriodRepresentation": {
"fromDateOffset": 0,
"toDateOffset": -1,
"style": "InclusiveToDate"
}
}
],
"pageCount": 25,
"pageStart": 0
}
Note the extra detail this response contains. From analyzing this response we can learn the following information about the utilities returned.
Each of the utilities returned has a different ownership type:
| Name | Ownership Type | Explanation |
| San Francisco City & County of | "ownership": "MUNI" | Publicly owned utilities subject to local public control and regulation. |
| Pacific Gas & Electric Co | "ownership": "INVESTOR" | Investor-owned utility managed as a private enterprise. |
| CleanPowerSF | "ownership": "COOP" | Member-owned utility, which is managed on a non-profit basis. |
Other potential values for ownership include: FEDERAL, POLITICAL_SUBDIVISION, RETAIL_ENERGY_MARKETER, WHOLESALE_ENERGY_MARKETER, TRANSMISSION, and STATE.
Now that we know how to find the utility our customer is on, it is time to learn how to find the exact tariff that applies to our customer!