{"openapi":"3.1.0","info":{"title":"Yahoo Shopping Japan (BYOK) API","version":"0.1.0","description":"Yahoo Shopping Japan (BYOK) lets an AI assistant read your own Yahoo Shopping Japan data through the Yahoo Shopping Japan API with a key you supply (Client ID (application ID)). Read-only: 6 tools (search_items, find_items_by_jan_code, list_store_items, get_keyword_ranking, get_rising_keywords, get_high_rating_trend_ranking). The BYOK key travels with each request, is used for that one call only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-yahoo-shopping-jp.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-yahoo-shopping-jp/docs"},"termsOfService":"https://connectorbay.com/byok-yahoo-shopping-jp/terms"},"servers":[{"url":"https://byok-yahoo-shopping-jp.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-yahoo-shopping-jp/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_items":{"post":{"operationId":"search_items","summary":"Search Yahoo! Shopping Japan items by keyword: name, price, sale price, stock, condition, review score, store, category,","description":"Search Yahoo! Shopping Japan items by keyword: name, price, sale price, stock, condition, review score, store, category, brand, JAN code and image. Japanese keywords work best. Use for \"Find the cheapest new Nike sneakers on Yahoo Shopping Japan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Search keyword (Japanese or English).","maxLength":200,"title":"Query","type":"string"},"genre_category_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Genre category ID, several joined by commas (OR); look up IDs with the category pages of Yahoo Shopping.","title":"Genre Category Id"},"brand_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Brand ID, several joined by commas (OR).","title":"Brand Id"},"price_from":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Lowest price in yen (inclusive).","title":"Price From"},"price_to":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Highest price in yen (inclusive).","title":"Price To"},"in_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for items in stock only, false for sold-out only.","title":"In Stock"},"is_discounted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for items on sale only.","title":"Is Discounted"},"shipping":{"anyOf":[{"enum":["free","conditional_free"],"type":"string"},{"type":"null"}],"default":null,"description":"free for free shipping or conditional_free for conditionally free shipping.","title":"Shipping"},"condition":{"anyOf":[{"enum":["new","used"],"type":"string"},{"type":"null"}],"default":null,"description":"new or used.","title":"Condition"},"sort":{"anyOf":[{"enum":["-score","+price","-price","-review_count"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: -score (recommended), +price (cheapest first), -price (dearest first), -review_count (most reviews).","title":"Sort"},"seller_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this store ID.","title":"Seller Id"},"results":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 50, default 20).","title":"Results"},"start":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Position of the first item, starting at 1 (start plus results must not exceed 1000).","title":"Start"}},"required":["query"],"title":"search_itemsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_items_by_jan_code":{"post":{"operationId":"find_items_by_jan_code","summary":"Find Yahoo! Shopping Japan items by JAN barcode: which stores sell it, at what price and with what reviews. Use for \"Whi","description":"Find Yahoo! Shopping Japan items by JAN barcode: which stores sell it, at what price and with what reviews. Use for \"Which stores sell JAN 4905524535815 and at what price\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"jan_code":{"description":"JAN code (13 digits).","maxLength":14,"title":"Jan Code","type":"string"},"in_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for items in stock only.","title":"In Stock"},"sort":{"anyOf":[{"enum":["-score","+price","-price","-review_count"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: -score (recommended), +price (cheapest first), -price (dearest first), -review_count (most reviews).","title":"Sort"},"results":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 50, default 20).","title":"Results"},"start":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Position of the first item, starting at 1 (start plus results must not exceed 1000).","title":"Start"}},"required":["jan_code"],"title":"find_items_by_jan_codeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_store_items":{"post":{"operationId":"list_store_items","summary":"List the items of one Yahoo! Shopping store, optionally narrowed by keyword, category or price. Use for \"Show items from","description":"List the items of one Yahoo! Shopping store, optionally narrowed by keyword, category or price. Use for \"Show items from store zozo under 5000 yen\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seller_id":{"description":"Store ID, the part after store.shopping.yahoo.co.jp/ in the store URL.","maxLength":60,"title":"Seller Id","type":"string"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional keyword inside the store.","title":"Query"},"genre_category_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Genre category ID, several joined by commas (OR); look up IDs with the category pages of Yahoo Shopping.","title":"Genre Category Id"},"brand_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Brand ID, several joined by commas (OR).","title":"Brand Id"},"price_from":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Lowest price in yen (inclusive).","title":"Price From"},"price_to":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Highest price in yen (inclusive).","title":"Price To"},"in_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for items in stock only, false for sold-out only.","title":"In Stock"},"is_discounted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for items on sale only.","title":"Is Discounted"},"shipping":{"anyOf":[{"enum":["free","conditional_free"],"type":"string"},{"type":"null"}],"default":null,"description":"free for free shipping or conditional_free for conditionally free shipping.","title":"Shipping"},"condition":{"anyOf":[{"enum":["new","used"],"type":"string"},{"type":"null"}],"default":null,"description":"new or used.","title":"Condition"},"sort":{"anyOf":[{"enum":["-score","+price","-price","-review_count"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: -score (recommended), +price (cheapest first), -price (dearest first), -review_count (most reviews).","title":"Sort"},"results":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 50, default 20).","title":"Results"},"start":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Position of the first item, starting at 1 (start plus results must not exceed 1000).","title":"Start"}},"required":["seller_id"],"title":"list_store_itemsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_keyword_ranking":{"post":{"operationId":"get_keyword_ranking","summary":"Most searched keywords on Yahoo! Shopping Japan with rank, previous rank, trend and related terms; optionally for one ca","description":"Most searched keywords on Yahoo! Shopping Japan with rank, previous rank, trend and related terms; optionally for one category. Use for \"What are people searching for on Yahoo Shopping Japan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"const":"ranking","type":"string"},{"type":"null"}],"default":"ranking","description":"ranking for the most searched keywords.","title":"Type"},"category_id":{"anyOf":[{"maximum":99999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only keywords within this category ID (1 for all).","title":"Category Id"},"hits":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many keywords to return (1 to 100, default 20).","title":"Hits"},"offset":{"anyOf":[{"maximum":980,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Offset into the ranking: 0 gives ranks 1 to 20, 20 gives 21 to 40.","title":"Offset"}},"title":"get_keyword_rankingArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_rising_keywords":{"post":{"operationId":"get_rising_keywords","summary":"Fastest-rising search keywords on Yahoo! Shopping Japan with rank and trend; optionally for one category. Use for \"Which","description":"Fastest-rising search keywords on Yahoo! Shopping Japan with rank and trend; optionally for one category. Use for \"Which search terms are surging on Yahoo Shopping Japan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"const":"up","type":"string"},{"type":"null"}],"default":"up","description":"up for the fastest-rising keywords.","title":"Type"},"category_id":{"anyOf":[{"maximum":99999999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only keywords within this category ID (1 for all).","title":"Category Id"}},"title":"get_rising_keywordsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_high_rating_trend_ranking":{"post":{"operationId":"get_high_rating_trend_ranking","summary":"Ranking of highly rated, trending Yahoo! Shopping Japan products with rank, prices, review score, store and image. Filte","description":"Ranking of highly rated, trending Yahoo! Shopping Japan products with rank, prices, review score, store and image. Filter by keyword, category, brand, store or price. Use for \"What are the top trending highly rated products in category 17583\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional keyword.","title":"Query"},"genre_category_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Genre category ID, several joined by commas (up to 50, OR).","title":"Genre Category Id"},"brand_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Brand ID, several joined by commas (up to 50, OR).","title":"Brand Id"},"seller_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Store ID, several joined by commas (up to 50, OR).","title":"Seller Id"},"price_from":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Lowest price in yen.","title":"Price From"},"price_to":{"anyOf":[{"maximum":100000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Highest price in yen.","title":"Price To"},"delivery":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for free-shipping items only.","title":"Delivery"},"offset":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Rank to start from (1 for the first).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many ranks to return (1 to 100, default 20).","title":"Limit"}},"title":"get_high_rating_trend_rankingArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}