Help:US Utility Rate Database API Tutorial

From Open Energy Information

Using the OpenEI Application Programming Interface (API)

This document attempts to explain how to use the RESTful Web API associated with the Utility Rate Database. Representational State Transfer (REST) is software architecture for distributed computer systems like the World Wide Web and has become the predominant web API design model. REST Documentation on OpenEI provides information about the use of the OpenEI API.

Requesting Utility Rates Data with OpenEI API

Requests to the OpenEI API can be made in the address bar of your internet search engine. The following is the base of the "request url" that allows a user to access utility rate data using the OpenEI API.

http://en.openei.org/services/rest/utility_rates

Any and all requests for rate data will begin with the string above plus a ?, and then parameters (defined below) that follow the ? will define what rate data the API will grant in its response.

This request url (uri) as well as the descriptions for entering parameters of the request can be accessed here.

There are a few basic requests that can be made to extract rate data from OpenEI. A user or application can extract rate data for a single rate, for a single utility, or a specific number of rates without reference to any specific rate or utility.

Required Parameters for all Utility Rates Data Requests

The API requires two parameters, version and format, regardless of the type of request being made by the user or application. All request parameters will be entered after the ? in the base request url and each parameter is separated by an &. The order of the parameters is irrelevant.

  1. Version is one of the parameters the API requires. Currently, there are two versions of the API, version 2 and 3. The request can be made for version 2, 3 or latest version, which in this case would be version 3. In order to use the version 3 of the API, a user or application would need to write version=latest or version=3.
    1. Request for version 3 API output (two possible requests):

      http://en.openei.org/services/rest/utility_rates?version=3

      http://en.openei.org/services/rest/utility_rates?version=latest
  2. Format is a required parameter and determines the file type the API will use in its respone to the request. There are a couple of different file formats that a user or application can request. They include json, csv, or json_plain.

    The json file, implemented by format=json, returns the rate data in a single string that can be read in your internet browser, text document reader, and is most likely to be useful if machine read.
    1. Request for API output in json_plain files:

      The json_plain file, implemented by format=json_plain, will be viewed immediately in your internet browser, and properties are more readably accessible by human medium. The json_plain file format is superior for testing the API, because data is clearly presented immediately in the internet browser and each property is returned on a separate line.

      http://en.openei.org/services/rest/utility_rates?version=latest&format=json_plain
    2. Request for API output in csv files:

      The csv file, implemented by format=csv will return a csv file which is the most desirable for immediate manual analysis using Microsoft Excel and can be easily imported to statistical software applications for analysis.

      http://en.openei.org/services/rest/utility_rates?version=latest&format=csv


Parameters that Define the Content of the Responses to Utility Rates Requests

  1. Detail is an optional parameter that determines how much of the data stored for any or each rate is returned by the request. There are two specifications of the detail parameter: minimal and full. The minimal detail specification, detail=mimimal, returns only the label (unique ID), uri, approval status, rate name, effective (start) date, end date, utility name, sector, description, source and source parent properties. The full detail specification, detail=full, returns all properties stored for the specified rates. The detail parameter is only explicitly optional because its omission from the request implies a default to minimal detail.

    Using the minimal detail parameter would be useful to get the labels for all the rates applicable to a specific utility.
    1. Request for API output in json_plain files with minimal detail (2 possible requests):

      http://en.openei.org/services/rest/utility_rates?version=latest&format=json_plain&detail=minimal

      http://en.openei.org/services/rest/utility_rates?version=latest&format=json_plain
    2. Request for API output in json_plain files with full detail:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=json_plain&detail=full
    3. Request for API output in csv files with full detail:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=csv&detail=full
  2. Getpage is an optional parameter, implemented by getpage="rate_label", that allows the user or application to request the data for a specific rate if you know the rate’s label value.
    1. Request for API output for City Water and Light Plant – General Service Large ate in json_plain file with full detail:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=json_plain&detail=full&getpage=539f70f6ec4f024411ece0c1
    2. Request for API output for City Water and Light Plant– General Service Large rate in csv file with full detail:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=csv&detail=full&getpage=539f70f6ec4f024411ece0c1
  3. Ratesforutility is an optional parameter, implemented by ratesforutility="utility_company_name", that returns data for all the rates entered for the utility named.
    1. Request for API output for all City Water and Light Plant rates in json_plain file with full detail:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=json_plain&detail=full&ratesforutility=City_Water_and_Light_Plant
    2. Request for API output for all City Water and Light Plant rates in csv file with full detail:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=csv&detail=full&ratesforutility=City_Water_and_Light_Plant
  4. Offset and Limit are parameters that are used in combination and return a batch of rates stored in the database based on the order that the rates are stored (ascending label value). The Offset parameter, implemented by offset=n, requests the API to return rates beginning with the n+1th rate in the database. The limit parameter, implemented by limit=m, defines how many rates to return in the batch starting from the offset.
    1. Request for API output for the full detail of 500 rates beginning with the 1st rate in a csv file:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=csv&detail=full&offset=0&limit=500
    2. Request for API output for the full detail of 500 rates beginning with the 501st rate in a csv file:

      http://en.openei.org/services/rest/utility_rates?version=latest&format=csv&detail=full&offset=500&limit=500


Requesting Utility Company Data with OpenEI API

Requests to the OpenEI API for utility company data can be made using the address bar of an internet search engine. The following is the base of the "request url" that allows a user to access utility company data using the OpenEI API.

http://en.openei.org/services/rest/utility_companies

Any and all requests for utility company data will begin with the string above, and the parameters that follow the ? will define what utility companies data the API will grant in its response.

This request url as well as the descriptions for entering parameters of the request can be accessed here.

Required Parameters for all Utility Company Data Requests

The API request for utility company data requires two parameters, version and format, regardless of the type of request being made by the user or application just as the utility rates request requires. See Required Parameters for all Utility Rates Data Requests above.

  1. Request for version 2 API output in json_plain files:

    http://en.openei.org/services/rest/utility_companies?version=2&format=json_plain
  2. Request for version 2 API output in csv files:

    http://en.openei.org/services/rest/utility_companies?version=2&format=csv


Parameters that Define the Content of the Responses to Utility Company Requests

  1. Detail is an optional parameter that determines how much of the data stored for any or each utility company is returned by the request. There are three specifications of the detail parameter; minimal, basic and full. More information about the specifications of the detail parameter is included above.
    1. Request for version 2 API output in json_plain files with full detail:

      http://en.openei.org/services/rest/utility_companies?version=2&format=json_plain&detail=full
    2. Request for version 2 API output in csv files with full detail:

      http://en.openei.org/services/rest/utility_companies?version=2&format=csv&detail=full
  2. Offset and Limit are parameters that are used in combination and return a batch of utility companies stored in the database based on the order that the companies are stored. The Offset parameter, implemented by offset=n, requests the API to return rates beginning with the n+1th rate in the database. The limit parameter, implemented by limit=m, defines how many rates to return in the batch starting from the offset.
    1. Request for version 2 API output for the full detail of 500 utility companies beginning with the 1st rate in a csv file:

      http://en.openei.org/services/rest/utility_companies?version=latest&format=csv&detail=full&offset=0&limit=500
    2. Request for version 2 API output for the full detail of 500 rates beginning with the 501st rate in a csv file:

      http://en.openei.org/services/rest/utility_companies?version=latest&format=csv&detail=full&offset=500&limit=500