{"id":24327840,"url":"https://github.com/7astro7/full_fred","last_synced_at":"2025-04-12T14:57:01.687Z","repository":{"id":45345147,"uuid":"348145842","full_name":"7astro7/full_fred","owner":"7astro7","description":"Full Python interface to Federal Reserve Economic Data (FRED)","archived":false,"fork":false,"pushed_at":"2025-01-05T23:23:13.000Z","size":318,"stargazers_count":108,"open_issues_count":4,"forks_count":26,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-03T19:12:15.209Z","etag":null,"topics":["economic-data","economics","finance","fred","python","statistics"],"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/7astro7.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-15T22:56:40.000Z","updated_at":"2025-03-13T02:18:01.000Z","dependencies_parsed_at":"2024-12-28T15:19:43.200Z","dependency_job_id":"070618ca-212f-48f9-a28f-37f92af7a06c","html_url":"https://github.com/7astro7/full_fred","commit_stats":{"total_commits":145,"total_committers":3,"mean_commits":"48.333333333333336","dds":0.03448275862068961,"last_synced_commit":"af1c83635de9f9a47089f36504c5cc9bf0d50996"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7astro7%2Ffull_fred","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7astro7%2Ffull_fred/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7astro7%2Ffull_fred/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7astro7%2Ffull_fred/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7astro7","download_url":"https://codeload.github.com/7astro7/full_fred/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248586248,"owners_count":21128997,"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","economics","finance","fred","python","statistics"],"created_at":"2025-01-17T22:16:06.239Z","updated_at":"2025-04-12T14:57:01.666Z","avatar_url":"https://github.com/7astro7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[![PyPI](https://img.shields.io/pypi/v/full_fred)](https://pypi.org/project/full_fred/)\n![PyPI Downloads](https://img.shields.io/pypi/dm/full_fred)\n![GitHub issues](https://img.shields.io/github/issues/7astro7/full_fred)\n![Unit Tests](https://github.com/7astro7/full_fred/actions/workflows/unittest.yml/badge.svg)\n![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)\n\n\n\n# full_fred\n`full_fred` is a Python interface to \n[FRED (Federal Reserve Economic Data)](https://fred.stlouisfed.org/) that\nprioritizes user preference, flexibility, and speed. `full_fred`'s API translates to Python\n[every type of request FRED supports](https://fred.stlouisfed.org/docs/api/fred/):\neach query for Categories, Releases, Series, Sources, and Tags \nfound within FRED's web service has a method associated with it in `full_fred`.\n`full_fred` minimizes redundant queries for the sake of users and FRED's servers. \nAfter a request for data is made to FRED web service the retrieved data \nis stored in a dictionary, accessible and fungible\n\n## Installation\n    pip install full-fred\n\n## Testing\n```full_fred``` requires ```pytest```. Tests can be run with ```FRED_API_KEY``` environment variable set and:\n\n```python\npytest\n```\n\n## Usage\n\n### API Key \nQueries to FRED web service require an API key. FRED has [free API keys available with an account (also free)](https://research.stlouisfed.org/useraccount/apikey)\n\nYou can tell ```full_fred``` about an api key in 2 secure ways:\n1. fred.api_key_file can be set by passing it to the constructor\n```python\nIn [4]: from full_fred.fred import Fred\n\nIn [5]: fred = Fred('example_key.txt')\n\nIn [6]: fred.get_api_key_file()\nOut[6]: 'example_key.txt'\n```\nThis will set it too\n```python\nIn [3]: fred.set_api_key_file('example_key.txt')\nOut[3]: True\n```\nIf the file assigned to ```api_key_file``` can't be found, ```full_fred``` will say so immediately if api_key_file is set using \nthe surefire ```fred.set_api_key_file()```  \n\n2. FRED_API_KEY Environment Variable\n\n```full_fred``` will automatically detect your api key if it's assigned to an environment variable named ```FRED_API_KEY```.\nTo check that FRED_API_KEY environment variable is detected, you can use \n\n```python\nIn [7]: fred.env_api_key_found()\nOut[7]: True\n```\n\n```full_fred``` does not store your api key in an attribute for the sake of security: to send queries to FRED's databases, ```full_fred``` uses the value of \nFRED_API_KEY environment variable or the first line of fred.api_key_file\n\n### Fetching data\n\nA pandas DataFrame stores observations when a request for data values is made\n\n```python\nfred.get_series_df('GDPPOT')\n    realtime_start realtime_end        date               value\n0       2021-04-03   2021-04-03  1949-01-01         2103.179936\n1       2021-04-03   2021-04-03  1949-04-01  2130.7327210000003\n2       2021-04-03   2021-04-03  1949-07-01  2159.4478710000003\n3       2021-04-03   2021-04-03  1949-10-01         2186.907265\n4       2021-04-03   2021-04-03  1950-01-01          2216.07306\n..             ...          ...         ...                 ...\n327     2021-04-03   2021-04-03  2030-10-01            23219.35\n328     2021-04-03   2021-04-03  2031-01-01            23318.31\n329     2021-04-03   2021-04-03  2031-04-01            23417.38\n330     2021-04-03   2021-04-03  2031-07-01            23516.38\n331     2021-04-03   2021-04-03  2031-10-01            23615.28\n\n[332 rows x 4 columns]\n```\nThe fetched data is stored in fred.series_stack (see __Accessing fetched data__ section for more on retrieving queried data)\n\n```python\nfred.series_stack['get_series_df']\n{'realtime_start': '2021-04-03',\n 'realtime_end': '2021-04-03',\n 'observation_start': '1600-01-01',\n 'observation_end': '9999-12-31',\n 'units': 'lin',\n 'output_type': 1,\n 'file_type': 'json',\n 'order_by': 'observation_date',\n 'sort_order': 'asc',\n 'count': 332,\n 'offset': 0,\n 'limit': 100000,\n 'series_id': 'GDPPOT',\n 'df':     \nrealtime_start      realtime_end        date               value\n 0       2021-04-03   2021-04-03  1949-01-01         2103.179936\n 1       2021-04-03   2021-04-03  1949-04-01  2130.7327210000003\n 2       2021-04-03   2021-04-03  1949-07-01  2159.4478710000003\n 3       2021-04-03   2021-04-03  1949-10-01         2186.907265\n 4       2021-04-03   2021-04-03  1950-01-01          2216.07306\n ..             ...          ...         ...                 ...\n 327     2021-04-03   2021-04-03  2030-10-01            23219.35\n 328     2021-04-03   2021-04-03  2031-01-01            23318.31\n 329     2021-04-03   2021-04-03  2031-04-01            23417.38\n 330     2021-04-03   2021-04-03  2031-07-01            23516.38\n 331     2021-04-03   2021-04-03  2031-10-01            23615.28\n \n [332 rows x 4 columns]}\n```\n\n\nTo find a specific category_id or to search FRED categories from\nmost general to most specific start with the root category 0. \nA search along the lines of the following can help to pinpoint different \ncategory_ids:\n\n```python\nIn [4]: fred.get_child_categories(0)\nOut[4]: \n{'categories': [{'id': 32991,\n   'name': 'Money, Banking, \u0026 Finance',\n   'parent_id': 0},\n  {'id': 10,\n   'name': 'Population, Employment, \u0026 Labor Markets',\n   'parent_id': 0},\n  {'id': 32992, 'name': 'National Accounts', 'parent_id': 0},\n  {'id': 1, 'name': 'Production \u0026 Business Activity', 'parent_id': 0},\n  {'id': 32455, 'name': 'Prices', 'parent_id': 0},\n  {'id': 32263, 'name': 'International Data', 'parent_id': 0},\n  {'id': 32213, 'name': 'Greenbook Projections', 'parent_id': 0},\n  {'id': 3008, 'name': 'U.S. Regional Data', 'parent_id': 0},\n  {'id': 33060, 'name': 'Academic Data', 'parent_id': 0}]}\n\nIn [5]: fred.category_stack['get_child_categories']\nOut[5]: \n{'categories': [{'id': 32991,\n   'name': 'Money, Banking, \u0026 Finance',\n   'parent_id': 0},\n  {'id': 10,\n   'name': 'Population, Employment, \u0026 Labor Markets',\n   'parent_id': 0},\n  {'id': 32992, 'name': 'National Accounts', 'parent_id': 0},\n  {'id': 1, 'name': 'Production \u0026 Business Activity', 'parent_id': 0},\n  {'id': 32455, 'name': 'Prices', 'parent_id': 0},\n  {'id': 32263, 'name': 'International Data', 'parent_id': 0},\n  {'id': 32213, 'name': 'Greenbook Projections', 'parent_id': 0},\n  {'id': 3008, 'name': 'U.S. Regional Data', 'parent_id': 0},\n  {'id': 33060, 'name': 'Academic Data', 'parent_id': 0}]}\n```\n\nThe [whole gamut of requests on FRED web service](https://fred.stlouisfed.org/docs/api/fred/) is implemented. The example below \nis one among many other methods in the API, listed in the next section\n\n```python\nIn [1]: from full_fred.fred import Fred\n\nIn [2]: fred = Fred()\n\nIn [3]: fred.get_series_vintagedates('FYFSD', limit = 15)\nOut[3]: \n{'realtime_start': '1776-07-04',\n 'realtime_end': '9999-12-31',\n 'order_by': 'vintage_date',\n 'sort_order': 'asc',\n 'count': 46,\n 'offset': 0,\n 'limit': 15,\n 'vintage_dates': [\n    '1998-02-02',\n    '1998-10-26',\n    '1999-02-01',\n    '1999-10-25',\n    '2000-02-07',\n    '2000-10-20',\n    '2001-04-09',\n    '2001-10-24',\n    '2002-02-04',\n    '2002-10-23',\n    '2003-02-03',\n    '2003-10-15',\n    '2004-02-02',\n    '2004-10-12',\n    '2005-02-23']}\n\nIn [4]: fred.series_stack['get_series_vintagedates']\nOut[4]: \n{'realtime_start': '1776-07-04',\n 'realtime_end': '9999-12-31',\n 'order_by': 'vintage_date',\n 'sort_order': 'asc',\n 'count': 46,\n 'offset': 0,\n 'limit': 15,\n 'vintage_dates': [\n    '1998-02-02',\n    '1998-10-26',\n    '1999-02-01',\n    '1999-10-25',\n    '2000-02-07',\n    '2000-10-20',\n    '2001-04-09',\n    '2001-10-24',\n    '2002-02-04',\n    '2002-10-23',\n    '2003-02-03',\n    '2003-10-15',\n    '2004-02-02',\n    '2004-10-12',\n    '2005-02-23']}\n```\n\n### Accessing fetched data\n\nThere are 5 stacks: \n\n```fred.category_stack```\n```fred.release_stack```\n```fred.series_stack```\n```fred.source_stack```\n```fred.tag_stack```\n\nAfter a method is called the returned data is stored using the method name for its key\n\nMethods that store data in category stack:\n```python\nfred.category_stack[\"get_a_category\"]\nfred.category_stack[\"get_child_categories\"]\nfred.category_stack[\"get_related_categories\"]\nfred.category_stack[\"get_series_in_a_category\"]\nfred.category_stack[\"get_tags_for_a_category\"]\nfred.category_stack[\"get_related_tags_for_a_category\"]\n```\n\nMethods that store data in release stack:\n```python\nfred.release_stack[\"get_a_release\"]\nfred.release_stack[\"get_tags_for_a_release\"]\nfred.release_stack[\"get_series_on_a_release\"]\nfred.release_stack[\"get_sources_for_a_release\"]\nfred.release_stack[\"get_related_tags_for_release\"]\nfred.release_stack[\"get_release_dates_all_releases\"]\nfred.release_stack[\"get_release_tables\"]\nfred.release_stack[\"get_release_dates\"]\nfred.release_stack[\"get_all_releases\"]\n```\n\nMethods that store data in series stack:\n```python\nfred.series_stack[\"get_a_series\"]\nfred.series_stack[\"get_categories_of_series\"]\nfred.series_stack[\"get_series_df\"]\nfred.series_stack[\"get_release_for_a_series\"]\nfred.series_stack[\"search_for_series\"]\nfred.series_stack[\"get_tags_for_series_search\"]\nfred.series_stack[\"get_related_tags_for_series_search\"]\nfred.series_stack[\"get_tags_for_a_series\"]\nfred.series_stack[\"get_series_updates\"]\nfred.series_stack[\"get_series_vintagedates\"]\n```\n\nMethods that store data in source stack:\n```python\nfred.source_stack[\"get_all_sources\"]\nfred.source_stack[\"get_releases_for_a_source\"]\nfred.source_stack[\"get_a_source\"]\n```\n\nMethods that store data in tag stack:\n```python\nfred.tag_stack[\"get_all_tags\"]\nfred.tag_stack[\"get_related_tags_for_a_tag\"]\nfred.tag_stack[\"get_series_matching_tags\"]\n```\n\n### full_fred realtime period and observation start/end defaults\nBy default ```fred.realtime_start``` and ```fred.realtime_end``` are set to None. \nrealtime_start and realtime_end arguments override ```fred.realtime_start``` and ```fred.realtime_end```.\n\n```fred.observation_start``` and ```fred.observation_end``` are also None by default. \nobservation_start and observation_end arguments override ```fred.observation_start``` and ```fred.observation_end```.\n\n## Contributing\nThe ```full_fred``` project welcomes feature requests, bug reports, bug fixes, documentation improvements, contributions of all kinds.\n```full_fred``` aims to be responsive in integrating patches and listening to your feedback to be a community-driven API.\nThis project is also new and while ```full_fred``` is still young there's great opportunity to contribute elements that may have disproportionate\nimpact in the long run\n\n## License\nApache v2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7astro7%2Ffull_fred","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7astro7%2Ffull_fred","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7astro7%2Ffull_fred/lists"}