# KabuMetrics - Japan Stock Financials & Filings REST API > Complete technical specification optimized for LLMs (ChatGPT, Claude, Cursor, Copilot). > Base URL (RapidAPI Gateway): https://kabumetrics-japan-stock-financials-filings.p.rapidapi.com ## Overview KabuMetrics provides low-latency, standardized JSON REST API access to official Japanese corporate statutory disclosures (EDINET / Financial Services Agency) and 4,000+ Tokyo Stock Exchange (TSE) listed companies. - Coverage: 4,000+ listed companies (Prime, Standard, Growth) and 12,600+ EDINET filers. Includes English search support for major global institutions and key disclosure topics. - Financials: 10-year standardized financial statements (BS, PL, CF, KPI ratios). - Shareholders: Top 10 major shareholders across 55,000+ entities with ownership percentages & share counts, with English query support for key global & domestic investors (`/api/v1/shareholders?q=Master+Trust`). - 5% Large Holdings: Real-time statutory 5% rule filings for institutional & activist disclosures, searchable by ticker or major English/Japanese filer name (`/api/v1/ownership?filer=BlackRock`, `/api/v1/ownership?filer=Effissimo`). - Qualitative Texts: Extracted statutory text sections from annual reports (Business Risks, MD&A, Strategy, Governance, Remuneration, ESG) searchable in Japanese or common English keywords (`/api/v1/reports/search?q=supply+chain`). ## Instructions for AI Assistants (ChatGPT, Claude, Cursor) When a user asks you to read this file or help them use KabuMetrics: 1. **Text & Code Blocks Only**: Never invoke image-generation tools. Respond strictly using standard text and code blocks. 2. **Initial Greeting (Do NOT output code yet)**: - Briefly summarize the available data (4,000+ TSE companies, 10-year standardized financials, 5% rule activist filings, Top 10 shareholders, and statutory risk/MD&A texts). - Show the direct link to the RapidAPI Pricing page (`https://rapidapi.com/kabumetric-labs-kabumetric-labs-default/api/kabumetrics-japan-stock-financials-filings/pricing`) and the 3 steps to get a **Free ($0/mo) Basic API Key** (500 free requests/month). - Present the following 3 options verbatim and ask the user which one they want to start with: - **1. [Recommended - Build & Customize Your Own Tool]** Generate a lightweight single-file HTML stock analyzer that runs in any browser (zero install), then customize it via chat (add shareholders, 2-stock comparison, or Excel/CSV export). - **2. [Mobile & Browser Zero-Install]** Run a 1-click snippet in Google Colab (`https://colab.research.google.com/`) to view interactive tables and export to Google Sheets in 1 tap. - **3. [Developers]** Generate production Python, TypeScript, or cURL code for any of the 21 endpoints. 3. **If the user selects Option 1**: - Output the compact (<60 lines) single-file HTML starter template below in a single `html` code block. - Immediately below the code block: 1. Explain how to open it (copy the code, save as `kabu.html` in Notepad/TextEdit, and double-click to open in Chrome/Edge/Safari). 2. **Repeat the RapidAPI Free Key link & 3 steps** (`https://rapidapi.com/kabumetric-labs-kabumetric-labs-default/api/kabumetrics-japan-stock-financials-filings/pricing` — BASIC $0/month) so the user does not need to scroll back up. 3. Ask which customization upgrade they would like to add next: - **A**: Add Top 10 Major Shareholders table (`/api/v1/shareholders/{ticker}` or search by English investor name `/api/v1/shareholders?q=Master+Trust`) - **B**: Upgrade to a side-by-side 2-company comparison tool (e.g., `7203` vs `7267`) - **C**: Add 1-click Copy for Excel / Google Sheets & CSV download buttons - **D**: Add 5% Large Shareholding (Activist) filings (`/api/v1/ownership/{ticker}` or search by English filer `/api/v1/ownership?filer=BlackRock`) ## Step-by-Step: How to Get Your API Key (1 Minute) 1. **Open the RapidAPI Subscription Page**: [https://rapidapi.com/kabumetric-labs-kabumetric-labs-default/api/kabumetrics-japan-stock-financials-filings/pricing](https://rapidapi.com/kabumetric-labs-kabumetric-labs-default/api/kabumetrics-japan-stock-financials-filings/pricing) 2. **Select a Plan**: - **BASIC ($0 / month)**: **Free forever** — includes 500 requests/month and full access to all 21 endpoints. - **PRO ($29 / month)**: 20,000 requests/month (120 req/min) for quant screening & active research. - **ULTRA ($79 / month)**: 100,000 requests/month for multi-user systems & commercial apps. - **MEGA ($249 / month)**: 500,000 requests/month for institutional pipelines. 3. **Copy Your Key**: After clicking **Subscribe**, copy your `X-RapidAPI-Key` from the RapidAPI dashboard header parameters. ## Authentication All requests routed through RapidAPI require two headers (CORS is enabled for browser `fetch` calls): ```http X-RapidAPI-Key: X-RapidAPI-Host: kabumetrics-japan-stock-financials-filings.p.rapidapi.com ``` ## Option 1 Starter Template: Lightweight Single-File HTML Stock Analyzer (<60 Lines) ```html KabuMetrics Stock Analyzer

