Choosing a financial data API: key items, statement hierarchy and XBRL facts

This page explains the differences between three entry points and what to check in one example request. Even with structured data, you still need to check the period, scope and missing values.

Rather than fetching everything available and deciding later, write the one row you want to display first. That makes it easier to choose the right API.

Figure: this is not a ranking of capabilities. It is a guide to choosing by the result you need.

To compare revenue, operating income and similar items by year, start with the income statement API. Use key items such as revenue and operatingIncome.

Fetch annual data first and check fiscalPeriod, period and accountingStandard in the response. Do not assume the first element of the array is the year you intended; sort the rows explicitly in the order you display them.

Items lined up under the same name do not mean the company and year conditions are the same. Using standardized items and judging whether a comparison is valid are separate.

To display table headings and line-item breakdowns, see the full financial statements API. Fields such as depth, parent_key and sort let you handle hierarchy and order.

For example, to show “Current assets” under “Assets”, and individual items under that, an array of amounts alone does not tell you the parent–child relations. Keep the parent and the order first, then decide on indentation and other display details.

The presentation hierarchy is not necessarily an addition formula. If you compare a parent's number with the sum of its children, also check signs, aggregation scope, heading rows and so on.

In this API, the parameter for the full year is quarter=FY. Do not copy period=annual from the income statement as is. Even for similar uses, check the parameter names and formats for each endpoint.

The XBRL facts API for annual securities reports is the entry point for values per element and context. You can filter with category for the classification and tag for a partial match on the element name.

Here, a fact means one reported value. The same element with a different period or scope is a different candidate. Do not adopt a returned row unconditionally as the company's current figure.

Keep your first request small

The example below requests up to 20 rows from the balance sheet classification for Toyota Motor (7203) for the fiscal year ended March 2026. It does not mean that 20 rows cover every item.

Real requests need an account and an API key. Replace YOUR_API_KEY below with your own key. Do not paste your key into articles or public repositories. Requests count against your quota, so check your current plan and usage in the docs and the dashboard.

curl --fail-with-body --get \
  'https://api.zenithcode.net/stable/financial-facts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'symbol=7203' \
  --data-urlencode 'fiscalPeriod=2026-03' \
  --data-urlencode 'category=Balance_Sheet' \
  --data-urlencode 'limit=20'

Python can make the request with the standard library alone. This example prints only the document information and the number of rows returned. The code itself does not interpret each row's conditions to pick the right number.

import json
from urllib.parse import urlencode
from urllib.request import Request, urlopen

query = urlencode({
    "symbol": "7203", "fiscalPeriod": "2026-03",
    "category": "Balance_Sheet", "limit": "20",
})
request = Request(
    "https://api.zenithcode.net/stable/financial-facts?" + query,
    headers={"x-api-key": "YOUR_API_KEY"},
)
with urlopen(request, timeout=30) as response:
    reports = json.load(response)
for report in reports:
    print(report["symbol"], report["fiscalPeriod"], report["docId"])
    print("rows returned:", len(report["facts"]))
    print("cut off by limit:", report["truncated"])

The JavaScript example runs on Node.js with fetch available. Do not embed a secret API key in code for a public browser page.

const query = new URLSearchParams({
  symbol: '7203', fiscalPeriod: '2026-03',
  category: 'Balance_Sheet', limit: '20',
});
const response = await fetch(
  `https://api.zenithcode.net/stable/financial-facts?${query}`,
  { headers: { 'x-api-key': 'YOUR_API_KEY' } },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const reports = await response.json();
for (const report of reports) {
  console.log(report.symbol, report.fiscalPeriod, report.docId);
  console.log('rows returned:', report.facts.length);
  console.log('cut off by limit:', report.truncated);
}

Check truncated before deciding you have everything

truncated=true means the results were cut off at the row limit. Do not conclude that a line item does not exist just because it is not among the 20 rows you received.

Narrow the classification or tag condition, or adjust the limit within what the specification allows. tag is a partial match on the element name, so even after narrowing, check the tags and contexts returned. The same row can appear in more than one request, so do not simply add up results and treat them as complete.

truncated=false does not mean you have every piece of information in the original report. It tells you that, within your conditions and the API's coverage, nothing was cut off by the limit.

Storing values alone makes it hard to check comparison conditions later. At minimum, keep the company, document, item, period, scope, unit and retrieval time.

For a chart, decide the fiscal year on the x-axis, the unit on the y-axis, how actuals and forecasts are distinguished, and how missing values are shown. If you drop the original period and keep only a year label, you may mix a full year and a six-month cumulative figure under the same label.

If you want to choose conditions yourself and build tables or charts, ZENITH Code is the place to start. If you want a ready-made company analysis screen, StockClub, also run by Crabgrass, is another option. ZENITH Code also provides organized data, so the difference is not “raw data vs processed data”.

• TDnet XBRL guide
• EDINET XBRL guide

• Income statement API
• Full financial statements API
• XBRL facts API
• Cumulative vs single quarters
• Working with point-in-time data

We at Crabgrass, Inc. build and operate the financial data API ZENITH Code. This is a technical article; it does not recommend buying or selling any financial product.