# Etsy — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Discover what shoppers are searching for on Etsy by accessing real-time trending keywords and popular search terms that can help you identify market demand and optimize your product listings. Get instant access to autocomplete suggestions and "Popular right now" trends to stay ahead of customer interests and improve your shop's visibility.

**Category:** Marketplaces | **Website:** [etsy.com/](https://etsy.com/) | **Docs:** [parse.bot/marketplace/9812261a-267f-4ae6-94ff-7bc177701c7e/etsy-com-api](https://parse.bot/marketplace/9812261a-267f-4ae6-94ff-7bc177701c7e/etsy-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### browse_category

Browse Etsy listings by category path. Returns paginated product listings within the specified category, parsed from the HTML listing cards.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_path` | string | Yes | Hierarchical category path using forward slashes (e.g. 'clothing/womens-clothing/dresses', 'jewelry/necklaces', 'jewelry/rings'). |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/browse_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_path":"<string>","page":"<integer>"}'
```

### get_listing_details

Retrieve full details for a single Etsy listing by its listing ID via Etsy's public JSON API. Returns product name, description, images, pricing, seller info, badges, tags, materials, and availability.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | Etsy listing ID (numeric string, e.g. '1548871956'). Obtainable from browse_category results[*].listing_id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/get_listing_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### get_listing_reviews

Retrieve reviews for a specific Etsy listing via the shop reviews API. Returns all recent shop reviews and filters for listing-specific ones. Providing the shop_id avoids an extra API call to resolve it.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | Etsy listing ID (numeric string). Obtainable from browse_category results[*].listing_id. |
| `shop_id` | string | No | Numeric shop ID. If omitted, auto-detected from the listing API. Obtainable from get_listing_details.shop_id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/get_listing_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>","shop_id":"<string>"}'
```

### get_shop_info

Retrieve basic profile information for an Etsy shop by its shop name. Returns name, URL, logo, aggregate rating, review count, and shop ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `shop_name` | string | Yes | Etsy shop name as it appears in the shop URL (e.g. 'TheBeadChest'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/get_shop_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shop_name":"<string>"}'
```

### get_shop_listings

List products from a specific Etsy shop with pagination. Returns basic product info including name, URL, image, price, and currency.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `shop_name` | string | Yes | Etsy shop name as it appears in the shop URL (e.g. 'TheBeadChest'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/get_shop_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","shop_name":"<string>"}'
```

### search_listings

Search for product listings on Etsy by keyword. Returns paginated results with basic product information extracted from structured data. Supports optional price range and attribute filters.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `is_handmade` | string | No | Filter handmade items. Accepted values: true, false. |
| `is_vintage` | string | No | Filter vintage items. Accepted values: true, false. |
| `max_price` | string | No | Maximum price filter value. |
| `min_price` | string | No | Minimum price filter value. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword (e.g. 'leather wallet'). |
| `sort_on` | string | No | Sort order. Accepted values: most_relevant, lowest_price, highest_price, date_desc. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/search_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_handmade":"<string>","is_vintage":"<string>","max_price":"<string>","min_price":"<string>","page":"<integer>","query":"<string>","sort_on":"<string>"}'
```

### search_shops

Search for Etsy shops by keyword. Returns a list of matching shop names and URLs extracted from the search results page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword for shops (e.g. 'jewelry', 'vintage clothing'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-etsy-com-api-9812261a/search_shops \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```