# Aldi Product

## Overview

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

## Description

Aldi Product API: fetch full product page data from an Aldi URL or path slug. Returns pricing, images, description, category and cooling flags.

## 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/product' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Filets d'anchois marinés (6806) on aldi.fr

```json
{
  "url": "https://www.aldi.fr/fiches-produits/filets-danchois-marines-6806.html",
  "brand": "GOLDEN SEAFOOD®",
  "price": 1.99,
  "title": "FILETS D'ANCHOIS MARINÉS",
  "images": [
    "https://s7g10.scene7.com/is/image/aldinord/6806.main.1.fr_fr.All.anchois",
    "https://s7g10.scene7.com/is/image/aldinord/6806_FILETS_ANCHOIS_MARINES_AIL"
  ],
  "category": "73-poisson",
  "currency": "EUR",
  "image_url": "https://s7g10.scene7.com/is/image/aldinord/6806.main.1.fr_fr.All.anchois",
  "is_cooling": true,
  "product_id": "6806",
  "sales_unit": "100 g",
  "description": "Pêche durable selon le référentiel MSC.",
  "product_slug": "filets-danchois-marines-6806",
  "short_description": "Au choix : Nature, ail et persil ou à la provençale."
}
```

## Documentation

## Overview
The **Aldi Product API** returns full product page data from Aldi online shops. Pass a **product URL** or **path slug**, optionally with **`region`**, and receive structured JSON with pricing, images, description, category, and cooling flags.

Piloterr parses the Next.js SSR payload (`#__NEXT_DATA__`) from the HTML, no browser rendering required.

Use [Aldi Search](https://www.piloterr.com/library/aldi-search) to discover listings, then [Aldi Product](https://www.piloterr.com/library/aldi-product) for the full record.

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

| `region` | Domain | Product URL pattern | Aliases |
|---|---|---|---|
| `fr` | aldi.fr | `/fiches-produits/{slug}.html` | `fr-fr` |
| `de` | aldi-nord.de | `/p/{slug}.html` | `de-de`, `aldi-nord` |
| `nl` | aldi.nl | `/product/{slug}.html` | `nl-nl` |
| `es-can` | aldi.es/can/… | `/can/producto/{slug}.html` | `can`, `canarias` |

Numeric product id alone (`6806`) is **not supported**: pass a full URL or slug path.

## Quickstart
```
GET https://api.piloterr.com/v2/aldi/product?query=fiches-produits/filets-danchois-marines-6806.html
GET https://api.piloterr.com/v2/aldi/product?query=https://www.aldi.fr/fiches-produits/filets-danchois-marines-6806.html
GET https://api.piloterr.com/v2/aldi/product?query=/p/example-slug-1234.html&region=de
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Product URL or site path slug |
| `region` | string | no | Country when `query` is a path only (default: `fr`) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Aldi product id |
| `title` | string | Product title |
| `url` | string | Canonical product URL |
| `image_url` | string \| null | Main image |
| `images` | string[] \| null | Ordered gallery |
| `price` | number \| null | Current price (`currentPrice.priceValue`) |
| `currency` | string | ISO currency |
| `brand` | string \| null | Brand name |
| `sales_unit` | string \| null | Pack size / unit |
| `short_description` | string \| null | Card teaser text |
| `description` | string \| null | Long description |
| `category` | string \| null | `mainCategoryID` when breadcrumb unavailable |
| `product_slug` | string \| null | URL slug |
| `is_cooling` | boolean \| null | Chilled / frozen product flag |

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

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query`, unsupported domain, or numeric id only |
| `404` | Page without `#__NEXT_DATA__` or unparsable product |
| `500` | Network or parsing error |

## Notes
- Search `category` uses Algolia breadcrumbs; product `category` may show raw `mainCategoryID` (e.g. `73-poisson`).
- Canarias product URLs must stay under `/can/` on `aldi.es`.
- Costs **1 credit** per call (HTTP crawler).

## Main use cases
- **PDP enrichment**: description, gallery, cooling flag
- **Price monitoring**: track Aldi shelf prices by region
- **Assortment intel**: brand, unit, category metadata