# Japan Shareholder Benefits (Kabunushi Yutai) Dataset (`kaichi-labs/kabuyutai-shareholder-benefits`) Actor

Filterable dataset of Japanese shareholder benefit (kabunushi yutai) programs from kabuyutai.com, with computed yield %. Screen hundreds of companies for high-yield perks in seconds instead of clicking through pages by hand. Filter by category, ticker, or yield. Pay per record, no subscription.

- **URL**: https://apify.com/kaichi-labs/kabuyutai-shareholder-benefits.md
- **Developed by:** [Yuji Kaichi](https://apify.com/kaichi-labs) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 stock records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🎁 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](https://www.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

```json
{
  "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

```bash
npm install
```

#### Run locally

```bash
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

```bash
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)

# Actor input Schema

## `benefitCategory` (type: `array`):

kabuyutai.comのカテゴリ文字列の一部を指定（例: "飲食料品"）。指定した文字列のいずれかを含むカテゴリを持つ銘柄のみ出力します。未指定なら全カテゴリ対象。

## `minBenefitYieldPct` (type: `integer`):

優待利回りの下限（%）。この値未満の銘柄は除外します。未指定なら0（フィルタなし）。

## `maxInvestmentJpy` (type: `integer`):

優待に必要な最低投資額の上限（円）。この値を超える銘柄は除外します。未指定ならフィルタなし。

## `tickerCodes` (type: `array`):

取得したい銘柄コード（4桁）を指定すると、その銘柄のみ出力します。未指定なら全銘柄を対象にします。

## Actor input object example

```json
{}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("kaichi-labs/kabuyutai-shareholder-benefits").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("kaichi-labs/kabuyutai-shareholder-benefits").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call kaichi-labs/kabuyutai-shareholder-benefits --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kaichi-labs/kabuyutai-shareholder-benefits"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gREmzPPQgxtOCvBNI/builds/rXdfowM3gVIvr7V1E/openapi.json