Etsy Category Scraper: Taxonomy Tree & Listing Counts

Export Etsy's category tree as flat rows: taxonomy ID, name, parent, full path and the number of listings Etsy reports for each category. Start from the top-level categories or from any taxonomy ID and go one to six levels deep. No Etsy login and no Etsy developer API key are needed.

This actor is about Etsy's category structure, not about products. To scrape listings, shops or reviews, use an Etsy listing, shop or review scraper; use this one to get the category IDs those tools (and Etsy's own search category filter) expect, and to see how big each niche is.

What you get

Field	Type	Notes
taxonomy_id	integer	Etsy category ID
name	string	Category name
parent_id	integer / null	Parent category ID (null for top-level categories)
parent_name	string / null	Parent category name
depth	integer	Level below the ID you asked for (1 = direct child)
path	string	Path from the requested ID, e.g. Jewelry > Necklaces > Charm Necklaces
path_ids	array	Taxonomy IDs along that path
listing_count	integer / null	Listings Etsy shows for the category. Not provided for the top-level categories
has_children	boolean / null	Whether the category has sub-categories. Null at the deepest level requested (not checked)
image_url	string / null	Category thumbnail

Use cases

• Category pickers and mapping: map your own product taxonomy to Etsy's IDs.
• Niche sizing: rank sub-categories of a branch by listing count to see where the volume is.
• Taxonomy change monitoring: schedule a monthly run and diff the output to spot new or removed categories.
• Seeding other scrapers: feed taxonomy_id values into your search or listing pipelines.

Input

Parameter	Type	Default	Description
taxonomyIds	array	["0"]	0 = Etsy's top-level categories. Any other ID returns that category's sub-categories.
maxDepth	integer	1	Levels to return (1-6). Each level after the first costs one Etsy request per category on the level above.
maxItems	integer	1000	Stops after this many rows in total.
proxyConfiguration	object	off	Optional. Normally not needed.

Example: Jewelry and Home & Living, three levels deep.

{ "taxonomyIds": ["1179", "891"], "maxDepth": 3, "maxItems": 2000 }

Top-level category IDs

66 Art & Collectibles, 891 Home & Living, 12584 Gifts, 1179 Jewelry, 374 Clothing, 825 Electronics & Accessories, 562 Craft Supplies & Tools, 1 Accessories, 132 Bags & Purses, 12545 Kids & Baby, 324 Books, 355 Movies, 356 Music, 199 Bath & Beauty, 1633 Weddings, 1330 Party Supplies, 1303 Paper & Stationery, 1553 Games & Puzzles, 1580 Toys, 1560 Sports & Outdoor Recreation, 1429 Shoes, 1351 Pet Supplies. Run with 0 to get the current list.

Example output

{
  "taxonomy_id": 1222,
  "name": "Charm Necklaces",
  "parent_id": 1217,
  "parent_name": "Necklaces",
  "depth": 2,
  "path": "Jewelry > Necklaces > Charm Necklaces",
  "path_ids": [1179, 1217, 1222],
  "listing_count": 400361,
  "has_children": false,
  "image_url": "https://i.etsystatic.com/8622539/r/il/1ab144/5226062085/il_fullxfull.5226062085_8jj5.jpg"
}

Scheduling and API

Use the Apify scheduler (for example monthly: 0 9 1 * *) and compare each run's dataset with the previous one, or call the actor through the Apify API with the same JSON input.

FAQ

Does it need an Etsy account or API key? No.

Why is listing_count empty for top-level categories? Etsy's category data does not report a count for them. Sub-categories carry one.

Why is has_children null? The actor only expands categories above the deepest level you requested. Raise maxDepth to learn more.

What happens with a leaf or unknown ID? A leaf category returns no rows (not an error). An ID that does not exist is reported in the log, and the run fails only if none of your IDs were usable.

How deep does the tree go? Usually three or four levels. Counts are as Etsy reports them at the time of the run and change daily.

Is it legal? The actor reads category data that Etsy shows publicly in its app. You are responsible for using it in line with Etsy's terms and applicable law.