# Woolworths (South Africa) — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Browse Woolworths South Africa's food categories and search for specific products while accessing detailed nutritional information and weight-based pricing. Find store locations across the country by province and suburb to check availability and plan your shopping trips.

**Category:** Food & Dining | **Website:** [woolworths.co.za/](https://woolworths.co.za/) | **Docs:** [parse.bot/marketplace/94630827-cc4b-4199-91d9-1bf19c8132c3/woolworths-co-za-api](https://parse.bot/marketplace/94630827-cc4b-4199-91d9-1bf19c8132c3/woolworths-co-za-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_food_categories

Retrieves all top-level food categories from Woolworths via Constructor.io browse API. Each category includes a name and group_id suitable for use with get_product_listing. Categories include seasonal collections, product types (Bakery, Frozen Food), and dietary preferences.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/get_food_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_details

Retrieves comprehensive product information including nutritional data, ingredients, allergens, dietary info, images, brand, rating, review count, and pricing. Use the product URL path from search_products or get_product_listing results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_url` | string | Yes | Product URL path from search_products or get_product_listing results (e.g. '/prod/Food/Meat-Poultry-Fish/Poultry/Crumbed/Crumbed-Chicken-Schnitzels-Avg-650-g/_/A-2034180000008'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_url":"<string>"}'
```

### get_product_listing

Retrieves a paginated list of products for a given category. Returns up to 24 products per page with pricing. Use offset to paginate (increments of 24). Each product includes id, name, url, price, price_per_kg, review_count, promo_label, and on_sale flag.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_url` | string | Yes | Category group_id from get_food_categories (e.g. 'ncat0010251', 'cat606522'). |
| `offset` | integer | No | Pagination offset. Results come in pages of 24. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/get_product_listing \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_url":"<string>","offset":"<integer>"}'
```

### get_store_locator_provinces

Retrieves all South African provinces available in the Woolworths store locator. Each province includes an ID, name, and flags for store pickup and liquor delivery availability.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/get_store_locator_provinces \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_store_locator_suburbs

Retrieves all suburbs with their IDs and postal codes for the Woolworths store locator. Use suburb IDs with get_stores_by_suburb to find nearby stores. Returns a large list of suburbs across all provinces.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/get_store_locator_suburbs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_stores_by_suburb

Retrieves Woolworths stores within a specified radius of a suburb. Returns store names, addresses, and phone numbers. Use suburb IDs from get_store_locator_suburbs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `distance` | integer | No | Search radius in km. |
| `suburb_id` | string | Yes | Suburb ID from get_store_locator_suburbs (e.g. '489', '462'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/get_stores_by_suburb \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distance":"<integer>","suburb_id":"<string>"}'
```

### search_products

Full-text search for food products by keyword via Constructor.io. Returns a paginated list of matching products (up to 24 per page) with prices. Use offset to paginate through results in increments of 24.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `offset` | integer | No | Pagination offset. Results come in pages of 24. |
| `query` | string | Yes | Search query (e.g. 'chicken', 'bread', 'organic'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-woolworths-co-za-api-94630827/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offset":"<integer>","query":"<string>"}'
```