{"id":15656546,"url":"https://github.com/twopirllc/alphavantageapi","last_synced_at":"2025-04-09T14:09:07.022Z","repository":{"id":40965103,"uuid":"142054116","full_name":"twopirllc/AlphaVantageAPI","owner":"twopirllc","description":"An Opinionated AlphaVantage API Wrapper in Python 3.9. Compatible with Pandas TA (pip install pandas_ta). Get your FREE API Key at https://www.alphavantage.co/support/","archived":false,"fork":false,"pushed_at":"2023-07-25T21:13:45.000Z","size":538,"stargazers_count":120,"open_issues_count":4,"forks_count":25,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-12-08T14:35:29.681Z","etag":null,"topics":["alphavantage-api","crypto","csv","finance","fx","indicators","json","openpyxl","pandas","pandas-dataframe-extension","pkl","python","sectors","stocks"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twopirllc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2018-07-23T18:35:03.000Z","updated_at":"2024-11-10T23:41:19.000Z","dependencies_parsed_at":"2024-10-26T21:17:34.802Z","dependency_job_id":"ecfe56ee-760d-412a-b7fb-bdd30136e3b9","html_url":"https://github.com/twopirllc/AlphaVantageAPI","commit_stats":{"total_commits":106,"total_committers":3,"mean_commits":"35.333333333333336","dds":"0.047169811320754707","last_synced_commit":"1aa23117d69991a10474d56ac7d090dbeea08627"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twopirllc%2FAlphaVantageAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twopirllc%2FAlphaVantageAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twopirllc%2FAlphaVantageAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twopirllc%2FAlphaVantageAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twopirllc","download_url":"https://codeload.github.com/twopirllc/AlphaVantageAPI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230043147,"owners_count":18163966,"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":["alphavantage-api","crypto","csv","finance","fx","indicators","json","openpyxl","pandas","pandas-dataframe-extension","pkl","python","sectors","stocks"],"created_at":"2024-10-03T13:03:06.505Z","updated_at":"2024-12-17T00:13:23.729Z","avatar_url":"https://github.com/twopirllc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Python Version](https://img.shields.io/pypi/pyversions/alphaVantage-api.svg)](https://pypi.org/project/alphaVantage-api/)\n[![PyPi Version](https://img.shields.io/pypi/v/alphaVantage-api.svg)](https://pypi.org/project/alphaVantage-api/)\n[![Package Status](https://img.shields.io/pypi/status/alphaVantage-api.svg)](https://pypi.org/project/alphaVantage-api/)\n[![Downloads](https://img.shields.io/pypi/dm/alphaVantage-api.svg?style=flat)](https://pypistats.org/packages/alphaVantage-api)\n[![Contributors](https://img.shields.io/badge/contributors-3-orange.svg?style=flat)](#contributors-)\n# AlphaVantageAPI\n*An Opinionated AlphaVantage API Wrapper in Python 3.9*\n\n\n\u003cbr/\u003e\n\n## Description\nThis API has been designed to simplify the process of aquiring financial data from [AlphaVantage](http://www.alphavantage.co/support/#api-key) and only depends on the **requests** and **Pandas** packages. This package can clean and export data into a variety of file formats such as: _csv_ (default), _json_, _pkl_, _html_, and _txt_ with assistance of **Pandas**. If the **openpyxl** package is also installed, it can also be saved as an **Excel** file format: _xlsx_.\n\n\u003cbr/\u003e\n\n## AlphaVantage Support and Contact\n* Email: support@alphavantage.co\n* [Slack](https://alphavantage.herokuapp.com/)\n* [Twitter: @alpha_vantage](https://twitter.com/alpha_vantage)\n* [Medium-AlphaVantage](https://medium.com/alpha-vantage)\n* Community events: https://alphavhack.devpost.com/\n\n\u003cbr/\u003e\n\n# Contributing\n\nContributions are welcome and I am open to new ideas or implementations. Thank you!\n\n* [Sciguymjm](https://github.com/Sciguymjm)\n\n\u003cbr/\u003e\n\n## Features\n* Access to AlphaVantage requires an [**API key**](http://www.alphavantage.co/support/#api-key). API Keys are **free**.\n* Built with Pandas for a simpler ETL pipeline.\n* Available export formats: _csv_ (default), _json_, _pkl_, _html_, _txt_, and _xlsx_ (if _openpyxl_ package is installed)\n* Extended the Pandas DataFrame with extension 'av'.  See the _*Extension Example*_ below.\n* Like terse commands?  The 'av' extension also includes their alias.  For example: df.av.daily_adjusted('aapl') = df.av.DA('aapl').  See help('aliases') for more shorter length commands.\n* Simplifies column names i.e. \"1. open\" -\u003e \"open\" when\n```clean=True```.\n* A help method to reduce looking up 'required' and 'optional' parameters for each function.\n* A call_history method to return all successful API calls.\n\n\u003cbr/\u003e\n\n## What's New?\n**!!!** Updated ```requirements.txt``` to fix ```urllib3``` security vulnerability. **!!!**\n* Added _Intraday Extended_\n* **There are some breaking changes!** Please see the _Classic Example_ and the _DataFrame Extension Example_ below.\n* AlphaVantage has added Fundamental Data: _Company Overview_, _Balance Sheet_, _Cash Flow_, _Income Statement_, _Earnings Calendar_, _IPO Calendar_ and _Listing Status_.\n\n\u003cbr/\u003e\n\n## What's Gone?\n* AlphaVantage has depreciated ```batch```, ```digital_intraday```, and ```sectors```.  \n\n\u003cbr/\u003e\u003cbr/\u003e\n\n**Installation**\n===================\n\nStable\n------\nThe ```pip``` version is the last most stable release. Version: *1.0.30*\n```sh\n$ pip install alphaVantage-api\n```\n\nLatest Version\n--------------\nBest choice! Version: *1.0.33*\n```sh\n$ pip install -U git+https://github.com/twopirllc/AlphaVantageAPI\n```\n\nExcel Export\n------------\n```sh\n$ pip install openpyxl\n```\n\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n**Programming Conventions**\n===========================\nThere are two ways of utilizing AlphaVantageAPI. The _Standard_ Class way or as a Pandas DataFrame Extension 'av'.\n\n_Standard_\n====================\nThis is the Object/Class way. Instantiate a Class with predefined parameters and then make calls.\n\n### Parameter Defaults\n```python\napi_key: str     = None\npremium: bool    = False\noutput_size: str = 'compact'\ndatatype: str    = 'json'\nexport: bool     = False\nexport_path: str = '~/av_data'\noutput: str      = 'csv'\nclean: bool      = False\nproxy: dict      = {}\n```\n\n## API Parameter Descriptions\n\n### **api_key**\n* If None, then do not forget to set your environment variable AV_API_KEY to API key. Otherwise set it in the class constructor.  If you have a Premium API key, do not forget to set the premium property to True as well.\n\n### **premium**\n* *Got premium?  Excellent! You do not need to wait 15.0001 seconds between each API call.\n\n### **output_size**\n* The other option is 'full'. See AlphaVantage API documentation for more details.\n\n### **datatype**\n* The preferred request type. See AlphaVantage API documentation for more details.\n\n### **export**\n* *Set it to True if you want to save the file locally according to the export_path property.\n\n### **export_path**\n* The path of where you want to save the data.\n\n### **output**\n* How to save/export the data locally. Other options are 'json', 'pkl', 'html', and 'txt'.  If _openpyxl_ is installed, then you can save as 'xlsz'.\n\n### **clean**\n* Simplifies the column header names for instance: \"1. open\" -\u003e \"open\".\n\n### **proxy**\n* See requests API documentation for more details.\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n# **Example**: Class(ic) Behavior\n\n## Initialization\n```python\nfrom alphaVantageAPI import AlphaVantage\n\n# Initialize the AlphaVantage Class with default values\nav = AlphaVantage(\n        api_key=None,\n        premium=False,\n        output_size=\"compact\",\n        datatype='json',\n        export=False,\n        export_path=\"~/av_data\",\n        output=\"csv\",\n        clean=False,\n        proxy={}\n    )\n```\n\n## Help!\n```python\n# Help: lists all the functions and indicators AlphaVantage API supports\nav.help()\n\n# Print 'function' aliases\nav.help(\"aliases\")\n\n# Help with a specific API function\nav.help(\"TIME_SERIES_DAILY\")\n\n# Help with an indicator\nav.help(\"BBANDS\")\n```\n\n## Class Usage\n```python\nimport pandas as pd\nimport alphaVantageAPI as AV\n\n# Initialize, clean and save \"full\" locally in \"csv\" to \"~/av_data\"\nav = AV.AlphaVantage(api_key=\"demo\", export=True, clean=True, output_size=\"full\")\n\n# Check Settings\nprint(av)\n\n# Parameters\nquery = \"AA\"\nticker, crypto = \"MSFT\", \"BTC\"\nbase_fx, to_fx = \"USD\", \"CAD\"\n\n# Symbol Search\nfound_symbols = av.search(query)\n\n# Global Quote\nquote_df = av.quote(ticker)\n\n\n# Earnings Calendar\n# The \"horizon\" is how many months out to look for Earnings. Options include:\n#   \"3month\", \"6month\", \"12month\". Default: \"3month\"\n# Optionally can use \"symbol\".\n#   Default: Returns all symbols with Earnings based on the \"horizon\".\n\n # All symbols with Earnings in 3 months\nearnings_df = av.earnings()\n# All symbols with Earnings in 6 months\nearnings6mo_df = av.earnings(horizon=\"6month\")\n\n# Earnings Calendar in 3 months for 'symbol'\nearnings_ticker_df = av.earnings(symbol=ticker)\n# Earnings Calendar in 6 months for 'symbol'\nearnings6mo_ticker_df = av.earnings(symbol=ticker, horizon=\"6month\")\n\n# IPO Calendar\nipos_df = av.ipos()\n\n\n# Listing Status\n# Optionally can use \"state\". Options: \"active\" or \"delisted\".\n#   Default: \"active\".\n# Optionally can use \"date\". Options: None or \"YYYY-MM-DD\".\n#   Default: None\nlisted_df = av.listed()\nlistedon_df = av.listed(date=\"2013-08-03\")\n\ndelisted_df = av.listed(state=\"delisted\")\ndelistedon_df = av.listed(state=\"delisted\", date=\"2009-02-14\")\n\n\n# Company Overview\noverview_df = av.overview(ticker)\n\n# Balance Sheet, Income Statement and Cash Flow each return a list or a dict (if\n# as_dict=True). Default: List with two DataFrames: [Quarterlydf, Annuallydf]\nbalance_list = av.balance(ticker)   # Balance Sheet\nQuarterlyBSdf = balance_list[0]\nAnnuallyBSdf = balance_list[1]\n\ncashflow_list = av.cashflow(ticker) # Cash Flow\nincome_list = av.income(ticker)     # Income Statement\n\n\n# FX / Currency\nfx_rate_df = av.fxrate(from_symbol=base_fx, to_symbol=to_fx) # Rate\nfx_I5_df = av.fx(from_symbol=base_fx, to_symbol=to_fx, function=\"FXI\", interval=5) # Intraday as int\nfx_I60_df = av.fx(from_symbol=base_fx, to_symbol=to_fx, function=\"FXI\", interval=\"60min\") # Intraday as str\nfx_D_df = av.fx(from_symbol=base_fx, to_symbol=to_fx, function=\"FXD\") # Daily\nfx_W_df = av.fx(from_symbol=base_fx, to_symbol=to_fx, function=\"FXW\") # Weekly\nfx_M_df = av.fx(from_symbol=base_fx, to_symbol=to_fx, function=\"FXM\") # Monthly\n\n# Crypto Rating\nbtc_rating_df = av.crypto_rating(symbol=crypto) # == ds.crypto_rating(crypto)\n\n# Digital/Crypto\nbtc_usd_D_df = av.digital(symbol=crypto, market=base_fx, function=\"CD\") # Daily\nbtc_usd_W_df = av.digital(symbol=crypto, market=base_fx, function=\"CW\") # Weekly\nbtc_usd_M_df = av.digital(symbol=crypto, market=base_fx, function=\"CM\") # Monthly\n\n# Generic Equity/ETF calls\nticker_I5_df = av.intraday(symbol=ticker, interval=5) # Intraday as int\nticker_I60_df = av.intraday(symbol=ticker, interval=\"60min\") # Intraday as str\nticker_IE5_df = av.intraday_extended(symbol=ticker, interval=5) # Adjusted Intraday Extended. Default slice: \"year1month1\"\nticker_IE30_df = av.intraday_extended(symbol=ticker, interval=\"30min\", slice=\"year2month6\") # Adjusted Intraday Extended with slice\nticker_IE60_R_df = av.intraday_extended(symbol=ticker, interval=60, slice=\"year2month1\", adjusted=False) # Raw Intraday Extended with slice\nticker_D_df = av.data(symbol=ticker, function=\"D\") # Daily\nticker_DA_df = av.data(symbol=ticker, function=\"DA\") # Daily Adjusted\nticker_W_df = av.data(symbol=ticker, function=\"W\") # Weekly\nticker_WA_df = av.data(symbol=ticker, function=\"WA\") # Weekly Adjusted\nticker_M_df = av.data(symbol=ticker, function=\"M\") # Monthly\nticker_MA_df = av.data(symbol=ticker, function=\"MA\") # Monthly Adjusted\n\n\n## Indicators\n# SMA(close, 20)\nticker_SMA_20_df = av.data(symbol=ticker, function=\"SMA\", series_type=\"close\", time_period=20)\n\n# STOCH(close)\nticker_STOCH_df = av.data(\"STOCH\", symbols[2], interval=\"daily\", series_type=\"close\")\n\n# List of symbols Daily\nsymbols = [\"AAPL\", \"MSFT\", \"XLK\"]\n# returns dict of DataFrames: {\"ABC\": pd.DataFrame(), ..\ntechs = av.data(symbols, \"D\").}\n[print(techs[s]) for s in symbols]\n\n# History of Successful Calls to AlphaVantage\nhistory = pd.DataFrame(av.call_history())\nprint(history)\n```\n\n## Call History\n```python\n# Returns all successfull calls to the API\nhistory_list = av.call_history()\n\n# Pretty display of Call History\nhistory_df = pd.DataFrame(history_list)[[\"symbol\", \"function\", \"interval\", \"time_period\"]]\nprint(history_df)\n```\n\n\u003cbr/\u003e\n\n# **Example**: DataFrame Extension 'av' Behavior\n\n## Initialization\n**For simplicity and protection of your AV API key, the extension uses the environment variable AV_API_KEY upon import of the module.**\n```python\nimport pandas as pd\nimport alphaVantageAPI\n```\n\n## Empty DataFrame: No current data, no problem!\nSince 'av' is an extension of a Pandas DataFrame, we need a DataFrame to work from.  Simply create an empty DataFrame, it's contents will be replaced anyhow.\n```python\ndf = pd.DataFrame()\n```\n\n## Setting properties\nSame as the Class properties above. Use the 'av' extension to change them prior to requesting data or adjusting on the fly\n```python\n# Your API KEY. Default: None\ndf.av.api_key = \"DEMO\"\n\n# Whether you have a Premium Account. Default: False\ndf.av.premium = False\n\n# Simplify OHLCV columns. Default: False\ndf.av.clean = True\n\n# Whether to export (save locally). Default: False\ndf.av.export = True\n\n# Output Size: \"compact\" or \"full\". Default: \"compact\"\ndf.av.output_size = \"full\"\n\n# Retrieval Format. Default: \"json\"\ndf.av.datatype = \"json\"\n\n# Export Path to save output format. Default: \"~/av_data\"\ndf.av.export_path = \"~/av_data\"\n\n# Final output format. Default: \"csv\"\ndf.av.output = \"csv\"\n\n# Proxy to use. Default: {}\ndf.av.proxy = {}\n```\n\n## Help!\n```python\n# Help: lists all the functions and indicators AlphaVantage API supports\ndf.av.help()\n\n# Print 'function' aliases\ndf.av.help(\"aliases\")\n\n# Help with a specific API function\ndf.av.help(\"TIME_SERIES_DAILY\")\n\n# Help with an indicator\ndf.av.help(\"BBANDS\")\n```\n\n\n## Data Acquisition Methods\n```python\nimport pandas as pd\nimport alphaVantageAPI\n\n# Create an Empty DataFrame to store the results\ndf = pd.DataFrame()\n\n# Apply AV settings to: Clean and save \"full\" locally in \"csv\" to \"~/av_data\"\ndf.av.api_key = \"DEMO\"\ndf.av.export = True\ndf.av.clean = True\ndf.av.output_size=\"full\"\n\n# Parameters\nquery = \"AA\"\nticker, crypto = \"MSFT\", \"BTC\"\nbase_fx, to_fx = \"USD\", \"CAD\"\n\nfound_symbols = df.av.search(query)\n\n# Global Quote\nquote_df = df.av.Q(ticker) # =\u003e df.av.quote(ticker)\nquote_df.av.name # returns \"MSFT\"\n\n# Company Information\nticker_overview = df.av.overview(ticker)\n\n# Earnings Calendar\n# The \"horizon\" is how many months out to look for Earnings. Options include:\n#   \"3month\", \"6month\", \"12month\". Default: \"3month\"\n# Optionally can use \"symbol\".\n#   Default: Returns all symbols with Earnings based on the \"horizon\".\nearnings_df = df.av.earnings()\nearnings6month_df = df.av.earnings(horizon=\"6month\")\nearnings12month_ticker_df = df.av.earnings(symbol=ticker, horizon=\"12month\")\n\n# IPO Calendar\nipos_df = df.av.ipos()\n\n\n# Listing Status\n# Optionally can use \"state\". Options: \"active\" or \"delisted\".\n#   Default: \"active\".\n# Optionally can use \"date\". Options: None or \"YYYY-MM-DD\".\n#   Default: None\nlisted_df = df.av.listed()\nlistedon_df = df.av.listed(date=\"2013-08-03\")\n\ndelisted_df = df.av.listed(state=\"delisted\")\ndelistedon_df = df.av.listed(state=\"delisted\", date=\"2009-02-14\")\n\n\n# Balance Sheet, Cash Flow, and the Income Statement each return two DataFrames\nticker_quarterly_balance, ticker_annual_balance = df.av.balance(ticker)\nticker_quarterly_cashflow, ticker_annual_cashflow = df.av.cashflow(ticker)\nticker_quarterly_income, ticker_annual_income = df.av.income(ticker)\n\n# FX / Currency\nfx_I5_df = df.av.fx_intraday(base_fx, to_currency=to_fx, interval=5)        # Intraday as int\nfx_I60_df = df.av.fx_intraday(base_fx, to_currency=to_fx, interval=\"60min\") # Intraday as str\nfx_D_df = df.av.fx_daily(base_fx, to_currency=to_fx)   # Daily\nfx_W_df = df.av.fx_weekly(base_fx, to_currency=to_fx)  # Weekly\nfx_M_df = df.av.fx_monthly(base_fx, to_currency=to_fx) # Monthly\n\n# Crypto Rating\nbtc_rating_df = df.av.crypto_rating(crypto)\nbtc_rating_df.av.name # returns \"BTC\"\n\n# Digital/Crypto\nbtc_usd_D_df = df.av.digital_daily(crypto, market=base_fx)   # Daily\nbtc_usd_D_df.av.name # returns \"BTC.USD\"\nbtc_usd_W_df = df.av.digital_weekly(crypto, market=base_fx)  # Weekly\nbtc_usd_M_df = df.av.digital_monthly(crypto, market=base_fx) # Monthly\n\n# Equities/ ETFs\nticker_I5_df = df.av.intraday(ticker, interval=5)        # Intraday as int\nticker_I5_df.av.name # returns \"MSFT\"\nticker_I60_df = df.av.intraday(ticker, interval=\"60min\") # Intraday as str\nticker_IE5_df = df.av.intraday_ext(ticker, interval=5) # Adjusted Intraday Extended. Default slice: \"year1month1\"\nticker_IE30_df = df.av.intraday_ext(ticker, interval=\"30min\", slice=\"year2month6\") # Adjusted Intraday Extended with slice\nticker_IE60_R_df = df.av.intraday_ext(ticker, interval=60, slice=\"year2month1\", adjusted=False) # Raw Intraday Extended with slice\n\nticker_D_df = df.av.daily(ticker)                        # Daily\nticker_DA_df = df.av.daily_adjusted(ticker)              # Daily Adjusted\nticker_W_df = df.av.weekly(ticker)                       # Weekly\nticker_WA_df = df.av.weekly_adjusted(ticker)             # Weekly Adjusted\nticker_M_df = df.av.monthly(ticker)                      # Monthly\nticker_MA_df = df.av.monthly_adjusted(ticker)            # Monthly Adjusted\n```\n\n\u003cbr/\u003e\n\n# Inspiration\n\nIf this module does not suit your style or workflow, consider some of the following *AlphaVantage API Python Wrapper* implementations by: [Romel Torres](https://github.com/RomelTorres/alpha_vantage) or [portfoliome](https://github.com/portfoliome/alphavantage)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwopirllc%2Falphavantageapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwopirllc%2Falphavantageapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwopirllc%2Falphavantageapi/lists"}