# Shopee Category Tree Scraper (`incognito_mode/shopee-category-scraper`) Actor

Export Shopee's complete category taxonomy across 11 countries - category ID, name, parent, full breadcrumb path, level, leaf flag and browsable URL - flattened out of Shopee's nested tree. One request per marketplace. No login or API key.

- **URL**: https://apify.com/incognito\_mode/shopee-category-scraper.md
- **Developed by:** [Elena Vance](https://apify.com/incognito_mode) (community)
- **Categories:** E-commerce, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 categories

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Shopee Category Tree Scraper

Shopee's **complete category taxonomy**, flattened into a clean table — across
**11 marketplaces**, one HTTP request each. No API key, no login, no browser.

Every row carries its own ancestry, so you never have to walk a nested JSON
blob: `categoryId`, `parentId`, `path`, `pathIds`, `level`, `isLeaf` and a
working category URL.

***

### What you get

```json
{
  "categoryId": 11027727,
  "name": "Tops",
  "region": "sg",
  "country": "Singapore",
  "level": 2,
  "parentId": 11012819,
  "parentName": "Women's Apparel",
  "path": "Women's Apparel > Tops",
  "pathIds": [11012819, 11027727],
  "rootId": 11012819,
  "rootName": "Women's Apparel",
  "isLeaf": true,
  "childCount": 0,
  "url": "https://shopee.sg/Tops-cat.11012819.11027727",
  "imageUrl": "https://down-sg.img.susercontent.com/file/sg-50009109-08d5…"
}
```

| Field | Notes |
| --- | --- |
| `categoryId` | Shopee's `catid` — the value product records reference |
| `path` / `pathIds` | Full breadcrumb as text and as IDs |
| `level` | Counted by the walk itself, so it is always right |
| `isLeaf` / `childCount` | Leaves are where products are actually filed |
| `url` | Built from the **full ancestry**, the way Shopee's own breadcrumbs do |
| `region` / `country` | Which marketplace this row came from |

#### About the URL

A Shopee category is addressed by its whole ancestry, not by its own ID:
`/Tops-cat.11012819.11027727`, not `/Tops-cat.11027727`. This Actor builds it
correctly, and the format is pinned in the test suite against real URLs taken
from Shopee's own breadcrumb JSON-LD.

For non-Latin names (Thai, Vietnamese, Chinese) the slug falls back to the
category ID — `https://shopee.co.th/11045208-cat.11044959.11045208`. The slug
is cosmetic; Shopee resolves the page from the trailing IDs.

### Input

```json
{
  "regions": ["sg", "my", "id"],
  "maxDepth": 0,
  "leavesOnly": false
}
```

| Option | Default | Notes |
| --- | --- | --- |
| `regions` | `["sg"]` | One request each. |
| `maxDepth` | `0` (whole tree) | `1` = departments only, `2` = departments + subcategories. |
| `leavesOnly` | `false` | Keep only categories with no children. |
| `maxItems` | `10000` | Hard cap across all marketplaces. |
| `proxyConfiguration` | off | Leave off — see below. |

Filters are applied **after** the tree is walked, never during it — so a
filtered row still carries its complete, correct parent path.

### Marketplaces

Singapore · Malaysia · Indonesia · Thailand · Vietnam · Philippines · Taiwan ·
Brazil · Mexico · Colombia · Chile

Category names come back in each marketplace's own language, and category IDs
differ per country — Singapore's tree is not Thailand's with translations.
Verified live: SG has 260 categories, TH has 264.

### Speed and cost

**One request per marketplace.** Singapore and Thailand together — 524
categories — take about 4 seconds at 256 MB. No browser is launched.

No proxy is used unless Shopee actually blocks an IP, and then the Actor
escalates on its own — datacenter first (included in every Apify plan, free
tier included), residential only if your plan has it.

### Use it for

- **Marketplace integration** — map your own catalogue's categories onto
  Shopee's IDs before listing.
- **Decoding product data** — turn the `categoryId` on a scraped product into
  a readable breadcrumb.
- **Cross-market comparison** — see how the same department is split
  differently in SG, MY and ID.
- **Category-level research** — a complete, stable frame to structure
  assortment analysis around.

### Related

**Shopee Product Catalog & Variant Scraper** returns the `categoryId` these
rows decode, **Shopee Official Brand Store Directory** lists the brands, and
**Shopee Shop & Seller Profile Scraper** covers the sellers.

# Actor input Schema

## `regions` (type: `array`):

Which Shopee countries to map. Each one costs a single HTTP request and returns that marketplace's complete taxonomy - about 260 categories.

## `maxDepth` (type: `integer`):

Keep only categories at or above this level. 1 = top-level departments only, 2 = departments and their subcategories. Leave at 0 for the whole tree.

## `leavesOnly` (type: `boolean`):

Keep only categories with no subcategories - the ones products are actually filed under. Every row still carries its full parent path.

## `maxItems` (type: `integer`):

Hard cap on rows stored across all marketplaces.

## `proxyConfiguration` (type: `object`):

Leave off. Every request calls Shopee directly first, which costs nothing. If an IP is blocked the Actor escalates on its own: first to a datacenter proxy (included in every Apify plan, free tier included), then to residential only if your plan has it.

## Actor input object example

```json
{
  "regions": [
    "sg"
  ],
  "maxDepth": 0,
  "leavesOnly": false,
  "maxItems": 10000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing every category.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "regions": [
        "sg"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("incognito_mode/shopee-category-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "regions": ["sg"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("incognito_mode/shopee-category-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "regions": [
    "sg"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call incognito_mode/shopee-category-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,incognito_mode/shopee-category-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bwDTO3c665OSsbkiR/builds/Uf0aQKGFkdkQa3Ohx/openapi.json