alpha_vantage Documentation

A python wrapper for Alpha Vantage API for financial data.

4,810 stars Python Python 1 file · ~4,661 tokens #alpha-vantage#alphavantage#api-wrapper#bitcoin#cryptocurrency#finance#financial-data#json
RAW Doc

File: README.md

alpha_vantage



Python module to get stock data/cryptocurrencies from the Alpha Vantage API

Alpha Vantage delivers a free API for real time financial data and most used finance indicators in a simple json or pandas format. This module implements a python interface to the free API provided by Alpha Vantage. It requires a free API key, that can be requested from http://www.alphavantage.co/support/#api-key. You can have a look at all the API calls available in their API documentation.

For code-less access to financial market data, you may also consider Wisesheets or the official Google Sheet Add-on or the Microsoft Excel Add-on by Alpha Vantage. Check out this guide for some common tips on working with financial market data.

News

  • From version 3.0.0 onwards, all options, commodities, and economic indicators are supported, as well as various additional features in alpha intelligence and fundamental data. All sector performance, extended intraday, and the FCAS crypto rating have been deprecated. Support for the month parameter for technical indicators and entitlement, as necessary, have also been added. This release is also friendly for porting from IEX Cloud, which was shut down in 2024. This library is now fully compatible with the sample Python code and schema published by API Market and Non-Brand Data.
  • From version 2.3.0 onwards, fundamentals data and extended intraday is supported.
  • From version 2.2.0 onwards, asyncio support now provided. See below for more information.
  • From version 2.1.3 onwards, rapidAPI key integration is now available.
  • From version 2.1.0 onwards, error logging of bad API calls has been made more apparent.
  • From version 1.9.0 onwards, the urllib was substituted by pythons request library that is thread safe. If you have any error, post an issue.
  • From version 1.8.0 onwards, the column names of the data frames have changed, they are now exactly what alphavantage gives back in their json response. You can see the examples in better detail in the following git repo: https://github.com/RomelTorres/av_example
  • From version 1.6.0, pandas was taken out as a hard dependency.

Install

To install the package use:

shell
pip install alpha_vantage

Or install with pandas support, simply install pandas too:

shell
pip install alpha_vantage pandas

If you want to install from source, then use:

shell
git clone https://github.com/RomelTorres/alpha_vantage.git
pip install -e alpha_vantage

✨ New! Don't want to write any code? Try out https://trading-agents.ai/ (#1 trending on Github), which uses the Alpha Vantage API at the backend.

Usage

To get data from the API, simply import the library and call the object with your API key. Next, get ready for some awesome, free, realtime finance data. Your API key may also be stored in the environment variable ALPHAVANTAGE_API_KEY.

python
from alpha_vantage.timeseries import TimeSeries
ts = TimeSeries(key='YOUR_API_KEY')
# Get json object with the intraday data and another with  the call's metadata
data, meta_data = ts.get_intraday('GOOGL')

To query data from a specific month in history, you may use the 'month' parameter for various features.

python
from alpha_vantage.timeseries import TimeSeries
from alpha_vantage.techindicators import TechIndicators
ts = TimeSeries(key='YOUR_API_KEY')
ti = TechIndicators(key='YOUR_API_KEY')
# Get json object with the 30-min interval intraday data and another with  the call's metadata for January, 2014.
data, meta_data = ts.get_intraday('GOOGL', month='2014-01', interval='30min')
#Get json object with the 30-min interval simple moving average (SMA) values and another with  the call's metadata for January, 2014.
data, meta_data = ti.get_sma('GOOGL', month='2014-01', interval='30min')

You may also get a key from rapidAPI. Use your rapidAPI key for the key variable, and set rapidapi=True

python
ts = TimeSeries(key='YOUR_API_KEY',rapidapi=True)

Internally there is a retries counter, that can be used to minimize connection errors (in case that the API is not able to respond in time), the default is set to
5 but can be increased or decreased whenever needed.

python
ts = TimeSeries(key='YOUR_API_KEY',retries='YOUR_RETRIES')

The library supports giving its results as json dictionaries (default), pandas dataframe (if installed) or csv, simply pass the parameter output_format='pandas' to change the format of the output for all the API calls in the given class. Please note that some API calls do not support the csv format (namely ForeignExchange and TechIndicators) because the API endpoint does not support the format on their calls either.

python
ts = TimeSeries(key='YOUR_API_KEY',output_format='pandas')

The pandas data frame given by the call, can have either a date string indexing or an integer indexing (by default the indexing is 'date'),
depending on your needs, you can use both.

python
# For the default date string index behavior
ts = TimeSeries(key='YOUR_API_KEY',output_format='pandas', indexing_type='date')
# For the default integer index behavior
ts = TimeSeries(key='YOUR_API_KEY',output_format='pandas', indexing_type='integer')

Data frame structure

The data frame structure is given by the call on alpha vantage rest API. The column names of the data frames
are the ones given by their data structure. For example, the following call:

