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

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

Batch mode — fetch three branches in one run:

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

Example Output

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

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

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

{
    "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:

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 and applicable laws.