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):

{
  "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 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)

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

{
  "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.