# Aldi Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/aldi/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/aldi-search |

## Description

Aldi Search API: list products from an Aldi category page URL or path across FR, DE, NL and Canarias shops. Returns prices, thumbnails and pagination.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/aldi/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Poisson & crustacés category on aldi.fr (page 1)

```json
{
  "results": [
    {
      "url": "https://www.aldi.fr/fiches-produits/dos-de-cabillaud-9855.html",
      "brand": "GOLDEN SEAFOOD®",
      "price": 9.99,
      "title": "Dos de cabillaud",
      "images": [
        "https://s7g10.scene7.com/is/image/aldinord/9855.main.01.freezer.gp2024",
        "https://s7g10.scene7.com/is/image/aldinord/Label_peche_durable_msc"
      ],
      "category": "Viandes et poissons > Poissons et crustacés",
      "currency": "EUR",
      "image_url": "https://s7g10.scene7.com/is/image/aldinord/9855.main.01.freezer.gp2024",
      "product_id": "9855",
      "sales_unit": "540G",
      "product_slug": "dos-de-cabillaud-9855",
      "short_description": "Régalez-vous avec notre délicieux dos de cabillaud…"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 46,
    "total_pages": 1,
    "total_results": 46
  }
}
```

## Documentation

## Overview
The **Aldi Search API** returns product listings from an Aldi **category page**. Pass a **category URL** or **site path**, optionally with **`region`** and **`page`**, and receive structured JSON with prices, thumbnails, brand, and pagination.

Piloterr fetches the SSR HTML and parses the embedded Next.js payload (`#__NEXT_DATA__`). Algolia initial results, no browser rendering required.

Use each result `url` with [Aldi Product](https://www.piloterr.com/library/aldi-product) for full PDP data.

## Supported regions
Default: `fr` → `www.aldi.fr`.

| `region` | Domain | Search (Algolia SSR) | Product URL pattern | Aliases |
|---|---|---|---|---|
| `fr` | aldi.fr | OK | `/fiches-produits/{slug}.html` | `fr-fr` |
| `de` | aldi-nord.de | OK | `/p/{slug}.html` | `de-de`, `aldi-nord` |
| `nl` | aldi.nl | Partial (0 hits SSR) | `/product/{slug}.html` | `nl-nl` |
| `es-can` | aldi.es/can/… | Partial (homepage) | `/can/producto/{slug}.html` | `can`, `canarias` |

Only these four Aldi domains are supported. Other Aldi URLs return **400**.

When `query` is a full Aldi URL, domain and region are detected automatically (`region` is ignored).

## Quickstart
```
GET https://api.piloterr.com/v2/aldi/search?query=produits/viande-poisson/poisson-crustace.html
GET https://api.piloterr.com/v2/aldi/search?query=https://www.aldi.fr/produits/viande-poisson/poisson-crustace.html
GET https://api.piloterr.com/v2/aldi/search?query=produits/viande-poisson/poisson-crustace.html&page=2
GET https://api.piloterr.com/v2/aldi/search?query=/p/fleisch-fisch.html&region=de
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Category page URL or site path (not a product URL) |
| `region` | string | no | Country when `query` is a path only (default: `fr`) |
| `page` | integer | no | 1-based page override (default: from URL or `1`) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Response: each listing (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Aldi product id |
| `title` | string | Product title |
| `url` | string | Absolute product URL |
| `image_url` | string \| null | Main image |
| `images` | string[] \| null | Gallery when multiple images |
| `price` | number \| null | Current price (may be absent on some hits) |
| `currency` | string | ISO currency |
| `brand` | string \| null | Brand name |
| `sales_unit` | string \| null | Pack size / unit |
| `short_description` | string \| null | Card teaser text |
| `category` | string \| null | Algolia breadcrumb path |
| `product_slug` | string \| null | URL slug |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page |
| `total_results` | integer \| null | Total matches (`nbHits`) |
| `total_pages` | integer \| null | Total pages (`nbPages`) |
| `next` | string \| null | Next page URL |

## Aldi workflow
1. [Aldi Search](https://www.piloterr.com/library/aldi-search): list category products (this endpoint)
2. [Aldi Product](https://www.piloterr.com/library/aldi-product): full PDP JSON

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query`, unsupported domain, or product URL passed to search |
| `404` | Page without `#__NEXT_DATA__` or no parseable listings |
| `500` | Network or parsing error |

## Notes
- `price` may be `null` when Aldi does not publish a price on the Algolia hit.
- Canarias queries must stay under the `/can/` path prefix on `aldi.es`.
- Costs **1 credit** per call (HTTP crawler).

## Main use cases
- **Category harvesting**: collect product ids and URLs from Aldi aisles
- **Price monitoring**: track Aldi promotions across FR / DE / NL / Canarias
- **Retail intel**: compare assortment before fetching full PDP data