🎁 Japan Shareholder Benefits (Kabunushi Yutai) Dataset

Get a structured, filterable dataset of Japanese shareholder benefit programs (株主優待) — the perks Japanese companies give shareholders on top of dividends (gift cards, product discounts, hotel stays, and more). Sourced from kabuyutai.com, Japan's leading shareholder-benefit comparison site, and enriched with computed yield metrics you won't get from the raw HTML.

Why this Actor

Screening for high-yield shareholder benefits by hand means opening hundreds of individual company pages. This Actor does that for you and returns ready-to-use JSON/CSV records — filterable by category, yield, ticker, or investment amount.

Sample output

{
  "ticker_code": "6181",
  "company_name": "タメニー (Tameny)",
  "benefit_summary": "Free membership voucher for matchmaking service \"Partner Agent\" (33,000 JPY value)",
  "min_investment_jpy": 7800,
  "benefit_yield_pct": 1833.33,
  "dividend_yield_pct": 0,
  "total_yield_pct": 1833.33,
  "rights_month": "9月",
  "source_url": "https://www.kabuyutai.com/kobetu/tameny.html"
}

Every record includes the minimum investment required, the benefit's cash value, computed benefit/dividend/total yield, and a link back to the source page for verification.

Who uses this

• No-code/automation builders (Make, n8n, Zapier) piping shareholder-benefit alerts into a Slack/LINE bot
• Developers building a personal or public shareholder-benefit screener/app
• International investors researching Japanese equities who can't easily read kabuyutai.com
• Analysts tracking benefit-yield trends over time

Pricing

Pay per event: $0.50 per 1,000 stock-record events (one event per matched benefit record returned). No subscription, no minimum. A full unfiltered run currently returns roughly 1,700 records (~$0.85).

Input parameters

All optional — omit any to get the full unfiltered dataset. See .actor/input_schema.json for the authoritative schema.

Parameter	Description
benefitCategory	Filter by category, partial match (array)
minBenefitYieldPct	Minimum benefit yield (%)
maxInvestmentJpy	Maximum minimum-investment amount (JPY)
tickerCodes	Filter to specific ticker codes (array)

Note: filters are applied after the full site crawl, so run cost/time is currently similar regardless of how narrow your filter is (tracked as a known optimization backlog item).

Data freshness & scope

Each run scrapes kabuyutai.com live — data reflects the site's current listings at run time, not a cached snapshot. required_shares (the literal share count needed) is not exposed by kabuyutai.com's search API and is always null; use min_investment_jpy for cost screening instead.

---

For developers (this repo)

Full requirements/design docs live under docs/ (SRS.md/SDD.md/TEST_PLAN.md etc.); operating rules are in CLAUDE.md/CONSTRAINTS.md.

Setup

$npm install

Run locally

npm start
# or via Apify CLI (pass an input file matching .actor/input_schema.json)
npx apify run --input-file=./tests/fixtures/input-default.json

Tests

npm test          # unit + integration (node:test)
npm run test:e2e  # E2E against a local HTTP test server standing in for kabuyutai.com
npm run test:coverage
npm run lint

Design notes

• Sole data source is kabuyutai.com's internal search JSON API (/tool/api/search/?p=N, see ADR-006)
• Politeness limits (ADR-004, maxConcurrency:2) are intentional; relaxing them requires explicit approval (CONSTRAINTS.md C-AI-010)