{"id":13540825,"url":"https://github.com/mortada/fredapi","last_synced_at":"2025-04-02T08:30:46.671Z","repository":{"id":19942457,"uuid":"23209140","full_name":"mortada/fredapi","owner":"mortada","description":"Python API for FRED (Federal Reserve Economic Data) and ALFRED (Archival FRED)","archived":false,"fork":false,"pushed_at":"2024-05-05T11:44:40.000Z","size":52,"stargazers_count":934,"open_issues_count":34,"forks_count":161,"subscribers_count":42,"default_branch":"master","last_synced_at":"2024-11-10T09:13:05.315Z","etag":null,"topics":["economic-data","finance","fred","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mortada.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2014-08-22T01:43:29.000Z","updated_at":"2024-11-09T22:06:45.000Z","dependencies_parsed_at":"2022-07-09T17:00:17.314Z","dependency_job_id":"72552079-e9b5-43cc-8cf4-6af0c9f0693a","html_url":"https://github.com/mortada/fredapi","commit_stats":{"total_commits":49,"total_committers":9,"mean_commits":5.444444444444445,"dds":"0.18367346938775508","last_synced_commit":"8a6beb9560ceba608ec4bfcebe7abde0e682463d"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mortada%2Ffredapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mortada%2Ffredapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mortada%2Ffredapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mortada%2Ffredapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mortada","download_url":"https://codeload.github.com/mortada/fredapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246269589,"owners_count":20750316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["economic-data","finance","fred","python"],"created_at":"2024-08-01T10:00:33.438Z","updated_at":"2025-04-02T08:30:46.393Z","avatar_url":"https://github.com/mortada.png","language":"Python","readme":"\n# fredapi: Python API for FRED (Federal Reserve Economic Data)\n\n[![Build and test GitHub](https://github.com/mortada/fredapi/actions/workflows/main.yml/badge.svg)](https://github.com/mortada/fredapi/actions)\n[![version](https://img.shields.io/badge/version-0.5.1-success.svg)](#)\n[![PyPI Latest Release](https://img.shields.io/pypi/v/fredapi.svg)](https://pypi.org/project/fredapi/)\n[![Downloads](https://static.pepy.tech/personalized-badge/fredapi?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=Downloads)](https://pepy.tech/project/fredapi)\n\n`fredapi` is a Python API for the [FRED](http://research.stlouisfed.org/fred2/) data provided by the\nFederal Reserve Bank of St. Louis. `fredapi` provides a wrapper in python to the \n[FRED web service](http://api.stlouisfed.org/docs/fred/), and also provides several convenient methods\nfor parsing and analyzing point-in-time data (i.e. historic data revisions) from [ALFRED](http://research.stlouisfed.org/tips/alfred/)\n\n`fredapi` makes use of `pandas` and returns data to you in a `pandas` `Series` or `DataFrame`\n\n## Installation\n\n```sh\npip install fredapi\n```\n\n## Basic Usage\n\nFirst you need an API key, you can [apply for one](http://api.stlouisfed.org/api_key.html) for free on the FRED website.\nOnce you have your API key, you can set it in one of three ways:\n\n* set it to the evironment variable FRED_API_KEY\n* save it to a file and use the 'api_key_file' parameter\n* pass it directly as the 'api_key' parameter\n\n```python\nfrom fredapi import Fred\nfred = Fred(api_key='insert api key here')\ndata = fred.get_series('SP500')\n```\n\n## Working with data revisions\nMany 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.\n\nIn [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*. \n\n- date: the date the value is for\n- realtime_start: the first date the value is valid\n- realitime_end: the last date the value is valid\n\nFor instance, there has been three observations (data points) for the GDP of 2014 Q1:\n\n```xml\n\u003cobservation realtime_start=\"2014-04-30\" realtime_end=\"2014-05-28\" date=\"2014-01-01\" value=\"17149.6\"/\u003e\n\u003cobservation realtime_start=\"2014-05-29\" realtime_end=\"2014-06-24\" date=\"2014-01-01\" value=\"17101.3\"/\u003e\n\u003cobservation realtime_start=\"2014-06-25\" realtime_end=\"2014-07-29\" date=\"2014-01-01\" value=\"17016.0\"/\u003e\n```\n\nThis 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.\n\n### Get first data release only (i.e. ignore revisions)\n\n```python\ndata = fred.get_series_first_release('GDP')\ndata.tail()\n```\nthis outputs:\n\n```sh\ndate\n2013-04-01    16633.4\n2013-07-01    16857.6\n2013-10-01    17102.5\n2014-01-01    17149.6\n2014-04-01    17294.7\nName: value, dtype: object\n```\n\n### Get latest data\nNote that this is the same as simply calling `get_series()`\n```python\ndata = fred.get_series_latest_release('GDP')\ndata.tail()\n```\nthis outputs:\n```\n2013-04-01    16619.2\n2013-07-01    16872.3\n2013-10-01    17078.3\n2014-01-01    17044.0\n2014-04-01    17294.7\ndtype: float64\n```\n### Get latest data known on a given date\n\n```python\nfred.get_series_as_of_date('GDP', '6/1/2014')\n```\nthis outputs:\n\n\u003ctable border=\"1\" class=\"dataframe\"\u003e\n  \u003cthead\u003e\n    \u003ctr style=\"text-align: right;\"\u003e\n      \u003cth\u003e\u003c/th\u003e\n      \u003cth\u003edate\u003c/th\u003e\n      \u003cth\u003erealtime_start\u003c/th\u003e\n      \u003cth\u003evalue\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2237\u003c/th\u003e\n      \u003ctd\u003e 2013-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-01-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17102.5\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2238\u003c/th\u003e\n      \u003ctd\u003e 2013-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-02-28 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17080.7\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2239\u003c/th\u003e\n      \u003ctd\u003e 2013-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-03-27 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17089.6\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2241\u003c/th\u003e\n      \u003ctd\u003e 2014-01-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-04-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17149.6\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2242\u003c/th\u003e\n      \u003ctd\u003e 2014-01-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-05-29 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17101.3\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n### Get all data release dates\nThis returns a `DataFrame` with all the data from ALFRED\n\n```python\ndf = fred.get_series_all_releases('GDP')\ndf.tail()\n```\nthis outputs:\n\n\u003ctable border=\"1\" class=\"dataframe\"\u003e\n  \u003cthead\u003e\n    \u003ctr style=\"text-align: right;\"\u003e\n      \u003cth\u003e\u003c/th\u003e\n      \u003cth\u003edate\u003c/th\u003e\n      \u003cth\u003erealtime_start\u003c/th\u003e\n      \u003cth\u003evalue\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2236\u003c/th\u003e\n      \u003ctd\u003e 2013-07-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-07-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 16872.3\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2237\u003c/th\u003e\n      \u003ctd\u003e 2013-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-01-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17102.5\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2238\u003c/th\u003e\n      \u003ctd\u003e 2013-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-02-28 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17080.7\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2239\u003c/th\u003e\n      \u003ctd\u003e 2013-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-03-27 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17089.6\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2240\u003c/th\u003e\n      \u003ctd\u003e 2013-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-07-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17078.3\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2241\u003c/th\u003e\n      \u003ctd\u003e 2014-01-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-04-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17149.6\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2242\u003c/th\u003e\n      \u003ctd\u003e 2014-01-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-05-29 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17101.3\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2243\u003c/th\u003e\n      \u003ctd\u003e 2014-01-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-06-25 00:00:00\u003c/td\u003e\n      \u003ctd\u003e   17016\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2244\u003c/th\u003e\n      \u003ctd\u003e 2014-01-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-07-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e   17044\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e2245\u003c/th\u003e\n      \u003ctd\u003e 2014-04-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 2014-07-30 00:00:00\u003c/td\u003e\n      \u003ctd\u003e 17294.7\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n### Get all vintage dates\n```python\nfrom __future__ import print_function\nvintage_dates = fred.get_series_vintage_dates('GDP')\nfor dt in vintage_dates[-5:]:\n    print(dt.strftime('%Y-%m-%d'))\n```\nthis outputs:\n```\n2014-03-27\n2014-04-30\n2014-05-29\n2014-06-25\n2014-07-30\n```\n\n### Search for data series\n\nYou can always search for data series on the FRED website. But sometimes it can be more convenient to search programmatically.\n`fredapi` provides a `search()` method that does a fulltext search and returns a `DataFrame` of results.\n\n```python\nfred.search('potential gdp').T\n```\nthis outputs:\n\n\u003ctable border=\"1\" class=\"dataframe\"\u003e\n  \u003cthead\u003e\n    \u003ctr style=\"text-align: right;\"\u003e\n      \u003cth\u003eseries id\u003c/th\u003e\n      \u003cth\u003eGDPPOT\u003c/th\u003e\n      \u003cth\u003eNGDPPOT\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003cth\u003efrequency\u003c/th\u003e\n      \u003ctd\u003eQuarterly\u003c/td\u003e\n      \u003ctd\u003eQuarterly\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003efrequency_short\u003c/th\u003e\n      \u003ctd\u003eQ\u003c/td\u003e\n      \u003ctd\u003eQ\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eid\u003c/th\u003e\n      \u003ctd\u003eGDPPOT\u003c/td\u003e\n      \u003ctd\u003eNGDPPOT\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003elast_updated\u003c/th\u003e\n      \u003ctd\u003e2014-02-04 10:06:03-06:00\u003c/td\u003e\n      \u003ctd\u003e2014-02-04 10:06:03-06:00\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003enotes\u003c/th\u003e\n      \u003ctd\u003e Real potential GDP is the CBO\u0026#39;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.\u003c/td\u003e\n      \u003ctd\u003eNone\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eobservation_end\u003c/th\u003e\n      \u003ctd\u003e2024-10-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e2024-10-01 00:00:00\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eobservation_start\u003c/th\u003e\n      \u003ctd\u003e1949-01-01 00:00:00\u003c/td\u003e\n      \u003ctd\u003e1949-01-01 00:00:00\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003epopularity\u003c/th\u003e\n      \u003ctd\u003e72\u003c/td\u003e\n      \u003ctd\u003e61\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003erealtime_end\u003c/th\u003e\n      \u003ctd\u003e2014-08-23 00:00:00\u003c/td\u003e\n      \u003ctd\u003e2014-08-23 00:00:00\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003erealtime_start\u003c/th\u003e\n      \u003ctd\u003e2014-08-23 00:00:00\u003c/td\u003e\n      \u003ctd\u003e2014-08-23 00:00:00\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eseasonal_adjustment\u003c/th\u003e\n      \u003ctd\u003eNot Seasonally Adjusted\u003c/td\u003e\n      \u003ctd\u003eNot Seasonally Adjusted\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eseasonal_adjustment_short\u003c/th\u003e\n      \u003ctd\u003eNSA\u003c/td\u003e\n      \u003ctd\u003eNSA\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003etitle\u003c/th\u003e\n      \u003ctd\u003eReal Potential Gross Domestic Product\u003c/td\u003e\n      \u003ctd\u003eNominal Potential Gross Domestic Product\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eunits\u003c/th\u003e\n      \u003ctd\u003eBillions of Chained 2009 Dollars\u003c/td\u003e\n      \u003ctd\u003eBillions of Dollars\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003eunits_short\u003c/th\u003e\n      \u003ctd\u003eBil. of Chn. 2009 \u0026#36;\u003c/td\u003e\n      \u003ctd\u003eBil. of \u0026#36;\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n## Dependencies\n- [pandas](http://pandas.pydata.org/)\n\n## More Examples\n- I have a [blog post with more examples](http://mortada.net/python-api-for-fred.html) written in an `IPython` notebook\n","funding_links":[],"categories":["Python","Data \u0026 Market Intelligence","Libraries","Economic \u0026 Macro Data"],"sub_categories":["Python","FRED (Federal Reserve Economic Data)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmortada%2Ffredapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmortada%2Ffredapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmortada%2Ffredapi/lists"}