Shopee Scraper

Scrape Shopee Web searches, products, ratings, shops, categories, and recommendations without maintaining browser sessions, anti-bot headers, signatures, cookies, or human-interaction behavior.

The Actor accepts Shopee Web page URLs and backend API URLs. Each request is processed independently and produces one row in the default dataset.

Quick start

{
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/search/search_items?keyword=tshirt"
    }
  ]
}

A run accepts 1 to 100 requests. The Actor waits for every request to reach a terminal state before publishing results and charging finalized events.

Input

Shared options are applied to every request. A value inside an individual request overrides the shared value for that request.

• requests - Required array containing 1 to 100 Shopee Web requests.
• language - Optional Shopee language header and cookie.
• userData.referrer - Optional HTTP referrer.
• userData.language - Optional request-specific language.
• enrichUrlQuery - Add required Shopee query parameters. Default: true.
• generateReferrer - Generate a realistic referrer. Default: true.
• emulateMobileDevice - Emulate mobile web traffic. Default: false.

Per-request fields:

• url - Required Shopee Web page or backend API URL.
• method - GET or POST. Default: GET.
• payload - JSON body for supported POST APIs.
• Any shared option above - Overrides that option for this request.

Unknown request options are passed to Charted Sea for forward compatibility. Shopee Android mall.shopee.* URLs are not supported by this Web Actor.

Supported Shopee Web APIs

Product Search by Keyword or Category

• URL Path:

  • /api/v4/search/search_items

• URL Parameters:

  • keyword: Search keyword, e.g., "tshirt".
  • match_id: Category ID from /api/v4/pages/get_category_tree.
  • categoryids: Comma-separated list of category IDs.
  • fe_categoryids: Comma-separated list of FE category IDs.
  • brandids: Comma-separated list of FE categorybrand IDs.

    Note: keyword, match_id, categoryids, fe_categoryids and brandids are mutually exclusive.

  • by (default = "relevancy"): Sort by "relevancy", "ctime", "sales", or "price".
  • order (default = "desc"): Sort order, "asc" or "desc".
  • limit (default = set by scraper): Number of results per page.
  • newest (default = 0): Offset for results, typically a multiple of limit.
  • page_type, scenario, version: Additional parameters with default settings.
  • extra_params, view_session_id: Automatically generated, unless overridden.

• Scraper Input Parameters

  • productSearch_enrichUrlQuery_pageSize: Number of results per request (default: 60).
  • productSearch_crawlNextPages: Set to true to crawl subsequent pages.
  • productSearch_crawlNextPages_maxPages: Limit on number of pages to crawl (default: 50).
  • productSearch_crawlNextPages_maxResults: Maximum products to crawl (default: 3000).
  • productSearch_crawlProductDetails: Set to true to crawl details of each product.

• Example Input:

{
  "requests": [
    // Search products with the "tshirt" keyword
    { "url": "https://shopee.sg/api/v4/search/search_items?keyword=tshirt" },
    
    // Search products in the category ID 11027421
    // Note: Shopee uses /api/v4/recommend/recommend_v2 for the category page now
    { "url": "https://shopee.sg/api/v4/search/search_items?match_id=11027421&scenario=PAGE_CATEGORY" },
    
    // Search products from the shop ID 290739469 (scenario PAGE_SHOP_SEARCH)
    { "url": "https://shopee.sg/api/v4/search/search_items?entry_point=ShopByPDP&match_id=290739469&page_type=shop&scenario=PAGE_SHOP_SEARCH" },
    
    // Search products from the shop ID 290739469 (scenario PAGE_SHOP)
    { "url": "https://shopee.sg/api/v4/search/search_items?match_id=290739469&page_type=shop&scenario=PAGE_SHOP" },
    
    // Search products from the brand ID 4508220
    { "url": "https://shopee.sg/api/v4/search/search_items?brandids=4508220&scenario=PAGE_OTHERS" }
  ],

  // Set the "limit" URL parameter to 60
  "productSearch_enrichUrlQuery_pageSize": 60,
  // Automatically crawl the next pages
  "productSearch_crawlNextPages": true,
  // Crawl until the 3rd page
  "productSearch_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of products to crawl
  "productSearch_crawlNextPages_maxResults": 180,
  // Automatically crawl the detail of each listed product
  "productSearch_crawlProductDetails": true
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • items: Array of product summaries.
  • items/itemid and items/shopid: Essential for scraping product details and ratings.
  • items/item_basic/name: Product name.
  • items/item_basic/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}, for example the URL to download the image "sg-11134201-7qvez-lgj50bviqvph8b" is "https://down-sg.img.susercontent.com/file/sg-11134201-7qvez-lgj50bviqvph8b".
  • items/item_basic/ctime: Creation timestamp.
  • items/item_basic/sold: Monthly sales.
  • items/item_basic/historical_sold: Total sales.
  • items/item_basic/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Product Listing API still provides these fields.

Similarly, access to multiple pages is not available anymore for keyword search in non-authenticated mode. Fortunately, the Android Product Search by Keyword or Category API still provides multiple pages.

Product Listing V2

• Request Method:

  • POST

• URL Path:

  • /api/v4/microsite/batch_get_item_card

