# Picard Search

## Overview

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

## Description

Picard Search API. Search frozen food listings on picard.fr by keyword or URL. Parses SFCC Search-UpdateGrid HTML; returns prices, Nutri-Score, ratings 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/picard/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'patate douce' on picard.fr (page 1)

```json
{
  "results": [
    {
      "url": "https://www.picard.fr/produits/inedites-patate-douce-patates-douce-enrobees-000000000000050935.html",
      "price": 3.4,
      "title": "Inédites à la patate douce, patates douce enrobées",
      "rating": 4.56,
      "category": "Légumes et fruits",
      "currency": "EUR",
      "image_url": "https://www.picard.fr/dw/image/v2/AAHV_PRD/on/demandware.static/-/Sites-catalog-picard/default/dw8a619f76/produits/000000000000050935_E.jpg?sw=258&sh=151&q=30",
      "packaging": "le sachet de 500 g",
      "reference": "50935",
      "nutriscore": "C",
      "product_id": "000000000000050935",
      "subcategory": "Féculents",
      "availability": "en stock",
      "reviews_count": null,
      "unit_price_text": "6,80 €/kg"
    },
    {
      "url": "https://www.picard.fr/produits/puree-patate-douce-000000000000050314.html",
      "price": 2.6,
      "title": "Purée de patate douce",
      "rating": 4.7,
      "category": "Légumes et fruits",
      "currency": "EUR",
      "image_url": "https://www.picard.fr/dw/image/v2/AAHV_PRD/on/demandware.static/-/Sites-catalog-picard/default/dwea0e1bd9/produits/legumes/edition/000000000000050314_E1.jpg?sw=258&sh=151&q=30",
      "packaging": "la boîte de 450 g",
      "reference": "50314",
      "nutriscore": "A",
      "product_id": "000000000000050314",
      "subcategory": "Légumes cuisinés",
      "availability": "en stock",
      "reviews_count": null,
      "unit_price_text": "5,77 €/kg"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "count": 21,
    "has_next": false,
    "per_page": 24
  }
}
```

## Documentation

## Overview
The **Picard Search API** returns frozen food product listings from picard.fr. Pass a **keyword** or a **full search URL**, optionally with **`page`**, and receive structured JSON with prices, Nutri-Score, ratings, availability and pagination.

Piloterr calls the SFCC AJAX endpoint `Search-UpdateGrid` and parses the HTML grid. No browser rendering required.

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

## Quickstart
```
GET https://api.piloterr.com/v2/picard/search?query=patate+douce
GET https://api.piloterr.com/v2/picard/search?query=patate+douce&page=1
GET https://api.piloterr.com/v2/picard/search?query=https://www.picard.fr/recherche?q=patate&lang=fr_FR
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword or full Picard search URL |
| `page` | integer | no | 1-based page number (default: `1`, 24 results per page) |
| `return_page_source` | boolean | no | Raw HTML as `{\"result\": \"...\"}` (default: `false`) |

## Listings (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | 18-digit SFCC product id |
| `reference` | string | Short Picard reference |
| `title` | string | Product title |
| `url` | string | Absolute product URL |
| `image_url` | string \| null | Card image |
| `price` | number \| null | Displayed price |
| `currency` | string | ISO currency (`EUR`) |
| `unit_price_text` | string \| null | Unit price label (e.g. `5,77 €/kg`) |
| `packaging` | string \| null | Pack size text |
| `rating` | number \| null | Average rating |
| `reviews_count` | integer \| null | Review count (often null on grid) |
| `category` | string \| null | Top category |
| `subcategory` | string \| null | Subcategory |
| `nutriscore` | string \| null | Nutri-Score grade |
| `availability` | string \| null | Stock label (`en stock`, …) |

## Pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Page size (24) |
| `count` | integer | Results on this page |
| `has_next` | boolean | More pages available |
| `next` | integer \| null | Next page number |

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

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Empty or unparsable search grid |
| `500` | Network or parsing error |

## Notes
- Picard.fr only (France).
- Costs **1 credit** per call (HTTP crawler).

## Main use cases
- **Catalog discovery**: harvest product ids and URLs by keyword
- **Price monitoring**: track listing prices and unit prices
- **Assortment intel**: Nutri-Score, categories and availability at scale