# Etsy Category Scraper (`axlymxp/etsy-category-scraper`) Actor

Extract Etsy's full category hierarchy by taxonomy ID. Returns categories, sub-categories, IDs, and images. No API key needed. Supports batch input and scheduled runs to monitor taxonomy changes.

- **URL**: https://apify.com/axlymxp/etsy-category-scraper.md
- **Developed by:** [axly](https://apify.com/axlymxp) (community)
- **Categories:** E-commerce, Agents, Automation
- **Stats:** 30 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 results

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/platform/actors/running/actors-in-store#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

## Etsy Category & Taxonomy Scraper — Full Hierarchy Extraction

Extract Etsy's complete category and sub-category hierarchy by taxonomy ID. No Etsy API key required — data is fetched directly from Etsy's mobile API. Use to build seller apps, populate category dropdowns, map product taxonomies, or monitor when Etsy adds new categories.

### What Data You Get

| Field       | Type    | Notes                                          |
| ----------- | ------- | ---------------------------------------------- |
| `id`        | integer | Etsy taxonomy ID                               |
| `title`     | string  | Root category display name (Mode A)            |
| `name`      | string  | Sub-category name (Mode B)                     |
| `image_url` | string  | Category thumbnail URL                         |
| `parent_id` | integer | Parent taxonomy ID (Mode B, cleaned output)    |
| `path`      | string  | Full dot-separated taxonomy path (full output) |
| `children`  | array   | Nested child categories (full output)          |

Enable `cleaned_result` for the lightweight format above. Disable it to receive the full raw API node including `breadcrumb`, `children`, `full_path_taxonomy_id`, and extended image objects.

### Use Cases

**1. Build a Product Categorization Tool**\
Map your inventory to Etsy taxonomy IDs before listing — reduces category mismatch and improves search visibility.

**2. Populate Category Dropdowns in Etsy Apps**\
Power category pickers in seller tools, Chrome extensions, or SaaS dashboards without hardcoding Etsy's tree.

**3. Competitive Category Analysis**\
Which categories have the deepest sub-category trees? Use the hierarchy to identify where Etsy is investing and where niches are emerging.

**4. Monitor Taxonomy Changes**\
Schedule a monthly run and diff the output to detect when Etsy adds new categories — an early signal of emerging product markets.

### How to Use

#### Input Parameters

| Parameter            | Type    | Default | Description                                                                                |
| -------------------- | ------- | ------- | ------------------------------------------------------------------------------------------ |
| `parent_taxonomy_id` | string  | `"0"`   | ID to fetch. `"0"` returns all root categories. Any other ID returns its sub-categories.   |
| `taxonomy_ids`       | array   | `[]`    | Batch mode — fetch multiple IDs in one run. Overrides `parent_taxonomy_id` when non-empty. |
| `cleaned_result`     | boolean | `true`  | Return simplified `{id, name/title, image_url}` output. Disable for full raw API response. |

#### Known Root-Level Taxonomy IDs

| ID         | Category                              |
| ---------- | ------------------------------------- |
| `0`        | All root categories (via search home) |
| `1430`     | Jewelry & Accessories                 |
| `69150408` | Clothing & Shoes                      |
| `891`      | Home & Living                         |
| `4`        | Art & Collectibles                    |
| `68887482` | Craft Supplies & Tools                |
| `281`      | Vintage                               |

#### Example Input

```json
{
    "parent_taxonomy_id": "0",
    "cleaned_result": true
}
```

Batch mode — fetch three branches in one run:

```json
{
    "taxonomy_ids": ["1430", "891", "4"],
    "cleaned_result": true
}
```

### Example Output

#### Mode A — Root categories (`parent_taxonomy_id: "0"`, cleaned)

```json
{
    "id": 1430,
    "title": "Jewelry & Accessories",
    "image_url": "https://i.etsystatic.com/cat/1430/square570.jpg"
}
```

#### Mode B — Sub-categories (`parent_taxonomy_id: "1430"`, cleaned)

```json
{
    "id": 1431,
    "name": "Necklaces",
    "image_url": "https://i.etsystatic.com/cat/1431/square570.jpg",
    "parent_id": 1430
}
```

### Pricing

Fetching all root categories (`"0"`) returns ~50 records — under **$0.10** at $1.00/1k.\
Fetching one branch (e.g. Jewelry) returns ~30–80 sub-categories — under **$0.10**.\
Fetching 10 branches via `taxonomy_ids` batch mode returns ~300–600 records — under **$1.00** total.

### Automate with Scheduling

Schedule a monthly run to detect when Etsy adds new categories:

1. Open your actor run → **Schedule** tab
2. Set CRON: `0 9 1 * *` (9am on the 1st of each month)
3. Compare output to the previous run to spot new taxonomy IDs

Or trigger via API:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/axlymxp~etsy-category-scraper/runs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parent_taxonomy_id": "0", "cleaned_result": true}'
```

### Use with AI Agents (MCP)

This actor is available on Apify's MCP Server. Connect it to your AI workflow to answer questions like "what are all Etsy jewelry sub-categories?" with live data on demand.

Configure at: <https://mcp.apify.com>

### FAQ

**What taxonomy ID should I use to get all top-level categories?**\
Use `"0"`. This calls Etsy's search home endpoint and returns all root category nodes (Jewelry, Home & Living, Clothing, etc.).

**What is a taxonomy ID?**\
Etsy organises its marketplace into a hierarchical category tree. Each node has a numeric ID. Use `"0"` for the root level, then pass any returned ID as input to fetch that branch's children.

**Does this actor require an Etsy API key?**\
No. The actor uses Etsy's mobile app API directly — no developer account or API key needed.

**Can I get multiple branches in one run?**\
Yes. Use the `taxonomy_ids` array parameter with a list of IDs (e.g. `["1430", "891", "4"]`) to fetch all branches in a single run.

**How often does Etsy's taxonomy change?**\
Etsy adds new categories a few times per year. Schedule a monthly run to catch changes automatically.

**Is this legal to use?**\
The actor accesses publicly available category data from Etsy's marketplace. Use in accordance with [Etsy's Terms of Service](https://www.etsy.com/legal/terms-of-use) and applicable laws.

# Actor input Schema

## `parent_taxonomy_id` (type: `string`):

Taxonomy ID to fetch. Use "0" for all root categories (Jewelry, Home & Living, etc.). Use any category ID (e.g. "1430") to get its sub-categories. Ignored if taxonomy\_ids is set.

## `taxonomy_ids` (type: `array`):

Fetch multiple taxonomy IDs in a single run. Each ID is fetched and its results pushed to the dataset tagged with parent\_id. Overrides parent\_taxonomy\_id when non-empty.

## `cleaned_result` (type: `boolean`):

Return simplified output with only id, name/title, and image\_url. Disable to get the full raw API response per category node.

## Actor input object example

```json
{
  "parent_taxonomy_id": "0",
  "taxonomy_ids": [],
  "cleaned_result": true
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/etsy-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 = {}

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

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

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

```

## CLI example

```bash
echo '{}' |
apify call axlymxp/etsy-category-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=axlymxp/etsy-category-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/Nb9euKzAWdS109vfN/builds/L8BX10sxxuTV5bYRx/openapi.json