# Boulanger API — France's electronics & appliance retailer: search, prices with éco-participation, marketplace offers, delivery & store pickup by postal code, store stock and reviews

> Search boulanger.com by keyword, or list a category, optionally narrowed by brand, seller (Boulanger or a marketplace seller), price range, condition (new / refurbished), minimum star rating and presence in one store, in one of the site's four sort orders. 40 products per page with price, struck-through price and its type, discount, éco-participation and private-copy levy included in the price, seller and seller type, condition, availability, rating, review count, energy class, key points and promotions; plus the source's own facet values (brands, sellers, stores, conditions) with counts. Needs `query` OR `category`.
> ReefAPI engine `boulanger` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/boulanger/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/boulanger/v1/search — 3 credits
Search boulanger.com by keyword, or list a category, optionally narrowed by brand, seller (Boulanger or a marketplace seller), price range, condition (new / refurbished), minimum star rating and presence in one store, in one of the site's four sort orders. 40 products per page with price, struck-through price and its type, discount, éco-participation and private-copy levy included in the price, seller and seller type, condition, availability, rating, review count, energy class, key points and promotions; plus the source's own facet values (brands, sellers, stores, conditions) with counts. Needs `query` OR `category`.

**Parameters:**
- `query` (string, optional) — Search words, as typed in the site's search box.
- `category` (string, optional) — A category slug — the part after /c/ in a boulanger.com category URL, or a product's `category_path[].slug` (e.g. `iphone-18`). Use instead of `query` (not both).
- `brand` (string, optional) — Brand name as the site shows it (case-insensitive) or a `facets.brands[].value`. An unknown brand answers 0 results.
- `seller` (string, optional) — Seller name: `Boulanger` for Boulanger's own offers, or a marketplace seller's name (e.g. `EasyLounge`) / a `facets.sellers[].value`.
- `min_price` (number, optional) — Minimum price in EUR (VAT included). Sent together with max_price as the site's own price range.
- `max_price` (number, optional) — Maximum price in EUR (VAT included).
- `condition` (enum, optional) — Product condition. [one of: new, refurbished]
- `min_rating` (integer, optional) — Minimum average star rating: 3, 4 or 5 (the site's 'N étoiles et plus').
- `store` (string, optional) — Only products present in this Boulanger store (code F + 3 digits, from `facets.stores[].value` or `delivery` `stores[].site_id`).
- `sort` (enum, optional, default "relevance") — Result order (the site's own four). [one of: relevance, price_asc, price_desc, rating]
- `page` (integer, optional, default 1) — Result page, 40 products per page. A page past the last one answers an empty list.

**Returns:** total, page, last_page, has_more, results[]{product_id, offer_id, url, title, brand, image, price, price_excl_vat, currency=EUR, strikeout_price, strikeout_label, discount_pct_printed, discount_pct, eco_participation, private_copy_levy, seller, seller_type, is_marketplace, condition, available, rating, rating_exact, review_count, energy_class, key_points[], flaps[], promotions[], category_codes[], price_witness} + facets{brands[], sellers[], stores[], conditions[], min_rating[]}{value, label, count}

**Example request body:**
```json
{
  "query": "television",
  "brand": "Samsung"
}
```

### POST https://api.reefapi.com/boulanger/v1/product — 2 credits
One boulanger.com product, complete: title, brand, EAN, manufacturer reference, release date, rating and review count, category path, key points, description, pictograms, images, energy label, full spec sheet, promotions with their dates, and EVERY offer — Boulanger's own and each marketplace seller's — with price (VAT included), struck-through price and its type (Prix de référence / Ancien prix), discount %, éco-participation and private-copy levy included in the price, other price components, availability, sale channels (web / store), legal warranty, trade-in eligibility, instalment plan and the supplier's legal identity.

**Parameters:**
- `product_id` (string, optional) — Boulanger product number: the number in a product URL boulanger.com/ref/<product_id> and the `product_id` of a search row (7 digits for Boulanger items, 10 for marketplace-only items). Provide product_id OR url.
- `url` (string, optional) — A boulanger.com product URL (…/ref/<number>); alternative to product_id.

**Returns:** product{product_id, url, pim_id, sku_id, title, brand, brand_code, eans[], manufacturer_reference, national_release_date, rating, review_count, price, currency, strikeout_price, strikeout_label, discount_pct, eco_participation, private_copy_levy, seller, is_marketplace, available, legal_warranty_months, offer_count, offers[]{offer_id, rank, seller, seller_id, seller_slug, is_boulanger, condition, price, price_excl_vat, strikeout_price, strikeout_type, strikeout_label, discount_pct, eco_participation, private_copy_levy, price_components[], available, buyable_channels[], legal_warranty_months, buyback_eligible, installment_plan, supplier}, promotions[]{code, type_code, label, flap_text, starts_at, ends_at}, category_path[]{name, slug, url}, key_points[], advantage, description, pictograms[], images[], energy_label_image, supplier, specs[]{group, specs[]{label, value}}}

**Example request body:**
```json
{
  "product_id": "1243116"
}
```

### POST https://api.reefapi.com/boulanger/v1/delivery — 3 credits
Delivery and pickup options of one offer for a French postal code, as the product page computes them: home delivery (standard / express / with installation), store pickup (Retrait en magasin, with the store), Drive, parcel pickup points (Colissimo, Mondial Relay, Chronopost) — each with carrier, earliest date window, price, price before discount and Club prices — plus the nearest stores and pickup points with distance, and what cannot be delivered there.

**Parameters:**
- `product_id` (string, optional) — Boulanger product number: the number in a product URL boulanger.com/ref/<product_id> and the `product_id` of a search row (7 digits for Boulanger items, 10 for marketplace-only items). Provide product_id OR url.
- `url` (string, optional) — A boulanger.com product URL (…/ref/<number>); alternative to product_id.
- `offer_id` (string, optional) — Optional: one offer of the product (an `offers[].offer_id` of `product`, e.g. a marketplace seller's). Default: the offer the site ranks first.
- `postal_code` (string, optional, default "75001") — French postal code (5 digits) the delivery / stock is computed for. Default 75001 (Paris), the site's own default.

**Returns:** product_id, offer_id, offer_price, postal_code, options[]{mode_code, carrier, method, method_label, service_label, seller_id, earliest_from, earliest_to, slot_count, price, price_before_discount, club_prices[], store, pickup_point}, stores[]{site_id, name, address{distance_km…}}, pickup_points[], not_available[], theoretical_shipping_prices[]

**Example request body:**
```json
{
  "product_id": "1243116",
  "postal_code": "75001"
}
```

### POST https://api.reefapi.com/boulanger/v1/store_stock — 3 credits
The Boulanger stores the site lists as still holding units of an offer (its 'derniers articles en magasin' list), nearest to a postal code first: store, site code, quantity, address and distance.

**Parameters:**
- `product_id` (string, optional) — Boulanger product number: the number in a product URL boulanger.com/ref/<product_id> and the `product_id` of a search row (7 digits for Boulanger items, 10 for marketplace-only items). Provide product_id OR url.
- `url` (string, optional) — A boulanger.com product URL (…/ref/<number>); alternative to product_id.
- `offer_id` (string, optional) — Optional: one offer of the product (an `offers[].offer_id` of `product`, e.g. a marketplace seller's). Default: the offer the site ranks first.
- `postal_code` (string, optional, default "75001") — French postal code (5 digits) the delivery / stock is computed for. Default 75001 (Paris), the site's own default.

**Returns:** product_id, offer_id, postal_code, count, total_quantity, stores[]{site_id, store, quantity, address{street, postal_code, city, department, region, lat, lon}, distance_km}

**Example request body:**
```json
{
  "product_id": "8011306"
}
```

### POST https://api.reefapi.com/boulanger/v1/reviews — 2 credits
Customer reviews of one product: star rating, title, full text, reviewer's public nickname, post time, experience date, helpful votes, photos and seller responses, with the source's review total and average. Up to 50 per call, paged with `page`.

**Parameters:**
- `product_id` (string, optional) — Boulanger product number: the number in a product URL boulanger.com/ref/<product_id> and the `product_id` of a search row (7 digits for Boulanger items, 10 for marketplace-only items). Provide product_id OR url.
- `url` (string, optional) — A boulanger.com product URL (…/ref/<number>); alternative to product_id.
- `sort` (enum, optional, default "newest") — Review order (the site's own). [one of: newest, rating_desc, rating_asc, helpful, with_photos]
- `page` (integer, optional, default 1) — Page of `limit` reviews.
- `limit` (integer, optional, default 20) — Reviews per page (1-50).

**Returns:** total, average, page, count, reviews[]{review_id, rating, title, text, reviewer, posted_at, experience_date, review_type, helpful_yes, helpful_no, photos[], seller_responses[], reviewed_product_id}

**Example request body:**
```json
{
  "product_id": "1243116"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=boulanger
- Human docs page: https://reefapi.com/docs/boulanger
- Overview page: https://reefapi.com/boulanger-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt