Search (by line items)

​

👋 Overview

This endpoint lets you search for specific financial metrics by specifying a set of line_items in your request.

You can search by any line item that is listed below in the Line Items section.

For example, you can search for net_income and total_debt for NVDA and AAPL and receive the following response:

{
  "search_results": [
    {
      "ticker": "NVDA",
      "report_period": "2024-07-28",
      "period": "ttm",
      "net_income": 53008000000,
      "total_debt": 9765000000
    },
    {
      "ticker": "AAPL",
      "report_period": "2024-06-29",
      "period": "ttm",
      "net_income": 101956000000,
      "total_debt": 101304000000
    }
  ]
}

To get started, please create an account and grab your API key at financialdatasets.ai.

You will use the API key to authenticate your API requests.

The Financials Search API lets you search for financial data across income statements, balance sheets, and cash flow statements for 16,000+ public companies, going back 30+ years.

​

🚀 Getting Started

There are 3 steps for making a successful API call:

1. Add your API key to the header of the request as X-API-KEY.
2. Prepare a JSON body with your search criteria, including tickers, line_items, period, and limit.
3. Execute the API request to the /financials/search endpoint using a POST method.

The period can be one of "ttm" (trailing twelve months), "annual", or "quarterly".

The limit is the maximum number of data points to return per ticker. For example, if you have 2 tickers and set the limit to 3, you will get 6 data points in total, 3 per ticker.

Note: tickers and line_items are required. By default, period is "ttm" and limit is 1.

​

🔎 Line Items

This endpoint lets you request data for specific line_items for a list of tickers.

You may specify multiple line_items to narrow down the search results.

You can also mix-and-match line_items from different financial statements. For example, you can search for net_income from the income statement and total_debt from the balance sheet.

Each line item consists of a key. The key is the name of the financial metric that you want to search for.

We charge $0.01 per 10 line items per search. For example, 5 line items costs $0.01, 15 line items costs $0.02, and so on.

​

💻 Example

import requests
import json

# Add your API key to the headers
headers = {
    "X-API-KEY": "your_api_key_here",
    "Content-Type": "application/json"
}

# Prepare the request body
body = {
  "period": "ttm",
  "tickers": ["NVDA", "AAPL"],
  "limit": 1,
  "line_items": [
    "net_income",
    "total_debt"
  ]
}

# Create the URL
url = 'https://api.financialdatasets.ai/financials/search/line-items'

# Make API request
response = requests.post(url, headers=headers, data=json.dumps(body))

# Parse search results, which are ordered by report period, newest to oldest
search_results = response.json().get('search_results')

# Print the results
for result in search_results:
    print(f"Ticker: {result['ticker']}")
    print(f"Report Period: {result['report_period']}")
    print(f"Revenue: ${result['net_income']:,.0f}")
    print(f"Total Debt: ${result['total_debt']:,.0f}")
    print("---")