• Request Body:

{
  "shop_item_ids": [
    {
      "item_id": 40505798777,
      "shop_id": 1521408445
    },
    // ...
  ]
}

The shop_item_ids is an array containing a list of item_id (product identifier) and shop_id (product owner identifier).

• Example Input:

{
  // List 5 products via their identifiers
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/microsite/batch_get_item_card",
      "method": "POST",
      "payload": {
        "shop_item_ids": [
          {
            "item_id": 40505798777,
            "shop_id": 1521408445
          },
          {
            "item_id": 40905798740,
            "shop_id": 1521408445
          },
          {
            "item_id": 42105798857,
            "shop_id": 1521408445
          },
          {
            "item_id": 43005798827,
            "shop_id": 1521408445
          },
          {
            "item_id": 27937932620,
            "shop_id": 1521408445
          }
        ]
      }
    }
  ]
}

• Example Response:

  • View example response

• Notable Response Fields:

  • data/item_cards: Array of product summaries.
  • data/item_cards/item_data/itemid and items/shopid: Essential for scraping product details and ratings.
  • data/item_cards/item_card_displayed_asset/name: Product name.
  • data/item_cards/item_card_displayed_asset/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}, for example the URL to download the image "sg-11134201-7qvez-lgj50bviqvph8b" is "https://down-sg.img.susercontent.com/file/sg-11134201-7qvez-lgj50bviqvph8b".
  • data/item_cards/item_data/ctime: Creation timestamp.
  • data/item_cards/item_data/item_card_display_price/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Product Listing API still provides these fields.

Product Details

• URL Path:

  • /api/v4/pdp/get_pc

• URL Parameters:

  • shop_id: The unique identifier of the shop.
  • item_id: The unique identifier of the product.

Note: Consider Cart Panel Item Detail as an alternative if success rate is too low.

• Scraper Input Parameters

  • productDetail_crawlProductRatings: Define the types of product ratings to crawl. Options include "ALL", "ONE_STAR", "TWO_STARS" to "FIVE_STARS", "WITH_COMMENTS", "WITH_MEDIA", "LOCAL_REVIEWS". Combine multiple values for a broader range, e.g., ["ONE_STAR", "TWO_STARS"].

  • productDetail_mode (optional): Controls how the product detail is retrieved and potentially corrected. Possible values:

    • "NORMAL" (default) - Simply scrapes /api/v4/pdp/get_pc and returns the raw response.

    • "AUGMENTED_WITH_VARIATIONS" - Scrapes both /api/v4/pdp/get_pc and one /api/v4/pdp/cart_panel/select_variation_pc request per product variant. The full /get_pc response is returned with an additional additionalResponses field containing the variation API responses.

    • "CORRECTED_WITH_VARIATIONS" - Same as AUGMENTED_WITH_VARIATIONS, but the /get_pc response is corrected using /select_variation_pc responses. This is useful when Shopee returns fake prices.

    • "FROM_CACHE_AND_CORRECTED" - Bypasses /get_pc entirely. The response is reconstructed from cached product data embedded in the product page and corrected using /select_variation_pc responses. This mode is particularly efficient and has a higher success rate when Shopee's anti-bot defenses are stricter.

      Info: Limitations of this mode:

      • Variant prices are unknown for out-of-stock items.
      • Variant stock behaves the same as in /get_pc (i.e., stock = 0 for out-of-stock, null otherwise).
      • Ratings are delayed (up to 24h behind real-time).

  productDetail_outOfStockPriceCorrectionStrategy (optional): Defines how to handle prices for out-of-stock variants in modes where price correction is applied (e.g. FROM_CACHE_AND_CORRECTED, CORRECTED_WITH_VARIATIONS). Options:

  • "SET_NULL" (default) - Sets the price of out-of-stock variants to null.
  • "SET_PRODUCT_PRICE" - Sets the variant price to the top-level product price.

Consider using "productDetail_mode": "FROM_CACHE_AND_CORRECTED" as a reliable fallback during periods of lower success rates.

• Example Input:

{
  // Get the details of a product
  "requests": [
    { "url": "https://shopee.sg/api/v4/pdp/get_pc?shop_id=414243778&item_id=23600133176" }
  ],
  
  // Automatically crawl ratings of any stars
  "productDetail_crawlProductRatings": ["ALL"],

  // Set the rating "limit" URL parameter to 50
  "productRatings_enrichUrlQuery_pageSize": 50,
  // Automatically crawl the next rating pages
  "productRatings_crawlNextPages": true,
  // Crawl until the 3rd rating page
  "productRatings_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of ratings to crawl
  "productRatings_crawlNextPages_maxResults": 150,
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/item/item_id and data/item/shop_id: Essential identifiers for the product and shop.
  • data/item/title: Product name.
  • data/item/description: Product description.
  • data/item/image: Image key. Convert to URL using the provided format: https://down-${country}.img.susercontent.com/file/${imageKey}.
  • data/item/ctime: Product creation timestamp.
  • data/item/fe_categories: Category information including parent categories.
  • data/item/models: Detailed SKU information.
  • data/product_review: Aggregated rating statistics.
  • data/product_shipping: Shipping details.
  • data/shop_detailed: Comprehensive shop details including name, username (slug), and image.

• Additional Notes:

  • When fake prices are detected in the Shopee response, a field diagnostic is added to the response with the content:

    {
        "fakePriceDetected": true
    }
    

  • When using any of the modes AUGMENTED_WITH_VARIATIONS, CORRECTED_WITH_VARIATIONS, or FROM_CACHE_AND_CORRECTED, a new response field additionalResponses is added. It contains the full list of /api/v4/pdp/cart_panel/select_variation_pc requests and responses used to augment or correct the result.

  • Although non-NORMAL modes may involve multiple internal requests (one per product variant), users are charged the same as for the NORMAL mode. Requests to /api/v4/pdp/cart_panel/select_variation_pc are considered auxiliary and are not billed separately.

Cart Panel Item Detail (web)

• Request Method:

  • POST

• URL Path:

  • /api/v4/cart/cart_panel/get_rw

• Request Body:

{
  "item_id": 23600133176, 
  "shop_id": 414243778
}

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/cart/cart_panel/get_rw",
      "method": "POST",
      "payload": {"item_id": 23600133176, "shop_id": 414243778}
    }
  ]
}

