# Woolworths AU Product Lookup API – AI & MCP (`dromb/woolworths-au-product-lookup-ai-mcp-unofficial`) Actor

Fast Woolworths Australia product search and single-item lookup with normalized prices, specials, availability, IDs, and item details for AI agents, MCP, and APIs.

- **URL**: https://apify.com/dromb/woolworths-au-product-lookup-ai-mcp-unofficial.md
- **Developed by:** [Dmitriy Gyrbu](https://apify.com/dromb) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Woolworths AU Product Lookup API – AI & MCP

Fast, low-overhead **Woolworths Australia product search and single-product lookup for AI agents, MCP tools, API workflows, and chat assistants**. It returns a compact, normalized JSON contract with explicit current price, regular price, unit price, stock/availability, specials, identifiers, links, and item-level enrichment.

**Best for 1–7 product results per call.** Search is hard-capped at 10 results. For 8+ products, category crawling, catalog extraction, scheduled monitoring, or bulk research, use the full **dromb/woolworths-au-product-search-catalog-unofficial** Actor instead.

### Choose the right Actor

| Need | Recommended Actor |
|---|---|
| 1–7 products | **This AI Lookup Actor** |
| One exact product | **This AI Lookup Actor** |
| MCP / AI agent / chatbot tool call | **This AI Lookup Actor** |
| 8+ products | `dromb/woolworths-au-product-search-catalog-unofficial` |
| Categories / taxonomy / broad monitoring | `dromb/woolworths-au-product-search-catalog-unofficial` |
| Bulk catalog or research workflows | `dromb/woolworths-au-product-search-catalog-unofficial` |

### Agent quick start

#### Search

```json
{
  "operation": "search",
  "query": "full cream milk",
  "maxResults": 5
}
```

The Actor returns at most `maxResults` **product** records. The default is 5 and the maximum is 10.

#### Exact item lookup

```json
{
  "operation": "item",
  "productId": "6073909"
}
```

You can use `url` instead of `productId`. For `item`, provide exactly one of these two fields, not both.

```json
{
  "operation": "item",
  "url": "https://www.woolworths.com.au/..."
}
```

A common agent flow is:

`search → select the best candidate → item`

Use the returned `productId` from search for the follow-up item call.

Search responses deliberately omit rich enrichment (`description`, `ingredients`, `allergens`, `nutrition`) to reduce token overhead. Call `item` for those fields.

### Input contract

| Field | Type | Purpose |
|---|---|---|
| `operation` | `search` or `item` | Select a bounded workflow |
| `query` | string | Required for `search` |
| `maxResults` | integer 1–10 | Search result cap; default 5 |
| `productId` | string | Exact item identifier; use exactly one of `productId` / `url` for item |
| `url` | string | Exact product URL alternative; use exactly one of `productId` / `url` for item |

No category crawler, raw payload, reverse-barcode experiment, pagination control, or other bulk-only fields are exposed here. The small schema is intentional so agents can choose and call the tool reliably.

### Output contract for AI agents

Every product result uses the same normalized field names:

- `currentPrice` — current effective AUD price; this is the price to quote as the present price.
- `regularPrice` — previous/regular AUD price only when an active discount is known; otherwise `null`.
- `unitPrice`, `unitQuantity`, `unitUnit` — comparable unit-pricing fields when available.
- `onSpecial`, `promotionType`, `promotionLabel` — promotion signals.
- `inStock` — `true`/`false` when known; **`null` means unknown, not false**.
- `productId`, `productUrl`, `barcode` — identifiers for follow-up work.
- `description`, `ingredients`, `allergens`, `nutrition` — intentionally `null` in search results to keep agent payloads compact; populated by `item` lookup when available.
- `fetchedAt` — UTC timestamp for this lookup.
- `query` — populated for search; always `null` for direct item lookups.

The Dataset Schema includes `title`, `description`, and `example` metadata for each field so MCP/LLM clients do not have to guess field semantics.

### No results and failures

A successful lookup with no product match writes a free control record:

```json
{
  "recordType": "status",
  "status": "no_results",
  "message": "No matching Woolworths products were found."
}
```

A real upstream/source failure is **not** disguised as `no_results`: the Actor writes a machine-readable `source_error` status record and fails the run. If a spending limit stops a multi-result response, a `partial_results` status record explains how many product rows were published.

### Pricing design

This Actor is designed for small, agentic calls:

- **Actor start:** target configuration `apify-actor-start` at **$0.00005** per start unit (up to 1 GB memory = one start event).
- **Product result:** target BRONZE price **$0.0014 per successfully published product**.
- Status/error records are **not** `product-result` events.
- Synthetic default Dataset item charging must remain disabled / $0 so status rows stay free.
- No separate enrichment fee.
- Platform usage is intended to be included in the event price (PPE + usage disabled) for predictable agent costs.

The Store pricing panel is authoritative for the active tier prices. For larger result sets, the separate bulk Actor is intentionally cheaper per row.

#### Recommended agent decision flow

1. Inspect the input schema and choose `search` for discovery or `item` for an exact lookup.
2. Start with `maxResults: 3–5` for search.
3. Read Dataset product rows and select by `productId`, `name`, price, and availability.
4. Chain the selected `productId` into `item` when richer details are needed.
5. Treat `recordType: status` as control information, not a product.
6. Treat a failed run with `invalid_input` or `source_error` as a real failure; do not invent product data.

### MCP / agent usage

This Actor is intended to be discoverable through Apify MCP and Apify AI once publication and agentic-payment eligibility are enabled. The tool has a deliberately small input schema and a stable normalized output schema so agents can inspect it, call it, and chain its `productId` into an exact item lookup.

### Reliability and scope

- Australia only (`countryCode=AU`, currency `AUD`).
- Search returns the retailer's current live result set, capped locally to 10.
- Availability can vary by location and time; `null` means the source did not provide a reliable signal.
- Product details and promotions can change after `fetchedAt`.

### Bulk alternative

Use **`dromb/woolworths-au-product-search-catalog-unofficial`** when you need larger searches, categories, catalog-oriented extraction, monitoring, or retailer-specific advanced workflows. The two Actors share the same proven retailer source logic but are packaged and priced for different workloads.

### Unofficial

This is an independent data-access tool and is not affiliated with or endorsed by Woolworths.

# Actor input Schema

## `operation` (type: `string`):

Use search for 1–10 matching products or item for one exact product. For bulk/category workflows use the separate bulk Actor.

## `query` (type: `string`):

Search words for Woolworths Australia, for example 'full cream milk'. Required when operation=search.

## `maxResults` (type: `integer`):

Maximum successful product records returned by search. Optimized for AI calls with 1–7 results; hard limit is 10.

## `productId` (type: `string`):

Exact Woolworths product identifier. Provide exactly one of Product ID or Product URL when operation=item.

## `url` (type: `string`):

Full Woolworths product URL. Provide exactly one of Product URL or Product ID when operation=item.

## Actor input object example

```json
{
  "operation": "search",
  "query": "full cream milk",
  "maxResults": 5,
  "productId": "888140",
  "url": "https://www.woolworths.com.au/shop/productdetails/888140"
}
```

# Actor output Schema

## `results` (type: `string`):

Structured product or status records from the default dataset.

## `runSummary` (type: `string`):

Machine-readable run status, counts, and billing event metadata.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "operation": "search",
    "query": "milk"
};

// Run the Actor and wait for it to finish
const run = await client.actor("dromb/woolworths-au-product-lookup-ai-mcp-unofficial").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "operation": "search",
    "query": "milk",
}

# Run the Actor and wait for it to finish
run = client.actor("dromb/woolworths-au-product-lookup-ai-mcp-unofficial").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "operation": "search",
  "query": "milk"
}' |
apify call dromb/woolworths-au-product-lookup-ai-mcp-unofficial --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dromb/woolworths-au-product-lookup-ai-mcp-unofficial"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/XGVgU6E5dZulR3e16/builds/oDeaI2kU0BSgmzL1x/openapi.json