# Lidl Search

## Overview

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

## Description

Lidl Search API: search product listings by keyword or URL across Lidl online shops in 27 countries. Parses Nuxt SSR payload from HTML; returns prices, ratings, brand 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/lidl/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'perceuse' on lidl.fr (page 1)

```json
{
  "results": [
    {
      "url": "https://www.lidl.fr/p/parkside-set-perceuse-a-percussion-psbm-750-c3/p100400894",
      "brand": "PARKSIDE®",
      "price": 20,
      "title": "PARKSIDE® Set perceuse à percussion PSBM 750 C3",
      "locale": "fr-fr",
      "rating": 4,
      "currency": "EUR",
      "image_url": "https://www.lidl.fr/assets/gcp941ea783e919400f859ed3e1193f144f.jpg",
      "old_price": 51.99,
      "product_id": "100400894",
      "review_count": 26,
      "discount_percentage": 61
    }
  ],
  "pagination": {
    "next": "https://www.lidl.fr/q/search?q=perceuse&offset=48&fetchsize=48",
    "page": 1,
    "per_page": 48,
    "total_pages": 4,
    "total_results": 147
  }
}
```

## Documentation

## Overview
The **Lidl Search API** returns product listings from Lidl online shops (`www.lidl.*`). Pass a **keyword** or a **full search URL**, optionally with **`region`**, and receive structured JSON with prices, ratings, brand, locale, currency, and pagination.

Piloterr fetches the SSR HTML and parses the embedded Nuxt 3 payload (`#__NUXT_DATA__`), no browser rendering required.

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

## Supported regions
27 countries. Default: `fr` → `www.lidl.fr`.

| `region` | Domain | Locale | Currency | Aliases |
|---|---|---|---|---|
| `fr` | lidl.fr | fr-fr | EUR | `fr-fr` |
| `de` | lidl.de | de-de | EUR | `de-de` |
| `es` | lidl.es | es-es | EUR | `es-es` |
| `it` | lidl.it | it-it | EUR | `it-it` |
| `pl` | lidl.pl | pl-pl | PLN | `pl-pl` |
| `nl` | lidl.nl | nl-nl | EUR | `nl-nl` |
| `be` / `fr-be` / `nl-be` | lidl.be | fr-be / nl-be | EUR | - |
| `gb` | lidl.co.uk | en-gb | GBP | `uk`, `en-gb` |
| `ch` / `at` / `dk` / `se` / `fi` / … | see docs | - |: | 27 countries total |

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

## Quickstart
```
GET https://api.piloterr.com/v2/lidl/search?query=perceuse
GET https://api.piloterr.com/v2/lidl/search?query=perceuse&region=fr
GET https://api.piloterr.com/v2/lidl/search?query=bohrer&region=de
GET https://api.piloterr.com/v2/lidl/search?query=https://www.lidl.de/q/search?q=bohrer
GET https://api.piloterr.com/v2/lidl/search?query=perceuse&page=2
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full Lidl search URL |
| `region` | string | no | Country code when `query` is a keyword (default: `fr`) |
| `page` | integer | no | 1-based page number (default: 1) |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Response: each listing (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | ERP number |
| `title` | string | Full product title |
| `url` | string | Absolute product URL |
| `image_url` | string \| null | Main image |
| `price` | number \| null | Current price |
| `old_price` | number \| null | Strikethrough price |
| `discount_percentage` | number \| null | Discount in % |
| `currency` | string | ISO currency from payload |
| `brand` | string \| null | Brand name |
| `rating` | number \| null | Average rating |
| `review_count` | integer \| null | Review count |
| `locale` | string | Shop locale |
| `images` | string[] \| null | Gallery when multiple images |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Results on this page |
| `total_results` | integer \| null | Total matches |
| `total_pages` | integer \| null | Total pages |
| `next` | string \| null | Full URL of next page (`offset=48`, …) |

Lidl paginates by **offset** (48 items per page): page 2 → `offset=48`.

## Lidl workflow
1. [Lidl Search](https://www.piloterr.com/library/lidl-search): discover listings (this endpoint)
2. [Lidl Product](https://www.piloterr.com/library/lidl-product): full PDP JSON

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` / `region` |
| `404` | Page without `#__NUXT_DATA__` or unparsable content |
| `500` | Network or parsing error |

## Notes
- Some shops may return `price: null` for certain products (assortment still returned).
- Costs **1 credit** per call (HTTP crawler).

## Main use cases
- **Price monitoring**: track Lidl promotions across European shops
- **Catalog discovery**: harvest ERP ids and URLs at scale
- **Cross-border retail intel**: compare pricing by country