• Example Response:

  • View example response

• Notable Response Fields:

  • data/item/item_id and data/item/shop_id: Essential identifiers for the product and shop.
  • data/item/title: Product name.
  • data/item/image: Image key. Convert to URL using the provided format: https://down-${country}.img.susercontent.com/file/${imageKey}.
  • data/item/models: Detailed SKU information.
  • data/item/models/stock: SKU stock level.
  • data/item/stock: Product stock level.

Note: Responses containing error codes matching 14696xxxxx are not scraping failures: they indicate the product doesn't exist, is sold out, or has been unlisted. If in doubt, you can call the /api/v4/microsite/batch_get_item_card API to confirm the product status.

Product Ratings

• URL Path:

  • /api/v2/item/get_ratings

• URL Parameters:

  • shopid & itemid: Unique identifiers for the shop and product.
  • limit (default = set by scraper): Number of results per page.
  • offset (default = 0): Offset for results, typically a multiple of limit.
  • type (default = 0, max = 5): Filter by number of stars (e.g. 2 = 2-stars ratings only). 0 = all ratings.
  • filter (default = 0): Filter by content: 1 = with comments, 3 = with media, 9 = local ratings, 0 = all ratings.
  • exclude_filter, filter_size, flag, fold_filter, relevant_reviews, request_source, tag_filter, variation_filters: Additional parameters with default settings.

• Scraper Input Parameters

  • productRatings_enrichUrlQuery_pageSize: Number of results per request (default: 6).
  • productRatings_crawlNextPages: Set to true to crawl subsequent pages.
  • productRatings_crawlNextPages_maxPages: Limit on number of pages to crawl (default: 500).
  • productRatings_crawlNextPages_maxResults: Maximum products to crawl (default: 3000).
  • productRatings_autofixError10002: Automatically corrects error 10002 by splitting requests (default: true).

• Example Input:

{
  // Get the ratings of a product
  "requests": [
    { "url": "https://shopee.sg/api/v2/item/get_ratings?shopid=414243778&itemid=23600133176" }
  ],

  // Set the rating "limit" URL parameter to 50
  "productRatings_enrichUrlQuery_pageSize": 50,
  // Automatically crawl the next rating pages
  "productRatings_crawlNextPages": true,
  // Crawl until the 3rd rating page
  "productRatings_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of ratings to crawl
  "productRatings_crawlNextPages_maxResults": 150,
  // Automatically fix the error 10002
  "productRatings_autofixError10002": true,
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/ratings/cmtid: Unique identifier for each rating.
  • data/ratings/ctime: Timestamp of the rating.
  • data/ratings/rating_star: Star rating from 1 to 5.
  • data/ratings/comment: Buyer's comment.
  • data/ratings/author_username: Buyer's username (sometimes anonymized).
  • data/ratings/author_portrait: Buyer's profile image.
  • data/ratings/images & videos: Media associated with the rating.
  • data/ratings/product_items: SKU details of the rated product.

Data Privacy Note: Always be mindful of buyers' personal information and comply with local data protection laws. Avoid storing personal data unless necessary.

Product Select Variation

This API is invoked when the user selects a variant/SKU on a product page.

• URL Path:

  • /api/v4/pdp/cart_panel/select_variation_pc
  • Or /api/v4/pdp/cart_panel/select_variation_rw
  • Or /api/v4/pdp/get/select_variation_rw

• Request Body Parameters:

  • shop_id: The unique identifier of the shop.
  • item_id: The unique identifier of the product.
  • selected_tiers: Object representing the variant indexes (e.g. {"0": 2} for the 3rd product color). You can obtain this parameter from the response of the /api/v4/pdp/get_pc API, in the field data/item/models/0/extinfo/tier_index.
  • quantity (optional, default = 1): Number of selected products.
  • tz_offset_in_minutes (optional, default = depend on the domain): Timezone offset in minutes (e.g. 420 for Asia/Jakarta).

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.co.id/api/v4/pdp/cart_panel/select_variation_pc",
      "method": "POST",
      "payload": {
        "item_id": 24731574651,
        "shop_id": 1269032741,
        "selected_tiers": {
          "0": 1, // 2nd color
          "1": 1 // 2nd size
        }
      }
    }
  ]
}

