DEV Community

Ikkun
Ikkun

Posted on Originally published at agentjournal.dev

TDnet disclosures as an API: what the documents do not keep

The short answer

TDnet is where Japanese listed companies publish timely disclosures: earnings revisions, dividend changes, M&A, officer changes, buybacks. It works, it is free to read, and it is the canonical source for this material. What it is not is an API: the public face is a browser view of PDFs, so anyone who wants the data in a pipeline ingests the feed themselves or buys a distribution product.

Two properties of that data decided my architecture, and neither is obvious from the outside:

  1. Almost none of the disclosures carry XBRL. In my store, 6 of 7,154 rows have an XBRL URL.
  2. The PDF link stops working after about five weeks. I probed it: documents 35 days old returned 200, documents 45 days old returned 404.

Both are reasonable choices for a disclosure system. Both change what you build on top of it.

What I measured

My ingest has been pulling the disclosure feed since March 2025. Current state of the table:

Quantity Value
Disclosures stored 7,154
Distinct security codes 2,887
Window 2025-03-05 to 2026-11-05
Rows carrying an XBRL URL 6
Rows added in the last 30 days 3,307

Three thousand disclosures a month across roughly 2,900 companies. That shape matters: this is a stream you keep up with, not a table you query later. Designing for "fetch on demand" and discovering the volume is a common way to spend a weekend.

The XBRL number surprised me more. Six out of seven thousand. XBRL in Japan means EDINET, which covers securities reports and quarterly filings with element level tagging. TDnet sits above that as the announcement layer, and announcements are PDFs because a PDF is what a company submits and what a person reads. If an agent needs structured numbers, the structured document is usually a separate filing that lands in EDINET. That is not a gap in TDnet, it is a division of labour between two systems that were designed for different readers.

The retention probe

I took disclosures from buckets at 31, 35, 45, 50 and 55 days of age and requested the stored document URL, with a browser user agent, four URLs per bucket:

31 days  ->  200 200 200 200
35 days  ->  200 200 200 200
45 days  ->  404
50 days  ->  404 404 404 404
55 days  ->  404 404 404 404
Enter fullscreen mode Exit fullscreen mode

The bucket at 40 days came back empty because no disclosures were published that day, a market holiday, which is its own small lesson about sampling by date.

So the document lifetime sits somewhere between five and six weeks. The metadata I keep is permanent and the document behind it is not. I learned this the boring way: a citation from my own output stopped resolving, and nothing in my pipeline had failed, because nothing in my pipeline was watching the link.

What that changes

Capture at ingest, not at query. When the disclosure appears, take the title, the company name, the code, the timestamp, the document type, and either the text or a copy of the PDF. Late fetches fail quietly, because the metadata still looks perfectly fine.

Separate the pointer from the content. My table stores document_url and it resolves for a while. An agent that cites it a month later is citing something that has already expired upstream. If you need citations that survive, the content has to be mirrored, and mirroring documents raises licensing questions that metadata does not.

Do not promise full text search you cannot serve. I do not mirror PDF text, so I can filter by company, code and date, and I cannot answer "find every disclosure that mentions a specific customer". Pretending otherwise produces a feature that works in a demo and fails under load.

Treat XBRL as a separate route. The six XBRL carrying disclosures are the exception. Structured numbers come from EDINET, which means a second ingest with its own vocabulary problem, covered in the EDINET API v2 notes.

Where a paid route fits

JPX sells disclosures as an addon to J-Quants, described on their product page as timely delivery of listed company disclosure documents during the day. If your requirement is intraday latency and a contract to point at, that is the right answer, and it is priced like a data product rather than a side project. If your requirement is "an agent should know what was announced about this company this month", ingesting the feed and keeping the metadata is enough, and it costs nothing.

The split is the familiar one in this data: the exchange sells freshness and accountability, and everyone else builds the joins.

What this route does not do

It is metadata only. No document text, no OCR of scanned PDFs, no full text search, and no promise that a document URL in a response still resolves. Coverage starts when the ingest started, so older disclosures are absent rather than sparse. The five week life of the upstream PDF means any feature that assumes permanence needs redesigning, and my own answers say so rather than pretending otherwise.

Where this landed

The disclosure table sits behind the same free key as the rest: an MCP tool called disclosures_get that takes a code and returns date, title and document URL, plus REST for the same data. The product page is at discli. The identifier problem underneath is in Japanese company data: three identifiers, and the neighbouring route is in J-Quants for agents.

If you have built a disclosure pipeline, did you mirror the documents or accept that citations expire?


Originally published at agentjournal.dev.

Top comments (0)