williams-sonoma.com APIwilliams-sonoma.com ↗
Search and browse Williams-Sonoma products by keyword or category. Retrieve pricing, descriptions, images, tags, and facets via 3 structured endpoints.
curl -X GET 'https://api.parse.bot/scraper/750a5533-f008-4473-9fd4-e7f12fa89b8c/search_products?limit=3&query=knives&offset=0' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for products by keyword with pagination. Returns a list of matching products with pricing, descriptions, and category tags.
| Param | Type | Description |
|---|---|---|
| limit | integer | Number of results per page. |
| queryrequired | string | Search keyword (e.g. 'cookware', 'knives', 'espresso') |
| offset | integer | Pagination offset (number of results to skip). |
{
"type": "object",
"fields": {
"limit": "integer number of results requested",
"total": "integer total number of matching products",
"offset": "integer current pagination offset",
"products": "array of product objects with product_id, title, image_url, product_url, price, regular_price, description, tags, facets, and brand"
},
"sample": {
"data": {
"limit": 3,
"total": 817,
"offset": 0,
"products": [
{
"tags": [
"cutlery-chef-knives",
"in-stock-ready-to-ship"
],
"brand": null,
"price": 135,
"title": "WÜSTHOF Classic Chef's Knife",
"facets": [
{
"name": "productType",
"values": [
"Chef's Knives"
]
}
],
"image_url": "https://assets.wsimgs.com/wsimgs/rk/images/dp/wcm/202608/0014/img167c.jpg",
"product_id": "wusthof-classic-chefs-knife",
"description": "The most indispensable of knives...",
"product_url": "https://www.williams-sonoma.com/products/wusthof-classic-chefs-knife/",
"regular_price": 135
}
]
},
"status": "success"
}
}About the williams-sonoma.com API
The Williams-Sonoma API covers 3 endpoints for searching, browsing, and retrieving detailed product data from williams-sonoma.com. The search_products endpoint accepts a keyword query and returns matching products with current prices, regular prices, descriptions, tags, and facets. The get_product_details endpoint exposes 10 fields per product including brand, image URL, and structured facet arrays — useful for building price trackers, comparison tools, or product catalogs.
Endpoints and What They Return
The API provides three endpoints: search_products, browse_category, and get_product_details. All three return product objects sharing the same field set — product_id, title, image_url, product_url, price, regular_price, description, tags, facets, and brand. The price field reflects the current or sale price, while regular_price holds the pre-discount value, making it straightforward to detect marked-down items.
Search and Browse
search_products takes a required query string (e.g. 'cookware', 'espresso', 'knives') plus optional limit and offset integers for pagination. The response includes a total count of all matching products alongside the paginated products array. browse_category works the same way but takes a category_id slug instead — for example 'cookware-sets', 'electrics', or 'espresso-makers' — letting you enumerate all products within a specific department without a free-text query.
Product Detail
get_product_details accepts a product_id slug (e.g. 'wusthof-classic-chefs-knife') obtained from either of the listing endpoints and returns the full product record. This includes the facets array — structured attribute pairs such as material, color, or capacity — and the tags array containing category classification strings. The brand field is returned as a string or null, and description provides the full product copy as plain text.
- Build a Williams-Sonoma price tracker that monitors the gap between
priceandregular_priceto surface discounted items. - Populate a kitchen equipment catalog by iterating
browse_categoryover slugs like'cookware-sets'and'electrics'. - Power a product comparison tool using
get_product_detailsto pull facets like material and capacity side by side. - Sync Williams-Sonoma product images and descriptions into an internal PIM using
image_urlanddescriptionfields. - Build a keyword-driven shopping assistant that queries
search_productsand returns ranked results with pricing. - Aggregate brand-level product listings by filtering the
brandfield across paginatedsearch_productsresults.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Williams-Sonoma offer an official developer API?+
What does the `facets` field contain in a product response?+
facets field is an array of objects, each with a name and values key. These represent structured product attributes — things like material, finish, or item dimensions — that Williams-Sonoma surfaces alongside the product listing. The exact facets vary by product type.How does pagination work across `search_products` and `browse_category`?+
limit (number of results to return) and offset (number of results to skip). The response always includes a total field representing the full match count, so you can calculate how many pages exist and iterate through them systematically.Does the API return customer reviews or ratings for products?+
Can I filter `search_products` results by brand or price range directly in the request?+
search_products endpoint accepts only a query string plus pagination parameters — there are no built-in filter parameters for brand, price range, or facet values. Filtering on those fields requires post-processing the returned brand, price, and facets fields client-side. You can fork this API on Parse and revise it to add server-side filter parameters.