Web Services

Documentation » Fetch all Utility Companies

https://api.openei.org/utility_companies?params

The /utility_companies endpoint returns a list of all utility companies with an Energy Informaion Administration ID and their aliases. For example, Xcel Energy of Colorado is an alias for Public Service Co of Colorado, so both Xcel Energy of Colorado and Public Service Co of Colorado will appear seperately in the returned list.

You'll need an API key to send a request. You can request a free API key using our signup form.

Alternatively, we also support a webpage where you can view all EIA Utility Companies and Aliases without using the API.

You are viewing documentation for version 2 of the API. You can also view other versions:

  • Version 1: Unsupported. Includes optional parameters limit, offset, callback, detail, and debug.
  • Version 3: Includes optional paramters callback, scope, and debug.

    • On this Page

    Standard Request

    The request URL provides the endpoint where your request will be sent. You'll need to send a GET request to:

    https://api.openei.org/utility_companies?parameters

    You'll replace parameters with any of the request parameters. All requests must include a version, format, and api_key.

    Minimum Request Example

    GET https://api.openei.org/utility_companies?version=latest&format=json&api_key=YOUR_API_KEY

    To retrieve a list of all companies:

    • Replace latest with the version of the API you would like to use.
    • Replace json with the format you would like to recieve your response in.
    • Replace YOUR_API_KEY with your API key.

    Request Parameters

    Parameter Required Value Description
    version Yes
    Options: latest, 1, 2, or 3
    		Choose which version of the API you would like to use. We reccomend using the latest version.
    format Yes
    Options: json, or json_plain

    The format determines how the response will be output. The format parameter will be disregarded if the debug parameter is set.

    api_key Yes
    Type: String

    You can request a free API key using our signup form.
    callback No
    Type:String
    		callback=<mycallback> — set mycallback as the json callback.
    debug No
    None
    		Print the ask query sent to the server.

    Response Fields

    Field Value Description
    label
    Type: string

    The page label is the last part of the web page path.

    For example, for page https://apps.openei.org/USURDB/rate/view/539fc9d7ec4f024d2f53f5b6, the page label is 539fc9d7ec4f024d2f53f5b6.
    uri
    Type: URI

    The link to the page in the URDB where the utility company is listed.

    Examples

    Get a list of utility companies in JSON format

    Request

    GET https://api.openei.org/Utility_companies ?version=2&format=json&limit=3&api_key=YOUR_API_KEY

    Be sure to:

    • Set the version to the version of the API you would like to use.
    • Replace YOUR_API_KEY with your API key.
    • Set the limit to the number of records you would like returned.

    Response

     1
 2
 3
 4
 5
 6
 7
 8
    		 
    {"properties": {},
      "items": [
          {"label": "3 Phases Energy Services",
           "uri":"https://openei.org/wiki/3 Phases Energy Services"},
          {"label": "4-County Electric Power Assn",
           "uri":"https://openei.org/wiki/4-County Electric Power Assn"},
          {"label": "A & N Electric Coop",
           "uri":"https://openei.org/wiki/A & N Electric Coop"}]

    Print the ask query sent to the server

    Request

    GET https://api.openei.org/Utility_companies ?version=2&format=json&api_key=YOUR_API_KEY&debug

    Be sure to:

    • Set the version to the version of the API you would like to use.
    • Replace YOUR_API_KEY with your API key.

    Response

          
    [URL: https://openei.org/w/api.php?
    
      
    [POST CONTENT: cmtitle=Category%3AEIA%20Utility%20Companies%20and%20Aliases&action=query&list=categorymembers&cmprop=title&cmnamespace=0&cmlimit=10000

    Errors

    Standard errors may be returned. In addition, the following service-specific errors may be returned:

    HTTP Status Code Description
    400 Invalid Request — One or more parameters did not pass validation or a parameter may be missing. Check the error section of the response to see how the request URL should be modified to address the error.
    500 A problem occurred on the server-side. This is likely due to a failure of a downsteram service. The request cannot be processed at this time.

    Additional Resources