# Japan Yahoo! Shopping Product Search (Official API) (`jpopendata/japan-yahoo-shopping-api`) Actor

Search Yahoo! Shopping (Japan) products via the official item-search API v3: price, store, brand, JAN, points, review score, stock. You supply your own Yahoo application ID. Unofficial; not affiliated with LY Corporation / Yahoo! JAPAN.

- **URL**: https://apify.com/jpopendata/japan-yahoo-shopping-api.md
- **Developed by:** [JP Open Data](https://apify.com/jpopendata) (community)
- **Categories:**
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 record scrapeds

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 Yahoo! Shopping Product Search (Official API v3)

**Search Japan's Yahoo! Shopping catalogue through the official Yahoo item-search API v3 (JSON) — clean, structured product records: price, store, brand, JAN, points, review score, stock.**

This Actor is a thin, polite client for the **official** Yahoo! Shopping Item Search API v3 (`shopping.yahooapis.jp`). It is **not a scraper** — it calls the documented JSON API the way Yahoo intends, using **your own Yahoo application ID**, and returns each product hit as a flat record with a legal envelope (`source` / `sourceUrl` / `license` / `retrievedAt`) on every item.

> **Unofficial tool.** Independently built and maintained. **Not affiliated with, endorsed by, or connected to LY Corporation, Yahoo! JAPAN, or Yahoo! Shopping.** "Yahoo!" and "Yahoo! JAPAN" are trademarks of their respective owners. Every record carries the credit **「Web Services by Yahoo! JAPAN」** that the Yahoo Developer Network API guidelines require.

***

### Quick start — verified input

Copy, paste, replace the key, run (verified against mock API fixtures in `npm test`; a live run needs your own application ID — see the next section for how to get one in two minutes):

```json
{
  "appId": "<your key>",
  "query": "緑茶",
  "maxItems": 100
}
```

`appId` is the only required field besides one search constraint. Get the key at https://e.developer.yahoo.co.jp/register (free; Yahoo! JAPAN ID needed) → アプリケーションの管理 → 新しいアプリケーションを開発 → copy the **Client ID**.

### ⚠️ You need your own Yahoo application ID

This Actor **does not bundle an API key.** You must supply your **own** free Yahoo! JAPAN application ID (Client ID) in the `appId` input.

1. Sign in with a Yahoo! JAPAN ID.
2. Register an application (Client ID) here: **https://e.developer.yahoo.co.jp/register**
3. Paste the Client ID into this Actor's `appId` field (it is stored as a secret).

Why this design? The Yahoo guidelines require every request to carry an application ID (アプリケーションID付与義務). By running under **your** ID, every call stays inside **your** Yahoo Developer Network agreement, Yahoo's per-application rate limit (30 requests/minute) applies to you, and there is no shared-key ownership problem. Compliance with the [Yahoo Developer Network guidelines](https://developer.yahoo.co.jp/attention/) and the LINEヤフー共通利用規約 is the responsibility of the application-ID holder — i.e. you.

### Credit-display obligation (クレジット表示義務)

Yahoo requires that data taken from their Web APIs be displayed with the credit **「Web Services by Yahoo! JAPAN」**. This Actor embeds that credit verbatim in the `license` field of every dataset record. If you display or republish the data, keep that credit visible.

### What you can search

At least **one** search constraint is required (this is a targeted query tool, not a full-catalogue dumper):

- `query` — free-text keyword (e.g. `緑茶`, `Nintendo Switch`)
- `janCode` — exact 8/13-digit JAN/EAN
- `genreCategoryId`, `categoryId`, `brandId`, `sellerId` — narrow to a genre, category, brand, or store
- plus optional `priceFrom` / `priceTo`, `sort`, `condition` (new/used), `inStock`

### Sample output (dataset item)

```json
{
  "itemName": "静岡県産 深蒸し緑茶 100g 3袋セット",
  "itemCode": "storeaaa_greentea-100g-3set",
  "priceJpy": 1980,
  "storeName": "静岡茶園 Yahoo!店",
  "sellerId": "storeaaa",
  "brandName": "静岡茶園",
  "janCode": "4901234567894",
  "categoryId": "2498",
  "categoryName": "緑茶・日本茶",
  "availability": "in_stock",
  "condition": "new",
  "pointAmount": 19,
  "reviewAverage": 4.55,
  "reviewCount": 231,
  "imageUrl": "https://item-shopping.c.yimg.jp/i/g/storeaaa_x_m.jpg",
  "itemUrl": "https://store.shopping.yahoo.co.jp/storeaaa/greentea-100g-3set.html",
  "affiliateUrl": null,
  "source": "Yahoo!ショッピング 商品検索API（Yahoo!デベロッパーネットワーク） / Yahoo! Shopping Item Search API, Yahoo! JAPAN",
  "sourceUrl": "https://developer.yahoo.co.jp/webapi/shopping/v3/itemsearch.html",
  "license": "Web Services by Yahoo! JAPAN（…クレジット表示）。… unofficial, not affiliated with LY Corporation / Yahoo! JAPAN. …",
  "retrievedAt": "2026-08-26T09:12:44Z"
}
```

`reviewAverage`/`reviewCount` are the **numeric** review score and count only — **review text and reviewer names are never retrieved.** Missing values are `null` (not zero-filled or empty-stringed).

### Input example

```json
{
  "appId": "<your key>",
  "query": "緑茶",
  "priceFrom": 500,
  "priceTo": 3000,
  "sort": "-review_count",
  "condition": "new",
  "inStock": true,
  "maxItems": 200
}
```

#### Common input mistakes

| Mistake | Correct |
|---------|---------|
| `"appId": "<your key>"` left as is / empty | paste your real Yahoo Client ID (the run fails immediately with a link to get one) |
| `{"appId": "…"}` with no search field | add `"query": "緑茶"` (or `janCode` / `genreCategoryId` / `categoryId` / `brandId` / `sellerId`) |
| `"sort": "price"` / `"cheapest"` | accepted — canonical tokens are `+price`, `-price`, `-review_count`, `-sold`, `-score` … |
| `"janCode": "1234"` | 8 or 13 digits, e.g. `"4901085081464"` |
| `"priceFrom": 3000, "priceTo": 500` (reversed) | `"priceFrom": 500, "priceTo": 3000` |
| `"condition": "refurbished"` | `"new"` or `"used"` (leave empty for both) |

#### Empty results?

A run that finds nothing completes with 0 items and a warning in the log (not a failure). Typical causes: an English `query` for a product Yahoo lists only in Japanese (try `緑茶` instead of `green tea`), a JAN that no store currently lists, a `sellerId`/`brandId`/`categoryId` that does not exist, or a price/condition/in-stock combination that excludes everything. Broaden the query or drop a filter and retry. HTTP 401/403 from Yahoo means the application ID is wrong or not yet activated — that fails the run visibly.

### Affiliate links (optional)

Set `affiliateId` (your ValueCommerce `sid`) and each record will include an `affiliateUrl`. Leave it empty for plain product data.

### Pricing

Pay per result — see the pricing tab. Note the Yahoo API's own limit of **30 requests per minute** per application ID; this Actor spaces requests ≥ 2.5 s apart and pages 50 hits per request, so a few hundred items take a minute or two.

### FAQ

**Is this official?**
No. **Unofficial**, not affiliated with LY Corporation / Yahoo! JAPAN. It is a client of Yahoo's official public item-search API.

**Do you store or resell Yahoo's data?**
No. The Actor fetches results live under **your** application ID and writes them to **your** Apify dataset. You are the API user; the data lands in your account. Keep the 「Web Services by Yahoo! JAPAN」 credit (embedded in every record) when you display it.

**Why is `appId` required and not provided?**
Because Yahoo binds API usage and rate limits to an application ID, and that ID should be yours. It is entered as a secret and redacted from all logs.

**How fresh is the data?**
Live at request time — it is the same catalogue Yahoo! Shopping serves.

**Any privacy concerns?**
Product/store/brand data only. Review bodies, reviewer names, and seller contact details are deliberately not read. Automated tests assert no phone/e-mail/address-shaped strings and full source attribution on every record.

**Rate limits / server load?**
One sequential connection, ≥ 2.5 s between requests (Yahoo caps at 30/min per appId), exponential backoff on 429/5xx, a hard per-run request budget, and no rate-limit evasion — a persistent block fails the run visibly.

### Search terms this Actor answers

Yahoo shopping API actor · Yahoo Shopping scraper · Japan e-commerce product data · Yahoo Japan product search API · Japan online shopping price data · Yahoo shopping item search v3 · Japanese product catalog API · Japan retail price monitoring

### Note for the Apify automated build test

This Actor **requires** a valid personal Yahoo `appId` (secret) to make any live call, so Apify's default automated run test cannot pass unattended (no key). **An automated-test exemption is requested for this Actor** (same handling as key-required API Actors). Functionality is covered by the unit test suite (`npm test`, 26 tests) over mock API fixtures; a live run needs the buyer's own application ID.

***

*Official API: Yahoo! Shopping Item Search API v3 — https://developer.yahoo.co.jp/webapi/shopping/v3/itemsearch.html . Guidelines: https://developer.yahoo.co.jp/attention/ . Credit 「Web Services by Yahoo! JAPAN」 is embedded in every record. Unofficial; not affiliated with LY Corporation / Yahoo! JAPAN.*

# Actor input Schema

## `appId` (type: `string`):

REQUIRED. YOUR OWN Yahoo! JAPAN application ID (Client ID) — a long alphanumeric string from the Yahoo Developer Network dashboard. This Actor does NOT bundle a shared key — every request runs under your application ID so it stays within your own Yahoo Developer Network agreement, and Yahoo's per-appID rate limit applies to you. Get one for free (Yahoo! JAPAN ID needed): https://e.developer.yahoo.co.jp/register → アプリケーションの管理 → 新しいアプリケーションを開発 (server-side app) → copy the Client ID.

## `query` (type: `string`):

Free-text product keyword (e.g. "緑茶", "Nintendo Switch"). Japanese matches best. At least ONE of query / janCode / genreCategoryId / categoryId / brandId / sellerId is required.

## `janCode` (type: `string`):

Exact 8- or 13-digit JAN/EAN barcode to look up a specific product, e.g. "4901085081464" (dashes/spaces are tolerated).

## `genreCategoryId` (type: `string`):

Yahoo genre category ID to restrict results (numeric, e.g. "2498"). Use the Yahoo category-search API to discover IDs.

## `categoryId` (type: `string`):

Yahoo product category ID to restrict results (numeric).

## `brandId` (type: `string`):

Yahoo brand ID to restrict results to one brand (numeric).

## `sellerId` (type: `string`):

Restrict results to a single Yahoo! Shopping store by its store/seller ID (the store slug in the URL, e.g. "yamada-denki").

## `priceFrom` (type: `integer`):

Lower price bound in yen (inclusive, whole number, e.g. 500).

## `priceTo` (type: `integer`):

Upper price bound in yen (inclusive, whole number, e.g. 3000). Must be >= priceFrom.

## `sort` (type: `string`):

Result ordering. `-score` relevance (default), `+price`/`-price` price asc/desc, `+name`/`-name`, `-review_count` most reviewed, `-sold` best-selling. Aliases such as "price\_asc", "cheapest", "most\_reviewed" are accepted via the API.

## `condition` (type: `string`):

Restrict to "new" (新品) or "used" (中古) items. Leave empty for both.

## `inStock` (type: `boolean`):

If true, only return items currently in stock ("true"/"false" strings are tolerated).

## `affiliateId` (type: `string`):

Optional. Your ValueCommerce affiliate ID (sid). When set, each record includes an affiliateUrl. Leave empty for plain product data.

## `affiliateType` (type: `string`):

Affiliate network for affiliateId. Default ValueCommerce.

## `maxItems` (type: `integer`):

Maximum number of products to output (1-1000, default 100). The upstream paginates 50 hits per request up to roughly 1000 hits per query.

## `maxApiRequests` (type: `integer`):

Hard safety cap on API requests per run (1-25, default 5; each page = up to 50 items). Politeness (1 connection, >= 2.5 s spacing per Yahoo's 30 req/min limit, exponential backoff on 429/5xx) is enforced in code.

## `proxyConfiguration` (type: `object`):

Apify proxy settings. Default is NO proxy (direct connection) — an official JSON API rarely needs one. The Actor backs off exponentially on 429/5xx and fails visibly on a persistent block; it never attempts rate-limit evasion.

## Actor input object example

```json
{
  "query": "緑茶",
  "janCode": "4901085081464",
  "inStock": false,
  "affiliateType": "vc",
  "maxItems": 100,
  "maxApiRequests": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `records` (type: `string`):

Structured product records with source attribution (source, sourceUrl, license, retrievedAt) on every item.

# 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 = {
    "query": "緑茶",
    "maxItems": 100,
    "maxApiRequests": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-yahoo-shopping-api").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 = {
    "query": "緑茶",
    "maxItems": 100,
    "maxApiRequests": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-yahoo-shopping-api").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 '{
  "query": "緑茶",
  "maxItems": 100,
  "maxApiRequests": 5
}' |
apify call jpopendata/japan-yahoo-shopping-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpopendata/japan-yahoo-shopping-api"
        }
    }
}

```

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/znUaVpSORocfGJlfw/builds/eGzhbZXLh7bHatdue/openapi.json