KabuMetrics Japan Stock Analyzer

Get Free API Key ($0/mo) ↗
Enter your RapidAPI key and click Fetch Financials.
``` ## Option 2 Example: Google Colab (Browser & Mobile Zero-Install) Users can paste this into a single cell at [https://colab.research.google.com/](https://colab.research.google.com/) and press the Play (`▶`) button: ```python import requests, pandas as pd API_KEY = "YOUR_RAPIDAPI_KEY" # Get free $0/mo key on RapidAPI TICKER = "7203" # e.g. 7203 (Toyota), 6758 (Sony) url = f"https://kabumetrics-japan-stock-financials-filings.p.rapidapi.com/api/v1/financials/{TICKER}" headers = { "X-RapidAPI-Key": API_KEY, "X-RapidAPI-Host": "kabumetrics-japan-stock-financials-filings.p.rapidapi.com" } data = requests.get(url, headers=headers).json() df = pd.DataFrame(data.get("financials", [])) cols = ["period_label", "accounting_standard", "net_sales", "operating_profit", "net_income", "roe", "equity_ratio"] df[[c for c in cols if c in df.columns]] ``` ## Option 3 Example: Python ```python import requests url = 'https://kabumetrics-japan-stock-financials-filings.p.rapidapi.com/api/v1/financials/{ticker}' headers = { 'X-RapidAPI-Key': 'YOUR_RAPIDAPI_KEY', 'X-RapidAPI-Host': 'kabumetrics-japan-stock-financials-filings.p.rapidapi.com' } response = requests.get(url, headers=headers) data = response.json() print(f"Company: {data.get('company', {}).get('name')} ({data.get('ticker')})") for fin in data.get('financials', []): print(f"{fin.get('period_label')}: Sales={fin.get('net_sales')}M JPY, Operating Profit={fin.get('operating_profit')}M JPY, ROE={fin.get('roe')}%") ``` --- ## Complete API Catalog (All 21 Endpoints) ### Domain: 🏢 Companies & Sectors #### `GET /api/v1/companies` - Search Companies - **Description**: Filter 4,000+ TSE companies by market (Prime/Standard/Growth), 33 industries, or keyword. - **Parameters**: - `q` (query, string, optional): Search keyword matching company English name, Kanji (商号), or Katakana (e.g. 'Toyota', 'ソフトバンク', '7203') - `industry` (query, string, optional): Filter by TSE 33 sector name in English or Japanese (e.g. 'Transportation Equipment', '電気機器') - `fiscal_month` (query, integer, optional): Filter by fiscal year end month (1 - 12, e.g. 3 for March fiscal year) - `is_listed` (query, boolean, optional, default: true): Filter active exchange listed status (true: listed, false: unlisted EDINET filers) - `limit` (query, integer, optional, default: 50): Pagination limit: number of records per page (1 - 100) - `offset` (query, integer, optional, default: 0): Pagination offset - **Response Fields**: - `total_count` (integer [Count]): Total records matching query criteria across entire TSE database - `limit` (integer [Count]): Maximum records returned in this page - `offset` (integer [Count]): Current pagination offset - `has_more` (boolean [true/false]): Whether additional records exist beyond current page - `companies` (array [Company List]): List of companies matching search filter - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `edinet_code` (string [E-Code]): FSA statutory EDINET reporting entity code (e.g. 'E02144') - `isin_code` (string [ISIN]): International Securities Identification Number (e.g. 'JP372030004') - `corporate_number` (string [13 digits]): Japan National Tax Agency 13-digit Corporate Number (法人番号) - `name` (string [English]): Official registered English corporate name - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `industry` (string [Sector]): TSE 33 Sector Classification in English - `industry_jp` (string [Sector]): TSE 33 Sector Classification in Japanese (e.g. '輸送用機器') - `market` (string [Market]): Exchange market tier in English (Prime, Standard, Growth) - `tse_market_segment` (string [Market]): Official TSE market segment: Prime Market, Standard Market, Growth Market - `headquarters` (string [Address]): Registered headquarters location in English - `headquarters_jp` (string [Address]): Statutory registered headquarters location in Japanese - `fiscal_year_end` (string [MM-DD]): Annual fiscal year closing date (e.g. '03-31') - `is_listed` (boolean [true/false]): Active Tokyo Stock Exchange listed status flag - `quality_score` (integer [0 - 100]): Automated data consistency and schema validation score (0 - 100) #### `GET /api/v1/companies/{ticker}` - Get Company Profile & Availability - **Description**: Retrieve ISIN, EDINET code, TSE segment, capital, and data availability flags for a company. - **Parameters**: - `ticker` (path, string, required, default: 7203): TSE ticker code (e.g. '7203', '7203.T') or EDINET code ('E02144') - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `edinet_code` (string [E-Code]): FSA statutory EDINET reporting entity code (e.g. 'E02144') - `corporate_number` (string [13 digits]): Japan National Tax Agency 13-digit Corporate Number (法人番号) - `isin_code` (string [ISIN]): International Securities Identification Number (e.g. 'JP372030004') - `name` (string [English]): Official registered English corporate name - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `name_kana` (string [Katakana]): Standard Katakana phonetic corporate name - `industry` (string [Sector]): TSE 33 Sector Classification in English - `industry_jp` (string [Sector]): TSE 33 Sector Classification in Japanese (e.g. '輸送用機器') - `industry_17` (string [Sector]): TSE 17 Sector Classification in English - `market` (string [Market]): Exchange market tier in English (Prime, Standard, Growth) - `tse_market_segment` (string [Market]): Official TSE market segment: Prime Market, Standard Market, Growth Market - `capital_stock` (float [JPY Millions]): Stated capital stock in millions of yen (資本金) - `headquarters` (string [Address]): Registered headquarters location in English - `headquarters_jp` (string [Address]): Statutory registered headquarters location in Japanese - `fiscal_year_end` (string [MM-DD]): Annual fiscal year closing date (e.g. '03-31') - `fiscal_month` (integer [1 - 12]): Fiscal year closing month as integer (e.g. 3 for March) - `is_listed` (boolean [true/false]): Active Tokyo Stock Exchange listed status flag - `quality_score` (integer [0 - 100]): Automated data consistency and schema validation score (0 - 100) - `data_available` (object [Flags]): Data presence boolean flags for financials, 5% rule, shareholders, risks - `has_5year_financials` (boolean [true/false]): Whether historical financial statements are available - `has_ownership_filings` (boolean [true/false]): Whether 5% rule ownership filings are available - `has_major_shareholders` (boolean [true/false]): Whether Top 10 major shareholders are available - `has_risk_reports` (boolean [true/false]): Whether Business Risks qualitative texts are available - `has_strategy_reports` (boolean [true/false]): Whether Management Strategy texts are available #### `GET /api/v1/industries` - List TSE Industries - **Description**: Get list of all 33 official Tokyo Stock Exchange industry sectors and constituent counts. - **Parameters**: - `is_listed` (query, boolean, optional, default: true): Only count active TSE listed companies (default: true) - **Response Fields**: - `total_industries_33` (integer [Count]): Total official TSE 33 sector categories (33) - `total_industries_17` (integer [Count]): Total official TSE 17 sector categories (17) - `industries` (array [Industries]): List of all official TSE industry sectors - `industry_code` (string [Code]): Internal sector classification code (e.g. '33_3600') - `name_en` (string [English]): Official sector or company name in English - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `companies_count` (integer [Count]): Number of listed companies belonging to this sector - `market_segments` (object [Breakdown]): Constituent breakdown by Prime, Standard, and Growth - `Prime` (integer [Count]): Companies listed on TSE Prime Market - `Standard` (integer [Count]): Companies listed on TSE Standard Market - `Growth` (integer [Count]): Companies listed on TSE Growth Market --- ### Domain: 📈 Financial Metrics #### `GET /api/v1/financials` - Search & Screen Financials - **Description**: Cross-sectional screener across all TSE companies by ROE, equity ratio, revenue, or operating profit. - **Parameters**: - `tickers` (query, string, optional): Comma-separated TSE ticker codes for bulk retrieval (e.g. '7203,6758,9432', max 50) - `min_roe` (query, float, optional): Minimum ROE percentage threshold (e.g. 15.0 for >= 15%) - `min_equity_ratio` (query, float, optional): Minimum equity ratio percentage threshold (e.g. 40.0 for >= 40%) - `min_revenue` (query, float, optional): Minimum annual revenue in JPY Millions (e.g. 100000 for >= 100B JPY) - `industry` (query, string, optional): Filter by TSE 33 sector name (e.g. '電気機器') - `accounting_standard` (query, string, optional): Filter by standard: 'IFRS', 'Japan GAAP', 'US GAAP' - `sort_by` (query, string, optional, default: period_end): Field to sort by: 'roe', 'operating_income', 'revenue', 'net_income' - `order` (query, string, optional, default: desc): Sort direction: 'asc' or 'desc' - `limit` (query, integer, optional, default: 50): Number of records to return (1 - 100) - `offset` (query, integer, optional, default: 0): Pagination offset - **Response Fields**: - `total_count` (integer [Count]): Total records matching query criteria across entire TSE database - `sorted_by` (string [Key]): Field by which the response records are sorted - `order` (string [asc/desc]): Sort direction ('asc' for ascending, 'desc' for descending) - `limit` (integer [Count]): Maximum records returned in this page - `offset` (integer [Count]): Current pagination offset - `has_more` (boolean [true/false]): Whether additional records exist beyond current page - `results` (array [Results]): List of result records matching screening filter - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `company` (object [Company Info]): Nested corporate profile object - `name` (string [English]): Official registered English corporate name - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `industry` (string [Sector]): TSE 33 Sector Classification in English - `industry_jp` (string [Sector]): TSE 33 Sector Classification in Japanese (e.g. '輸送用機器') - `market` (string [Market]): Exchange market tier in English (Prime, Standard, Growth) - `period_end` (string [YYYY-MM-DD]): Fiscal period end closing date - `period_label` (string [Label]): Human-readable fiscal period label (e.g. 'FY2025') - `accounting_standard` (string [Standard]): Adopted accounting standard: 'IFRS', 'Japan GAAP', 'US GAAP' - `currency` (string [ISO-4217]): Reporting currency code ('JPY') - `revenue` (float [JPY Millions]): Top-line revenue (synonym of net_sales) - `net_sales` (float [JPY Millions]): Net sales / Operating revenue (売上高 / 営業収益) - `operating_profit` (float [JPY Millions]): Operating profit / Operating income (営業利益) - `net_income` (float [JPY Millions]): Net profit attributable to owners of parent (当期純利益) - `total_assets` (float [JPY Millions]): Total balance sheet assets (総資産) - `net_assets` (float [JPY Millions]): Total balance sheet net assets / equity (純資産) - `roe` (float [%]): Return on Equity percentage (自己資本利益率) - `equity_ratio` (float [%]): Shareholders' equity to total assets ratio (自己資本比率) - `eps` (float [JPY]): Earnings per share (1株当たり当期純利益) - `bps` (float [JPY]): Book-value net assets per share (1株当たり純資産) - `operating_cash_flow` (float [JPY Millions]): Cash flows from operating activities (営業活動によるCF) - `free_cash_flow` (float [JPY Millions]): Free cash flow = Operating CF minus Capex (FCF) #### `GET /api/v1/financials/{ticker}` - Get 10-Year Financials - **Description**: Retrieve 10-year standardized quarterly & annual balance sheet, P&L, and cash flows for a specific ticker. - **Parameters**: - `ticker` (path, string, required, default: 7203): TSE ticker symbol (e.g. '7203', '7203.T') or EDINET code ('E02144') - `doc_type` (query, string, optional): Filter document type: '120' (Annual 有報), '140' (Quarterly 四半期報告書) - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `company` (object [Company Info]): Nested corporate profile object - `name` (string [English]): Official registered English corporate name - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `industry` (string [Sector]): TSE 33 Sector Classification in English - `industry_jp` (string [Sector]): TSE 33 Sector Classification in Japanese (e.g. '輸送用機器') - `market` (string [Market]): Exchange market tier in English (Prime, Standard, Growth) - `total_periods` (integer [Count]): Total fiscal accounting periods returned - `financials` (array [Periods]): Time-series array of statutory financial statements - `period_end` (string [YYYY-MM-DD]): Fiscal period end closing date - `period_label` (string [Label]): Human-readable fiscal period label (e.g. 'FY2025') - `document_type` (string [Statutory]): FSA statutory disclosure document type name - `accounting_standard` (string [Standard]): Adopted accounting standard: 'IFRS', 'Japan GAAP', 'US GAAP' - `currency` (string [ISO-4217]): Reporting currency code ('JPY') - `net_sales` (float [JPY Millions]): Net sales / Operating revenue (売上高 / 営業収益) - `operating_profit` (float [JPY Millions]): Operating profit / Operating income (営業利益) - `net_income` (float [JPY Millions]): Net profit attributable to owners of parent (当期純利益) - `total_assets` (float [JPY Millions]): Total balance sheet assets (総資産) - `net_assets` (float [JPY Millions]): Total balance sheet net assets / equity (純資産) - `roe` (float [%]): Return on Equity percentage (自己資本利益率) - `equity_ratio` (float [%]): Shareholders' equity to total assets ratio (自己資本比率) - `eps` (float [JPY]): Earnings per share (1株当たり当期純利益) - `bps` (float [JPY]): Book-value net assets per share (1株当たり純資産) - `operating_cash_flow` (float [JPY Millions]): Cash flows from operating activities (営業活動によるCF) - `free_cash_flow` (float [JPY Millions]): Free cash flow = Operating CF minus Capex (FCF) - `submitted_at` (string [Datetime]): Statutory EDINET submission timestamp --- ### Domain: 🔍 5% Large Holdings #### `GET /api/v1/ownership` - Search Large Shareholdings (5% Rule) - **Description**: Screen activist and institutional filings by filer name, stake change %, or date window. - **Parameters**: - `filer` (query, string, optional): Search by filer name in English, Kanji, or Katakana (e.g. 'Silchester', 'BlackRock', '野村') - `ticker` (query, string, optional): Filter by target company ticker (e.g. '7203') - `category` (query, string, optional): Filter by purpose category: 'investment' (純投資), 'strategic' (政策投資), 'activist' (重要提案行為) - `is_activist` (query, boolean, optional): Set true to filter specifically for activist proposals and management engagement - `min_holding_ratio` (query, float, optional): Minimum total holding ratio percentage (e.g. 5.0, 10.0) - `days` (query, integer, optional): Filings submitted within last N days (e.g. 30, 90, 365) - `limit` (query, integer, optional, default: 50): Maximum records to return (1 - 100) - **Response Fields**: - `total_count` (integer [Count]): Total records matching query criteria across entire TSE database - `limit` (integer [Count]): Maximum records returned in this page - `offset` (integer [Count]): Current pagination offset - `has_more` (boolean [true/false]): Whether additional records exist beyond current page - `results` (array [Results]): List of result records matching screening filter - `doc_id` (string [EDINET ID]): Unique FSA statutory filing document identifier (DocID) - `target_company` (object [Target]): Target company whose shares are held - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `name` (string [English]): Official registered English corporate name - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `industry` (string [Sector]): TSE 33 Sector Classification in English - `filer` (object [Filer]): Shareholder institution or individual filing the report - `filer_type` (string [Type]): Filer class: 'institution' or 'individual' - `edinet_code` (string [E-Code]): FSA statutory EDINET reporting entity code (e.g. 'E02144') - `holding_ratio` (float [%]): Current total shareholding percentage (株券等保有割合) - `prev_holding_ratio` (float [%]): Previously reported shareholding percentage - `change_ratio` (float [% (Delta)]): Net change in holding percentage (+/- points) - `shares_held` (integer [Shares]): Total shares held including joint holders - `purpose_category` (string [Category]): Standardized purpose: 'investment' (純投資), 'strategic' (政策投資), 'activist' (重要提案行為) - `purpose_category_jp` (string [Category JP]): Japanese standardized purpose classification - `purpose_text_jp` (string [Statutory Text]): Verbatim statutory investment purpose text from filing - `is_activist` (boolean [true/false]): Flag indicating shareholder activist intent (management engagement/proposals) - `joint_holders_count` (integer [Count]): Number of joint holders included in this filing - `filing_date` (string [YYYY-MM-DD]): Date filed to the Financial Services Agency #### `GET /api/v1/ownership/{ticker}` - Get Company Large Holdings - **Description**: Retrieve historical 5% rule filings and stake changes for a specific target company. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker symbol (e.g. '7203') - `is_activist` (query, boolean, optional): Only return activist/management proposal filings - `days` (query, integer, optional): Lookback window in days (e.g. 180, 365) - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `filings_count` (integer [Count]): Total 5% rule filings on record for target ticker - `filings` (array [Filings]): List of historical 5% rule statutory submissions - `filing_date` (string [YYYY-MM-DD]): Date filed to the Financial Services Agency - `filer_name` (string [English]): English name of filing institution or investor - `filer_name_jp` (string [Japanese]): Japanese statutory name of filing institution - `holding_ratio` (float [%]): Current total shareholding percentage (株券等保有割合) - `previous_ratio` (float [%]): Previous holding ratio percentage - `purpose` (string [Excerpt]): Statutory purpose summary excerpt - `doc_id` (string [EDINET ID]): Unique FSA statutory filing document identifier (DocID) --- ### Domain: 👥 Major Shareholders #### `GET /api/v1/shareholders` - Search Major Shareholders - **Description**: Search Top 10 shareholder rosters across all TSE listed companies by name. - **Parameters**: - `q` (query, string, optional): Shareholder name keyword in English, Kanji, or Katakana (e.g. 'Master Trust', '信託口', 'Berkshire') - `ticker` (query, string, optional): Filter by target company ticker - `min_ratio` (query, float, optional): Minimum shareholding ratio percentage (e.g. 10.0 for >= 10%) - `rank` (query, integer, optional): Filter by shareholder rank (1 to 10) - `latest_only` (query, boolean, optional, default: true): Only match latest annual filing periods - `limit` (query, integer, optional, default: 50): Maximum records to return - **Response Fields**: - `total_count` (integer [Count]): Total records matching query criteria across entire TSE database - `limit` (integer [Count]): Maximum records returned in this page - `offset` (integer [Count]): Current pagination offset - `has_more` (boolean [true/false]): Whether additional records exist beyond current page - `results` (array [Results]): List of result records matching screening filter - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `company` (object [Company Info]): Nested corporate profile object - `name` (string [English]): Official registered English corporate name - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `industry` (string [Sector]): TSE 33 Sector Classification in English - `period_end` (string [YYYY-MM-DD]): Fiscal period end closing date - `rank` (integer [1 - 10]): Shareholder ownership ranking (1st to 10th) - `shareholder_name` (string [English]): Resolved official English name of major shareholder - `shareholder_name_jp` (string [Kanji]): Statutory shareholder name as filed in annual report - `shareholder_type` (string [Type]): Shareholder class: 'trust', 'corporation', 'individual', 'foreign' - `is_verified` (boolean [true/false]): Automated balance and checksum verification status - `shares_held` (integer [Shares]): Total shares held including joint holders - `shareholding_ratio` (float [%]): Percentage of total issued & outstanding shares owned - `shareholder_address_jp` (string [Address]): Statutory registered address of shareholder #### `GET /api/v1/shareholders/{ticker}` - Get Top 10 Major Shareholders - **Description**: Get verified Top 10 major shareholders, shares held, and percentage of ownership for a ticker. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code (e.g. '7203') - `latest_only` (query, boolean, optional, default: true): Set true for latest period Top 10; false for 10-year historical rosters - `period_end` (query, string, optional): Filter by specific fiscal period closing date (YYYY-MM-DD) - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `period_end` (string [YYYY-MM-DD]): Fiscal period end closing date - `document_type` (string [Statutory]): FSA statutory disclosure document type name - `shareholders` (array [Shareholders]): Official roster of Top 10 major shareholders as reported in filings - `rank` (integer [1 - 10]): Shareholder ownership ranking (1st to 10th) - `shareholder_name` (string [English]): Resolved official English name of major shareholder - `shareholder_name_jp` (string [Kanji]): Statutory shareholder name as filed in annual report - `shareholder_type` (string [Type]): Shareholder class: 'trust', 'corporation', 'individual', 'foreign' - `is_verified` (boolean [true/false]): Automated balance and checksum verification status - `shares_held` (integer [Shares]): Total shares held including joint holders - `shareholding_ratio` (float [%]): Percentage of total issued & outstanding shares owned - `shareholder_address_jp` (string [Address]): Statutory registered address of shareholder --- ### Domain: 🌱 Human Capital & ESG #### `GET /api/v1/esg` - Search Human Capital & ESG - **Description**: Screen companies by female manager ratio, male childcare leave rate, or average salary. - **Parameters**: - `min_female_ratio` (query, float, optional): Minimum female management ratio % (e.g. 10.0 for >= 10%) - `min_salary` (query, integer, optional): Minimum average annual employee salary in JPY (e.g. 8000000) - `min_employees` (query, integer, optional): Minimum employee headcount (e.g. 1000) - `industry` (query, string, optional): Filter by TSE 33 sector name - `limit` (query, integer, optional, default: 50): Maximum records to return - **Response Fields**: - `total_count` (integer [Count]): Total records matching query criteria across entire TSE database - `limit` (integer [Count]): Maximum records returned in this page - `offset` (integer [Count]): Current pagination offset - `has_more` (boolean [true/false]): Whether additional records exist beyond current page - `results` (array [Results]): List of result records matching screening filter - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `company` (object [Company Info]): Nested corporate profile object - `name` (string [English]): Official registered English corporate name - `name_jp` (string [Kanji]): Official registered Japanese corporate name (商号) - `industry` (string [Sector]): TSE 33 Sector Classification in English - `period_end` (string [YYYY-MM-DD]): Fiscal period end closing date - `employees` (integer [Persons]): Total consolidated employees headcount - `avg_annual_salary` (integer [JPY]): Average annual employee salary in Japanese yen - `avg_age` (float [Years]): Average employee age - `avg_length_of_service` (float [Years]): Average tenure / years of service - `female_management_ratio` (float [%]): FSA statutory female management ratio - `female_director_ratio` (float [%]): Statutory female board director / officer ratio - `headcount` (object): Standalone vs consolidated employee headcount breakdown - `human_capital` (object): Structured diversity and wage disparity indicators - `male_childcare_leave_ratio` (float [%]): Male parental leave take-up rate - `gender_gender_gender_wage_gap_all` (float [%]): Gender wage gap across all staff (Women / Men %) - `gender_gender_gender_wage_gap_regular` (float [%]): Gender wage gap for regular full-time staff (Women / Men %) #### `GET /api/v1/esg/{ticker}` - Get Company Human Capital History - **Description**: Retrieve time series of statutory diversity, salaries, and employee metrics for a specific ticker. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code (e.g. '7203') - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `total_periods` (integer [Count]): Total fiscal accounting periods returned - `latest` (object [Latest Metrics]): Most recent statutory fiscal period ESG disclosures - `period_end` (string [YYYY-MM-DD]): Fiscal period end closing date - `employees` (integer [Persons]): Total consolidated employees headcount - `avg_annual_salary` (integer [JPY]): Average annual employee salary in Japanese yen - `avg_age` (float [Years]): Average employee age - `avg_length_of_service` (float [Years]): Average tenure / years of service - `female_management_ratio` (float [%]): FSA statutory female management ratio - `female_director_ratio` (float [%]): Statutory female board director / officer ratio - `headcount` (object): Standalone vs consolidated employee headcount breakdown - `human_capital` (object): Structured diversity and wage disparity indicators - `male_childcare_leave_ratio` (float [%]): Male parental leave take-up rate - `gender_gender_gender_wage_gap_all` (float [%]): Gender wage gap across all staff (Women / Men %) - `gender_gender_gender_wage_gap_regular` (float [%]): Gender wage gap for regular full-time staff (Women / Men %) --- ### Domain: 📑 Qualitative Texts #### `GET /api/v1/reports/search` - Full-Text Search Reports - **Description**: FTS5 semantic full-text search across all statutory securities reports by keyword. - **Parameters**: - `q` (query, string, required): Search keyword in Japanese or English (e.g. 'supply chain', '半導体', '為替') - `section` (query, string, optional): Filter section: 'risks', 'mda', 'strategy', 'governance', 'remuneration', 'sustainability' - `industry` (query, string, optional): Filter by TSE 33 sector name - `years` (query, integer, optional, default: 3): Historical search window in years (1 - 5) - `limit` (query, integer, optional, default: 20): Maximum text matches to return - **Response Fields**: - `query` (string [Text]): Original search keyword queried - `total_matches` (integer [Count]): Total text sections matching search keyword - `limit` (integer [Count]): Maximum records returned in this page - `results` (array [Results]): List of result records matching screening filter - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `company_name` (string [Text]): Corporate name - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `fiscal_year` (integer [YYYY]): Reporting fiscal year - `headline` (string [Heading]): Specific risk or text disclosure headline - `snippet` (string [HTML Excerpt]): Contextual text excerpt highlighted around search keyword - `char_count` (integer [Chars]): Character count of the extracted section text #### `GET /api/v1/reports/{ticker}/risks` - Get Business Risks (事業等のリスク) - **Description**: Extract legally mandated Business Risks section and key summary points for a company. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code (e.g. '7203') - `year` (query, integer, optional): Fiscal year (e.g. 2024). Defaults to latest. - `doc_id` (query, string, optional): Specific statutory document submission ID - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `ticker_full` (string [ticker.T]): Tokyo Stock Exchange-suffixed symbol for global market compatibility (e.g. '7203.T') - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `section_name_jp` (string [Japanese]): Exact statutory Japanese heading from annual securities report - `document` (object [Document Info]): Source disclosure report metadata - `document_name` (string [Name]): Official statutory report title - `submitted_at` (string [Datetime]): Statutory EDINET submission timestamp - `summary` (array [Bullet Points]): Algorithmic key risk summary points - `content` (array [Sections]): Array of parsed statutory subsections and paragraphs - `title` (string [Title JP]): Original Japanese disclosure subsection title - `title_en` (string [Title EN]): Normalized English translated subsection title - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/mda` - Get MD&A Analysis - **Description**: Extract Management Discussion and Analysis of Financial Condition and Operating Results. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `year` (query, integer, optional): Fiscal year (e.g. 2024) - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `section_name_jp` (string [Japanese]): Exact statutory Japanese heading from annual securities report - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/strategy` - Get Management Strategy - **Description**: Extract corporate strategy, target KPIs, and business environment analysis. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `year` (query, integer, optional): Fiscal year - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `section_name_jp` (string [Japanese]): Exact statutory Japanese heading from annual securities report - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/governance` - Get Corporate Governance - **Description**: Extract statutory disclosures on board oversight, committee structures, and internal audit. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `year` (query, integer, optional): Fiscal year - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `section_name_jp` (string [Japanese]): Exact statutory Japanese heading from annual securities report - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/remuneration` - Get Officer Remuneration - **Description**: Extract statutory director compensation policies, performance-linked pay, and stock options. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `year` (query, integer, optional): Fiscal year - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `section_name_jp` (string [Japanese]): Exact statutory Japanese heading from annual securities report - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/sustainability` - Get Sustainability Disclosures - **Description**: Extract statutory TCFD climate scenarios, governance, and environmental disclosures. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `year` (query, integer, optional): Fiscal year - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `section_name_jp` (string [Japanese]): Exact statutory Japanese heading from annual securities report - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/rd_activities` - Get R&D Activities - **Description**: Extract descriptions of research and development projects, patent investments, and R&D spend. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `year` (query, integer, optional): Fiscal year - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `section` (string [Slug]): Standardized section key (e.g. 'risks', 'mda', 'strategy') - `section_name` (string [English]): Official English section heading name - `section_name_jp` (string [Japanese]): Exact statutory Japanese heading from annual securities report - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/full-text` - Get Report Full Text - **Description**: Retrieve complete statutory document text concatenated across all XBRL sections. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `year` (query, integer, optional): Fiscal year - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `document_type` (string [Statutory]): FSA statutory disclosure document type name - `total_characters` (integer [Chars]): Total character length of the entire statutory filing - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML #### `GET /api/v1/reports/{ticker}/{section}` - Get Dynamic Report Section - **Description**: Retrieve any specific statutory section by internal section slug identifier. - **Parameters**: - `ticker` (path, string, required, default: 7203): Target company ticker code - `section` (path, string, required, default: risks): Section slug: 'risks', 'mda', 'strategy', 'governance', 'remuneration', 'sustainability', 'rd_activities' - `year` (query, integer, optional): Fiscal year - **Response Fields**: - `ticker` (string [4 digits]): Tokyo Stock Exchange 4-digit security code (e.g. '7203') - `requested_section` (string [Slug]): Requested statutory section identifier - `status` (string [Status]): Execution status flag ('success', 'ok') - `text` (string [Full Text]): Full verbatim statutory disclosure text parsed from XBRL/HTML ---