python
from alpha_vantage.timeseries import TimeSeries
from pprint import pprint
ts = TimeSeries(key='YOUR_API_KEY', output_format='pandas')
data, meta_data = ts.get_intraday(symbol='MSFT',interval='1min', outputsize='full')
pprint(data.head(2))

Would result on:

The headers from the data are specified from Alpha Vantage (in previous versions, the numbers in the headers were removed, but long term is better to have the data exactly as Alpha Vantage produces it.)

Plotting

Time Series

Using pandas support we can plot the intra-minute value for 'MSFT' stock quite easily:

python
from alpha_vantage.timeseries import TimeSeries
import matplotlib.pyplot as plt

ts = TimeSeries(key='YOUR_API_KEY', output_format='pandas')
data, meta_data = ts.get_intraday(symbol='MSFT',interval='1min', outputsize='full')
data['4. close'].plot()
plt.title('Intraday Times Series for the MSFT stock (1 min)')
plt.show()

Giving us as output:

Technical indicators

The same way we can get pandas to plot technical indicators like Bollinger Bands®

python
from alpha_vantage.techindicators import TechIndicators
import matplotlib.pyplot as plt

ti = TechIndicators(key='YOUR_API_KEY', output_format='pandas')
data, meta_data = ti.get_bbands(symbol='MSFT', interval='60min', time_period=60)
data.plot()
plt.title('BBbands indicator for  MSFT stock (60 min)')
plt.show()

Giving us as output:

Crypto currencies.

We can also plot crypto currencies prices like BTC:

python
from alpha_vantage.cryptocurrencies import CryptoCurrencies
import matplotlib.pyplot as plt

cc = CryptoCurrencies(key='YOUR_API_KEY', output_format='pandas')
data, meta_data = cc.get_digital_currency_daily(symbol='BTC', market='CNY')
data['4b. close (USD)'].plot()
plt.tight_layout()
plt.title('Daily close value for bitcoin (BTC)')
plt.grid()
plt.show()

Giving us as output:
")

Foreign Exchange (FX)

The foreign exchange endpoint has no metadata, thus only available as json format and pandas (using the 'csv' format will raise an Error)

python
from alpha_vantage.foreignexchange import ForeignExchange
from pprint import pprint
cc = ForeignExchange(key='YOUR_API_KEY')
# There is no metadata in this call
data, _ = cc.get_currency_exchange_rate(from_currency='BTC',to_currency='USD')
pprint(data)

Giving us as output:

text
{
    '1. From_Currency Code': 'BTC',
    '2. From_Currency Name': 'Bitcoin',
    '3. To_Currency Code': 'USD',
    '4. To_Currency Name': 'United States Dollar',
    '5. Exchange Rate': '5566.80500105',
    '6. Last Refreshed': '2017-10-15 15:13:08',
    '7. Time Zone': 'UTC'
}

Asyncio support

From version 2.2.0 on, asyncio support will now be available. This is only for python versions 3.5+. If you do not have 3.5+, the code will break.

The syntax is simple, just mark your methods with the async keyword, and use the await keyword.

Here is an example of a for loop for getting multiple symbols asyncronously. This greatly improving the performance of a program with multiple API calls.

python
import asyncio
from alpha_vantage.async_support.timeseries import TimeSeries

symbols = ['AAPL', 'GOOG', 'TSLA', 'MSFT']


async def get_data(symbol):
    ts = TimeSeries(key='YOUR_KEY_HERE')
    data, _ = await ts.get_quote_endpoint(symbol)
    await ts.close()
    return data

loop = asyncio.get_event_loop()
tasks = [get_data(symbol) for symbol in symbols]
group1 = asyncio.gather(*tasks)
results = loop.run_until_complete(group1)
loop.close()
print(results)

We have written a much more in depth article to explain asyncio for those who have never used it but want to learn about asyncio, concurrency, and multi-threading. Check it out here: Which Should You Use: Asynchronous Programming or Multi-Threading?

Examples

I have added a repository with examples in a python notebook to better see the
usage of the library: https://github.com/RomelTorres/av_example

Tests

In order to run the tests you have to first export your API key so that the test can use it to run, also the tests require pandas, mock and nose.

shell
export API_KEY=YOUR_API_KEY
cd alpha_vantage
nosetests

Documentation

The code documentation can be found at https://alpha-vantage.readthedocs.io/en/latest/

Contributing

Contributing is always welcome. Just contact us on how best you can contribute, add an issue, or make a PR.

Community Pulses:

Contact:

You can reach/follow the Alpha Vantage team on any of the following platforms:

Star if you like it.

If you like or use this project, consider showing your support by starring it.

:venezuela:-:de:

File: docs/source/alpha_vantage.rst

alpha\_vantage package

Submodules

alpha\_vantage\.alphavantage module

.. automodule:: alpha_vantage.alphavantage
:members:
:undoc-members:
:show-inheritance:

