Woolworths APIwoolworths.com.au ↗
Access Woolworths supermarket product data: search, category browse, nutritional details, specials, and autocomplete — all via a single structured API.
What is the Woolworths API?
The Woolworths API covers 6 endpoints that expose product search, category browsing, full product detail (including nutritional info and allergens), and current specials from woolworths.com.au. The get_product_detail endpoint returns over a dozen fields per product — barcode, health star rating, country of origin, ingredients, and category hierarchy — identified by a numeric stockcode from search results.
curl -X POST 'https://api.parse.bot/scraper/d5aff3d6-33c4-431f-bf9d-6191efaec2e6/search_products' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"page": "1",
"page_size": "5",
"sort_type": "TraderRelevance",
"is_special": "true",
"search_term": "milk"
}'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 woolworths-com-au-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.
"""Walkthrough: Woolworths SDK — search products, browse categories, get details."""
from parse_apis.woolworths_australia_product_api import Woolworths, Sort, IsSpecial, ProductNotFound
client = Woolworths()
# Search for milk products sorted by price, capped at 5 results.
for product in client.products.search(query="milk", sort=Sort.PRICE_ASC, limit=5):
print(product.name, product.price, product.cup_string)
# Get autocomplete suggestions for a partial term.
result = client.products.suggestions(query="choc")
print(result.suggestions, result.auto_corrected_term)
# Browse current specials on chocolate — take one item.
special = client.products.specials(query="chocolate", limit=1).first()
if special:
print(special.name, special.price, special.savings_amount)
# Get full product details via the productdetails collection.
if special:
try:
detail = client.productdetails.get(stockcode=str(special.stockcode))
print(detail.name, detail.country_of_origin, detail.health_star_rating)
except ProductNotFound as exc:
print(f"Product gone: {exc.stockcode}")
# List categories and drill into one.
cat = client.categories.list(limit=1).first()
if cat:
for p in cat.products(category_url=cat.url_friendly_name, sort=Sort.PRICE_DESC, limit=3):
print(p.name, p.brand, p.price)
print("exercised: products.search / products.suggestions / products.specials / productdetails.get / categories.list / category.products")
Search for products by keyword with pagination and sorting. Returns matching products with pricing, availability, and stock information. Paginates via page number; total_products gives the full count of matching results across all pages.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| page_size | integer | Number of products per page. |
| sort_type | string | Sort order for results. |
| is_special | string | Filter to only show products on special. Accepts: true, false. |
| search_term | string | Search query term. |
{
"type": "object",
"fields": {
"page": "integer - current page number",
"products": "array of product objects with stockcode, name, brand, price, was_price, cup_price, cup_measure, cup_string, package_size, is_on_special, savings_amount, is_in_stock, is_available, image_url, url_friendly_name",
"page_size": "integer - items per page",
"search_term": "string - the query used",
"total_products": "integer - total matching products across all pages"
},
"sample": {
"data": {
"page": 1,
"products": [
{
"name": "Woolworths Full Cream Milk 3L",
"brand": "Woolworths",
"price": 5.15,
"cup_price": 1.72,
"image_url": "https://cdn1.woolworths.media/content/wowproductimages/medium/888140.jpg",
"stockcode": 888140,
"was_price": 5.15,
"cup_string": "$1.72 / 1L",
"cup_measure": "1L",
"is_in_stock": true,
"is_available": true,
"package_size": "3L",
"is_on_special": false,
"savings_amount": 0,
"url_friendly_name": "woolworths-full-cream-milk"
}
],
"page_size": 5,
"search_term": "milk",
"total_products": 309
},
"status": "success"
}
}About the Woolworths API
Search and Browse Products
The search_products endpoint accepts a search_term and returns paginated product listings including price, was_price, cup_price, cup_measure, and package_size. You can sort results using sort_type (e.g. PriceAsc, CUPDesc) and filter to on-sale items only by setting is_special to true. The response includes total_products so you can calculate pagination offsets with page and page_size.
The list_categories endpoint returns the full Woolworths category tree — departments, categories, and subcategories — each with a node_id and url_friendly_name. Pass those values as category_id and category_url to get_category_products to browse a specific section of the store. The same sort and pagination controls from search_products are available here.
Product Detail and Nutritional Data
get_product_detail takes a stockcode (a numeric ID from any product listing response) and returns the complete product record: images array, barcode, brand, unit, is_new flag, and a nested category object with department, category, and subcategory fields. Nutritional information, ingredients, allergens, and health star rating are included where the product record carries them.
Specials and Suggestions
get_specials filters the product catalogue to currently promoted items. It requires a search_term to scope results — passing 'milk' or 'bread' returns only specials in that segment rather than the full promotions list. For autocomplete workflows, search_suggestions accepts a partial term and returns up to 10 suggestion strings along with an auto_corrected_term field for typo handling.
The Woolworths API is a managed, monitored endpoint for woolworths.com.au — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when woolworths.com.au 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 woolworths.com.au 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?+
- Track price changes on specific products by comparing
priceandwas_pricefields over time - Build a grocery price comparison tool using
cup_priceandcup_measureacross similar products - Monitor current specials in a category by combining
list_categorieswithget_specials - Populate a nutrition database using allergens, ingredients, and health star rating from
get_product_detail - Implement a store search bar backed by
search_suggestionsfor real-time autocomplete - Audit category hierarchy for catalogue mapping by walking the
list_categoriesresponse tree - Alert users when a tracked stockcode drops in price by polling
get_product_detailperiodically
| 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 Woolworths have an official developer API?+
What fields does get_product_detail return beyond basic pricing?+
price, brand, and unit, the endpoint returns barcode, images (array of URLs), is_new, a nested category object with department, category, and subcategory strings, and cup_price. Where available, the product record also includes nutritional information, ingredients, allergens, and a health star rating.Does get_specials return all current Woolworths promotions at once?+
get_specials requires a search_term parameter to scope which specials are returned. Passing an empty or broad term may return limited results. To cover the full specials catalogue, you would need to call the endpoint multiple times with different search terms or category keywords. The API covers paginated specials within a given search scope. You can fork it on Parse and revise to add a category-scoped specials endpoint using category_id from list_categories.Is store availability or click-and-collect stock level data included?+
price, was_price, cup_price, and an is_on_sp flag but do not include per-store stock levels or click-and-collect availability. You can fork it on Parse and revise to add a store-availability endpoint if that data becomes accessible.How does pagination work across the listing endpoints?+
search_products, get_category_products, and get_specials all accept page and page_size parameters. search_products and get_specials return total_products in the response; get_category_products returns total_record_count. Divide the total by page_size to calculate the number of pages to iterate.