Quick Start

Overview

This quickstart guide is the place to look if you haven't done anything with the Genability API before. It goes over the basics of getting an App set up, making a request, and getting back some data. So without further ado, let's get started.

Get an API Key

If you haven't created a Genability App yet, go here to do so. Make sure to write down your app ID and key: you'll be using them a lot.

Get Data About Your Local Utility

Authenticate

In order to make any requests to the API, the first thing you need to do is authenticate. To do so, you'll need to use HTTP Basic Auth, as described on our Security page. Normally, you would authenticate in code and make the request programmatically. If you just want to see the data, though, you can put your credentials into your browser's username/password dialog and get a JSON response that way.

Make a Request

For this tutorial, we're going to be working with Load Serving Entities (LSEs -- our name for utilities). To get a list of all of the LSEs in your ZIP code, use the following request:

https://api.genability.com/rest/public/lses?zipCode=94105

In this case, we're using the ZIP code 94105, which is the ZIP code of Genability's office. Here's the response:

{
    "status": "success",
    "count": 7,
    "type": "LoadServingEntity",
    "results": [
    {
        "lseId": 1074,
        "name": "San Francisco City & County of",
        "code": "16612",
        "websiteHome": null
    },
    {
        "lseId": 100276,
        "name": "SunRun",
        "code": "IQ44576381",
        "websiteHome": "http://www.sunrunhome.com/"
    },
    {
        "lseId": 100280,
        "name": "Borrego Solar",
        "code": "IQ29897192",
        "websiteHome": "http://www.borregosolar.com/"
    },
    {
        "lseId": 100333,
        "name": "NRG Solar",
        "code": "IQ81598450",
        "websiteHome": "http://www.nrgsolar.com/"
    },
    {
        "lseId": 100334,
        "name": "ASHRAE",
        "code": "",
        "websiteHome": "https://www.ashrae.org/"
    },
    {
        "lseId": 734,
        "name": "Pacific Gas & Electric Co",
        "code": "14328",
        "websiteHome": "http://www.pge.com/"
    },
    {
        "lseId": 100281,
        "name": "State of California Incentives",
        "code": "",
        "websiteHome": null
    }],
    "pageCount": 25,
    "pageStart": 0
}

In this response you'll see that we actually got two things back: a Response and a list of LSE instances in the response's results property. All of the data returned back from the Genability API is wrapped in responses like this. This allows us to send back an informative message if, for example, the LSE that you're looking for doesn't exist. You can learn more about responses on their dedicated page.

So it turns out that there are actually seven different LSEs in this area. This is great if you're in an area with multiple utilities and you want the user to select from among them, but what we're really interested in here is the one that serves electricity to our office: Pacific Gas & Electric (PG&E).

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 ID of PG&E's LSE record, which we got from the response to our last request. The LSE summary for PG&E looks like this:

{
    "status": "success",
    "count": 1,
    "type": "LoadServingEntity",
    "results": [
    {
        "lseId": 734,
        "name": "Pacific Gas & Electric Co",
        "code": "14328",
        "websiteHome": "http://www.pge.com/"
    }]
}

Again, we get back a Response object and a list of results, even though there's actually only one result in this case. This particular result doesn't tell us very much that we didn't already know. Like before, it's enough to populate a dropdown list, but that's about it. What if we want a lot more information about PG&E? With the Genability API, that's easy. Just make a slight tweak to your request:

https://api.genability.com/rest/public/lses/734?fields=ext

Which returns:

{
    "status": "success",
    "count": 1,
    "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": 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
    }]
}

Now we're talking! What we've done is added a new query parameter to our request: ?fields=ext. This tells the API to return the extended set of fields for this query, 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: regular, which is what gets returned by default, extended, and mininimum. You can read more about them, along with other standard request parameters, on the Requests page.

Next Steps

Now you've got some API calls under your belt, you're ready to start on a savings analysis. The first step for any analysis is to create and populate an account. Check out our dedicated How-To!

  • Look in our Helper Libraries for some examples of using our APIs with Java.
  • Get familiar with handling common error responses by using our Echo method.
  • Using Google Chrome? Download Postman. You can use it to quickly test out the request parameters and response formats for all of our endpoints.
  • Not sure what to do next? Send us an email at support@genability.com.