Search (by line items)

​

👋 Overview

This Line Items Search API lets you pull specific line items for a list of tickers by specifying a set of line_items in your request.

Line items are financial data points that are found in the income statement, balance sheet, and cash flow statement.

Examples of line items are revenue, net income, total debt, free cash flow, and so on.

The purpose of this API is to let you easily get specific data points for a list of tickers in a single API request.

You can also specify a start_date and end_date to filter the line items by a specific date range.

Finally, you can specify a period, which must be one of "ttm", "annual", or "quarterly".

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.

​

🚀 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("---")