Quick Start

This quickstart guide is the place to begin if you are brand new to the Genability Signal APIs. Here we go over the basics of getting credentials, making a request, and getting some data back. So without further ado, let’s get started.

Each and every request to the Genability Signal APIs need to be authenticated, which is how we know who is making the call and how we can keep your data private. If you don’t have one yet, your first step is to create your own Genability User Account. So please go do it now!

Create or Join an Org

Once you have your own User Account, you then need to either join an existing Organization, or create a new one. An Organization is your team or company (we often call them “Org’s” for short). Each API call to Genability is associated with one Org. Furthermore, the APIs that store and share data do so at an Org level; only the Org that created the data can later see and manage it. We have a 14 day free trial if your company or team is not yet a paying customer or does not yet have an Org.

So let’s give your User Account membership to an Org. Log in to Dash and navigate to the Org Settings page. Here you have the option of creating a brand new Org (including inviting other team members to it), or you can request membership to an existing Org that matches your email domain, where one already exists. Note your User Account can be a member of more than one Org if that makes sense for you. Go ahead and either create an Org, or request membership of one. You will get a confirmation email when the Org’s administrator approves your request.

Once you belong to an Org, you can move on to the next step.

Create an API Application

The actual credentials you use when making a Genability Signal API call belong to an Application (or App for short). This App in turn belongs to the Org from above. Often our customers will create multiple Apps, say, for test vs production or for mobile vs web. You can have as many Apps as you want. You manage your Organizations Apps in the Org Applications page in Dash. Either click on the “Create Application” button or select one of the existing Apps that you’d like to use credential for.

If you are on a free trial, you will need to enter a valid credit card in order to create an Application and get an API Key. Just remember to cancel your subscription before the end of the trial if you do not want to be billed.

API Credentials & Authentication

Each App has an appId and and appKey. The appId is equivalent to your applications user name. The appKey is like its password, and as such should be kept private and should be changed from time to time. Both values are automatically generated by Genability and together they are used to authenticate every API requests. To pass us these two value, you’ll use HTTP Basic Auth. How to do this is described in detail on our API Security page.

Make your first request

OK, enough messing about! Let’s make an API call. From the command line (swapping out your own appId and appKey) …

curl -u APP_ID:APP_KEY https://api.genability.com/rest/echo/hello

… which should return the following …

1
{"status":"success","count":1,"type":null,"results":["Hello World","Hello World!"]}

The above is an API call to our Echo API. The endpoint is useful for getting going, including making sure your code handles validation and exception errors. We suggest coming back to this API once you are deeper into integrating. For now, on with the Quick Start!

Normally, you would create the authentication HTTP header programatically. However, if you paste the above URL into your favorite web browsers address bar, you can put your appId and appKey in the username and password fields of the Basic Authentication dialog when it pops up. If it works, you get JSON back!

Understanding the response

All our REST APIs return Javascript Object Notation (JSON). In addition, all our REST APIs return a response in a standard “envelope” that has the main results in the results property, in a structure that is specific to that endpoint (for example a simple array with the string Hello World in it for this endpoint). Surrounding that are standard fields that tell you a few other things about what you got back. For instance the count tells you how many items matched, and the type gives you details of what the structure in the results is. Other fields help with pagination, what the status was etc. You can see all the standard response fields in the REST Response page.

1
2
3
4
5
6
7
8
9
{
  "status": "success",
  "count": 1,
  "type": null,
  "results": [
    "Hello World",
    "Hello World!"
  ]
}

Find your home’s electric utility

Now we are up and running and have made our first request, let’s do something a bit more meaningful. Let’s use the Load Serving Entities API. A Load Serving Entity, or LSE, is a Utility or any other entity that services the load of a building (hence the name). Let’s get a list of all of the residential electricity LSEs for your ZIP or post code by using the following request:

https://api.genability.com/rest/public/lses?zipCode=94105&residentialServiceTypes=ELECTRICITY&sortOn=totalCustomers&sortOrder=DESC&fields=ext

