{ "openapi": "3.0.1", "info": { "title": "Mercari Japan Scraper – Listings & Item Details", "description": "Scrape Mercari Japan listings, sold prices and item details. Search many keywords or paste Mercari URLs; filter by brand, category, condition and shipping; exclude keywords; pick individual sellers or Mercari Shops; enrich with descriptions, photos, seller ratings and shipping. Read-only, MCP-ready.", "version": "0.0", "x-build-id": "MvuyOIPGl4CZ8nykm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datalab-jp~mercari-japan-listings-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datalab-jp-mercari-japan-listings-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/datalab-jp~mercari-japan-listings-scraper/runs": { "post": { "operationId": "runs-sync-datalab-jp-mercari-japan-listings-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/datalab-jp~mercari-japan-listings-scraper/run-sync": { "post": { "operationId": "run-sync-datalab-jp-mercari-japan-listings-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "keywords": { "title": "Search keywords", "type": "array", "description": "One or more search terms for Mercari Japan, each run as its own search, e.g. ['ポケモンカード'] or ['ガンプラ', 'Nintendo Switch']. Japanese terms match the most listings because titles are Japanese; English brand/model names usually work, and a few known Chinese terms are retried in Japanese when they return nothing. If omitted with no `startUrls`, a health-check search for 'ポケモンカード' runs. Each keyword is capped by `maxItems`, the run by `maxTotalItems`; duplicates across keywords are returned once.", "default": [ "ポケモンカード" ], "items": { "type": "string" } }, "status": { "title": "Listing status", "uniqueItems": true, "type": "array", "description": "Which listing states to include; pick one or more of 'on_sale' (currently for sale — sourcing and stock checks), 'sold_out' (completed sales, i.e. real transaction prices for comps research) and 'trading' (bought, transaction not yet finished). Defaults to ['on_sale'] when omitted. An empty list is rejected. To get every state, pass all three values; 'sold_out' does not silently include 'trading'.", "items": { "type": "string", "enum": [ "on_sale", "sold_out", "trading" ], "enumTitles": [ "On sale", "Sold (price research)", "Trading (sale in progress)" ] }, "default": [ "on_sale" ] }, "maxItems": { "title": "Max items per keyword / URL", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum listings returned for each keyword or search URL, e.g. 100 for a quick look or 2000 for a full sweep. Each returned listing is one billable result, so together with `maxTotalItems` this is your main cost control. Defaults to 100 when omitted; accepts 1–5000 (Mercari never exposes more than 15,000 matches per search). Pagination stops as soon as the cap or the end of results is reached.", "default": 100 }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Mercari Japan URLs, mixed freely: a search URL like 'https://jp.mercari.com/search?keyword=ガンプラ&status=on_sale' (its filters apply), an item URL 'https://jp.mercari.com/item/m12345678901' (that listing with full details), or a Shops URL 'https://jp.mercari.com/shops/product/…'. Only jp.mercari.com / www.mercari.com are accepted; others are skipped and listed in SEARCH_REPORT. Leave empty to use `keywords` only. Item and Shops URLs always fetch details (billed as item-detail).", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "excludeKeywords": { "title": "Exclude keywords", "type": "array", "description": "Words that must NOT appear in the listing title, e.g. ['まとめ売り', 'ジャンク'] to drop bulk lots and junk items, or ['ケース'] to drop accessories. Applied by Mercari's own search engine, so the excluded listings never count toward `maxItems`. Leave empty to exclude nothing. Multiple words are combined: a listing is removed if it contains any of them.", "default": [], "items": { "type": "string" } }, "sellerType": { "title": "Seller type", "enum": [ "all", "individual", "shop" ], "type": "string", "description": "Restrict results to individual sellers or Mercari Shops (business storefronts), e.g. 'individual' to source second-hand goods from private sellers or 'shop' to see only professional shop stock. Defaults to 'all' when omitted. The output column `sellerType` tells you which kind each row is; Shops rows link to /shops/product/ URLs and are enriched through the Shops API when details are requested.", "default": "all" }, "categoryId": { "title": "Category IDs", "type": "array", "description": "Mercari numeric category IDs to restrict the search, e.g. [1289] for ポケモンカードゲーム or [82] for all トレーディングカード. Find the ID in the `category_id` parameter of a Mercari search URL after choosing a category on the website, or in the `categoryId` column of a previous run. Leave empty to search all categories. Multiple IDs are OR-ed.", "default": [] }, "brandId": { "title": "Brand IDs", "type": "array", "description": "Mercari numeric brand IDs, e.g. the `brand_id` value from a Mercari search URL after picking a brand filter on the website. Useful for sourcing one brand across many product names. Leave empty for no brand filter. Multiple IDs are OR-ed; the matched brand is returned in `brandId` / `brandName`.", "default": [] }, "itemConditionId": { "title": "Item condition IDs", "type": "array", "description": "Condition grades to include, using Mercari's scale 1–6: 1 = 新品、未使用 (new, unused), 2 = 未使用に近い (like new), 3 = 目立った傷や汚れなし (no noticeable damage), 4 = やや傷や汚れあり (some wear), 5 = 傷や汚れあり (worn), 6 = 全体的に状態が悪い (poor). Example: [1, 2] for near-new stock only. Leave empty to include every condition. The grade of each row is returned in `condition` / `conditionId`.", "default": [] }, "shippingPayerId": { "title": "Shipping paid by", "type": "array", "description": "Who pays domestic shipping: 2 = seller (送料込み, price is all-in within Japan) or 1 = buyer (着払い). Example: [2] to compare only all-in prices. Leave empty to include both. The result is also exposed per row as `shippingPayer` and `shippingIncluded`; note this covers Japanese domestic shipping only, not international forwarding.", "default": [] }, "priceMin": { "title": "Minimum price (JPY)", "type": "integer", "description": "Lower price bound in Japanese yen, e.g. 1000 to skip cheap accessories or 30000 for high-value items only. Whole yen, no currency symbol. Leave empty for no minimum. Works together with `priceMax`; the pair must satisfy priceMin ≤ priceMax." }, "priceMax": { "title": "Maximum price (JPY)", "type": "integer", "description": "Upper price bound in Japanese yen, e.g. 5000 for budget items or 100000 to exclude outliers. Whole yen, no currency symbol. Leave empty for no maximum. Works together with `priceMin`." }, "sortBy": { "title": "Sort by", "enum": [ "score", "created", "priceHigh", "priceLow", "likes" ], "type": "string", "description": "Result order, mirroring the Mercari website: 'score' (Mercari relevance, default), 'created' (most recently listed first — use this for new-listing monitors), 'priceHigh', 'priceLow', or 'likes' (most liked first). Defaults to 'score' when omitted. Note that 'created' is ordered by `updatedAt`, because sellers can bump an old listing back to the top; a scheduled monitor should track the highest `updatedAt` it has seen.", "default": "score" }, "fetchItemDetails": { "title": "Fetch item details", "type": "boolean", "description": "When true, every listing is enriched from its item page: full description, original-size photos, seller name and rating breakdown, shipping method, origin and lead time, likes, comments and full category path. Defaults to false (listing-level fields only) — faster and cheaper. Each successfully enriched row is billed as one item-detail event on top of the listing result; rows whose detail page cannot be fetched keep listing-level fields and are not billed. Item/Shops URLs are always enriched.", "default": false }, "autoRetryKeywordMapping": { "title": "Retry zero-result Chinese keywords in Japanese", "type": "boolean", "description": "When true (default), a keyword that returns zero listings and appears in a small, verified alias table (e.g. 宝可梦 → ポケモン, 高达 → ガンダム, 海贼王 → ONE PIECE) is retried once with its Japanese equivalent; the term actually used is returned in `keywordUsed` and `keywordMapped` is set to true. The original keyword is always tried first, and the alias is used only when the original returned nothing. Set to false to disable the retry and get the plain zero result with a hint in SEARCH_REPORT.", "default": true }, "maxTotalItems": { "title": "Max items for the whole run", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Hard cap on listings returned by the entire run, across all keywords and URLs, e.g. 500 for a bounded scheduled job or 10000 for a bulk export. Protects against runaway cost when many keywords are supplied. Defaults to 1000 when omitted; accepts 1–50000. When the cap is hit the run stops paginating and notes `totalLimitReached: true` in SEARCH_REPORT.", "default": 1000 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy settings. By default the Actor connects directly (no proxy): measured on 2026-09-09, Mercari's APIs answered 450 listings in 12.6 s with zero errors this way, at about a quarter of the cost of a residential proxy. If direct access is ever blocked, enable Apify Proxy here; with no group chosen the Actor uses Japan-based residential IPs (RESIDENTIAL, country JP), the configuration known to work. Residential traffic is billed per GB by Apify.", "default": { "useApifyProxy": false } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }