Alpha Vantage Tutorial (with Python/pandas Examples)

Alpha Vantage is one of the best free data sources for both historical prices and fundamental data. This tutorial shows all you need to know to get started.

Getting Alpha Vantage API key

To use Alpha Vantage API, you need an API key. Get it by registering on their website.

They have free and paid plans, subject to usage limits. The free plan allows maximum 500 API calls per day or 5 API calls per minute.

Once you have the API key, it is best to include it as constant at the beginning of your code. It is a string of 16 characters (at least in my case), including uppercase letters and digits.

AV_API_KEY = 'BD167Z1D2D74NVWM'  # not real

URL structure

Alpha Vantage datasets are accessible via URLs with a consistent structure:

https://www.alphavantage.co/query? ... parameters ...

For example:

End of day historical prices:
https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=IBM&apikey=demo

Intraday stock prices:
https://www.alphavantage.co/query?function=TIME_SERIES_INTRADAY&symbol=IBM&interval=5min&apikey=demo

Company balance sheet:
https://www.alphavantage.co/query?function=BALANCE_SHEET&symbol=IBM&apikey=demo

Earnings calendar for all US stocks 3 months ahead:
https://www.alphavantage.co/query?function=EARNINGS_CALENDAR&horizon=3month&apikey=demo

Output format

If you click on the example links above, you can see the actual data output (the apikey=demo does not work for other symbols, you need your own valid API key).

The output format for most datasets is JSON. Some are in CSV format for efficiency reasons.

URL parameters

Different datasets require different URL parameters. Those needed for most reports are:

• function = dataset type, e.g. TIME_SERIES_DAILY or BALANCE_SHEET
• symbol = the stock symbol (not needed for EARNINGS_CALENDAR and other multi-symbol datasets)
• apikey = your API key

Some datasets have additional optional parameters, such as start and end date or frequency.

Steps to get Alpha Vantage data

The steps for getting Alpha Vantage data into Python are:

1. Have your API key.
2. Construct the API request URL with correct parameters.
3. Call the URL and download data.
4. Process the data to your liking.

We have already discussed the first two steps. The rest depends on two things:

• API output format (JSON vs CSV)
• Your desired final output format (e.g. pandas DataFrame, database)

So it will be different for everyone. That said, because many people will want it in a pandas DataFrame, let's show how to get there.

Getting Alpha Vantage data into pandas DataFrame

CSV to pandas (pd.read_csv)

With the CSV API output format it is easy using pandas.read_csv(). You can pass the API url directly as argument:

import pandas as pd
url = "https://www.alphavantage.co/query?function=LISTING_STATUS&apikey=demo"
data = pd.read_csv(url)

JSON to pandas (requests.json + pd.DataFrame)

With the JSON API output format it is best to use Python requests module and its json() function for parsing and only then pass its output to the pandas DataFrame constructor, rather than using the pandas.read_json() function, due to the somehow complicated structure of the API output.

import requests
url = "https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=IBM&apikey=demo"
r = requests.get(url)
data = r.json()

The output of requests.json() is a dict:

{'Meta Data': {'1. Information': 'Daily Prices (open, high, low, close) and Volumes',
  '2. Symbol': 'IBM',
  '3. Last Refreshed': '2023-02-01',
  '4. Output Size': 'Compact',
  '5. Time Zone': 'US/Eastern'},
 'Time Series (Daily)': {'2023-02-01': {'1. open': '134.4900',
   '2. high': '135.7900',
   '3. low': '132.8000',
   '4. close': '135.0900',
   '5. volume': '5428898'},
  '2023-01-31': {'1. open': '135.5000',
   '2. high': '135.6500',
   '3. low': '133.7600',
   '4. close': '134.7300',
   '5. volume': '7206448'},
  '2023-01-30': {'1. open': '134.3200',
   ...

It has two items. The first key is 'Meta Data' and its value is another dict with summary information about the request.

The second item contains the actual data. Its key (for this particular dataset type – TIME_SERIES_DAILY) is 'Time Series (Daily)'. It can be converted to pandas DataFrame:

import pandas as pd
data = pd.DataFrame(data['Time Series (Daily)']).T

Notice the .T at the end. We need to transpose the DataFrame to get dates in rows and the different variables (open, high, low, close, volume) in columns:

             1. open   2. high    3. low  4. close 5. volume
2023-02-01  134.4900  135.7900  132.8000  135.0900   5428898
2023-01-31  135.5000  135.6500  133.7600  134.7300   7206448
2023-01-30  134.3200  136.1100  133.9800  135.3000   5375712
2023-01-27  134.4400  135.4880  133.7701  134.3900   8143146
2023-01-26  137.5300  138.2700  132.9800  134.4500  17548483

You may also want to rename the columns to remove the ordinal numbers.

data.columns = ['open', 'high', 'low', 'close', 'volume']

... and sort from oldest to newest (by default, Alpha Vantage time series are ordered from most recent data point to oldest):

data = data.sort_index()

alpha_vantage Python module

There is an easier way.

In various programming languages there are (unofficial) libraries for easier manipulation of Alpha Vantage data. Python has the most.

Install the alpha_vantage module:

pip install alpha_vantage

Notice the underscore. There is another library named alphavantage, but the examples in this tutorial only work with the underscore one.

Now we can download historical prices directly into pandas DataFrame:

from alpha_vantage.timeseries import TimeSeries

# Create TimeSeries object, enter your API key as arg
# Set output format ('pandas' / 'json' / 'csv')
ts = TimeSeries(key='demo', output_format='pandas')

# hp = historical prices (pd.df)
# md = meta data (dict)
hp, md = ts.get_daily_adjusted(symbol='IBM', outputsize='full')

All methods of the TimeSeries class to get different datasets:

get_daily
get_daily_adjusted
get_intraday
get_intraday_extended
get_monthly
get_monthly_adjusted
get_quote_endpoint
get_symbol_search
get_weekly
get_weekly_adjusted

Dealing with usage limits

If you are bulk downloading data, the easiest way to deal with Alpha Vantage usage limits is to make the execution wait 12 seconds between iterations, so you don't make more than 5 calls per minute. For instance, you can use the sleep function in Python.

Other programming languages

The code examples are in Python, but Alpha Vantage API supports various other languages (including but not limited to NodeJS, PHP, C#/.NET, R), where the code follows similar logic.

Alpha Vantage can also connect to Excel and Google Sheets (official add-ons here).

Official documentation

https://www.alphavantage.co/documentation/