U.S. Energy Information Administration - EIA - Independent Statistics and Analysis

OPEN DATA

Committed to making energy data more accessible, understandable,
relevant, and responsive to your needs.

API Commands

EIA's API uses a modified RESTful architecture, where a separate URI is used for each query command with query string variables, both required and optional, providing input parameters. Two such query string input parameters apply to all commands:

api_key: Required. A valid API key is required and may be obtained from Registration
out: Optional. Valid values are “xml” or “json”. If missing or any other value, the API call will return JSON formatted output.

API Series Query

CORRECTIONS AND CHANGES

The fields "lat", "lon", and "iso3166" have been deprecated. The "lat" and "lon" fields are being replaced by a combined "latlon" field which is the latitude and longitude values separated by a comma. There is also a secondary field for latitude and longitude being added called "latlon2". The "iso3166" field is being replaced by "geography". It will return geographic information in the ISO3166 format. For data series that are comprised of multiple regions, a list of ISO3166 codes separated by a '+' will be returned. There is also a secondary geography field being called "geography2" (27 May 2014).
For series which are EIA projections, there will be a field called "lastHistoricalPeriod". Data points for periods after this are projections (27 May 2014).
Fields will only be returned if they have a value (27 May 2014).
Quarterly data format will be corrected to yyyyQq (26 Aug 2013).
The output "updated" field returned will follow the ISO 8601 formatting standard (26 Aug 2013).

ENHANCEMENTS

The new optional parameters "start" and "end" have been added to filter the data returned. These take values in the same format as the dates in the returned data. When "start" is used, values will be returned beginning with the provided value. When "end" is used, values will be returned ending with the provided value. The existing "num" parameter can be used in conjunction with the "end" parameter to return the n-values from an end point. The "num" parameter cannot be used in conjunction with the "start" parameter and an error will be returned when trying to do so (05 Jan 2015).
The list semicolon separated (';') list of series IDs for up to 100 series. It is recommended to use the POST protocol to transmit the series_id field if more than 10 series are requested in the single call (26 Aug 2013).
An optional "num" variable can specify the maximum number of most recent points returns (26 Aug 2013).
Output returns the series data along with the header information (23 Jan 2013).

Gets the series header and data consisting of the follow properties: name, series key, first date in series, last date in series, units long, units abbreviated, periodicity, last updated date, notes, and copyright. For the Electricity branch of the EIA API, the series' notes field is a concatenation of the data set's definition, the fuel filter's definition, and the sector's definition, and, (if it exists) the geography definition. The series name is similarly determined from the applicable data set and filter names.

Returns the series ID followed by the series data as an array of date-value pairs. Dates are formatted as yyyy, yyyyQq, yyyymm, yyyymmdd for annual, quarterly, monthly, and daily/weekly data respectively. Values are either numeric if valid, "null" is missing, "w" if withheld, or "*" is statistically insignificant. Additional codes may be defined in future releases.

http://api.eia.gov/series/?series_id=sssssss&api_key=YOUR_API_KEY_HERE[&num=][&out=xml|json]

series_id: Required. The series id (also called source key) is a case-insensitive string consisting of letters, numbers, dashes ("-") and periods (".") that uniquely identifies an EIA series. Multiple series can be fetched in a single request by using a semi-colon separated list of series id's. The number of series in a single request is limited to 100.

Sample output (whitespaces added below for readability):

