Alpha Vantage Fundamental Data

Alpha Vantage provides several fundamental datasets for each stock - latest and historical financial statements (income statement, balance sheet, cash flow statement), earnings history, and summary company overview. This page explains how to get each, complete with parameters and output formats.

API URL format

Alpha Vantage datasets are generally accessible with API URL where the main parameter is function, which specifies the dataset required.

Most datasets also have the parameter symbol, which specifies the stock symbol, and apikey, where you enter your Alpha Vantage API key.

For example:

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

The example URLs on this page use apikey=demo, which only works with symbol=IBM. For other symbols you need to get your own API key.

Income statement

Income statement is accessible using function=INCOME_STATEMENT. The complete URL (the IBM demo example) is:

https://www.alphavantage.co/query?function=INCOME_STATEMENT&symbol=IBM&apikey=demo

Balance sheet

Balance sheet for each company is available under function=BALANCE_SHEET. The url is:

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

Cash flow statement

Cash flow statement is under function=CASH_FLOW. The URL is:

https://www.alphavantage.co/query?function=CASH_FLOW&symbol=IBM&apikey=demo

Earnings history

Besides financial statements, Alpha Vantage also has an earnings history dataset under function=EARNINGS (again with symbol and apikey as other required parameters). The URL is:

https://www.alphavantage.co/query?function=EARNINGS&symbol=IBM&apikey=demo

This dataset includes annual and quarterly earnings per share (EPS) history for given stock. The quarterly earnings also come with analyst estimates and surprise amount and percentage (how much actual reported earnings differed from analyst estimates each quarter).

Output format

Most Alpha Vantage API functions return output in JSON format, with a few exceptions which return a CSV file. The financial statement datasets are all in JSON.

To download and process the JSON format in Python, you can use the requests module with json() on the output:

import requests

SYMBOL = 'AAPL'
DATASET = 'INCOME_STATEMENT'

AV_API_KEY = ...  # Your Alpha Vantage API key
URL = 'https://www.alphavantage.co/query?function={}&symbol={}&apikey={}'

r = requests.get(URL.format(DATASET, SYMBOL, AV_API_KEY))
data = r.json()

The financial statement datasets (income statement, balance sheet, cash flow) all follow the same structure.

Each has three parts: symbol, annualReports, and quarterlyReports.

The report parts have multiple items each, one for each reported period, ordered from the latest to oldest. Each period includes the key fiscalDateEnding - the period end date as yyyy-mm-dd.

Here is an example JSON output for IBM income statement:

{
    "symbol": "IBM",
        "annualReports": [
            {
                "fiscalDateEnding": "2021-12-31",
                "reportedCurrency": "USD",
                "grossProfit": "31486000000",
                "totalRevenue": "57350000000",
                "costOfRevenue": "25865000000",
                ...
            },
            {
                "fiscalDateEnding": "2020-12-31",
                "reportedCurrency": "USD",
                "grossProfit": "30865000000",
                ...
            }
            ...
        ],
        "quarterlyReports": [
            {
                "fiscalDateEnding": "2022-09-30",
                "reportedCurrency": "USD",
                "grossProfit": "7430000000",
                ...

Earnings calendar

For future earnings release dates you can use function=EARNINGS_CALENDAR, either for a single stock or (when you omit the symbol parameter) for all available symbols.

The earnings calendar dataset has an additional parameter horizon, which is either 3month (default), 6month, or 12month, and specifies how far ahead to look for earnings dates.

Here is an example URL:

https://www.alphavantage.co/query?function=EARNINGS_CALENDAR&horizon=3month&apikey=demo

Unlike the financial statements and earnings history datasets, the earnings calendar output is a CSV instead of JSON.

Company overview

For a quick summary of a stock and its most important fundamental figures, such as EPS, P/E ratio, dividend yield, profit margin, or market cap, you can use the company overview dataset under function=OVERVIEW.

You can find an example with URL, Python code, and detailed explanation of its individual fields on another page.