# Picard Product

## Overview

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

## Description

Picard Product API. Fetch full frozen food product data from a Picard URL or reference. Returns pricing, images, description, Nutri-Score, Planet-Score, breadcrumb and reviews.

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

## Example Response

### Purée de patate douce (050314) on picard.fr

```json
{
  "url": "https://www.picard.fr/produits/puree-patate-douce-000000000000050314.html",
  "gtin": "3270160503148",
  "brand": "Picard",
  "label": "Convient aux végétariens",
  "price": 2.6,
  "range": "Purées",
  "title": "Purée de patate douce",
  "images": [
    "https://www.picard.fr/dw/image/v2/AAHV_PRD/on/demandware.static/-/Sites-catalog-picard/default/dwea0e1bd9/produits/legumes/edition/000000000000050314_E1.jpg?sh=200",
    "https://www.picard.fr/dw/image/v2/AAHV_PRD/on/demandware.static/-/Sites-catalog-picard/default/dwea0e1bd9/produits/legumes/edition/000000000000050314_E1.jpg?sw=672&sh=392&q=30&frz-v=115"
  ],
  "origin": "Produit élaboré en France à partir de patate douce cultivée en Espagne et au Portugal",
  "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?sh=200",
  "packaging": "la boîte de 450 g",
  "reference": "050314",
  "breadcrumb": [
    {
      "url": "https://www.picard.fr/",
      "name": "Accueil",
      "position": 1
    },
    {
      "url": "https://www.picard.fr/rayons",
      "name": "Rayons",
      "position": 2
    },
    {
      "url": "https://www.picard.fr/rayons/legumes-et-fruits",
      "name": "Légumes et fruits",
      "position": 3
    },
    {
      "url": "https://www.picard.fr/produits/puree-patate-douce-000000000000050314.html",
      "name": "Purée de patate douce",
      "position": 6
    }
  ],
  "nutriscore": "A",
  "product_id": "000000000000050314",
  "unit_price": 5.77,
  "description": "Redécouvrez un légume oublié avec cette purée de patate douce au petit goût de châtaigne.",
  "planetscore": "C",
  "subcategory": "Légumes cuisinés",
  "availability": "InStock",
  "subcategory2": "Purées",
  "reviews_count": 336,
  "unit_price_text": "Prix au kilo\n5,77 €/kg"
}
```

## Documentation

## Overview
The **Picard Product API** returns full product page data from picard.fr. Pass a **product URL** or **numeric reference** (`050314`) and receive structured JSON with pricing, images, description, breadcrumb, Nutri-Score, Planet-Score, origin and reviews.

Piloterr fetches the product HTML page via HTTP and parses the SFCC markup. No browser rendering required.

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

## Quickstart
```
GET https://api.piloterr.com/v2/picard/product?query=050314
GET https://api.piloterr.com/v2/picard/product?query=https://www.picard.fr/produits/puree-patate-douce-000000000000050314.html
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Product URL (`/produits/...html`) or numeric reference |
| `return_page_source` | boolean | no | Raw HTML as `{\"result\": \"...\"}` (default: `false`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `product_id` | string | 18-digit SFCC product id |
| `reference` | string | Short Picard reference |
| `title` | string | Product title |
| `url` | string | Canonical product URL |
| `price` | number \| null | Displayed price |
| `currency` | string | ISO currency (`EUR`) |
| `unit_price` | number \| null | Parsed unit price per kg |
| `unit_price_text` | string \| null | Unit price label |
| `packaging` | string \| null | Pack size text |
| `brand` | string \| null | Brand name |
| `label` | string \| null | Product label badge |
| `description` | string \| null | Long description |
| `origin` | string \| null | Origin / sourcing text |
| `image_url` | string \| null | Main image |
| `images` | string[] \| null | Gallery URLs |
| `rating` | number \| null | Average rating |
| `reviews_count` | integer \| null | Review count |
| `category` | string \| null | Top category |
| `subcategory` | string \| null | Subcategory |
| `subcategory2` | string \| null | Range / sub-range |
| `range` | string \| null | Product range |
| `nutriscore` | string \| null | Nutri-Score grade |
| `planetscore` | string \| null | Planet-Score grade |
| `gtin` | string \| null | GTIN / EAN |
| `availability` | string \| null | Stock code or label |
| `breadcrumb` | array | `{name, url, position}` trail |

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

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Product not found or unparsable page |
| `500` | Network or parsing error |

## Notes
- Reference-only queries (`050314`) resolve via internal grid search.
- Picard.fr only (France).
- Costs **1 credit** per call (HTTP crawler).

## Main use cases
- **PDP enrichment**: description, gallery, breadcrumb, scores
- **Price monitoring**: price and unit price per kg
- **Retail intel**: origin, labels and category taxonomy