What does this request mean? Broken down from left to right …

Request Section	Description
`https://`	We recommend using https for all API traffic.
`api.genability.com`	Our production API environment is at api.genability.com. You’ll probably always make calls to this server.
`/rest`	If you look in the path of this request, you’ll see it starts with /rest. Almost all of our APIs are RESTful in nature.
`/public`	this denotes the version. Its typically either `v1` or `public`	Versioning details
`/lses`	This part of the request path denotes the actual endpoint you are calling. In this case Get LSEs.	API Reference
`zipCode=94105`	The call will only find LSEs that are active in the ZIP code `94105`, which is the ZIP code of Genability’s office.
`residentialServiceTypes=ELECTRICITY`	Genability tracks different types of LSEs, including utilities that just provide service to businesses, those that just provide natural gas, rooftop and community solar companies, agencies that provide incentives and rebates and more. In our case, we just want utilities that provide electricity to residential customers.
`sortOn=totalCustomers&sortOrder=DESC`	Any API endpoint that can return more than one item in its response has the ability for the caller to request how the results are sorted. In this case we wanted to put the most likely utility at the top of the list, and the least at the bottom. So we sorted on the `totalCustomers` field.	Sorting details.
`fields=ext`	This tells the API to return the extended set of fields for this queries results, rather than the regular set. You can use this parameter in a lot of different places in order to get back additional information from the API. In fact, there are three different options for the amount of data that you want the API to return: standard, which is what gets returned by default, `ext`ended, and `min`inimum. You can read more about them, along with other standard request parameters.	Fields details.

Learn all about our standard REST parameters on the REST Requests page.

Here’s the response you get back when making the above call:

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": 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": 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": 100773,
      "name": "CleanPowerSF",
      "lseCode": "CPSF",
      "code": "",
      "websiteHome": "http://sfwater.org/index.aspx",
      "offeringType": "Bundle",
      "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": null,
      "transportationRevenues": 1,
      "transportationSales": 1,
      "transportationCustomers": 1,
      "billingPeriodRepresentation": {
        "fromDateOffset": 0,
        "toDateOffset": -1,
        "style": "InclusiveToDate"
      }
    }
  ],
  "pageCount": 25,
  "pageStart": 0
}

As you can see, we got back a list with three residential electricity utilities, each with their details populated in the results list. Also, the type property is populated in this call. It tells us that in the results we have JSON that conforms to the LoadServingEntity structure. In many cases, we have types that are reused across different endpoints.

Get Data About a Single Utility

Genability’s API endpoints follow a pattern that should be familiar to people who have worked with REST APIs before. That pattern is:

To get a list of every instance of a particular object, make a GET request to the root of that object’s service. For example, to get every LSE you would make a GET request to /rest/v1/lses.
To get a particular instance, add a URL parameter to your request that specifies which instance you’re interested in. To get the data for PG&E, that request would look like this:

https://api.genability.com/rest/public/lses/734

Notice that we added the URL parameter 734 onto the end of our request. This is the unique ID of PG&E’s LSE record, the lseId, which we got from the response to our last request. The LSE summary for PG&E looks like the following. Again, note that we reuse the LoadServingEntity type. However, for this call we did not ask for fields=ext so did not get back the extended fields:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "status": "success",
    "count": 1,
    "type": "LoadServingEntity",
    "results": [
    {
        "lseId": 734,
        "name": "Pacific Gas & Electric Co",
        "code": "14328",
        "websiteHome": "http://www.pge.com/"
    }]
}

Congratulations!

You made it though the Quick Start!

Where to next?

Now you’ve got some API calls under your belt, you’re ready to move on and learn more about building new energy applications. We suggest you now review our Tutorials, and pick the one that best matches your use case. Our Tutorials are step by step guides that tell you the common approach to a given problem. All of our Tutorials are described in this page.

Sign up for a User Account