# Checkers — 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.

> Search for groceries, browse product categories, and find Checkers store locations across South Africa all in one place. Get detailed product information, discover popular items, and locate the nearest store to shop conveniently.

**Category:** Food & Dining | **Website:** [checkers.co.za/](https://checkers.co.za/) | **Docs:** [parse.bot/marketplace/aba8c6dd-64c9-4cda-bb5b-f294ac126540/checkers-co-za-api](https://parse.bot/marketplace/aba8c6dd-64c9-4cda-bb5b-f294ac126540/checkers-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-checkers-co-za-api-aba8c6dd/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### find_stores

Find Checkers stores near a geographic coordinate. Returns an array of stores sorted by proximity, each with name, brand (CHECKERS, CHECKERS_HYPER, CHECKERS_LIQUORSHOP, MEDIRITE), full address, geolocation, trading hours, facilities, and departments. Child stores (e.g. LiquorShop inside a Hyper) are nested in the parent's 'children' array.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude of the location (e.g. -33.89 for Cape Town area) |
| `lng` | number | Yes | Longitude of the location (e.g. 18.56 for Cape Town area) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-checkers-co-za-api-aba8c6dd/find_stores \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lng":"<number>"}'
```

### get_category_products

List all products within a specific category or sub-category. Accepts a category ID from list_categories and returns paginated product results with the same shape as search_products. Use totalCount for pagination bounds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID from the list_categories endpoint (e.g. '67075e5eff987811364007e6' for Appliances) |
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number (0-indexed) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-checkers-co-za-api-aba8c6dd/get_category_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","limit":"<integer>","page":"<integer>"}'
```

### get_image_url

Resolve a Checkers image ID to its full CDN URL. Accepts an imageId as returned by product endpoints (imageIds, imageId fields) and category endpoints (imageId field), and returns the complete URL where the image is served. No network request is made to the image host; this is a pure URL construction.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `image_id` | string | Yes | Image identifier as returned by product and category endpoints (e.g. '6a5973a6f76689d8c79e254f') |

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

### get_popular_searches

Retrieve the most popular search terms on the Checkers site, ranked by cumulative search count. Each term includes its count and an updatedOn timestamp. Useful for discovering trending products or auto-suggesting search queries.

**Estimated cost:** Metered

_No parameters required._

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

### get_product_details

Retrieve full details for a single product by its URL slug. The slug format is the product name lowercased with spaces replaced by hyphens, followed by the article number and 'EA' (e.g. 'clover-fresh-full-cream-milk-2l-10136729EA'). Returns nutritional info, ingredients, allergens, images, stock, and pricing.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Product URL slug in format '<product-name-hyphenated>-<articleNumber>EA' (e.g. 'clover-fresh-full-cream-milk-2l-10136729EA') |

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

### list_categories

Retrieve the full product department and category hierarchy as a tree structure. Returns all categories up to 3 levels deep (departments → categories → sub-categories). Each node includes its ID, name, level, and nested children. Use category IDs from this tree as input to get_category_products.

**Estimated cost:** Metered

_No parameters required._

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

### search_products

Full-text search over all Checkers products by keyword. Returns a paginated list of products with prices (in ZAR cents), stock availability, images, promotions, and nutritional attributes. Results include a totalCount field for pagination. Each product exposes a slug-compatible identifier (lowercase name + articleNumber + 'EA') usable with get_product_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number (0-indexed) |
| `query` | string | Yes | Search keyword (e.g. 'milk', 'bread', 'chips') |

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