{ "request":{ "command":"series", "series_id":"ELEC.GEN.ALL-AK-99.A" }, "series":[ { "series_id":"ELEC.GEN.ALL-AK-99.A" "name":"Net Generation : All Fuels : Alaska : All Sectors", "units":"thousand megawatthours", "f":"A", "unitsshort":"", "description":"Summation of all fuels used for electricity generation; All sectors; ", "copyright":"None", "source":"EIA, U.S. Energy Information Administration", "iso3166":"USA-AK", DEPRECATED "lat":"", DEPRECATED "lon":"", DEPRECATED "latlon":"43.5589,-91.2325", "latlon2":"43.5589,-91.2325", "geography":"USA-AK", "geography2":"USA-AK", "lastHistoricalPeriod":"2013", "start":"2001", "end":"2013", "updated":"2013-08-23T17:37:44-0400", "data":[ ["2012",6979.39223], ["2011",6871.03279], ["2010",6759.5757], ["2009",6702.15939], ["2008",6774.83438], ... } ]}

API Geoset Query

Gets a set of the series belonging to the geoset requested by geoset_id input parameter and matching the list of regions requested defined in the regions input parameter. If a series does not exist Only the series matching the regions requested are returned. The fields of each series returned is described in the series command documentation.

A geoset is a relational metadata structure that organizes time series into sets that can be mapped. The geoset command is used by free EIA Visualization Library to create embeddable interactive maps. The API's API Browser contains code snippets and live examples of how to map each geoset contained in the EIA data API. EIA's entire State Energy Data System, Coal, Electricity, International data sets are organized into geosets and can be map using the library. Follow the links for examples of how to use the EIA Visualization Library with no coding required.

Coders wanting to create their own visualization library can call the geoset command using the following parameters:

http://api.eia.gov/geoset/?geoset_id=sssssss&regions=region1,region2,region3,...&api_key=YOUR_API_KEY_HERE[&start=|&num=][&end=][&out=xml|json]

geoset_id: Required. The series id (also called source key) is a case-insensitive string consisting of letters, numbers, dashes ("-") and periods (".") that uniquely identifies an EIA series.

regions: Required. A semicolon-separated list of region codes requested. Series whose geoset_id and region fields match will be returned.

Sample output (whitespaces added below for readability):

{ "request":{ "command":"geoset", "series_id":"ELEC.GEN.ALL-99.A" }, "series":[ { "series_id":"ELEC.GEN.ALL-AK-99.A" "name":"Net Generation : All Fuels : Alaska : All Sectors", "units":"thousand megawatthours", "f":"A", "unitsshort":"", "description":"Summation of all fuels used for electricity generation; All sectors; ", "copyright":"None", "source":"EIA, U.S. Energy Information Administration", "latlon":"43.5589,-91.2325", "geography":"USA-AK", "start":"2001", "end":"2013", "updated":"2013-08-23T17:37:44-0400", "data":[ ["2012",6979.39223], ["2011",6871.03279], ["2010",6759.5757], ["2009",6702.15939], ["2008",6774.83438], ... } ]}

API Relation Query

Gets a set of the series belonging to the relation requested for the region requested. A relation is an EIA defined metadata structure that indicates breakdowns or details of summary statistics into composite statistics. Relations are defined between geosets, and therefore apply to all of the geoset's time series.

The relation command is used by free EIA Visualization Library to create embeddable interactive maps displaying these breakdowns. The API Browser contains code snippets and live examples of of interactive visualizations that how to create contained in the EIA data API. Relations can be found, when applicable, in EIA's State Energy Data System, Coal , Electricity, International data sets. Follow the links for examples of how to use the EIA Visualization Library to create interactive maps and charts using relationships (no coding required.)

Coders wanting to create their own visualization library can call the geoset command using the following parameters:

http://api.eia.gov/relation/?relation_id=rrrrrrr&region=region1&api_key=YOUR_API_KEY_HERE[&start=|&num=][&end=][&out=xml|json]

geoset_id: Required. The series id (also called source key) is a case-insensitive string consisting of letters, numbers, dashes ("-") and periods (".") that uniquely identifies an EIA series.

regions: Required. A semicolon-separated list of region codes requested. Series whose geoset_id and region fields match will be returned.

Sample output (whitespaces added below for readability):

{ "request":{ "command":"geoset", "series_id":"ELEC.GEN.ALL-99.A" }, "series":[ { "series_id":"ELEC.GEN.ALL-AK-99.A" "name":"Net Generation : All Fuels : Alaska : All Sectors", "units":"thousand megawatthours", "f":"A", "unitsshort":"", "description":"Summation of all fuels used for electricity generation; All sectors; ", "copyright":"None", "source":"EIA, U.S. Energy Information Administration", "latlon":"43.5589,-91.2325", "geography":"USA-AK", "start":"2001", "end":"2013", "updated":"2013-08-23T17:37:44-0400", "data":[ ["2012",6979.39223], ["2011",6871.03279], ["2010",6759.5757], ["2009",6702.15939], ["2008",6774.83438], ... } ]}

API Category Query

Gets name and id for a single category, and also lists its children categories' names and ids.

http://api.eia.gov/category/?api_key=YOUR_API_KEY_HERE[&category_id=nn][&out=xml|json]

category _id: Optional. A unique numerical id of the category to fetch. If missing, the API's root category is fetched.

Sample output (whitespaces added below for readability):

{ "request":{ "category_id":0, "command":"category" } "category":{ "category_id":"0", "parent_category_id":"371", "name":"Electricity", "notes":"", "childcategories":[ {"category_id":"1","name":"Net Generation"}, {"category_id":"1017","name":"Power Plant Level Data"}, ... ], "childseries":[] } }

API Series Categories Query

Gets a list of category names and IDs the series is a member of.

http://api.eia.gov/series/categories/?series_id=&api_key=YOUR_API_KEY_HERE[&out=xml|json]

series_id: Required. The series id (also called source key) is a case-insensitive string consisting of letters, numbers, dashes ("-") and periods (".") that uniquely identifies an EIA series.

Sample output (whitespaces added below for readability):

{ "request":{ "command":"series\/categories", "series_id":"ELEC.GEN.ALL-AK-99.A" }, "series_categories":[ { "series_id":"ELEC.GEN.ALL-AK-99.A", "categories":[ {"category_id":"1","name":"Net Generation"}, ... ] } ] }

API Updates Data Query

Many applications will need to maintain a copy of EIA data to drive heavy data-processing and republishing operations. The update query allows your application to efficiently stay current with EIA's data releases while staying within the Terms of Service agreement which prohibits excessive server requests, such as repeatedly requesting all the data series in the EIA API. Currently, the EIA API contains 465,000 electricity series organized into 39,000 categories. As we add petroleum, natural gas, international, and state estimates over the coming months, this number will swell to over a million series. Continuous requesting all the series in the EIA API may lead to a termination of your license key. The update query avoids this problem by allowing your application to find out if anything has been updated in electricity prices for example, and only quest data is the series have been updated using the series/data query.

Returns a paginated list of series in descending order by the series' last updated date (i.e. most recent updates first). Only the series_id and the series updated date are returned. If a category_id is specified, only series belonging to that category are checked. If a start category is not specified, the query defaults to the API's root category. If the optional variable "deep" is set to true, the entire branch of the category tree if checked for updates, otherwise only series belonging to the specified category are checked.

http://api.eia.gov/updates/?api_key=YOUR_API_KEY_HERE[&category_id=X][&deep=true|false][&firstrow=nnnnn][&rows=nn][&out=xml|json]

category _id: Optional. A unique numerical id of the start category to fetch. If missing, the API's root category is fetched.

deep: Optional. If true, include the series in all descendent categories. If missing or false, only series directly in the start category will be returned.

rows: Optional. Determines the maximum number of rows returned for each request, up to 10,000. Missing or invalid value results a default value of 50 as the maximum rows returned with each call.

firstrow: Optional. Integer specifying the zero-based index of the first row to return, providing a means to page through the updated series. Note that it is possible to page through the all of the API's series in this manner

Sample output (whitespaces added below for readability):

{ "request": { "category_id": 0, "query": "updates", "deep": "false", "firstrow": 1, "rows": 200 }, "updates":[ {"series_id": "ELEC.GEN.ALL-AK-99.A", "updated": "11-SEP-12 10.34.13 AM"}, {"series_id": "ELEC.GEN.ALL-AL-99.A", "updated": "11-SEP-12 10.34.13 AM"}, {"series_id": "ELEC.GEN.ALL-CN-99.A", "updated": "11-SEP-12 10.34.13 AM"}, ... ] }

API Search Data Query

Returns the series ID as an array followed by series facet data as an array. Additional codes may be defined in future releases.

Series ID Search

search_value: Required.
http://api.eia.gov/search/?search_term=series_id&search_value="PET.MB"

Keyword Search

search_value: Required.
http://api.eia.gov/search/?search_term=name&search_value="crude oil"

Date Search

search_value: Required.
http://api.eia.gov/search/?search_term=last_updated&search_value=[2015-01-01T00:00:00Z TO 2015-01-01T23:59:59Z]

Pagination on Search (default page number = 1)

search_value and page_num: Required.
http://api.eia.gov/search/?search_term=name&search_value="crude oil"&page_num=4

Manipulate Rows Per Page

search_value, page_num, and rows_per_page: Required.
http://api.eia.gov/search/?search_term=name&search_value="crude oil"&rows_per_page=25&page_num=4