alpha\_vantage\.cryptocurrencies module

.. automodule:: alpha_vantage.cryptocurrencies
:members:
:undoc-members:
:show-inheritance:

alpha\_vantage\.foreignexchange module

.. automodule:: alpha_vantage.foreignexchange
:members:
:undoc-members:
:show-inheritance:

alpha\_vantage\.sectorperformance module

.. automodule:: alpha_vantage.sectorperformance
:members:
:undoc-members:
:show-inheritance:

alpha\_vantage\.techindicators module

.. automodule:: alpha_vantage.techindicators
:members:
:undoc-members:
:show-inheritance:

alpha\_vantage\.timeseries module

.. automodule:: alpha_vantage.timeseries
:members:
:undoc-members:
:show-inheritance:

Module contents

.. automodule:: alpha_vantage
:members:
:undoc-members:
:show-inheritance:

File: docs/index.rst

.. alpha_vantage documentation master file, created by
sphinx-quickstart on Sun May 28 14:23:31 2017.
You can adapt this file completely to your liking, but it should at least
contain the root toctree directive.

Welcome to alpha_vantage's documentation!

|Build Status| |PyPI version| |Documentation Status|

Python module to get stock data from the Alpha Vantage API

The Alpha Vantage Stock API <https://www.alphavantage.co/>_ provides free JSON access to the stock market, plus a comprehensive set of technical indicators. This project is a python wrapper around this API to offer python plus json/pandas support. I hope you enjoy it.
It requires a free API, that can be requested on http://www.alphavantage.co/support/#api-key. This stock API article <https://medium.com/@patrick.collins_58673/stock-api-landscape-5c6e054ee631>_ also contains general guidance on ingesting and integrating with market data.

If you are a spreadsheet user, see also:
Microsoft Excel Add-on <https://appsource.microsoft.com/en-us/product/office/WA200001365>_ and
Google Sheets Add-on <https://gsuite.google.com/marketplace/app/alpha_vantage_market_data/434809773372>_

Install

To install the package use:

.. code:: shell

text
pip install alpha_vantage

If you want to install from source, then use:

.. code:: shell

text
git clone https://github.com/RomelTorres/alpha_vantage.git
pip install -e alpha_vantage

Usage Example

This is a simple code snippet to get global quotes from the

.. code:: python

text
from alpha_vantage.timeseries import TimeSeries
import matplotlib.pyplot as plt

ts = TimeSeries(key='YOUR_API_KEY', output_format='pandas')
data, meta_data = ts.get_intraday(symbol='MSFT',interval='1min', outputsize='full')
data['close'].plot()
plt.title('Intraday Times Series for the MSFT stock (1 min)')
plt.show()

Code & Issue Tracker

The code is hosted in github: https://github.com/RomelTorres/alpha_vantage
And the issue tracker as well: https://github.com/RomelTorres/alpha_vantage/issues

Contributions

If you have a feature that you want to see merged in the code, please do a pull request with it and it will be evaluated.

Community Pulse

  • Alpha Vantage used by Harvard COVID-19 Global Policy Tracker <https://projects.iq.harvard.edu/covidpt/global-policy-tracker>_ (link <https://www.hbs.edu/covid-19-business-impact/Insights/Economic-and-Financial-Impacts/Global-Policy-Tracker>) and a recent economic review <http://blogs.harvard.edu/econreview/2020/08/25/why-you-need-a-reliable-stock-market-data-api-in-2020/>
  • Alpha Vantage featured in Xignite stock API press release <https://www.xignite.com/news/best-6-free-and-paid-stock-market-apis/>_ and Best 5 (Free and Paid) Stock Market APIs in 2020 <https://wp.nyu.edu/qids/2020/06/23/best-stock-api-2020/>_ by NYU's Quantitative Investing project

License

This project is licensed under the MIT license.

Contents

.. toctree::
:maxdepth: 4

Indices and tables

  • :ref:genindex
  • :ref:modindex
  • :ref:search

Documentation

To find out more about the available api calls, visit the alpha-vantage
documentation at http://www.alphavantage.co/documentation/

.. |Build Status| image:: https://travis-ci.org/RomelTorres/alpha_vantage.png?branch=master
:target: https://travis-ci.org/RomelTorres/alpha_vantage
.. |PyPI version| image:: https://badge.fury.io/py/alpha-vantage.svg
:target: https://badge.fury.io/py/alpha_vantage
.. |Documentation Status| image:: https://readthedocs.org/projects/alpha-vantage/badge/?version=latest
:target: http://alpha-vantage.readthedocs.io/en/latest/?badge=latest

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#alpha-vantage Browse alpha-vantage catalog → #alphavantage Browse alphavantage catalog → #api-wrapper Browse api-wrapper catalog → #bitcoin Browse bitcoin catalog → #cryptocurrency Browse cryptocurrency catalog → #finance Browse finance catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →