# Carrefour Suggest

## Overview

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

## Description

Get product suggestions from Carrefour by keyword or EAN, returning matching products with pricing, availability, and product details.

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

## Example Response

### Suggest by keyword 'coca'

```json
{
  "results": [
    {
      "id": "product-5000112611861",
      "type": "product",
      "links": {
        "self": "/p/soda-au-cola-gout-original-coca-cola-5000112611861",
        "reviews": "/product/5000112611861/reviews"
      },
      "attributes": {
        "ean": "5000112611861",
        "slug": "soda-au-cola-gout-original-coca-cola",
        "brand": "COCA-COLA",
        "title": "Soda au Cola Goût Original COCA-COLA",
        "format": "1,75L",
        "offers": {
          "5000112611861": {
            "0261_150_6": {
              "id": "0261-150-6",
              "type": "offer",
              "attributes": {
                "ean": "5000112611861",
                "price": {
                  "price": 2.39,
                  "perunit": 1.37,
                  "perunitlabel": "1.37 € / L",
                  "unitofmeasure": "L"
                },
                "availability": {
                  "purchasable": true
                }
              }
            }
          }
        },
        "packaging": "la bouteille d'1,75L",
        "categories": [
          {
            "id": "27070",
            "slug": "boissons",
            "label": "Boissons",
            "level": 1
          },
          {
            "id": "27073",
            "slug": "colas-thes-glaces-et-soft-drinks",
            "label": "Colas, Thés glacés, Sirops et Sodas",
            "level": 2
          }
        ],
        "nutriscore": null,
        "shorttitle": "Soda au Cola Goût Original COCA-COLA",
        "businesstype": "food",
        "customerreviews": {
          "count": 33,
          "rates": null,
          "average": 4.79
        }
      }
    }
  ]
}
```

## Documentation

## Overview
Get instant product suggestions from Carrefour by keyword or EAN barcode. Returns matching products with pricing, availability, category hierarchy, and customer reviews.

## Quickstart
```
GET https://api.piloterr.com/v2/carrefour/suggest?query=coca
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword (e.g. `coca`) or EAN barcode |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results[].attributes.ean` | string | Product EAN |
| `results[].attributes.title` | string | Product title |
| `results[].attributes.brand` | string | Brand name |
| `results[].attributes.offers` | object | Price and availability |

## Main use cases
- Power autocomplete search features with Carrefour product data
- Look up Carrefour products by EAN barcode
- Discover product IDs and slugs for the Carrefour Product endpoint
- Build grocery automation tools by searching by brand keyword