Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mortada/fredapi
Python API for FRED (Federal Reserve Economic Data) and ALFRED (Archival FRED)
https://github.com/mortada/fredapi
economic-data finance fred python
Last synced: about 2 months ago
JSON representation
Python API for FRED (Federal Reserve Economic Data) and ALFRED (Archival FRED)
- Host: GitHub
- URL: https://github.com/mortada/fredapi
- Owner: mortada
- License: apache-2.0
- Created: 2014-08-22T01:43:29.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-07-22T11:14:13.000Z (about 1 year ago)
- Last Synced: 2024-04-04T07:03:32.809Z (6 months ago)
- Topics: economic-data, finance, fred, python
- Language: Python
- Homepage:
- Size: 45.9 KB
- Stars: 838
- Watchers: 41
- Forks: 153
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fintech - fredapi - Python API for FRED (Federal Reserve Economic Data) and ALFRED (Archival FRED) (Libraries / Python)
- awesome-fintech - fredapi - Python API for FRED (Federal Reserve Economic Data) and ALFRED (Archival FRED) (Other)
- jimsghstars - mortada/fredapi - Python API for FRED (Federal Reserve Economic Data) and ALFRED (Archival FRED) (Python)
README
# fredapi: Python API for FRED (Federal Reserve Economic Data)
[](https://github.com/mortada/fredapi/actions)
[](#)
[](https://pypi.org/project/fredapi/)
[](https://pepy.tech/project/fredapi)
`fredapi` is a Python API for the [FRED](http://research.stlouisfed.org/fred2/) data provided by the
Federal Reserve Bank of St. Louis. `fredapi` provides a wrapper in python to the
[FRED web service](http://api.stlouisfed.org/docs/fred/), and also provides several convenient methods
for parsing and analyzing point-in-time data (i.e. historic data revisions) from [ALFRED](http://research.stlouisfed.org/tips/alfred/)
`fredapi` makes use of `pandas` and returns data to you in a `pandas` `Series` or `DataFrame`
## Installation
```sh
pip install fredapi
```
## Basic Usage
First you need an API key, you can [apply for one](http://api.stlouisfed.org/api_key.html) for free on the FRED website.
Once you have your API key, you can set it in one of three ways:
* set it to the evironment variable FRED_API_KEY
* save it to a file and use the 'api_key_file' parameter
* pass it directly as the 'api_key' parameter
```python
from fredapi import Fred
fred = Fred(api_key='insert api key here')
data = fred.get_series('SP500')
```
## Working with data revisions
Many economic data series contain frequent revisions. `fredapi` provides several convenient methods for handling data revisions and answering the quesion of what-data-was-known-when.
In [ALFRED](http://research.stlouisfed.org/tips/alfred/) there is the concept of a *vintage* date. Basically every *observation* can have three dates associated with it: *date*, *realtime_start* and *realtime_end*.
- date: the date the value is for
- realtime_start: the first date the value is valid
- realitime_end: the last date the value is valid
For instance, there has been three observations (data points) for the GDP of 2014 Q1:
```xml
```
This means the GDP value for Q1 2014 has been released three times. First release was on 4/30/2014 for a value of 17149.6, and then there have been two revisions on 5/29/2014 and 6/25/2014 for revised values of 17101.3 and 17016.0, respectively.
### Get first data release only (i.e. ignore revisions)
```python
data = fred.get_series_first_release('GDP')
data.tail()
```
this outputs:
```sh
date
2013-04-01 16633.4
2013-07-01 16857.6
2013-10-01 17102.5
2014-01-01 17149.6
2014-04-01 17294.7
Name: value, dtype: object
```
### Get latest data
Note that this is the same as simply calling `get_series()`
```python
data = fred.get_series_latest_release('GDP')
data.tail()
```
this outputs:
```
2013-04-01 16619.2
2013-07-01 16872.3
2013-10-01 17078.3
2014-01-01 17044.0
2014-04-01 17294.7
dtype: float64
```
### Get latest data known on a given date
```python
fred.get_series_as_of_date('GDP', '6/1/2014')
```
this outputs:
date
realtime_start
value
2237
2013-10-01 00:00:00
2014-01-30 00:00:00
17102.5
2238
2013-10-01 00:00:00
2014-02-28 00:00:00
17080.7
2239
2013-10-01 00:00:00
2014-03-27 00:00:00
17089.6
2241
2014-01-01 00:00:00
2014-04-30 00:00:00
17149.6
2242
2014-01-01 00:00:00
2014-05-29 00:00:00
17101.3
### Get all data release dates
This returns a `DataFrame` with all the data from ALFRED
```python
df = fred.get_series_all_releases('GDP')
df.tail()
```
this outputs:
date
realtime_start
value
2236
2013-07-01 00:00:00
2014-07-30 00:00:00
16872.3
2237
2013-10-01 00:00:00
2014-01-30 00:00:00
17102.5
2238
2013-10-01 00:00:00
2014-02-28 00:00:00
17080.7
2239
2013-10-01 00:00:00
2014-03-27 00:00:00
17089.6
2240
2013-10-01 00:00:00
2014-07-30 00:00:00
17078.3
2241
2014-01-01 00:00:00
2014-04-30 00:00:00
17149.6
2242
2014-01-01 00:00:00
2014-05-29 00:00:00
17101.3
2243
2014-01-01 00:00:00
2014-06-25 00:00:00
17016
2244
2014-01-01 00:00:00
2014-07-30 00:00:00
17044
2245
2014-04-01 00:00:00
2014-07-30 00:00:00
17294.7
### Get all vintage dates
```python
from __future__ import print_function
vintage_dates = fred.get_series_vintage_dates('GDP')
for dt in vintage_dates[-5:]:
print(dt.strftime('%Y-%m-%d'))
```
this outputs:
```
2014-03-27
2014-04-30
2014-05-29
2014-06-25
2014-07-30
```
### Search for data series
You can always search for data series on the FRED website. But sometimes it can be more convenient to search programmatically.
`fredapi` provides a `search()` method that does a fulltext search and returns a `DataFrame` of results.
```python
fred.search('potential gdp').T
```
this outputs:
series id
GDPPOT
NGDPPOT
frequency
Quarterly
Quarterly
frequency_short
Q
Q
id
GDPPOT
NGDPPOT
last_updated
2014-02-04 10:06:03-06:00
2014-02-04 10:06:03-06:00
notes
Real potential GDP is the CBO's estimate of the output the economy would produce with a high rate of use of its capital and labor resources. The data is adjusted to remove the effects of inflation.
None
observation_end
2024-10-01 00:00:00
2024-10-01 00:00:00
observation_start
1949-01-01 00:00:00
1949-01-01 00:00:00
popularity
72
61
realtime_end
2014-08-23 00:00:00
2014-08-23 00:00:00
realtime_start
2014-08-23 00:00:00
2014-08-23 00:00:00
seasonal_adjustment
Not Seasonally Adjusted
Not Seasonally Adjusted
seasonal_adjustment_short
NSA
NSA
title
Real Potential Gross Domestic Product
Nominal Potential Gross Domestic Product
units
Billions of Chained 2009 Dollars
Billions of Dollars
units_short
Bil. of Chn. 2009 $
Bil. of $
## Dependencies
- [pandas](http://pandas.pydata.org/)
## More Examples
- I have a [blog post with more examples](http://mortada.net/python-api-for-fred.html) written in an `IPython` notebook