{
  "openapi": "3.0.1",
  "info": {
    "title": "Naver Shopping Scraper & Keyword Rank Tracker (네이버 쇼핑 순위)",
    "description": "Enter Naver Shopping keywords and get ranked Plus Store products (tested to rank 1,000) for 6 sort orders, with rank change, price, discount, store, rating, reviews and stock. Optionally add reviews, seller prices and Q&A for the top products in the same run. No login.",
    "version": "0.5",
    "x-build-id": "EaMnWUTWrluLrBkzy"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/magenta_courser~naver-shopping-rank-tracker/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-magenta_courser-naver-shopping-rank-tracker",
        "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/magenta_courser~naver-shopping-rank-tracker/runs": {
      "post": {
        "operationId": "runs-sync-magenta_courser-naver-shopping-rank-tracker",
        "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/magenta_courser~naver-shopping-rank-tracker/run-sync": {
      "post": {
        "operationId": "run-sync-magenta_courser-naver-shopping-rank-tracker",
        "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": "Keywords",
            "type": "array",
            "description": "Search keywords (required unless you use \"Search links with filters\") to check on Naver Shopping (search.shopping.naver.com), one per line, typed as a Korean shopper would. You can also paste a Naver Shopping search URL; its query is used. Examples: 무선 이어폰 (wireless earbuds), 강아지 사료 (dog food), 선크림 (sunscreen). Each keyword is searched once per sort order in the Naver Plus Store product list (Smart Store and Brand Store products; no ads, no external malls).",
            "items": {
              "type": "string"
            }
          },
          "sorts": {
            "title": "Sort orders",
            "type": "array",
            "description": "Optional. Sort orders to check; default [\"REL\"]. Each keyword is searched once per sort order and every row has a \"sort\" field. REL = Naver ranking (the default order shoppers see), PURCHASE = most purchased, REVIEW = most reviews, LOW_PRICE = lowest price, HIGH_PRICE = highest price, RECENT = newest. Ranks are organic only (no ads). LOW_PRICE, HIGH_PRICE and REVIEW are checked against prices and review counts; a page that is not in that order is retried and, if it stays wrong, the search fails without charge. PURCHASE and RECENT cannot be checked from the data; if page 1 matches the default order the search is kept and marked sortCheck = sameAsDefault.",
            "items": {
              "type": "string",
              "enum": [
                "REL",
                "PURCHASE",
                "REVIEW",
                "LOW_PRICE",
                "HIGH_PRICE",
                "RECENT"
              ],
              "enumTitles": [
                "Naver ranking (default)",
                "Most purchased",
                "Most reviews",
                "Lowest price",
                "Highest price",
                "Newest"
              ]
            },
            "default": [
              "REL"
            ]
          },
          "maxRank": {
            "title": "Max rank",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Optional. How deep to scan each keyword and sort order: products ranked 1 to maxRank are returned, 100 per request. Default 100. We have tested full scans up to rank 1,000; Naver's list stops at rank 10,000, which is the maximum accepted here, but scans deeper than 1,000 have not been tested end to end. You are charged per product row, so maxRank is also your row count per keyword and sort order: 3 keywords x 2 sorts x maxRank 100 = up to 600 charged rows.",
            "default": 100
          },
          "myProductIds": {
            "title": "My product IDs (optional)",
            "type": "array",
            "description": "Optional. Your products to track, one per line: Naver Shopping product ID (nvMid), Smart Store product number, or a product URL. Examples: 13103686932, 90648198024, https://smartstore.naver.com/yourstore/products/13103686932. For each keyword and sort order you get one free row (type = myProductSummary) with the rank, price and price gap to the #1 product. The row also has previousRank, droppedOut (it had a rank in the last run and is no longer within the scanned ranks) and isRankDropAlert. found = false means the product was not within the ranksScanned ranks of a completed search; found = null means the search did not finish (see searchStatus and stopReason), so absence is unknown.",
            "items": {
              "type": "string"
            }
          },
          "myStoreNames": {
            "title": "My store names (optional)",
            "type": "array",
            "description": "Optional. Stores to track, one per line: store name as shown on Naver, Smart Store URL, or the store ID from that URL (spaces and letter case are ignored). Examples: 필립스 오디오 공식몰 (Philips Audio official store), philipsav_official, https://smartstore.naver.com/philipsav_official. For each keyword and sort order you get one free row (type = myStoreSummary) with the store's best rank, average rank and how many of its products are within the scanned ranks. found follows the same rules as for products.",
            "items": {
              "type": "string"
            }
          },
          "compareWithLastRun": {
            "title": "Compare with last run",
            "type": "boolean",
            "description": "Add previousRank, rankChange (positive = moved up) and isNewEntry to each product, compared with the last completed run of the same keyword and sort order. The previous ranks are kept in a named key-value store in your account, so scheduled daily runs line up automatically.",
            "default": true
          },
          "outputMode": {
            "title": "Output",
            "enum": [
              "all",
              "changesOnly"
            ],
            "type": "string",
            "description": "\"changesOnly\" saves (and charges) only products that are new in the ranks or whose rank, price, stock (sold out / back in stock) or review count changed since the last completed run of the same keyword and sort order. The first run has nothing to compare with, so it saves everything. Needs \"Compare with last run\".",
            "default": "all"
          },
          "historyStoreName": {
            "title": "History store name",
            "type": "string",
            "description": "Named key-value store that keeps the last ranks per keyword and sort order. Use a different name for each separate tracking project.",
            "default": "naver-shopping-rank-history"
          },
          "rankDropAlertThreshold": {
            "title": "Rank drop alert threshold",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Optional. Flags a product whose rank fell by this many places or more since the last completed run of the same keyword and sort order: isRankDropAlert = true on its row. Default 10; 0 turns the flag off. For products listed in \"My product IDs\" the drops are also collected in RUN_SUMMARY.alerts (type = rank_drop), together with products that left the scanned ranks (type = dropped_out, droppedOut = true on the free summary row). Alerts never add charged rows. Needs \"Compare with last run\".",
            "default": 10
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Keep the default: Apify residential proxy, country KR (South Korea). Naver Shopping blocks many data-center IPs. Change it only if you have your own Korean residential proxies.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ],
              "apifyProxyCountry": "KR"
            }
          },
          "minPrice": {
            "title": "Minimum price (KRW)",
            "minimum": 0,
            "type": "integer",
            "description": "Optional. Keep only products whose price (after discount, field \"price\") is at or above this amount in Korean won. Applied to the products read within \"Max rank\"; rank stays the real position in Naver's list. Products outside the range are not saved and not charged."
          },
          "maxPrice": {
            "title": "Maximum price (KRW)",
            "minimum": 0,
            "type": "integer",
            "description": "Optional. Keep only products whose price (after discount) is at or below this amount in Korean won. Example: minPrice 10000 and maxPrice 30000 keeps products from 10,000 to 30,000 won. Tip: with sorts = [\"LOW_PRICE\"] the list itself starts at the cheapest products."
          },
          "filters": {
            "title": "Quick filters",
            "type": "array",
            "description": "Optional. Keep only products that match every selected filter, decided from the fields of each row: FREE_SHIPPING (isFreeShipping), FREE_RETURN (isFreeReturn), TODAY_DISPATCH (isTodayDelivery), ARRIVAL_GUARANTEE (N delivery, isArrivalGuarantee), OFFICIAL_STORE (isOfficialStore), BRAND_STORE (isBrandStore), RATING_4_8 (rating 4.8 or higher), IN_STOCK (not sold out), ONLY_OVERSEAS / EXCLUDE_OVERSEAS, ONLY_SECONDHAND / EXCLUDE_SECONDHAND.",
            "items": {
              "type": "string",
              "enum": [
                "FREE_SHIPPING",
                "FREE_RETURN",
                "TODAY_DISPATCH",
                "ARRIVAL_GUARANTEE",
                "OFFICIAL_STORE",
                "BRAND_STORE",
                "RATING_4_8",
                "IN_STOCK",
                "ONLY_OVERSEAS",
                "EXCLUDE_OVERSEAS",
                "ONLY_SECONDHAND",
                "EXCLUDE_SECONDHAND"
              ],
              "enumTitles": [
                "Free shipping",
                "Free returns",
                "Ships today",
                "Arrival guarantee (N delivery)",
                "Official or certified store",
                "Brand store",
                "Rating 4.8 or higher",
                "In stock",
                "Only overseas products",
                "No overseas products",
                "Only used products",
                "No used products"
              ]
            }
          },
          "categoryIds": {
            "title": "Category IDs",
            "type": "array",
            "description": "Optional. Keep only products in these Naver Shopping categories, one ID per line. Any level works: every product row has its category IDs in \"categoryPath\" (e.g. 50000002>50000191>50000445) and the name of the deepest one in \"categoryName\", so run once without this filter to find the IDs. Example: 50000445 (sunscreen).",
            "items": {
              "type": "string"
            }
          },
          "onlyStores": {
            "title": "Only these stores",
            "type": "array",
            "description": "Optional. Keep only products sold by these stores, one per line: store name as shown on Naver, Smart Store URL, or the store ID from that URL (spaces and letter case are ignored). Example: philipsav_official. To get a free one-row rank summary for a store instead, use \"My store names\".",
            "items": {
              "type": "string"
            }
          },
          "searchUrls": {
            "title": "Search links with filters",
            "type": "array",
            "description": "Optional. For filters that only exist on the Naver website (brand, specs, style, features): search on https://search.shopping.naver.com/ns/search, tick the filters, copy the address bar and paste it here, one link per line. Example: https://search.shopping.naver.com/ns/search?query=치마&brandIds=1339 (skirts of one brand). The filter parameters of the link are sent to Naver unchanged, so ranks are positions in that filtered list, and each link is tracked separately from the plain keyword (field \"searchFilters\"). The link's own sort and page are ignored; use \"Sort orders\" and \"Max rank\". A link without filters is treated as its keyword.",
            "items": {
              "type": "string"
            }
          },
          "extrasTopProducts": {
            "title": "Products per search that get extras",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Optional. Only used when at least one extra below is on. The top N products of each keyword and sort order get the extras; products in \"My product IDs\" found in the ranks come first. A product reached by several searches gets its extras once. Default 10, maximum 100.",
            "default": 10
          },
          "includeSellerOffers": {
            "title": "Include seller offers (price comparison)",
            "type": "boolean",
            "description": "For products matched to a Naver price-comparison catalog (catalogId is set): one row per competing offer (type = sellerOffer), cheapest first with shipping included: offerPrice, offerShippingFee, offerPriceWithShipping, offerStoreName, offerRating, offerReviewCount, offerStockQuantity, offerIsCatalogWinner, offerUrl. Lists Naver stores (Smart Store and Brand Store) only; offers of other malls such as Coupang or 11st are not included. Products without a catalog get no offer rows.",
            "default": false
          },
          "maxOffersPerProduct": {
            "title": "Max offers per product",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Optional. Offers saved per product when \"Include seller offers\" is on, cheapest first. Default 20, maximum 200.",
            "default": 20
          },
          "includeReviewStats": {
            "title": "Include review score breakdown",
            "type": "boolean",
            "description": "One row per product (type = reviewStats): reviewCount, rating, score1Count to score5Count (reviews at 1 to 5 stars), textReviewCount, photoReviewCount, videoReviewCount, afterMonthUseReviewCount, bestReviewCount, recentReviewCount, recentRating and reviewEvaluations (how reviewers answered Naver's questions for this kind of product, e.g. \"사이즈: 작아요 5% · 잘 맞아요 81% · 커요 14%\").",
            "default": false
          },
          "includeReviews": {
            "title": "Include reviews",
            "type": "boolean",
            "description": "One row per review (type = review): reviewRating (1 to 5), reviewText, reviewDate, purchasedOption, mediaCount, hasImages, hasVideos, imageUrls, reviewStoreName, reviewPosition, reviewsTotal. Reviewer names, IDs and profile images are never collected; mobile numbers and e-mail addresses typed into a review are masked.",
            "default": false
          },
          "reviewSource": {
            "title": "Review source",
            "enum": [
              "STORE",
              "CATALOG"
            ],
            "type": "string",
            "description": "STORE (default): reviews of the ranked product itself, the first 40 of the chosen order; with imageUrls holding one representative photo per review. CATALOG: reviews Naver shows on the price-comparison page, from all Naver stores selling that catalog product, with every photo; only for products with a catalogId, and collected once per catalog.",
            "default": "STORE"
          },
          "reviewSort": {
            "title": "Review order",
            "enum": [
              "RANKING",
              "RECENT",
              "HIGH_RATING",
              "LOW_RATING"
            ],
            "type": "string",
            "description": "Order of the reviews. RECENT, HIGH_RATING and LOW_RATING are checked against the returned dates and ratings (reviewSortVerified); reviews that come back in another order are not saved or charged. CATALOG supports RANKING and RECENT.",
            "default": "RANKING"
          },
          "maxReviewsPerProduct": {
            "title": "Max reviews per product",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Optional. Reviews saved per product when \"Include reviews\" is on. Default 20. STORE: up to 40 (Naver serves the first 40 of an order without login). CATALOG: up to 500.",
            "default": 20
          },
          "includeQna": {
            "title": "Include product Q&A",
            "type": "boolean",
            "description": "One row per public product question (type = qna), newest first: questionText, questionDate, isAnswered, answerText (the seller's replies), answerDate, answerCount, qnaTotal. Secret questions are skipped. Asker IDs are never collected; mobile numbers and e-mail addresses in the text are masked.",
            "default": false
          },
          "maxQnaPerProduct": {
            "title": "Max questions per product",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Optional. Questions saved per product when \"Include product Q&A\" is on. Default 10, maximum 100. Each answered question needs one more request for its answer.",
            "default": 10
          },
          "maxRequests": {
            "title": "Max requests per run",
            "minimum": 1,
            "maximum": 1000000,
            "type": "integer",
            "description": "Optional. Upper limit on HTTP requests for the whole run, retries included. Default: 2 per 100 ranks per search + 5. When it is used up, the run stops, keeps what it saved and marks unfinished searches as budgetLimited or notStarted in RUN_SUMMARY."
          },
          "maxRunMinutes": {
            "title": "Max run time (minutes)",
            "minimum": 1,
            "maximum": 1440,
            "type": "integer",
            "description": "Optional. The run stops sending new requests after this many minutes, default 60, and keeps what it saved. Independent of this, the run also stops after 10 blocked requests in a row (stopReason = blocked) instead of retrying every remaining page."
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}