> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visita.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Retail API

> Access retail product and pricing intelligence

# Retail API

Access real-time and historical pricing data for retail products across major South African retailers.

## Search Products

```http theme={null}
GET /api/v1/retail/products
```

### Query Parameters

| Parameter      | Type    | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| `search`       | string  | Search name, description, or brand          |
| `brand`        | string  | Filter by brand name                        |
| `category`     | string  | Filter by category                          |
| `store`        | string  | Filter by store name                        |
| `onlySpecials` | boolean | Only return products on special             |
| `sortBy`       | string  | `newest`, `price_asc`, `price_desc`, `name` |
| `page`         | number  | Page number (default: 1)                    |
| `limit`        | number  | Results per page (max: 100)                 |

### Example Request

```bash theme={null}
curl -H "x-api-key: your_key" \
  "https://visita.co.za/api/v1/retail/products?search=milk&onlySpecials=true"
```

## Get Product Details

```http theme={null}
GET /api/v1/retail/products/:id
```

Returns full product information including:

* Canonical product data
* Current listings across all tracked stores
* Historical pricing data for trend analysis
* **Enrichment Metadata**: Nutrition facts, ingredients, and Eco-Score from OpenFoodFacts (where available).

### Example Response

```json theme={null}
{
  "id": "8db036a7-0cfd-48a0-bab8-1c39eee3259e",
  "name": "Verification Snickers",
  "barcode": "5000159418547",
  "enrichment": {
    "nutrition": {
      "nutriments": { "energy-kj_100g": 2023, "fat_100g": 23, "sugars_100g": 51 },
      "nutritionGrades": "e"
    },
    "ingredients": {
      "ingredientsText": "Sugar, peanuts, glucose syrup, skimmed milk powder...",
      "allergens": ["en:peanuts", "en:milk", "en:soya"]
    },
    "ecoScore": { "grade": "d", "score": 38 },
    "servingSize": "50g",
    "productType": "food"
  },
  "listings": [ ... ],
  "history": [ ... ]
}
```

## Retail Statistics

```http theme={null}
GET /api/v1/retail/stats
```

Returns platform-wide retail metrics such as `totalProducts`, `activeSpecials`, and `trackedStores`.

## Retail Pulse Analytics (Enterprise/Pro)

Access deep-dive market intelligence through our analytics endpoints. These require the `read:retail:analytics` permission.

### Category Price Trends

```http theme={null}
GET /api/v1/retail/analytics/trends
```

Returns historical monthly average price data by category. Useful for identifying inflation patterns or category-level pricing shifts.

### Store Promotion Density

```http theme={null}
GET /api/v1/retail/analytics/promotions
```

Returns the percentage of products on special per store. Useful for competitor analysis and store positioning research.

## Filter Options

```http theme={null}
GET /api/v1/retail/filters
```

Returns available filter values to assist in UI building:

* `brands`: List of unique brands
* `categories`: List of product categories
* `stores`: List of all tracked stores

<Info>
  Retail data is aggregated from major retailers (Checkers, Pick n Pay, etc.) and updated daily.
</Info>

```http theme={null}
GET /api/v1/retail/filters
```

Returns available filter values to assist in UI building:

* `brands`: List of unique brands
* `categories`: List of product categories
* `stores`: List of all tracked stores

<Info>
  Retail data is aggregated from major retailers (Checkers, Pick n Pay, etc.) and updated daily.
</Info>