edinet-tools

Read Japan's EDINET regulatory filings as typed Python objects: financial reports, 5% shareholding disclosures, tender offers and more. Each filing can be read from EDINET's CSV conversion, from the filing's own inline XBRL, or from its XBRL instance.

Python 3.10+. No runtime dependencies. Company lookup works offline; fetching filings requires a free EDINET API key.

Install and configure

pip install edinet-tools
export EDINET_API_KEY=your_key_here

Get your key from EDINET API registration (video walkthrough). You can also set it in Python with edinet_tools.configure(api_key="...").

Upgrading to 0.9.0: financial values, currency selection and per-holder share totals change even on the default CSV path. Read MIGRATING.md before re-parsing stored reports.

Parse an annual report

This example reads Toyota's annual report filed June 10, 2026. The document ID identifies a specific filing; it is not a request for the latest report.

import edinet_tools

report = edinet_tools.fetch_and_parse("S100Y8NY", "120")
print(report.net_sales)
print(report.net_income_owners)
print(report.accounting_standard)
print(report.source_elements.get("net_sales"))
print(report.units.get("net_sales"))

Financial parsers read the filing's declared accounting standard first: J-GAAP, IFRS or US GAAP. Listed fallbacks remain where no eligible fact is found on that standard. source_elements, source_contexts and units identify the selected source on annual, quarterly and semi-annual reports. Other report types expose those maps but leave them empty.

An absent field or provenance entry is not a zero. A typed value can be None when no eligible fact is found or an extraction check withholds it; extraction_flags records the checks that produced flags. An empty flags list does not establish completeness or correctness.

Find companies and filings

Company lookup uses bundled FSA registry snapshots and needs no API key.

import edinet_tools

toyota = edinet_tools.entity("7203")
print(toyota.name, toyota.edinet_code)

edinet_tools.entity("Toyota")
edinet_tools.entity("E02144")
edinet_tools.entity_by_corporate_number("1180301018771")
edinet_tools.search("bank", limit=5)

Lookup accepts digit or alphanumeric tickers and handles width, gaiji and middle-dot variants in names. The bundled snapshots are dated October 5, 2026. Loading data older than a year emits StaleDataWarning.

List a day's annual filings, then select by the filer's EDINET code:

import edinet_tools

docs = edinet_tools.documents("2026-06-10", doc_type="120")
for doc in docs:
    if doc.filer_edinet_code == "E02144":
        print(doc.doc_id, doc.doc_description, doc.filing_datetime)

A quiet day returns an empty list. toyota.documents(doc_type="120", days=365) scans a year, making a document-list request for each day. For chronology, use the document-list submission metadata. Some report types' tagged filing_date can retain the original date after an amendment.

Choose a source

"ixbrl" is an alias for "xbrl". The CSV source downloads type 5; the two native sources download type 1. The inline reader raises UnsupportedInlineXBRL for unsupported constructs instead of guessing. Catch native-reader errors through edinet_tools.exceptions.EdinetError; UnsupportedInlineXBRL is not exported from the top-level package. Choosing the instance reader is explicit; there is no automatic fallback.

To parse a saved type-1 package without an API key:

from pathlib import Path
from edinet_tools import parse_xbrl
from edinet_tools.parsers.xbrl_rows import extract_rows_from_package

zip_bytes = Path("S100Y4NW_type1.zip").read_bytes()
report = parse_xbrl(zip_bytes, "240", source="xbrl", doc_id="S100Y4NW")

files = extract_rows_from_package(zip_bytes, source="xbrl")
for file in files:
    for row in file["data"]:
        print(row["要素ID"], row["値"], row["コンテキストID"])

Download a package with doc.fetch(type=1) or edinet_tools.api.fetch_document(doc_id, type=1). Type 2 returns PDF; type 5 returns CSV. Source rows also retain HTML, decimals, scale, sign, nil status and period dates.

The native path preserves text beyond the CSV's 30,000-character cut. For example, S100Y4NW's tender-offer purpose section has 75,894 characters. Text tables retain tabs between cells and newlines between rows. Source choice can also affect typed values in multi-series fund packages; inspect their field identities before combining figures.

Other report types

Parse a joint 5% shareholding filing:

import edinet_tools

report = edinet_tools.fetch_and_parse("S100YRDM", "350")
print(report.filer_name, report.target_company)
print(report.ownership_pct, report.is_joint_filing)
for holder in report.joint_holders:
    print(holder.name_jp, holder.shares_held, holder.stock_lines_held)

On a joint filing, ownership_pct is the co-filers' group total. Each holder's shares_held is the filed total after deductions and can be zero or negative. stock_lines_held counts stock lines before deductions; it excludes depositary receipts, trust certificates, warrants and convertibles. The member totals need not sum to the group total.

Parse a tender-offer registration:

import edinet_tools

report = edinet_tools.fetch_and_parse("S100Y4NW", "240")
print(report.acquirer_name, report.target_name)
print(report.holding_ratio_after)

Every report supports fields() and to_dict(). Unmapped elements and narrative sections remain available through raw_fields, unmapped_fields, text_blocks and raw_facts.

Coverage and limits

All 42 EDINET document codes route to typed parsers. This does not imply complete field extraction for every legal form. Amendments share their base parser; amendment attributes vary between report types.

For financial reports, keep owners-of-parent and whole-group figures separate: net_income_owners versus net_income_total, and net_assets_owners versus net_assets_total. J-GAAP filers do not file a single owners-only net-assets element. Unit provenance matters when storing monetary figures, and segment rows require a checked denominator and scope before summing.

See the CHANGELOG for the full known limits and MIGRATING.md for changes to stored-data semantics.

Development

git clone https://github.com/matthelmer/edinet-tools.git
cd edinet-tools
python -m pip install -e ".[dev]"
python -m pytest tests/ -q

Tests cover real filings, accounting standards, context and currency selection, numeric precision, API errors and native-reader refusals.

License

MIT. Independent project, not affiliated with Japan's Financial Services Agency. Verify data independently before making financial decisions.