• Example Response:

  • /api/v4/pdp/cart_panel/select_variation_pc Response
  • /api/v4/pdp/cart_panel/select_variation_rw Response

• Notable Response Fields:

  • data/product_price/price/single_value: Product variant price.
  • data/tier_variation_display_indicators: Variant descriptions.

Batch Product Select Variation

This is not a real Shopee API, but a "batch" scraping task that executes multiple Product Select Variation requests.

Fixed Pricing: A single batch task is billed the same as one Product Details request, regardless of how many variants are queried. This makes cost estimation straightforward: no need to account for the number of variants per product.

• URL Path:

  • /api/v4/pdp/cart_panel/select_variation_pc/batch
  • Or /api/v4/pdp/cart_panel/select_variation_rw/batch
  • Or /api/v4/pdp/get/select_variation_rw/batch

• Request Body Parameters:

  • shop_id: The unique identifier of the shop.

  • item_id: The unique identifier of the product.

  • selected_tiers: Array of objects representing the variant indexes (e.g. [{"0": 0}, {"0": 1}, {"0": 2}]). You can obtain this parameter from the response of the /api/v4/pdp/get_pc API, in the field data/item/models/0/extinfo/tier_index.

    Note: The type of this parameter is the main difference with a non-batch Product Select Variation request.

  • quantity (optional, default = 1): Number of selected products.

  • tz_offset_in_minutes (optional, default = depend on the domain): Timezone offset in minutes (e.g. 420 for Asia/Jakarta).

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.tw/api/v4/pdp/cart_panel/select_variation_pc/batch",
      "method": "POST",
      "payload": {
        "item_id": 21018510657,
        "shop_id": 800684625,
        "selected_tiers": [
          {
            "0": 0
          },
          {
            "0": 1
          },
          {
            "0": 3
          },
          {
            "0": 4
          },
          {
            "0": 5
          },
          {
            "0": 2
          }
        ]
      }
    }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data: Array of sub-tasks.
  • data/0/requestBody/selected_tiers: Product variant index.
  • data/0/responseBody/data/product_price/price/single_value: Product variant price.
  • data/0/responseBody/data/tier_variation_display_indicators: Variant descriptions.

Product Recommendation

• URL Path:

  • POST /api/v4/recommend/product_detail_page

• Request Body Parameters:

  • shopid (optional): Shop identifier.
  • itemid (optional): Product identifier.
  • catid (optional): Category identifier.
  • limit (default = 48): Number of results per page.
  • offset (default = 0): Offset for results, typically a multiple of limit.

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/recommend/product_detail_page",
      "method": "POST",
      "payload": {
        "offset": 0,
        "limit": 48,
        "shopid": 119013379,
        "itemid": 20395639234,
        "catid": 100634
      }
    }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/sections/units: Array of product summaries.
  • data/sections/units/itemid and shopid: Essential for scraping product details and ratings.
  • data/sections/units/name: Product name.
  • data/sections/units/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}, for example the URL to download the image "sg-11134201-7qvez-lgj50bviqvph8b" is "https://down-sg.img.susercontent.com/file/sg-11134201-7qvez-lgj50bviqvph8b".
  • data/sections/units/ctime: Creation timestamp.
  • data/sections/units/sold: Monthly sales.
  • data/sections/units/historical_sold: Total sales.
  • data/sections/units/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Product Listing API still provides these fields.

Product Recommendation (bis)

• URL Path:

  • POST /api/v4/recommend/recommend_post

• Request Body Parameters:

  • shopid (optional): Shop identifier.
  • itemid (optional): Product identifier.
  • catid (optional): Category identifier.
  • limit (default = 25): Number of results per page.
  • offset (optional): Number of skipped results.
  • section, item_card, bundle: Additional parameters with default settings.

Note: This API is called in the "From The Same Shop" section at the bottom of a product page. Shopee usually invokes it with limit=25 and no offset, or with limit=48 and offset=0 (or 48, 96, ...)

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/recommend/recommend_post",
      "method": "POST",
      "payload": {
        "limit": 25,
        "section": "from_same_shop",
        "shopid": 18254273,
        "itemid": 809240155,
        "catid": 100001,
        "item_card": 3,
        "bundle": "product_detail_page_ftss"
      }
    }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/sections[0]/data/item: Product summary.
  • data/sections[0]/data/item/itemid and shopid: Essential for scraping product details and ratings.
  • data/sections[0]/data/item/name: Product name.
  • data/sections[0]/data/item/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}, for example the URL to download the image "sg-11134201-7qvez-lgj50bviqvph8b" is "https://down-sg.img.susercontent.com/file/sg-11134201-7qvez-lgj50bviqvph8b".
  • data/sections[0]/data/item/ctime: Creation timestamp.
  • data/sections[0]/data/item/sold: Monthly sales.
  • data/sections[0]/data/item/historical_sold: Total sales.
  • data/sections[0]/data/item/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Product Listing API still provides these fields.

Product Recommendation V2

