# 					Frequently Asked Questions				

        - Obtaining API Keys
        - Data Updates
        - No Errors, but No Data
        - The Data is Wrong
        - EIA's Excel/Google Add-In
        - API Throttles
        - APIv1 Questions

----

## Obtaining API Keys

#### I registered for an API key, but didn't receive it in email?

Please ensure developer@eia.gov is whitelisted by your spam filters or IT department.

----

## Data Updates 

#### Is there an update field in APIv2 like there was in APIv1?

No. For performance reasons, we had to remove this feature.

#### When is your API data updated, including for a specific product?

APIv2 now directly accesses our public-facing databases. It is updated constantly and not at regular intervals.

APIv2 routes do not all specifically correspond to a given EIA publication, although some do. Some API requests query multiple EIA publications and databases. As such, depending on the route, API data may be paired directly with product releases, or it may receive incremental updates from other EIA sources.

#### How soon after publication does data from the WPSR and WNGSR show in the API?

Within two hours.

Because of their sensitive nature, the 10:30 a.m. releases for the WPSR (**Weekly Petroleum Storage Report) and WNGSR (*Weekly Natural Gas Storage Report*) are processed differently than some of our other data.

Your best resource for to-the-second access to this data is our dedicated information release server at: ir.eia.gov.

----

## No Errors, but No Data

#### I am receiving a return (not an error) from the API, but not any specific data points?

Check to be sure that you are:
        - Ending your route using  “/data” . If you do not, you are making a metadata request.
        - Using the  “data[]”  parameter. This parameter tells the API what data rows it should return to you.

Full documentation is available at www.eia.gov/opendata/documentation.php.

----

## The Data is Wrong

#### The data appears incomplete; shouldn't I be receiving more data?

The maximum number of rows our API can return is 5,000 (300 in XML format). The total field, near the top of the return, defines the total number of data points responsive to your request.

In APIv2.1 and beyond, we will also return a warning header in the response (while still returning data) if your request exceeds the 5,000-row maximum.

To process all the responsive data, use the pagination parameters such as length and offset. Alternatively, you can filter your request down with the use of the facet parameter.

Full documentation is available at www.eia.gov/opendata/documentation.php.

#### I believe specific data points are incorrect or confusing. Who do I talk to?

Specific data quality questions are best directed to our many energy and market experts here at EIA.

----

## EIA's Excel/Google Add-In

#### I'm receiving an "invalid procedure or argument" error.

If you receive this error from Excel, it is likely due to your add-in not communicating via HTTPS. The most common cause is an out-of-date Excel add-in; please download a fresh copy. If you have already done so, it is possible your firewall or other network device is blocking access to https://api.eia.gov. Please consult with your IT support team.

#### How do I update the EIA/FRED Excel add-in?

If you're running the Excel add-in, click on the top ribbon "EIA Info" button, and select "Check for Updates".

If you haven't updated your add-in in a few years, this function may also display an error. Please download a fresh copy manually from our website: https://www.eia.gov/opendata/excel.

#### I've updated my add-in, but Excel says I'm running an old version?

If you continue to receive Excel errors after updating, please try manually removing the old EIA add-in, then installing the new one. This option is typically located under File -> Options -> Add-Ins, but your specific OS or Excel version may vary slightly.

----

## API Throttles

#### What are the specific throttles for the API?

Unfortunately, due to cybersecurity concerns, we are not able to publish our specific firewall rules.

As per industry practices, our throttling limits are based on—among other factors—your key's usage, current demand against that data series, and requests from your IP.

Speaking generally and under ideal network conditions, if you keep your sustained rate less than ~9,000 per hour and your burst rate beneath 5 per second, your key won't be throttled or temporarily disabled. Specific API routes may have slower restrictions due to their complexity. 

#### I exceeded the API's throttle. How long does my key ban last?

Depending on how your program was using the API, your key ban will last between a few seconds and a number of minutes.

EIA cybersecurity measures are designed to ensure fair usage, to uphold data security, and to prevent malicious attacks. Although we do not release specifics, our throttling parameters help maintain optimal performance and reliability for everyone accessing EIA data.

Key bans are not permanent, or last beyond an hour, unless under the most extreme circumstances.

----

## APIv1 Questions

#### Why is EIA sunsetting APIv1? Can EIA leave APIv1 alone and run APIv2 in parallel?

APIv2 was designed to address the most common requests from our developer community, improve data consistency, enhance cybersecurity, and create a self-describing, machine-discoverable API.

Unfortunately, it is cost-prohibitive for EIA to run both APIv2 and APIv1 in parallel. We've added a number of backward-compatibility features to make the transition as smooth as possible.

#### What exact day is APIv1 shutting down?

We aren't able to provide a specific date at this time, but we will as the date draws closer. For your planning purposes, we are targeting January 2023.

#### What backward-compatibility features exist in APIv2?

If you visit https://www.eia.gov/opendata/#translate you can use the API translator. Enter your APIv1 seriesID, and it will produce an APIv2 query you can use in your own code.

You may query the API with a v1 seriesID using this route:

https://api.eia.gov/v2/seriesid/APIv1-SERIESID-HERE

The Excel add-in already automatically converts your workbooks' APIv1 seriesIDs into their v2 equivalents.

A word of caution: There is not a perfect 1:1 mapping between an APIv1 seriesID and APIv2 routes. APIv2 maps all our data to its tree hierarchy and uses facets and other parameters to filter on that data. You may receive more or fewer data rows than you were expecting when using our backward-compatibility features. All returns are provided with APIv2 metadata and JSON/XML formatting.

#### I use your embed feature to insert EIA visualizations on my website. Why am I now seeing API_KEY_MISSING instead of a chart?

Our embed feature now requires the use of an API key. We know our embedded features are popular, and a few high-traffic websites were unintentionally degrading our service with their embeds.