# Etsy Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | private |
| **Method** | `GET` |
| **Endpoint** | `/v2/etsy/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/etsy-search |

## Description

Search Etsy listings in real time and get prices, seller ratings, images, and tags as structured JSON without managing proxies.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/etsy/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search handmade ceramic mug

```json
{
  "page": 1,
  "results": [
    {
      "url": "https://www.etsy.com/listing/1584729301/handmade-ceramic-coffee-mug-pottery-mug",
      "tags": [
        "ceramic mug",
        "handmade mug",
        "pottery",
        "coffee mug",
        "stoneware",
        "gift",
        "kitchen"
      ],
      "price": 34,
      "title": "Handmade Ceramic Coffee Mug, Pottery Mug with Handle, Stoneware Mug 12oz",
      "images": [
        "https://i.etsystatic.com/28471930/r/il/a3c4f1/4721830291/il_794xN.4721830291_k4m9.jpg"
      ],
      "rating": 4.9,
      "category": "home-and-living",
      "currency": "USD",
      "seller_id": "28471930",
      "is_vintage": false,
      "listing_id": "1584729301",
      "seller_url": "https://www.etsy.com/shop/ClayworksByMara",
      "is_handmade": true,
      "seller_name": "ClayworksByMara",
      "review_count": 1247,
      "thumbnail_url": "https://i.etsystatic.com/28471930/r/il/a3c4f1/4721830291/il_794xN.4721830291_k4m9.jpg",
      "is_free_shipping": true,
      "quantity_available": 43
    },
    {
      "url": "https://www.etsy.com/listing/1612847563/large-ceramic-mug-with-geometric-design",
      "tags": [
        "large mug",
        "geometric",
        "ceramic",
        "artisan pottery",
        "16oz",
        "modern"
      ],
      "price": 42.5,
      "title": "Large Ceramic Mug with Geometric Design, Artisan Pottery Mug 16oz",
      "images": [
        "https://i.etsystatic.com/31924750/r/il/d8f3b9/5102847391/il_794xN.5102847391_r8t2.jpg"
      ],
      "rating": 4.7,
      "category": "home-and-living",
      "currency": "USD",
      "seller_id": "31924750",
      "is_vintage": false,
      "listing_id": "1612847563",
      "seller_url": "https://www.etsy.com/shop/EarthAndFireStudio",
      "is_handmade": true,
      "seller_name": "EarthAndFireStudio",
      "review_count": 389,
      "thumbnail_url": "https://i.etsystatic.com/31924750/r/il/d8f3b9/5102847391/il_794xN.5102847391_r8t2.jpg",
      "is_free_shipping": false,
      "quantity_available": 12
    }
  ],
  "total_pages": 242,
  "total_results": 4823,
  "results_per_page": 20
}
```

### Search vintage leather wallet

```json
{
  "page": 1,
  "results": [
    {
      "url": "https://www.etsy.com/listing/1498302741/vintage-bifold-leather-wallet",
      "tags": [
        "leather wallet",
        "bifold",
        "vintage",
        "minimalist",
        "men gift",
        "slim wallet"
      ],
      "price": 28,
      "title": "Vintage Bifold Leather Wallet, Minimalist Card Holder, Men's Slim Wallet",
      "images": [
        "https://i.etsystatic.com/19384721/r/il/c2f4b7/3847201938/il_794xN.3847201938_t5w1.jpg"
      ],
      "rating": 4.8,
      "category": "accessories",
      "currency": "USD",
      "seller_id": "19384721",
      "is_vintage": false,
      "listing_id": "1498302741",
      "seller_url": "https://www.etsy.com/shop/LeatherCraftCo",
      "is_handmade": true,
      "seller_name": "LeatherCraftCo",
      "review_count": 643,
      "thumbnail_url": "https://i.etsystatic.com/19384721/r/il/c2f4b7/3847201938/il_794xN.3847201938_t5w1.jpg",
      "is_free_shipping": true,
      "quantity_available": 27
    }
  ],
  "total_pages": 61,
  "total_results": 1204,
  "results_per_page": 20
}
```

## Documentation

## Overview
Etsy hosts over 90 million active listings from independent sellers. Prices, availability, and seller ratings shift continuously. Etsy applies Cloudflare. Piloterr handles that detection layer so you get clean JSON with a single GET request.

## Quickstart
```
GET https://api.piloterr.com/v2/etsy/search?query=handmade+ceramic+mug
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search keyword |
| `page` | integer | no | Page number (default: 1) |
| `category` | string | no | Category slug |
| `min_price` | number | no | Minimum price in USD |
| `max_price` | number | no | Maximum price in USD |
| `sort` | string | no | Sort order |
| `free_shipping` | boolean | no | Free shipping only |

## Main use cases
- Monitor competitor pricing across Etsy categories in real time
- Track top-rated listings per keyword to identify trending products early
- Build keyword research tools for Etsy sellers and marketplace analysts
- Collect listing data for cross-platform comparison with Amazon Handmade or Folksy
- Feed price alert systems for buyers tracking specific items

Get access at https://www.piloterr.com/pricing