# Leboncoin Search

## Overview

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

## Description

Scrape Leboncoin search results or category pages by URL, returning paginated listings with price, location, and attributes. Returns structured JSON by default, or raw HTML on demand.

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

## Example Response

### Browse car listings in Île-de-France

```json
{
  "ads": [
    {
      "url": "https://www.leboncoin.fr/voitures/2718234567.htm",
      "body": "Renault Megane IV Estate diesel, CT valable 2 ans, révision à jour, non fumeur.",
      "owner": {
        "name": "Sophie",
        "type": "private"
      },
      "price": [
        9900
      ],
      "images": {
        "nb_images": 8,
        "small_url": "https://img.leboncoin.fr/api/cdn/thumbs/xyz12345.jpg"
      },
      "status": "active",
      "list_id": 2718234567,
      "subject": "Renault Megane IV Estate 1.5 DCI 110 Business",
      "location": {
        "city": "Versailles",
        "zipcode": "78000",
        "region_name": "Île-de-France",
        "department_name": "Yvelines"
      },
      "attributes": [
        {
          "key": "brand",
          "value": "renault",
          "value_label": "Renault"
        },
        {
          "key": "model",
          "value": "Megane IV Estate",
          "value_label": "Megane IV Estate"
        },
        {
          "key": "regdate",
          "value": "2018",
          "value_label": "2018"
        },
        {
          "key": "mileage",
          "value": "89000",
          "value_label": "89 000 km"
        },
        {
          "key": "fuel",
          "value": "diesel",
          "value_label": "Diesel"
        },
        {
          "key": "gearbox",
          "value": "manual",
          "value_label": "Manuelle"
        },
        {
          "key": "critair",
          "value": "2",
          "value_label": "Crit'Air 2"
        }
      ],
      "category_id": "2",
      "category_name": "Voitures",
      "creation_date": "2024-09-18T09:30:00+02:00"
    }
  ],
  "total": 12481,
  "pagination": {
    "page": 1,
    "total_pages": 100
  }
}
```

## Documentation

## Overview
Extract listings from any Leboncoin search or category URL. Returns paginated, structured JSON by default. Switch to raw HTML via `return_page_source=true`.

## Quickstart
```
GET https://api.piloterr.com/v2/leboncoin/search?query=https://www.leboncoin.fr/recherche?text=macbook
```

## Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes | - | Leboncoin search or category URL |
| `return_page_source` | boolean | no | `false` | `false` = parsed JSON, `true` = raw HTML |

## Status codes
- `200` Search succeeded
- `404` No results or page not found (applies to both JSON and HTML modes)
- `400` Invalid input

## Main use cases
- Scrape regional car listings for market analysis
- Monitor category pages for new listings
- Build price intelligence dashboards
- Aggregate classifieds data across regions