Audit 35 — Japan deep research: EDINET v2 ingestion (GO)

Status: GO — EDINET v2 API confirmed as canonical, machine-readable source for directors' / large-shareholder filings in Japan.

Source

• Regulator: Financial Services Agency (FSA), Kanto Local Finance Bureau (Kinshō)
• Legal basis: Financial Instruments and Exchange Act (FIEA, 金融商品取引法)
• Endpoint base: https://api.edinet-fsa.go.jp/api/v2
• Auth: API key registration (free, no rate-limit fee tier)
• Public docs: https://disclosure2.edinet-fsa.go.jp/

Endpoints used

• List by date: GET /api/v2/documents.json?date=YYYY-MM-DD&type=2&Subscription-Key=<KEY>
• Detail CSV: GET /api/v2/documents/{docID}?type=5&Subscription-Key=<KEY> (CSV ZIP)
• Detail XBRL: GET /api/v2/documents/{docID}?type=1&Subscription-Key=<KEY> (XBRL ZIP, fallback)

Filter

Keep docTypeCode ∈ {350, 360, 361}:

Code	Form	Japanese name
350	Large shareholding report	大量保有報告書
360	Officer's share-holding report	役員株式保有報告書
361	Officer's share-holding change report	役員株式保有変動報告書

Volume expectation

• ~5–30 filings/day across the three forms (off-season) up to ~80/day around quarterly reporting peaks.
• Annual: ~5,000–10,000 filings/year combined.
• Throughput: comfortably ≤ 60s daily cron with 1 req/s pacing.

Currency

JPY → EUR at merge time via FxHistory pair JPYEUR (Yahoo JPYEUR=X, convention 1 JPY = X EUR, ≈ 0.00585 on 2026-05). Helper: ensureJpyEurCoverage(fromDate, toDate, dryRun) in src/lib/ingest/merge-staging.ts.

Anticipated top issuers (sanity check)

Toyota (7203), Sony (6758), SoftBank Group (9984), Nintendo (7974), Mitsubishi UFJ (8306), Keyence (6861), Recruit (6098), Tokyo Electron (8035).

Files shipped (this round)

• prisma/schema.prisma — JpFiling model
• prisma/migrations/20260517300000_jp_filings/migration.sql
• src/lib/ingest/jp-edinet.ts — list + detail + CSV parse + upsert + runIngestion
• scripts/ingest-jp-edinet.ts — CLI runner
• src/app/api/cron/jp-edinet/route.ts — Bearer-gated daily cron (60s)
• .github/workflows/ingest-jp-edinet.yml — daily 10:00 UTC
• vercel.json — function entry + cron schedule
• src/lib/ingest/merge-staging.ts — mergeJpFiling handler, ensureJpyEurCoverage helper, JP: namespace
• src/lib/market.ts — jp market mapping + JP: prefix
• src/components/landing/LandingMarkets.tsx — Japan tile
• src/lib/sources-registry.ts — JP source registry

Idempotency

Upsert keyed on edinetDocId (EDINET docID, globally unique, immutable). Re-running the same ?date= inserts 0 new rows for unchanged data.

Next action — required to activate

EDINET_API_KEY is NOT YET CONFIGURED.

1. Register at: https://api.edinet-fsa.go.jp/api/v2/auth/
2. Add to .env.local:

   EDINET_API_KEY="<key from FSA>"
   

3. Add EDINET_API_KEY as a GitHub Actions secret on the repo (same value).
4. Add EDINET_API_KEY to Vercel project env (Production + Preview).
5. Verify locally: npm run ingest:jp-edinet 2026-05-15
6. Merge into Declaration: npm run merge:staging

Until the key is configured, the ingest module returns { status: "skipped", reason: "EDINET_API_KEY env not set; register at https://api.edinet-fsa.go.jp/api/v2/auth/" }. The cron route, CLI and GH workflow all exit cleanly without erroring.