Alpha Vantage Python Library

Common errors

• ValueError: Invalid API call. Please retry or visit the documentation (https://www.alphavantage.co/documentation/) for <FUNCTION_NAME>.

  cause This error typically occurs when an invalid symbol or an unsupported function/parameter is used, or when attempting to access a premium feature (like `outputsize='full'`) with a free API key.
  fix Double-check the symbol and parameters against the Alpha Vantage API documentation. Ensure your API key supports the requested feature. For historical data, try `outputsize='compact'` if using a free key. Confirm the API key is correctly provided to the library.

• KeyError: 'Time Series (Daily)'

  cause This usually indicates that the API response did not contain the expected 'Time Series (Daily)' key, often due to an invalid API key, an incorrect symbol, or hitting API rate limits, leading to an empty or malformed response from the Alpha Vantage API.
  fix Verify your API key is correct and active. Check the symbol for typos or if it's supported by Alpha Vantage. Ensure you are not exceeding the API call limits (5 calls/minute for free tier). Inspect the raw JSON response if possible to diagnose the missing key.

• Could not authenticate. Please check your credentials.

  cause The Alpha Vantage API key provided is invalid, expired, or has insufficient permissions for the requested data.
  fix Obtain a new API key from the Alpha Vantage website. Double-check that the API key is copied and pasted correctly without extra spaces or characters. Ensure it's correctly passed to the `TimeSeries` (or other client) constructor, or set as the `ALPHAVANTAGE_API_KEY` environment variable.

Warnings

• gotcha The free Alpha Vantage API key has strict rate limits, typically 5 calls per minute and 500 calls per day. Exceeding these limits will result in API errors or blocked access. Some user reports indicate stricter limits (e.g., 25/day) in certain scenarios.
  Fix: Implement proper rate limiting and exponential backoff in your code. For higher call volumes, consider a premium Alpha Vantage plan. Store your API key as an environment variable (ALPHAVANTAGE_API_KEY) to avoid hardcoding.
• breaking As of version 3.0.0, several data endpoints have been deprecated. Specifically, 'All sector performance, extended intraday, and the FCAS crypto rating have been deprecated.' This means functions related to these services will no longer work or return data.
  Fix: Review the official Alpha Vantage API documentation for updated endpoints and alternative data sources if your application relies on these deprecated features. Adjust your code to use new or existing supported functions.
• gotcha The `outputsize='full'` parameter for historical time series data (e.g., `get_daily_adjusted`) is a premium feature. Using it with a free API key will result in an 'Invalid API call' error message from the Alpha Vantage API.
  Fix: For free API keys, use `outputsize='compact'` which returns the latest 100 data points. To access full historical data, a premium Alpha Vantage membership is required.
• gotcha Prior to version 1.8.0, the library might have modified column names (e.g., removing numbers like '4. close' to 'close'). From version 1.8.0 onwards, DataFrame column names precisely match the JSON response from the Alpha Vantage API. This can break older code expecting simplified names.
  Fix: Update your code to account for the exact column names returned by the API. If migrating old code, verify the expected column names in your data processing logic.

Install

• pip install alpha-vantage Install base package
• pip install "alpha-vantage[pandas]" Install with pandas support

Imports

• TimeSeries

  from alpha_vantage.timeseries import TimeSeries

• DigitalCurrency

  from alpha_vantage.cryptocurrencies import DigitalCurrency

• FundamentalData

  from alpha_vantage.fundamentaldata import FundamentalData

Quickstart

This quickstart demonstrates how to initialize the `TimeSeries` object with an API key (preferably from an environment variable) and fetch daily adjusted stock data and a real-time global quote, displaying the output using pandas DataFrames. Ensure you have `pandas` installed for DataFrame output.

import os
from alpha_vantage.timeseries import TimeSeries
import pandas as pd

# Get your Alpha Vantage API key from environment variable or replace 'YOUR_API_KEY'
# Register for a free API key at https://www.alphavantage.co/support/#api-key
api_key = os.environ.get('ALPHAVANTAGE_API_KEY', 'YOUR_API_KEY')

if api_key == 'YOUR_API_KEY':
    print("Warning: Please replace 'YOUR_API_KEY' with your actual Alpha Vantage API key or set the ALPHAVANTAGE_API_KEY environment variable.")
    print("You can get a free API key at: https://www.alphavantage.co/support/#api-key")
    exit()

try:
    # Initialize TimeSeries with your API key and set output format to pandas DataFrame
    ts = TimeSeries(key=api_key, output_format='pandas')

    # Get daily adjusted time series for a symbol (e.g., IBM)
    print("Fetching daily adjusted data for IBM...")
    data, meta_data = ts.get_daily_adjusted(symbol='IBM', outputsize='compact')

    print("\n--- Daily Adjusted Data (last 5 rows) ---")
    print(data.tail())

    # Get real-time global quote for a symbol
    print("\nFetching global quote for AAPL...")
    global_quote, meta_global_quote = ts.get_global_quote(symbol='AAPL')

    print("\n--- Global Quote for AAPL ---")
    # The global_quote result is usually a dictionary, not a DataFrame for single quotes
    # Convert to DataFrame for consistent printing, if it's a dict (which it often is for single quote)
    if isinstance(global_quote, dict):
        print(pd.DataFrame([global_quote]))
    else:
        print(global_quote)

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure your API key is correct and you are not exceeding rate limits (5 calls/minute for free tier).")