Use case · Research
Researchers and quants working with long financial histories
Key points
- check_circlekey-metrics separates PER and PBR as of each period end from trailing twelve-month (TTM) metrics.
- check_circlefinancial-facts returns XBRL elements from annual reports by tag name.
- check_circleResearch by you or within your company is Basic Use. Before publishing results, check Article 8 of the Terms.
Before, and with ZENITH Code
Before
- removeParsing annual report XBRL yourself to assemble financial history.
- removeHandling stock split adjustments and amended filings on your own.
- removeMixing period-end and current values until you could not tell which date a metric referred to.
With ZENITH Code
- check_circlePeriod-end PER and PBR and the latest values based on today's price come from different endpoints, so they never mix.
- check_circleSplit-adjusted EPS and BPS are included in key-metrics.
- check_circleXBRL elements come with Japanese and English labels and dimension members.
Endpoints to use
A set for building time-series panel data.
- GET
/stable/key-metricsKey financial metrics (per period)Period-end PER and PBR, TTM metrics, split-adjusted EPS1 tokens per call - GET
/stable/income-statementIncome statementIncome time series with sources1 tokens per call - GET
/stable/financial-factsAnnual report XBRL factsXBRL elements from annual reports10 tokens per call - GET
/stable/financial-statement-fullFull financial statement (hierarchical)Every filed line item with its hierarchy10 tokens per call - GET
/stable/valuation-historyValuation history (PER, PBR, dividend yield)PER, PBR and dividend yield history (uses prices, so shown only when signed in)10 tokens per call - GET
/stable/industry-benchmarksIndustry benchmarks by sectorSector medians and quartiles as a reference10 tokens per call
Plan fit and what you may show
Research for yourself, or within your company, is Basic Use and Pro is often enough. Sharing among several researchers requires Business.
| Plan | Monthly | Monthly tokens | Showing to third parties (excluding exchange data) |
|---|---|---|---|
| Free | $0 | 5,000 | Not allowed (your own research and analysis, or internal use for a company) |
| ProFits this use | $89 | 100,000 | Not allowed (your own research and analysis, or internal use for a company) |
| BusinessFits this use | $499 | 1,000,000 | Allowed (display in your service, providing processed results, sharing within your organization) |
| Enterprise | Custom | Custom | Allowed (display in your service, providing processed results, sharing within your organization) |
If you publish aggregates or charts from the data in a paper or report, check Article 8 of the Terms and contact us beforehand if needed. Exchange data such as stock prices may not be published.
The Terms are the authoritative source on what you may show or provide. If your use is unclear, contact us before you start. Terms, Article 8 · Pricing
Code example
Line up the ROE of three companies by fiscal year (Python and pandas).
curl -sG "https://api.zenithcode.net/stable/key-metrics" \ --data-urlencode "symbol=7203" \ --data-urlencode "period=annual" \ --data-urlencode "limit=10" \ -H "x-api-key: YOUR_API_KEY"
Things to note
- errorPER and PBR in key-metrics are as of each period end. Values based on today's price are in /stable/key-metrics-latest.
- errorQuarterly income figures are cumulative from the start of the fiscal year. Subtract the previous quarter's cumulative figure to get a single quarter.
- errorvaluation-history responses include the closing price (close). That is exchange data and may not be published.
FAQ for investors and developers
How many years of data are there?expand_more
It depends on the company. For example, annual income statements for Toyota Motor (7203) start from the fiscal year ended March 2014. Check each company's response for the exact range.
Can I download in bulk as CSV?expand_more
Endpoints that return lists (arrays) support ?format=csv. Responses with nested fields are easier to handle as JSON.
Can several people in a lab use it?expand_more
Sharing the data among several people in an organization is licensed on Business or higher.
FAQ for AI builders and researchers
Can I reproduce point-in-time values?expand_more
Income statements and similar responses carry the source and publication time (provenance). Check when each figure was published before relying on it.
How should null values be handled?expand_more
null means "not disclosed" or "cannot be computed", not zero. Treat it as missing.
What units are used?expand_more
Ratios are 0–1 decimals (0.1 = 10%), amounts are in yen and multiples are plain numbers (x).
Disclaimer
This page explains how to use a Japanese equity data API and how its data is defined. It is not a solicitation to invest or a recommendation to buy or sell any security. The content reflects information at the time of writing and is not guaranteed to be accurate or complete. Investment decisions are your own responsibility.
What you may show or provide to third parties depends on your plan and Article 8 of the Terms. Exchange data such as stock prices may not be shown to third parties on any plan. Terms, Article 8 · Data sources and terms of use