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 1 of the API. This version is currently unsupported. You can also view other versions:

  • Version 2: Includes optional paramters callback, 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, csv, json_plain, or list (experimental)

      The format determines how the response will be output.
    • If format=csv, include the 'realheadernames' variable to return OpenEI semantic property header names; assume simple header names if realheadernames variable is not set.
    • 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.
    limit No
    Type: Integer
    		 Maximum record count is 1000.
    offset No
    Type: Integer
    Default:0
    		 The offset from which to start retrieving records.
    callback No
    Type:String
    		callback=<mycallback> — set mycallback as the json callback.
    detail No
    Type:String
    Default:minimal
    Options: full, basic or minimal"
    • detail=full - returns every variable possible. Since this results in a lot of data that can time-out returning to your server, use a limit=500 and set an offset (e.g. 501) if you want more data. Variables are set based on a manual update from the Template:_______ page, which shows all variables of interest that the form entry uses and the wiki displays.
    • Compare to detail=basic and detail=minimal, which is the default.
    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.
    type
    Type: string

    type=Utility_companies

    Examples

    Get a list of utility companies in JSON format

    Request

    GET https://api.openei.org/Utility_companies ?version=1&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
9
10
11
    		 
    {"properties": {},
      "items": [
          {"label": "3 Phases Energy Services",
           "uri":"https://openei.org/wiki/3 Phases Energy Services",
           "type":"EIA_Utility_Companies_and_Aliases"},
          {"label": "4-County Electric Power Assn",
           "uri":"https://openei.org/wiki/4-County Electric Power Assn",
           "type":"EIA_Utility_Companies_and_Aliases"},
          {"label": "A & N Electric Coop",
           "uri":"https://openei.org/wiki/A & N Electric Coop",
           "type":"EIA_Utility_Companies_and_Aliases"}]

    Get a list of utility companies in CSV format

    Request

    GET https://api.openei.org/utility_companies?version=1&format=csv&limit=6&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

    PageName
"3 Phases Energy Services"
"4-County Electric Power Assn"
"A & N Electric Coop"

    Print the ask query sent to the server

    Request

    GET https://api.openei.org/Utility_companies ?version=1&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