# Bricorama Search ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/bricorama/search` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 1 credit per call | | **Documentation** | https://www.piloterr.com/library/bricorama-search | ## Description Search Bricorama by keyword or search URL and page the home-improvement grid. ## 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/bricorama/search' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### perceuse, first product ```json { "results": [ { "ean": "3999991691267", "url": "https://www.bricorama.fr/p/perceuse-visseuse-sans-fil-18v/3999991691267", "name": "Perceuse visseuse sans fil 18V", "brand": "GO/ON", "image": "https://assets-big.cdn-mousquetaires.com/medias/domain11440/media2624/393739-2ftpvnauip-large.jpg", "price": 27.9, "seller": null, "currency": "EUR", "delivery": "Retrait en 2h en magasin", "position": 1, "was_price": null, "availability": "En stock selon magasin", "price_display": "27,90 €", "discount_display": null, "was_price_display": null } ], "pagination": { "next": "https://www.bricorama.fr/search?q=perceuse&page=2", "page": 1, "per_page": 48, "total_pages": null, "total_results": null } } ``` ## Documentation ## Overview **Bricorama** product search on www.bricorama.fr. `query` is a keyword or a `/search?q=` URL. The response is `{ results, pagination }`. Each card has the EAN, name, brand, current price and, when the card shows them, the crossed-out price, the seller and the delivery line. A product URL (`/p/...`) returns `400`. ## Quickstart ``` GET https://api.piloterr.com/v2/bricorama/search?query=perceuse GET https://api.piloterr.com/v2/bricorama/search?query=perceuse&page=2 GET https://api.piloterr.com/v2/bricorama/search?query=https://www.bricorama.fr/search?q=perceuse ``` ## `query` **Example (keyword):** perceuse **Example (search URL):** https://www.bricorama.fr/search?q=perceuse `query` is required. Only `www.bricorama.fr` is accepted. | Form | Example | What happens | |---|---|---| | Keyword | `perceuse` | Builds `https://www.bricorama.fr/search?q=perceuse`. | | Search URL | `https://www.bricorama.fr/search?q=perceuse` | Uses that listing. `page` adds or replaces `?page=`. | A product URL returns `400`. Another host returns `400`. An empty value returns `400`. `page` below 1 returns `400`. `page` starts at 1. Page 2 of the same listing is `?page=2`. ## Parameters | Parameter | Type | Required | Description | |---|---|---|---| | `query` | string | yes | Keyword or `/search?q=` URL | | `page` | integer | no | Page from 1. Sent as `?page=` on the listing. | ## Response fields | Field | Type | Description | |---|---|---| | `results[]` | array | Product cards on this page | | `results[].position` | integer | Position on the page, from 1 | | `results[].ean` | string \| null | EAN from the product URL | | `results[].name` | string | Product name | | `results[].brand` | string \| null | Brand | | `results[].url` | string | Product URL under `/p/` | | `results[].image` | string \| null | Main image | | `results[].price` | number \| null | Current price in euros | | `results[].price_display` | string \| null | Price as shown, for example `27,90 €` | | `results[].was_price` | number \| null | Crossed-out price | | `results[].was_price_display` | string \| null | Crossed-out price as shown | | `results[].discount_display` | string \| null | Discount badge, for example `-30%` | | `results[].currency` | string \| null | `EUR` when a price is present | | `results[].availability` | string \| null | Stock sentence on the card | | `results[].delivery` | string \| null | Pickup or shipping line | | `results[].seller` | string \| null | Marketplace seller, or null | | `pagination.page` | integer | Requested page | | `pagination.per_page` | integer | Cards returned on this page | | `pagination.total_results` | null | Not published by the page | | `pagination.total_pages` | null | Not published by the page | | `pagination.next` | string \| null | Next page URL | ## Notes `price` is the current price (`27.9`) and `price_display` keeps the French comma (`27,90 €`). `was_price` is the crossed-out price. It is `null` when the card has no discount. `discount_display` is the badge shown on the card, such as `-30%`. `seller` is set when the card names a marketplace seller. It is `null` for Bricorama. `availability` is the stock sentence on the card. It is not a lookup for one store. The page does not publish a result total, so `total_results` and `total_pages` are `null`. `next` is the next page URL. The sample below keeps the first card. A live call returns every card on the page. ## Main use cases - Track French DIY prices - Page a tool or paint keyword - Take a product URL into Product ## Error codes | Code | Meaning | |---|---| | `400` | Empty query, unknown host, product URL, or `page` below 1 | | `403` | Blocked | | `404` | No product card on the page | | `500` | Fetch failed | ## Related endpoints [Bricorama Product](https://www.piloterr.com/library/bricorama-product)