Coles APIcoles.com.au ↗
Access Coles.com.au product data including search, category browsing, product details with nutritional info, and current specials via 6 structured endpoints.
What is the Coles API?
The Coles API provides 6 endpoints for retrieving product data from Coles.com.au, Australia's major supermarket chain. Use search_products to find items by keyword, browse by category or subcategory using slug-based navigation, fetch full product details including nutritional information and ingredient lists, and pull paginated lists of current specials with discount pricing.
curl -X GET 'https://api.parse.bot/scraper/dd2897d9-0135-464a-b16a-54ccc10e02e4/search_products?page=1&query=milk' \ -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 coles-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: Coles Supermarket SDK — search, browse, and inspect products."""
from parse_apis.coles_supermarket_api import Coles, ProductNotFound
client = Coles()
# Search for products by keyword, capped to 5 results.
for product in client.products.search(query="milk", limit=5):
print(product.name, product.brand, product.price)
# Drill into a single product's full details via its slug.
item = client.products.search(query="bread", limit=1).first()
if item:
detail = client.products.get(slug=item.slug)
print(detail.name, detail.price, detail.ingredients)
# Browse the category tree and list products in a category.
cat = client.categories.list(limit=1).first()
if cat:
print(cat.name, cat.seo_token)
for p in cat.products(limit=3):
print(p.name, p.price, p.promotion_type)
# List current specials with discount info.
for special in client.specials.list(limit=3):
print(special.name, special.price, special.was_price)
# Handle a product-not-found error gracefully.
try:
client.products.get(slug="nonexistent-product-slug-000000")
except ProductNotFound as exc:
print(f"Not found: {exc.slug}")
print("exercised: products.search / products.get / categories.list / category.products / specials.list")
Full-text search across the Coles product catalog. Matches product name, brand, and description. Returns a paginated list of products sorted by relevance. Each page contains up to 48 products.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| queryrequired | string | Search keyword to match against product name, brand, and description. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"products": "array of product objects with id, name, brand, description, size, availability, price, was_price, unit_price, unit_measure, comparable, promotion_type, image_url, slug",
"page_size": "integer number of products per page (48)",
"total_results": "integer total number of matching products"
},
"sample": {
"data": {
"page": 1,
"products": [
{
"id": 8150288,
"name": "Full Cream Milk",
"size": "3L",
"slug": "coles-full-cream-milk-3l-8150288",
"brand": "Coles",
"price": 5.15,
"image_url": "https://www.coles.com.au/8/8150288.jpg",
"was_price": 0,
"comparable": "$1.72/ 1L",
"unit_price": 1.72,
"description": "COLES FULL CREAM MILK 3L",
"availability": true,
"unit_measure": "1 l",
"promotion_type": null
}
],
"page_size": 48,
"total_results": 144
},
"status": "success"
}
}About the Coles API
Endpoints and Data Coverage
The API covers product search, category navigation, product detail lookup, and promotional pricing. search_products accepts a query string and returns paginated results — each product object includes id, name, brand, price, and a slug that can be passed directly to get_product_details. Pagination is controlled via the page parameter, and total_results lets you calculate how many pages exist for a given query.
Category and Subcategory Browsing
get_all_categories returns the full category tree up to 3 levels deep, with each node exposing an id, name, seoToken (the slug used in other endpoints), and nested catalogGroupView children. Pass a top-level seoToken value such as dairy-eggs-fridge to get_category_products, or pair a parent category with a child slug in get_subcategory_products to narrow results further. All three browsing endpoints return the same paginated product array shape.
Product Details and Nutritional Data
get_product_details takes a slug and returns the most complete record available: current price in AUD, was_price for discounted items (or null if not on sale), an images array, a categories path, an ingredients string, and a nutritional_info object breaking down values per serving and per 100g/ml. This endpoint is the only one that exposes nutritional and ingredient data.
Specials and Promotional Pricing
get_specials returns a paginated feed of currently discounted products. Each result includes both price and was_price, making it straightforward to calculate the discount amount or percentage. The total_results field indicates how many active specials are listed at the time of the request.
The Coles API is a managed, monitored endpoint for coles.com.au — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when coles.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 coles.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 budget tool by searching for items with
search_productsand aggregating current prices - Monitor Coles weekly specials by polling
get_specialsand surfacing new discounts to subscribers - Power a nutrition tracker by pulling
nutritional_infofromget_product_detailsfor scanned or searched items - Populate a recipe costing app by mapping ingredients to Coles products and retrieving live prices
- Audit category structure for retail analysis using the
get_all_categoriesendpoint's three-level hierarchy - Compare brand pricing across a subcategory by iterating
get_subcategory_productsresults and grouping bybrand
| 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 Coles have an official public developer API?+
What does `get_product_details` return that the search and browse endpoints do not?+
get_product_details is the only endpoint that returns ingredients, nutritional_info (with per-serving and per-100g/ml breakdowns), and a full images array. The search and browse endpoints return a summary product object with id, name, brand, price, and slug, but no nutritional or ingredient data.Are store availability or stock levels included in the response?+
Does `get_specials` include all promotional types, such as multi-buy offers or loyalty card prices?+
was_price differs from the current price. Promotional mechanics such as multi-buy deal conditions or Flybuys member-only pricing are not represented as distinct fields. You can fork this API on Parse and revise it to add endpoints that surface those promotional details.How do I get the correct slug for `get_category_products` or `get_subcategory_products`?+
get_all_categories first. Each category object includes a seoToken field that is the slug accepted by the category and subcategory browsing endpoints. For subcategory calls, pass the parent category's seoToken as category and the child node's seoToken as subcategory.