Williams-Sonoma APIwilliams-sonoma.com ↗
Search and browse Williams-Sonoma products by keyword or category. Retrieve pricing, descriptions, images, tags, and facets via 3 structured endpoints.
What is the Williams-Sonoma 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.
curl -X GET 'https://api.parse.bot/scraper/750a5533-f008-4473-9fd4-e7f12fa89b8c/search_products?limit=5&query=cookware&offset=0' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace williams-sonoma-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Williams-Sonoma Product API — search, browse by category, drill into details."""
from parse_apis.williams_sonoma_product_api import WilliamsSonoma, CategoryId, ProductNotFound
client = WilliamsSonoma()
# Search the catalog for cookware; limit caps total items fetched.
for product in client.products.search(query="cookware", limit=3):
print(product.title, product.price, product.regular_price)
# Browse a specific category using the CategoryId enum.
category = client.category(CategoryId.COOKWARE_SETS)
for item in category.products(limit=3):
print(item.title, item.price, item.brand)
# Drill into a summary for the full product record.
summary = client.products.search(query="espresso", limit=1).first()
if summary:
print(summary.title, summary.product_url)
# Fetch a single product by slug directly; handle not-found.
try:
detail = client.products.get(product_id="chef-classic-ss-11-piece-cookware-set")
print(detail.title, detail.price, detail.additional_info)
except ProductNotFound as exc:
print(f"Product not found: {exc.product_id}")
print("exercised: products.search / products.get / category.products / ProductNotFound")
Full-text search across the Williams-Sonoma product catalog. Returns paginated results ordered by relevance. Each product includes pricing, description snippet, category tags, and a slug ID usable with get_product_details for the full record.
| 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": 5,
"total": 1026,
"offset": 0,
"products": [
{
"tags": [
"cookware-in-stock",
"college-cookware-electrics",
"cookware-best-sellers"
],
"brand": null,
"price": 209.95,
"title": "Cuisinart Chef's Classic Stainless Steel 11-Piece Cookware Set",
"facets": [
{
"name": "avlIn12W",
"values": [
1208
]
}
],
"image_url": "https://assets.wsimgs.com/wsimgs/rk/images/dp/wcm/202617/0371/img2c.jpg",
"product_id": "chef-classic-ss-11-piece-cookware-set",
"description": "Inspired by the equipment used in professional French kitchens...",
"product_url": "https://www.williams-sonoma.com/products/chef-classic-ss-11-piece-cookware-set/",
"regular_price": 290
}
]
},
"status": "success"
}
}About the Williams-Sonoma API
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.
The Williams-Sonoma API is a managed, monitored endpoint for williams-sonoma.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when williams-sonoma.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official williams-sonoma.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.