• URL Path:

  • POST /api/v4/recommend/recommend_v2

• Request Body Parameters:

  • catid: Category identifier.
  • limit (default = 24): Number of results per page.
  • offset (optional): Number of skipped results.
  • cat_level: Category level (e.g. 3).
  • bundle (optional): Set to "category_landing_page" by default.

Note: This API is called in the category page.

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/recommend/recommend_v2",
      "method": "POST",
      "payload": {
        "catid": 11027421,
        "offset": 0,
        "limit": 60,
        "bundle": "category_landing_page",
        "cat_level": 1
      }
    }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/units[0]/item: Product summary.
  • data/units[0]/item/item_data/itemid and shopid: Essential for scraping product details and ratings.
  • data/units[0]/item/item_card_displayed_asset/name: Product name.
  • data/units[0]/item/item_card_displayed_asset/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}, for example the URL to download the image "sg-11134201-7qvez-lgj50bviqvph8b" is "https://down-sg.img.susercontent.com/file/sg-11134201-7qvez-lgj50bviqvph8b".
  • data/units[0]/item/item_data/ctime: Creation timestamp.
  • data/units[0]/item/item_card_display_sold_count/monthly_sold_count: Monthly sales.
  • data/units[0]/item/item_card_display_sold_count/historical_sold_count: Total sales.
  • data/units[0]/item/item_data/item_card_display_price/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Product Listing API still provides these fields.

Shopee Category Tree

• URL Path:

  • /api/v4/pages/get_category_tree

• Example Input:

