Etsy API endpoint
Searches Etsy listings across shops for the required keywords `q`, in Etsy's default relevance order. Page with `offset` (default 0) and `limit` (default 36, max 100). The response gives the total match `count`, and each result has listing id, title, URL, image, price, shop name and rating, quantity and sold-out flag. Read `currency`, since it is not fixed to USD.
/etsy/searchQuery parameters:
q (required) — search keywords.offset (optional, default 0) — 0-based result offset.limit (optional, default 36, max 100) — page size.Results are returned in Etsy's default relevance ordering; alternate sort orders are not yet exposed.
Response includes count (total matches) and a results array of listing
cards in the same shape as docs/etsy-shop-listings.md's listings array:
{listing_id, title, url, image, price, price_int, currency, shop_id, shop_name, shop_rating, is_sold_out, quantity}.
Note: price/price_int/currency reflect the request's render locale —
currency is not fixed to USD, so read currency rather than assume a unit.
| Field | Filled in, of 28 checked | Values in the sample |
|---|---|---|
| listing_id | 28 | |
| title | 28 | “Personalized ceramic mug, Handmade heart thumb rest coffee…” and 27 other values |
| url | 28 | etsy.com |
| image | 28 | i.etsystatic.com |
| price | 28 | 22.53 to 80.78, median 40 |
| price_int | 28 | 2,253 to 8,078, median 4,000 |
| currency | 28 | USD in all 28 |
| shop_id | 28 | |
| shop_name | 28 | “MargieGrodskyPottery” and 23 other values |
| shop_rating | 28 | 4.8 to 5, median 4.95 |
| quantity | 28 | 1 to 9,289, median 49 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | Yes | Search keywords | handmade mug | |
| offset | integer | No | 0-based result offset | 0 | |
| limit | integer | No | Page size (default 36, max 100) | 36 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/etsy/search?q=handmade+mug&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"query": "handmade mug",
"offset": 0,
"count": 112886,
"results": [
{
"listing_id": "4474501681",
"title": "Custom Mermaid Mug, Crystal Handle, Mothers Day Gift",
"shop_id": "7894049",
"shop_name": "MerakiDesigned",
"price": "5371901",
"price_int": 5371901,
"currency": "VND",
"url": "https://www.etsy.com/listing/4474501681/handmade-ceramic-mermaid-mug-gold",
"quantity": 7,
"is_sold_out": false
}
]
}
}Request schema
No body schema
Response schema
#/definitions/etsy.searchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | etsy.MobileSearchResponse | No | ||||
| data.count | integer | No | 112886 | |||
| data.offset | integer | No | 0 | |||
| data.query | string | No | handmade mug | |||
| data.results | array | No | ||||
| data.results[].currency | string | No | ||||
| data.results[].image | string | No | ||||
| data.results[].is_sold_out | boolean | No | ||||
| data.results[].listing_id | string | No | 1044347578 | |||
| data.results[].price | string | No | $29.99 | |||
| data.results[].price_int | integer | No | ||||
| data.results[].quantity | integer | No | ||||
| data.results[].shop_id | string | No | ||||
| data.results[].shop_name | string | No | ||||
| data.results[].shop_rating | number | No | ||||
| data.results[].title | string | No | ||||
| data.results[].url | string | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/etsy/search?q=handmade+mug&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"