# Sainsbury’s Grocery Price & Availability (`dromb/sainsburys-uk-grocery-price-availability`) Actor

- **URL**: https://apify.com/dromb/sainsburys-uk-grocery-price-availability.md
- **Developed by:** [Dmitriy Gyrbu](https://apify.com/dromb) (community)
- **Categories:** Automation, Developer tools, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.60 / 1,000 dataset items

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/platform/actors/running/actors-in-store#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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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

## Sainsbury's UK Grocery Scraper

Extract structured Sainsbury's UK grocery products, prices, availability, categories, reviews, recommendations, and product batches. Use the data for price monitoring, assortment research, product discovery, promotion tracking, and catalogue enrichment.

### Disclaimer

This Actor is an unofficial tool for accessing public Sainsbury's UK grocery data.
It is not affiliated with, endorsed by, or connected to Sainsbury's in any way.
Use responsibly and respect rate limits and site changes.

### Why use this scraper?

- Monitor current, unit, and previous prices where publicly exposed.
- Research product availability, promotions, and assortment changes.
- Export products, categories, reviews, and recommendations as JSON, CSV, Excel, or through the Apify API.
- Resolve multiple known product slugs in one ordered batch.

### Supported Modes

- **search**: Search for products by keyword
- **item**: Get product information by SEO slug
- **category**: Get products in a category
- **categories**: Get the category tree
- **taxonomy**: Get the product taxonomy
- **recommendations**: Get product recommendations
- **reviews**: Get product reviews
- **batch**: Process multiple product slugs in one run

### Supported Data

- current price
- unit price
- previous price where genuinely exposed
- availability
- product identity
- promotions where exposed

### Not Supported In This Version

- Nectar pricing
- personalized "Your Nectar Prices"
- postcode-specific pricing
- store-specific pricing
- paid-proxy portability guarantee

### Input Schema

#### Common Fields

- `mode` (required): The operation mode
- `proxyConfiguration` (optional): Proxy configuration object

#### Mode-Specific Inputs

##### search
- `query` (required): Search keyword
- Default page size: 60
- `maxResults` (optional): Result cap, default 60, maximum 600
- `maxPages` (optional): Page cap, default 1, maximum 10
- `pageStart` (optional): Starting page, default 1

##### item
- `productSlug` (required): Product SEO slug, for example `gb/groceries/sainsburys-british-semi-skimmed-milk-2-27l-4-pint`
- Must be raw, not percent-encoded

##### category
- `query` (optional): Search keyword within category
- `categoryId` (optional): Category ID
- Default page size: 60
- `maxResults`, `maxPages`, and `pageStart` use the same bounded pagination contract as search

##### categories
No additional inputs required

##### taxonomy
No additional inputs required

##### recommendations
- `productId` (required): Product ID
- Default limit: 18

##### reviews
- `productId` (required): Product ID
- Default limit: 10

##### batch
- `items` (required): Non-empty array of product SEO slugs
- Processes each slug independently
- Returns both successful and failed results

### Output Schema

#### Dataset Envelope

Each Dataset record includes:
- `mode`: Actor mode that generated the record
- `success`: Whether the operation succeeded
- `recordType`: Type of record (product, category, taxonomy, recommendation, review, error)
- `data`: Record data when `success=true`
- `error`: Error details when `success=false`
- `warnings`: Warning messages
- `source`: Endpoint identifier (E1-E7)
- `fetchedAt`: ISO 8601 timestamp

#### Key-Value Store Summary

The run summary is stored in KVS under the `summary` key:
- `status`: Run status
- `mode`: Actor mode executed
- `count`: Number of records generated

### Pricing

This Actor uses Apify Pay per event pricing. The current price for your plan is shown by Apify before you start a run.

- Every row written to the default Dataset is a billable result.
- A structured error row produced for an invalid item inside a batch is also a billable Dataset item.
- Run summaries stored in the default key-value store are not billed separately.

### Pricing And Location Disclosure

- **Status**: DEFAULT_OR_UNKNOWN_PRICE_CONTEXT unless explicitly verified
- **Postcode-specific pricing**: Not supported
- **Store-specific pricing**: Not supported
- **Availability and prices**: Can change over time
- **Nectar pricing**: Not included in this version

### Proxy and access behavior

Direct access is the proven default. Optional Apify proxy configuration can be supplied for blocked or location-sensitive runs, but paid-proxy portability is not guaranteed. Keep result and page limits bounded to reduce upstream load.

### Error Handling

#### Error Types
- **`validation_error`**: Invalid input such as unsupported mode or missing required field
- **`http_error`**: HTTP error response such as 400, 403, 404, or 500
- **`transport_error`**: Network or transport failure such as timeout or DNS failure

#### Batch Behavior
- Processes each item independently
- Returns both successful and failed results
- Preserves duplicate valid inputs and valid input order
- Does not fail the entire run on individual item failures

#### Zero-Row Cases
- Recommendations may validly return zero rows
- Reviews may validly return zero rows

### Usage Examples

#### Search
```json
{
  "mode": "search",
  "query": "milk"
}
````

#### Item

```json
{
  "mode": "item",
  "productSlug": "gb/groceries/sainsburys-british-semi-skimmed-milk-2-27l-4-pint"
}
```

#### Batch

```json
{
  "mode": "batch",
  "items": [
    "gb/groceries/sainsburys-british-semi-skimmed-milk-2-27l-4-pint",
    "gb/groceries/sainsburys-british-whole-milk-2-27l-4-pint"
  ]
}
```

### Limitations

- No real-time data guarantee
- No nationwide uniform price guarantee
- No postcode-specific pricing
- No store-specific pricing
- No paid proxy portability guarantee

# Actor input Schema

## `mode` (type: `string`):

Choose one operation per run

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

Search keyword for search and category modes

## `productSlug` (type: `string`):

Required for item mode; use the raw Sainsbury's product SEO slug

## `categoryId` (type: `string`):

Category ID for category mode

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

Required for recommendations and reviews modes

## `items` (type: `array`):

Required non-empty list of raw product SEO slugs for batch mode

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

Search/category result cap; default 60, maximum 600

## `maxPages` (type: `integer`):

Search/category page cap; default 1, maximum 10

## `pageStart` (type: `integer`):

First search/category page; default 1

## `proxyConfiguration` (type: `object`):

Proxy configuration object

## Actor input object example

```json
{
  "mode": "search",
  "query": "milk",
  "productSlug": "gb/groceries/sainsburys-british-semi-skimmed-milk-2-27l-4-pint",
  "categoryId": "12151",
  "productId": "357937",
  "items": [
    "gb/groceries/sainsburys-british-semi-skimmed-milk-2-27l-4-pint"
  ]
}
```

# Actor output Schema

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

Structured Sainsbury’s grocery, category, taxonomy, recommendation, review, or error records produced by the selected mode.

## `summary` (type: `string`):

Execution summary stored in the default key-value store.

# 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 = {
    "query": "milk"
};

// Run the Actor and wait for it to finish
const run = await client.actor("dromb/sainsburys-uk-grocery-price-availability").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 = { "query": "milk" }

# Run the Actor and wait for it to finish
run = client.actor("dromb/sainsburys-uk-grocery-price-availability").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "query": "milk"
}' |
apify call dromb/sainsburys-uk-grocery-price-availability --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=dromb/sainsburys-uk-grocery-price-availability",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Sainsbury’s Grocery Price & Availability",
        "version": "0.3",
        "x-build-id": "QazEZfOpqL3zKHPZ5"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/dromb~sainsburys-uk-grocery-price-availability/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-dromb-sainsburys-uk-grocery-price-availability",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/dromb~sainsburys-uk-grocery-price-availability/runs": {
            "post": {
                "operationId": "runs-sync-dromb-sainsburys-uk-grocery-price-availability",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/dromb~sainsburys-uk-grocery-price-availability/run-sync": {
            "post": {
                "operationId": "run-sync-dromb-sainsburys-uk-grocery-price-availability",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "mode"
                ],
                "properties": {
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "search",
                            "item",
                            "category",
                            "categories",
                            "taxonomy",
                            "recommendations",
                            "reviews",
                            "batch"
                        ],
                        "type": "string",
                        "description": "Choose one operation per run",
                        "default": "search"
                    },
                    "query": {
                        "title": "Search Query",
                        "type": "string",
                        "description": "Search keyword for search and category modes"
                    },
                    "productSlug": {
                        "title": "Product Slug (SEO)",
                        "type": "string",
                        "description": "Required for item mode; use the raw Sainsbury's product SEO slug"
                    },
                    "categoryId": {
                        "title": "Category ID",
                        "type": "string",
                        "description": "Category ID for category mode"
                    },
                    "productId": {
                        "title": "Product ID",
                        "type": "string",
                        "description": "Required for recommendations and reviews modes"
                    },
                    "items": {
                        "title": "Batch Items (SEO Slugs)",
                        "minItems": 1,
                        "type": "array",
                        "description": "Required non-empty list of raw product SEO slugs for batch mode",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "Maximum Results",
                        "minimum": 1,
                        "maximum": 600,
                        "type": "integer",
                        "description": "Search/category result cap; default 60, maximum 600"
                    },
                    "maxPages": {
                        "title": "Maximum Pages",
                        "minimum": 1,
                        "maximum": 10,
                        "type": "integer",
                        "description": "Search/category page cap; default 1, maximum 10"
                    },
                    "pageStart": {
                        "title": "Starting Page",
                        "minimum": 1,
                        "type": "integer",
                        "description": "First search/category page; default 1"
                    },
                    "proxyConfiguration": {
                        "title": "Proxy Configuration",
                        "type": "object",
                        "description": "Proxy configuration object"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```