{
  // Get the category tree
  "requests": [
    { "url": "https://shopee.sg/api/v4/pages/get_category_tree" }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/category_list/catid: Unique identifier for each category.
  • data/category_list/name: Category name.
  • data/category_list/children: Sub-categories.

Note: This API only provides the two top category levels.

Category Details

• URL Path:

  • /api/v4/search/get_fe_category_detail

• URL Parameters:

  • catids: Unique identifiers for the category.

• Example Input:

{
  // Retrieve details for a specific category
  "requests": [
    { "url": "https://shopee.sg/api/v4/search/get_fe_category_detail?catids=11027710" }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/categories/catid: The unique identifier for the category.
  • data/categories/parent_cat_id: Identifier for the parent category, helping to understand category hierarchy.
  • data/categories/display_name: The category name as displayed in different languages across the platform.

Official Shops

• URL Path:

  • /api/v4/official_shop/get_shops_by_category

• URL Parameters:

  • category_id (default = -1): Specify a category ID to retrieve official shops within that category. Use -1 to list all official shops.
  • need_zhuyin: An additional parameter, typically set to default.

Note: Only shops associated with registered brands are considered "official" on Shopee.

• Example Input:

{
  // Retrieve a list of all official shops
  "requests": [
    { "url": "https://shopee.sg/api/v4/official_shop/get_shops_by_category" }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/brands/brand_ids/shopid: The unique identifier for each official shop.
  • data/brands/brand_ids/brand_name: The name of the brand associated with the shop.
  • data/brands/brand_ids/username: The shop's username or slug, useful for direct queries or referencing.

Shop Search By Keyword

• URL Path:

  • /api/v4/search/search_user

• URL Parameters:

  • keyword (minimum: 3 characters): Enter a search term, such as "adi", to find relevant shops.
  • limit (default = set by scraper): Number of results per page.
  • offset (default = 0): Offset for results, typically a multiple of limit.
  • page, with_search_cover: Additional parameters with default settings.

Note: This API covers all shops on Shopee, both mall and non-mall. Tip: For a comprehensive shop list, consider searching with various trigrams.

• Scraper Input Parameters

  • shopSearch_enrichUrlQuery_pageSize: Number of results per request (default: 6).
  • shopSearch_crawlNextPages: Set to true to crawl subsequent pages.
  • shopSearch_crawlNextPages_maxPages: Limit on number of pages to crawl (default: 500).
  • shopSearch_crawlNextPages_maxResults: Maximum shops to crawl (default: 30000).
  • shopSearch_crawlShopDetails: Set to true to crawl details of each shop.

• Example Input:

{
  // Search shop with the "adi" keyword
  "requests": [
    { "url": "https://shopee.sg/api/v4/search/search_user?keyword=adi" }
  ],

  // Set the "limit" URL parameter to 50
  "shopSearch_enrichUrlQuery_pageSize": 50,
  // Automatically crawl the next pages
  "shopSearch_crawlNextPages": true,
  // Crawl until the 3rd page
  "shopSearch_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of shops to crawl
  "shopSearch_crawlNextPages_maxResults": 150,
  // Automatically crawl the detail of each listed shop
  "shopSearch_crawlShopDetails": true
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/users/shopid: Unique identifier for the shop.
  • data/users/shopname: Name of the shop.
  • data/users/username: The shop's username or slug, useful for direct queries or referencing.
  • data/users/portrait: Shop image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}, for example the URL to download the image "6d4ff02a5978ee10a7b4527c25396b0b" is "https://down-sg.img.susercontent.com/file/6d4ff02a5978ee10a7b4527c25396b0b".

Shop Detail

• URL Path:
  • /api/v4/shop/get_shop_base

Note: Please use Shop Detail V2 instead. It seems that Shopee is not using get_shop_base anymore and tends to block it.

• URL Parameters:

  • username: Specify the shop's username (not the shop ID).
  • shopid: Specify the shop's ID.

    Note: Use either username or shopid, but not both at the same time.

  • entry_point, need_cancel_rate, request_source, version: Additional parameters with default settings.

• Scraper Input Parameters

  • shopDetail_crawlShopProducts: Set to true to enable automatic crawling of the shop's products.

• Example Input:

{
  // Retrieve detailed information about a specific shop
  "requests": [
    { "url": "https://shopee.sg/api/v4/shop/get_shop_base?username=xiaomiofficialstore.sg" }
  ],
  
  // Automatically crawl shop products
  "shopSearch_crawlShopDetails": true,

  // Set the product "limit" URL parameter to 30
  "shopProducts_enrichUrlQuery_pageSize": 30,
  // Automatically crawl the next product pages
  "shopProducts_crawlNextPages": true,
  // Crawl until the 3rd product page
  "shopProducts_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of products to crawl
  "shopProducts_crawlNextPages_maxResults": 90,
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/shopid: The unique identifier for the shop.
  • data/name: Official name of the shop.
  • data/description: Brief description of the shop.
  • data/cover: Image key for the shop's profile picture. Convert to URL using the provided format: https://down-${country}.img.susercontent.com/file/${imageKey}.
  • data/account/username: The shop's unique username or slug.
  • data/ctime: Timestamp marking the shop's creation.
  • data/shop_rating: Aggregated rating details of the shop.
  • data/seller_metrics: Various metrics providing insights into the shop's performance.
  • data/item_count: Total number of products offered by the shop.

Shop Detail V2

• URL Path:

  • /api/v4/shop/get_shop_base_v2

• Request Body Parameters:

  • username: Shop's unique username or slug.
  • shopid: Unique identifier for the shop.

    Note: Use either username or shopid, but not both at the same time.

  • entry_point, request_source, livestream_params: Automatically generated, unless overridden.

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/shop/get_shop_base_v2",
      "method": "POST",
      "payload": {
        "request_source": "mobile_shop_home_page",
        "livestream_params": {
        },
        "shopid": 18254273,
        // Alternatively: "username": "optimumnutrition"
      }
    }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/shopid: The unique identifier for the shop.
  • data/name: Official name of the shop.
  • data/description: Brief description of the shop.
  • data/cover: Image key for the shop's profile picture. Convert to URL using the provided format: https://down-${country}.img.susercontent.com/file/${imageKey}.
  • data/account/username: The shop's unique username or slug.
  • data/ctime: Timestamp marking the shop's creation.
  • data/shop_rating: Aggregated rating details of the shop.
  • data/seller_metrics: Various metrics providing insights into the shop's performance.
  • data/item_count: Total number of products offered by the shop.

Shop Products

• URL Path:

  • api/v4/shop/rcmd_items

• URL Parameters:

  • shop_id: Unique identifier for the shop.
  • limit (default = set by scraper): Number of results per page.
  • offset (default = 0): Offset for results, typically a multiple of limit.
  • sort_type (default = 1): Sorting option for products. 1 = popular first, 2 = latest first, 13 = top sales first, 8 = price low to high, 4 = price high to low
  • cat_id (optional): Filter products by a category.
  • bundle, upstream: Additional parameters with default settings.

• Scraper Input Parameters

  • shopProducts_enrichUrlQuery_pageSize: Number of results per request (default: 30).
  • shopProducts_crawlNextPages: Set to true to crawl subsequent pages.
  • shopProducts_crawlNextPages_maxPages: Limit on number of pages to crawl (default: 100).
  • shopProducts_crawlNextPages_maxResults: Maximum products to crawl (default: 3000).
  • shopProducts_crawlNextPages_minSales: Minimum sales threshold for page crawling (optional). Crawling stops when a product with sales equal to or less than this value appears, assuming products are sorted by sales in descending order.
  • shopProducts_crawlProductDetails: Set to true to automatically crawl product details (default: false).

• Example Input:

{
  // Get the products of a shop
  "requests": [
    { "url": "https://shopee.sg/api/v4/shop/rcmd_items?shop_id=178877065" }
  ],

  // Set the product "limit" URL parameter to 30
  "shopProducts_enrichUrlQuery_pageSize": 30,
  // Automatically crawl the next product pages
  "shopProducts_crawlNextPages": true,
  // Crawl until the 3rd product page
  "shopProducts_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of products to crawl
  "shopProducts_crawlNextPages_maxResults": 150,
  // Automatically crawl product details
  "shopProducts_crawlProductDetails": true
}

• Example Response:
  • View Full Example Response

Note: This API is scraped by using the POST method.

• Notable Response Fields:
  • data/items: Array of product summaries.
  • data/items/itemid and items/shopid: Essential for scraping product details and ratings.
  • data/items/name: Product name.
  • data/items/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}.
  • data/items/ctime: Creation timestamp.
  • data/items/stock: Stock level.
  • data/items/sold: Monthly sales.
  • data/items/historical_sold: Total sales.
  • data/items/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Shop Products API still provides these fields.

Shop Products V2

Retrieve products from a Shopee shop, sorted by popularity, recency, sales, or price.

• URL Path:

  • api/v4/shop/get_products_tab_data_v2

• Request Body Parameters:

  • shop_id: Unique identifier for the shop.
  • top_item_ids (optional): Comma-separated list of item IDs to prioritize (e.g. "22649016235,16324283563,24624953124").
  • limit (default = set by scraper): Number of results per page.
  • offset (default = 0): Offset for results, typically a multiple of limit.
  • by (default = "popular"): Sorting criteria: "popular", "latest", "topsales" or "price".
  • order (default = "desc"): Sorting direction: "asc" or "desc".
  • item_card_use_scene (optional, automatically set based on by):
    • "popular" -> "products_tab_popular"
    • "latest" -> "products_tab_latest"
    • "topsales" -> "products_tab_topsales"
    • "price" -> "products_tab_price"

• Scraper Input Parameters

  • emulateMobileDevice (default: true): Whether to emulate a mobile device (true) or a desktop browser (false).

Note: At the moment, it seems that it only works on mobile browsers (emulateMobileDevice = true).

• Scraper Input Parameters
  • shopProducts_enrichUrlQuery_pageSize: Number of results per request (default: 30).
  • shopProducts_crawlNextPages: Set to true to crawl subsequent pages.
  • shopProducts_crawlNextPages_maxPages: Limit on number of pages to crawl (default: 100).
  • shopProducts_crawlNextPages_maxResults: Maximum products to crawl (default: 3000).
  • shopProducts_crawlNextPages_minSales: Minimum sales threshold for page crawling (optional). Crawling stops when a product with sales equal to or less than this value appears, assuming products are sorted by sales in descending order.
  • shopProducts_crawlProductDetails: Set to true to automatically crawl product details (default: false).

Note: The API returns different response structures depending on the browser type. Set emulateMobileDevice accordingly.

• Example Input:

{
  "requests": [
    {
      "url": "https://shopee.sg/api/v4/shop/get_products_tab_data_v2",
      "method": "POST",
      "payload": {
        "order": "desc",
        "top_item_ids": "",
        "by": "popular",
        "item_card_use_scene": "products_tab_popular",
        "shop_id": 18254273,
        "limit": 20,
        "offset": 0
      }
    }
  ],
  "emulateMobileDevice": false,

  // Set the product "limit" URL parameter to 30
  "shopProducts_enrichUrlQuery_pageSize": 30,
  // Automatically crawl the next product pages
  "shopProducts_crawlNextPages": true,
  // Crawl until the 3rd product page
  "shopProducts_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of products to crawl
  "shopProducts_crawlNextPages_maxResults": 150,
  // Automatically crawl product details
  "shopProducts_crawlProductDetails": true
}

• Example Response:
  • Desktop Response
  • Mobile Response

Note: This API uses the POST method.

• Notable Fields (Desktop):

  • data/item_cards: Array of product summaries.
  • data/item_cards/item_card_data/itemid and shopid: Product identifiers.
  • data/item_cards/item_card_data/name: Product name.
  • data/item_cards/item_card_data/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}.
  • data/item_cards/item_card_data/ctime: Creation timestamp.
  • data/item_cards/item_card_data/stock: Stock level.
  • data/item_cards/item_card_data/sold: Monthly sales.
  • data/item_cards/item_card_data/historical_sold: Total sales.
  • data/item_cards/item_card_data/price: Divide by 100,000 to get actual price.

• Notable Fields (Mobile):

  • data/item_cards: Array of product summaries.
  • data/item_cards/item_card_data/centralize_item_card/item_card/itemid and shopid: Product identifiers.
  • data/item_cards/item_card_data/centralize_item_card/item_card/item_card_displayed_asset/name: Product name.
  • data/item_cards/item_card_data/centralize_item_card/item_card/item_card_displayed_asset/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}.
  • data/item_cards/item_card_data/centralize_item_card/item_card/ctime: Creation timestamp.
  • data/item_cards/item_card_data/centralize_item_card/item_card/item_card_display_sold_count/monthly_sold_count: Monthly sales.
  • data/item_cards/item_card_data/centralize_item_card/item_card/item_card_display_sold_count/historical_sold_count: Total sales.
  • data/item_cards/item_card_data/centralize_item_card/item_card/item_card_display_price/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Product Listing API still provides these fields.

Keyword Suggestion

• URL Path:
  • /api/v4/search/search_suggestion

Note: The keyword suggestions are normally displayed under the top search bar.

• URL Parameters:

  • limit (default = set by scraper): Number of results per page.
  • offset (default = 0): Offset for results, typically a multiple of limit.
  • bundle: An additional parameter, usually set to default.

• Scraper Input Parameters

  • keywordSuggestions_enrichUrlQuery_pageSize: Number of keyword suggestions per request (default: 8).
  • keywordSuggestions_crawlNextPages: Set to true to crawl subsequent pages.
  • keywordSuggestions_crawlNextPages_maxPages: Limit on number of pages to crawl (default: 55).
  • keywordSuggestions_crawlNextPages_maxResults: Maximum keyword suggestions to crawl (default: 440).

• Example Input:

{
  // Retrieve the 50 top suggested keywords
  "requests": [
    { "url": "https://shopee.sg/api/v4/search/search_suggestion?limit=50" }
  ],

  // Set the "limit" URL parameter to 50
  "keywordSuggestions_enrichUrlQuery_pageSize": 50,
  // Automatically crawl the next pages
  "keywordSuggestions_crawlNextPages": true,
  // Crawl until the 3rd page
  "keywordSuggestions_crawlNextPages_maxPages": 3,
  // Alternatively, indicate the maximum number of keyword suggestions to crawl
  "keywordSuggestions_crawlNextPages_maxResults": 150
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • data/queries/text: Suggested keyword.

Keyword Autocompletion

• URL Path:

  • /api/v4/search/search_hint

• URL Parameters:

  • keyword: The initial characters of a potential search term.
  • extra_params, search_type, version: Additional parameters with default settings.

• Example Input:

{
  // Retrieve autocomplete suggestions for the keyword prefix "n"
  "requests": [
    { "url": "https://shopee.sg/api/v4/search/search_hint?keyword=n" }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • keywords/keyword: Suggested keyword based on the input characters.

Supermarket Product Search

• URL Path:

  • /api/v4/search/search_mart_items

• URL Parameters:

  • by (default = "relevancy"): Sort by "relevancy", "discount", "sales", or "price".
  • order (default = "desc"): Sort order, "asc" or "desc".
  • limit (default = 25): Number of results per page.
  • newest (default = 0): Offset for results, typically a multiple of limit.
  • keyword (optional): Search keyword, e.g., "cheese".

• Example Input:

{
  "requests": [
    // First page of the "all products" page
    { "url": "https://shopee.sg/api/v4/search/search_mart_items?by=relevancy&limit=25&newest=0&order=desc" },

    // Search for the "cheese" keyword
    { "url": "https://shopee.sg/api/v4/search/search_mart_items?by=relevancy&keyword=cheese&limit=25&newest=0&order=desc" }
  ]
}

• Example Response:

  • View Full Example Response

• Notable Response Fields:

  • items: Array of product summaries.
  • items/itemid and items/shopid: Essential for scraping product details and ratings.
  • items/item_basic/name: Product name.
  • items/item_basic/image: Image key. Convert to URL with https://down-${country}.img.susercontent.com/file/${imageKey}, for example the URL to download the image "sg-11134201-7qvez-lgj50bviqvph8b" is "https://down-sg.img.susercontent.com/file/sg-11134201-7qvez-lgj50bviqvph8b".
  • items/item_basic/ctime: Creation timestamp.
  • items/item_basic/sold: Monthly sales.
  • items/item_basic/historical_sold: Total sales.
  • items/item_basic/price: Divide by 100,000 to get actual price.

Note: Unfortunately sold and stock are not available anymore in non-authenticated mode. However, the Shop Products V2 API and Android Product Listing API still provides these fields.

Output

The default dataset contains one row per input request:

{
  "marketplaceRunUuid": "...",
  "taskUuid": "...",
  "url": "https://shopee.sg/api/v4/search/search_items?keyword=tshirt",
  "status": "SUCCESS",
  "responseBody": {
    "items": []
  }
}

Output fields:

• marketplaceRunUuid - Charted Sea marketplace-run ID.
• taskUuid - Charted Sea scraping-task ID.
• url - Original requested URL.
• status - Terminal request status.
• responseBody - Shopee response for a successful request.
• error - Error description for an unsuccessful request.

Rows remain in the same logical request order. One failed request does not hide successful rows from the same batch.

Pricing

Pay as you go with no subscription or monthly minimum:

• Successful standard Shopee Web request: $0.005.
• Successful product-detail or batch product-variation request: $0.00998.
• Proxy usage: $0.00013 per started block of 100 proxy units.
• Actor start: $0.00005 per GB of Actor memory, with a minimum of one event.
• Dataset result: $0.00001 per result written to the default dataset.

The product-detail price applies to Shopee product page URLs, /api/v4/pdp/get_pc, /api/v4/pdp/get_rw, and batch select-variation APIs. Every other supported Shopee Web API uses the standard price.

Failed or cancelled requests are not charged as successful Shopee requests. Proxy usage varies with the requested API, response size, anti-bot conditions, and multi-page options. Use Apify's maximum total charge setting to bound an execution's total cost.

Charging

This is a PAY_PER_EVENT Actor. A completed execution can charge:

• One csea-scrape-shopee-web event per successful standard request.
• One csea-scrape-shopee-web-product-detail event per successful product-detail request.
• Finalized csea-proxy-unit events for proxy usage consumed by the requests.

The Actor classifies only finalized successful task URLs. Charging is persisted and resumed without intentionally duplicating events.

Graceful aborts and retries

A graceful Apify abort cancels known Charted Sea tasks and waits for backend finalization. Interrupted Actor executions persist their marketplace run, charging, and output state so they can resume without intentionally duplicating charges or dataset rows.

Operational guidance

• Start with small batches when testing new endpoints.
• Monitor success rates during major Shopee campaigns.
• Expect stricter anti-bot behavior during high-traffic sales.
• Use bounded pagination options for large listing and rating requests.