AlphaVantageAPI An Opinionated AlphaVantage API Wrapper in Python 3.9 Description This API has been designed to simplify the process of aquiring financial data from AlphaVantage 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 . AlphaVantage Support and Contact Email: support@alphavantage.co Slack Twitter: @alpha_vantage Medium-AlphaVantage Community events: https://alphavhack.devpost.com/ Contributing Contributions are welcome and I am open to new ideas or implementations. Thank you! Sciguymjm Features Access to AlphaVantage requires an API key . API Keys are free . Built with Pandas for a simpler ETL pipeline. Available export formats: csv (default), json , pkl , html , txt , and xlsx (if openpyxl package is installed) Extended the Pandas DataFrame with extension 'av'. See the Extension Example below. 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. Simplifies column names i.e. "1. open" -> "open" when clean=True . A help method to reduce looking up 'required' and 'optional' parameters for each function. A call_history method to return all successful API calls. What's New? !!! Updated requirements.txt to fix urllib3 security vulnerability. !!! Added Intraday Extended There are some breaking changes! Please see the Classic Example and the DataFrame Extension Example below. AlphaVantage has added Fundamental Data: Company Overview , Balance Sheet , Cash Flow , Income Statement , Earnings Calendar , IPO Calendar and Listing Status . What's Gone? AlphaVantage has depreciated batch , digital_intraday , and sectors . Installation Stable The pip version is the last most stable release. Version: 1.0.30 $ pip install alphaVantage-api Latest Version Best choice! Version: 1.0.33 $ pip install -U git+https://github.com/twopirllc/AlphaVantageAPI Excel Export $ pip install openpyxl Programming Conventions There are two ways of utilizing AlphaVantageAPI. The Standard Class way or as a Pandas DataFrame Extension 'av'. Standard This is the Object/Class way. Instantiate a Class with predefined parameters and then make calls. Parameter Defaults api_key : str = None premium : bool = False output_size : str = 'compact' datatype : str = 'json' export : bool = False export_path : str = '~/av_data' output : str = 'csv' clean : bool = False proxy : dict = {} API Parameter Descriptions api_key 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. premium *Got premium? Excellent! You do not need to wait 15.0001 seconds between each API call. output_size The other option is 'full'. See AlphaVantage API documentation for more details. datatype The preferred request type. See AlphaVantage API documentation for more details. export *Set it to True if you want to save the file locally according to the export_path property. export_path The path of where you want to save the data. output 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'. clean Simplifies the column header names for instance: "1. open" -> "open". proxy See requests API documentation for more details. Example : Class(ic) Behavior Initialization from alphaVantageAPI import AlphaVantage # Initialize the AlphaVantage Class with default values av = AlphaVantage ( api_key = None , premium = False , output_size = "compact" , datatype = 'json' , export = False , export_path = "~/av_data" , output = "csv" , clean = False , proxy = {} ) Help! # Help: lists all the functions and indicators AlphaVantage API supports av . help () # Print 'function' aliases av . help ( "aliases" ) # Help with a specific API function av . help ( "TIME_SERIES_DAILY" ) # Help with an indicator av . help ( "BBANDS" ) Class Usage import pandas as pd import alphaVantageAPI as AV # Initialize, clean and save "full" locally in "csv" to "~/av_data" av = AV . AlphaVantage ( api_key = "demo" , export = True , clean = True , output_size = "full" ) # Check Settings print ( av ) # Parameters query = "AA" ticker , crypto = "MSFT" , "BTC" base_fx , to_fx = "USD" , "CAD" # Symbol Search found_symbols = av . search ( query ) # Global Quote quote_df = av . quote ( ticker ) # Earnings Calendar # The "horizon" is how many months out to look for Earnings. Options include: # "3month", "6month", "12month". Default: "3month" # Optionally can use "symbol". # Default: Returns all symbols with Earnings based on the "horizon". # All symbols with Earnings in 3 months earnings_df = av . earnings () # All symbols with Earnings in 6 months earnings6mo_df = av . earnings ( horizon = "6month" ) # Earnings Calendar in 3 months for 'symbol' earnings_ticker_df = av . earnings ( symbol = ticker ) # Earnings Calendar in 6 months for 'symbol' earnings6mo_ticker_df = av . earnings ( symbol = ticker , horizon = "6month" ) # IPO Calendar ipos_df = av . ipos () # Listing Status # Optionally can use "state". Options: "active" or "delisted". # Default: "active". # Optionally can use "date". Options: None or "YYYY-MM-DD". # Default: None listed_df = av . listed () listedon_df = av . listed ( date = "2013-08-03" ) delisted_df = av . listed ( state = "delisted" ) delistedon_df = av . listed ( state = "delisted" , date = "2009-02-14" ) # Company Overview overview_df = av . overview ( ticker ) # Balance Sheet, Income Statement and Cash Flow each return a list or a dict (if # as_dict=True). Default: List with two DataFrames: [Quarterlydf, Annuallydf] balance_list = av . balance ( ticker ) # Balance Sheet QuarterlyBSdf = balance_list [ 0 ] AnnuallyBSdf = balance_list [ 1 ] cashflow_list = av . cashflow ( ticker ) # Cash Flow income_list = av . income ( ticker ) # Income Statement # FX / Currency fx_rate_df = av . fxrate ( from_symbol = base_fx , to_symbol = to_fx ) # Rate fx_I5_df = av . fx ( from_symbol = base_fx , to_symbol = to_fx , function = "FXI" , interval = 5 ) # Intraday as int fx_I60_df = av . fx ( from_symbol = base_fx , to_symbol = to_fx , function = "FXI" , interval = "60min" ) # Intraday as str fx_D_df = av . fx ( from_symbol = base_fx , to_symbol = to_fx , function = "FXD" ) # Daily fx_W_df = av . fx ( from_symbol = base_fx , to_symbol = to_fx , function = "FXW" ) # Weekly fx_M_df = av . fx ( from_symbol = base_fx , to_symbol = to_fx , function = "FXM" ) # Monthly # Crypto Rating btc_rating_df = av . crypto_rating ( symbol = crypto ) # == ds.crypto_rating(crypto) # Digital/Crypto btc_usd_D_df = av . digital ( symbol = crypto , market = base_fx , function = "CD" ) # Daily btc_usd_W_df = av . digital ( symbol = crypto , market = base_fx , function = "CW" ) # Weekly btc_usd_M_df = av . digital ( symbol = crypto , market = base_fx , function = "CM" ) # Monthly # Generic Equity/ETF calls ticker_I5_df = av . intraday ( symbol = ticker , interval = 5 ) # Intraday as int ticker_I60_df = av . intraday ( symbol = ticker , interval = "60min" ) # Intraday as str ticker_IE5_df = av . intraday_extended ( symbol = ticker , interval = 5 ) # Adjusted Intraday Extended. Default slice: "year1month1" ticker_IE30_df = av . intraday_extended ( symbol = ticker , interval = "30min" , slice = "year2month6" ) # Adjusted Intraday Extended with slice ticker_IE60_R_df = av . intraday_extended ( symbol = ticker , interval = 60 , slice = "year2month1" , adjusted = False ) # Raw Intraday Extended with slice ticker_D_df = av . data ( symbol = ticker , function = "D" ) # Daily ticker_DA_df = av . data ( symbol = ticker , function = "DA" ) # Daily Adjusted ticker_W_df = av . data ( symbol = ticker , function = "W" ) # Weekly ticker_WA_df = av . data ( symbol = ticker , function = "WA" ) # Weekly Adjusted ticker_M_df = av . data ( symbol = ticker , function = "M" ) # Monthly ticker_MA_df = av . data ( symbol = ticker , function = "MA" ) # Monthly Adjusted ## Indicators # SMA(close, 20) ticker_SMA_20_df = av . data ( symbol = ticker , function = "SMA" , series_type = "close" , time_period = 20 ) # STOCH(close) ticker_STOCH_df = av . data ( "STOCH" , symbols [ 2 ], interval = "daily" , series_type = "close" ) # List of symbols Daily symbols = [ "AAPL" , "MSFT" , "XLK" ] # returns dict of DataFrames: {"ABC": pd.DataFrame(), .. techs = av . data ( symbols , "D" ).} [ print ( techs [ s ]) for s in symbols ] # History of Successful Calls to AlphaVantage history = pd . DataFrame ( av . call_history ()) print ( history ) Call History # Returns all successfull calls to the API history_list = av . call_history () # Pretty display of Call History history_df = pd . DataFrame ( history_list )[[ "symbol" , "function" , "interval" , "time_period" ]] print ( history_df ) Example : DataFrame Extension 'av' Behavior Initialization For simplicity and protection of your AV API key, the extension uses the environment variable AV_API_KEY upon import of the module. import pandas as pd import alphaVantageAPI Empty DataFrame: No current data, no problem! Since '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. df = pd . DataFrame () Setting properties Same as the Class properties above. Use the 'av' extension to change them prior to requesting data or adjusting on the fly # Your API KEY. Default: None df . av . api_key = "DEMO" # Whether you have a Premium Account. Default: False df . av . premium = False # Simplify OHLCV columns. Default: False df . av . clean = True # Whether to export (save locally). Default: False df . av . export = True # Output Size: "compact" or "full". Default: "compact" df . av . output_size = "full" # Retrieval Format. Default: "json" df . av . datatype = "json" # Export Path to save output format. Default: "~/av_data" df . av . export_path = "~/av_data" # Final output format. Default: "csv" df . av . output = "csv" # Proxy to use. Default: {} df . av . proxy = {} Help! # Help: lists all the functions and indicators AlphaVantage API supports df . av . help () # Print 'function' aliases df . av . help ( "aliases" ) # Help with a specific API function df . av . help ( "TIME_SERIES_DAILY" ) # Help with an indicator df . av . help ( "BBANDS" ) Data Acquisition Methods import pandas as pd import alphaVantageAPI # Create an Empty DataFrame to store the results df = pd . DataFrame () # Apply AV settings to: Clean and save "full" locally in "csv" to "~/av_data" df . av . api_key = "DEMO" df . av . export = True df . av . clean = True df . av . output_size = "full" # Parameters query = "AA" ticker , crypto = "MSFT" , "BTC" base_fx , to_fx = "USD" , "CAD" found_symbols = df . av . search ( query ) # Global Quote quote_df = df . av . Q ( ticker ) # => df.av.quote(ticker) quote_df . av . name # returns "MSFT" # Company Information ticker_overview = df . av . overview ( ticker ) # Earnings Calendar # The "horizon" is how many months out to look for Earnings. Options include: # "3month", "6month", "12month". Default: "3month" # Optionally can use "symbol". # Default: Returns all symbols with Earnings based on the "horizon". earnings_df = df . av . earnings () earnings6month_df = df . av . earnings ( horizon = "6month" ) earnings12month_ticker_df = df . av . earnings ( symbol = ticker , horizon = "12month" ) # IPO Calendar ipos_df = df . av . ipos () # Listing Status # Optionally can use "state". Options: "active" or "delisted". # Default: "active". # Optionally can use "date". Options: None or "YYYY-MM-DD". # Default: None listed_df = df . av . listed () listedon_df = df . av . listed ( date = "2013-08-03" ) delisted_df = df . av . listed ( state = "delisted" ) delistedon_df = df . av . listed ( state = "delisted" , date = "2009-02-14" ) # Balance Sheet, Cash Flow, and the Income Statement each return two DataFrames ticker_quarterly_balance , ticker_annual_balance = df . av . balance ( ticker ) ticker_quarterly_cashflow , ticker_annual_cashflow = df . av . cashflow ( ticker ) ticker_quarterly_income , ticker_annual_income = df . av . income ( ticker ) # FX / Currency fx_I5_df = df . av . fx_intraday ( base_fx , to_currency = to_fx , interval = 5 ) # Intraday as int fx_I60_df = df . av . fx_intraday ( base_fx , to_currency = to_fx , interval = "60min" ) # Intraday as str fx_D_df = df . av . fx_daily ( base_fx , to_currency = to_fx ) # Daily fx_W_df = df . av . fx_weekly ( base_fx , to_currency = to_fx ) # Weekly fx_M_df = df . av . fx_monthly ( base_fx , to_currency = to_fx ) # Monthly # Crypto Rating btc_rating_df = df . av . crypto_rating ( crypto ) btc_rating_df . av . name # returns "BTC" # Digital/Crypto btc_usd_D_df = df . av . digital_daily ( crypto , market = base_fx ) # Daily btc_usd_D_df . av . name # returns "BTC.USD" btc_usd_W_df = df . av . digital_weekly ( crypto , market = base_fx ) # Weekly btc_usd_M_df = df . av . digital_monthly ( crypto , market = base_fx ) # Monthly # Equities/ ETFs ticker_I5_df = df . av . intraday ( ticker , interval = 5 ) # Intraday as int ticker_I5_df . av . name # returns "MSFT" ticker_I60_df = df . av . intraday ( ticker , interval = "60min" ) # Intraday as str ticker_IE5_df = df . av . intraday_ext ( ticker , interval = 5 ) # Adjusted Intraday Extended. Default slice: "year1month1" ticker_IE30_df = df . av . intraday_ext ( ticker , interval = "30min" , slice = "year2month6" ) # Adjusted Intraday Extended with slice ticker_IE60_R_df = df . av . intraday_ext ( ticker , interval = 60 , slice = "year2month1" , adjusted = False ) # Raw Intraday Extended with slice ticker_D_df = df . av . daily ( ticker ) # Daily ticker_DA_df = df . av . daily_adjusted ( ticker ) # Daily Adjusted ticker_W_df = df . av . weekly ( ticker ) # Weekly ticker_WA_df = df . av . weekly_adjusted ( ticker ) # Weekly Adjusted ticker_M_df = df . av . monthly ( ticker ) # Monthly ticker_MA_df = df . av . monthly_adjusted ( ticker ) # Monthly Adjusted Inspiration If this module does not suit your style or workflow, consider some of the following AlphaVantage API Python Wrapper implementations by: Romel Torres or portfoliome
