# Pingo Doce — 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.

> Access current promotions, search and explore products with detailed information, locate nearby Pingo Doce stores, and discover recipes from Portugal's leading supermarket. Browse product categories, view digital leaflets, and find the best deals all in one place.

**Category:** Food & Dining | **Website:** [pingodoce.pt/](https://pingodoce.pt/) | **Docs:** [parse.bot/marketplace/d5bd308e-aacb-4494-a877-c009abafe0c5/pingodoce-pt-api](https://parse.bot/marketplace/d5bd308e-aacb-4494-a877-c009abafe0c5/pingodoce-pt-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-pingodoce-pt-api-d5bd308e/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_folhetos

Fetch current and recent promotional leaflets (folhetos) and catalogs from the Pingo Doce website.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pingodoce-pt-api-d5bd308e/get_folhetos \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_categories

Retrieve all top-level product categories available in the store. Returns category names, URLs, and category group IDs where available.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pingodoce-pt-api-d5bd308e/get_product_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_details

Fetch full details for a specific product by its URL. Returns product information including pricing, description, origin (when available), and nutritional data (when available). Some products may not have origin or nutrition information depending on the product type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full product URL (e.g. 'https://www.pingodoce.pt/home/produtos/mercearia/azeite-oleo-e-vinagre/azeite/azeite-virgem-extra-as-nossas-planicies-pingo-doce-654603.html') or path starting with '/'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pingodoce-pt-api-d5bd308e/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### get_promotions

Fetch current promotional products from the store catalog. Returns paginated results of products currently on promotion. Pagination is offset-based via the start parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Category ID for promotions filtering. |
| `limit` | integer | No | Number of products to return per page. |
| `start` | integer | No | Offset for pagination (0-based index of the first result). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pingodoce-pt-api-d5bd308e/get_promotions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","limit":"<integer>","start":"<integer>"}'
```

### get_receitas

Fetch recipes from the Pingo Doce site. Optionally filter by search keyword. Returns recipe titles, URLs, and thumbnail images.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | No | Search keyword for filtering recipes (e.g. 'frango', 'chocolate'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pingodoce-pt-api-d5bd308e/get_receitas \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### get_stores

Find Pingo Doce store locations near a specific coordinate. Returns stores within the given radius sorted by proximity. Each store includes address, services, and opening hours.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | No | Latitude coordinate for the search center. |
| `lng` | number | No | Longitude coordinate for the search center. |
| `radius` | integer | No | Search radius in meters. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pingodoce-pt-api-d5bd308e/get_stores \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lng":"<number>","radius":"<integer>"}'
```

### search_products

Search for products by keyword across the store catalog. Returns paginated results matching the search query. Pagination is offset-based via the start parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of products to return per page. |
| `query` | string | Yes | Search keyword (e.g. 'leite', 'azeite'). |
| `start` | integer | No | Offset for pagination (0-based index of the first result). |

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