# Leboncoin: Search listings

`leboncoin/listings/search` · version 2.1.0 · pilot · 100 credits a call

One page of a leboncoin.fr search, 35 listings at most, exactly as the page shows them, descriptions included.

Categories: Real estate, Cars, E-commerce

## When to use

You need the listings of a leboncoin.fr search: title, description, price, place, seller, photos, every attribute (property, vehicle, job...), and whether the seller shows a phone (`has_phone`). Set the search up on leboncoin.fr (category, place, filters, sort), then pass its URL. For a seller's number, call leboncoin/phones/get on a listing with `has_phone`.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "leboncoin", "operation": "listings/search", "options": {"url": "https://www.leboncoin.fr/recherche?category=9&locations=Lyon__45.76_4.83_7308_5000__d69&real_estate_type=2&sort=time&order=desc"}}'
```

The answer's `next` is the whole call for the following page: send it as it is. `null` on the last page.

Beside `options`, the call takes:

| Parameter | Type | Description |
|---|---|---|
| `fields` | array of string | The record fields to keep, by path (`title`, `address.city`); `object`, `id` and `position` always come. Left out: every field. |
| `limit` | integer | Only the first N records of this call (1 to 1000), in the call's order; the call costs the same, and `next` keeps the limit. Left out: every record. |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string (uri) | yes |  | A leboncoin.fr search, exactly as the browser shows it once the search is set up (category, place, filters, keywords, sort), its `page` the page to start at (page=2 is the second page). Sort by date, newest first, with sort=time&order=desc ("Plus récentes"). Every filter of the site is read; a parameter Leboncoin does not filter on is refused, never ignored. |
| `cursor` | string |  |  | Where to go on, from `next` in an answer, as it is: opaque, and only for the search it was given with (otherwise `invalid_cursor`). Leave it out to start at the URL's page. It goes on where the previous page ended, as Leboncoin's own next page does: a page reached by its URL alone is read as a link to it shows it, and Leboncoin may skip the listings that the featured copies of the page before pushed down. |

## Record

Each item of `results`. Every field is always present, `null` when the site gives nothing.

| Field | Type | Description |
|---|---|---|
| `object` | `"listing"` | The kind of record: a listing, whichever site it comes from. |
| `id` | string | Leboncoin's listing id; repeated in ids.listing_id. |
| `position` | integer | Its place among the cards the search shows, across pages (35 a page): 36 is the first of page 2. A featured copy has a place of its own, as on the page. |
| `featured` | boolean | Shown with Leboncoin's "À la une" badge at this place (a paid option). Sorted by date, Leboncoin also puts such listings at the top of the page: the same listing then comes twice, featured at the top and in its own place by date, as the page shows it. |
| `url` | string (uri) | The listing on leboncoin.fr. |
| `title` | string |  |
| `description` | string | null | The seller's text, as written (line breaks kept). |
| `category` | object |  |
| `category.id` | string | Leboncoin's category id: 2 cars, 9 property sales, 10 rentals... |
| `category.name` | string | As Leboncoin names it |
| `ad_type` | `offer`, `demand` | An offer (selling, renting, hiring) or a demand (looking for). |
| `status` | string | Leboncoin's status of the listing: active on a search page. |
| `price` | object | null | The price the listing shows; null when it shows none (jobs, gifts). |
| `price.amount` | number |  |
| `price.currency` | `"EUR"` | ISO 4217. |
| `buyer_fee` | object | null | What Leboncoin adds for a buyer who pays on the site (its buyer protection); null when it does not apply. |
| `buyer_fee.amount` | number |  |
| `buyer_fee.currency` | `"EUR"` | ISO 4217. |
| `shipping` | array | The ways the seller ships, each with its price; empty when the listing is hand to hand only. |
| `shipping[].type` | string | null | Leboncoin's name of the carrier or service: mondial_relay, shop2shop, colissimo, custom_shipping... |
| `shipping[].price` | object | null | The price the listing shows; null when it shows none (jobs, gifts). |
| `shipping[].price.amount` | number |  |
| `shipping[].price.currency` | `"EUR"` | ISO 4217. |
| `shipping[].base_price` | object | null | The price before Leboncoin's discount, when it shows one. |
| `shipping[].base_price.amount` | number |  |
| `shipping[].base_price.currency` | `"EUR"` | ISO 4217. |
| `published_at` | string (date-time) | The first publication, UTC. |
| `republished_at` | string (date-time) | The date the listing shows and "Plus récentes" sorts by, UTC: its first publication, or the last time it was put back on top (an option, an edit). |
| `expires_at` | string | null (date-time) | When the listing goes offline unless renewed, UTC; null when Leboncoin does not say. |
| `has_phone` | boolean | The listing shows a "Voir le numéro" button: leboncoin/phones/get reads its number. |
| `is_boosted` | boolean | Leboncoin's own flag for a listing pushed by an option. |
| `paid_options` | object | The options the seller paid for, under Leboncoin's own names: urgent (the Urgent badge), photosup (more photos), booster and continuous_top_ads (put back on top), gallery, sub_toplist, highlight; has_option when any is on. |
| `paid_options.urgent` | boolean |  |
| `paid_options.gallery` | boolean |  |
| `paid_options.photosup` | boolean |  |
| `paid_options.sub_toplist` | boolean |  |
| `paid_options.continuous_top_ads` | boolean |  |
| `paid_options.highlight` | boolean |  |
| `paid_options.booster` | boolean |  |
| `paid_options.has_option` | boolean |  |
| `photos` | array | Every photo, in the listing's order, at the largest size Leboncoin serves. |
| `photos[].url` | string (uri) |  |
| `photos[].is_floor_plan` | boolean | Leboncoin's own reading of the photo as a floor plan (property listings). |
| `photo_count` | integer |  |
| `videos` | array |  |
| `videos[].url` | string (uri) |  |
| `videos[].provider` | string | null | youtube |
| `videos[].id` | string | null | The video's id at its provider. |
| `location` | object |  |
| `location.city` | string | null |  |
| `location.postal_code` | string | null |  |
| `location.district` | string | null | The part of the city, when the seller gave an address: Golfe Juan in Vallauris. |
| `location.department` | object | null |  |
| `location.department.id` | string | Leboncoin's id: the department's number (13, 2A), or its own for a region. |
| `location.department.name` | string | null |  |
| `location.region` | object | null | The region as Leboncoin files it (its former regions: Aquitaine, Rhône-Alpes). |
| `location.region.id` | string | Leboncoin's id: the department's number (13, 2A), or its own for a region. |
| `location.region.name` | string | null |  |
| `location.country_code` | string | null | ISO 3166-1 alpha-2. |
| `location.latitude` | number | null |  |
| `location.longitude` | number | null |  |
| `location.precision` | `street_number`, `street`, `district`, `city`, null | What the point stands for, as Leboncoin says; null when it does not say. |
| `location.from_address` | boolean | The seller gave an address; otherwise only a city, and the point stands for the city. |
| `seller` | object |  |
| `seller.type` | `private`, `pro` |  |
| `seller.id` | string | null | Leboncoin's user id. |
| `seller.name` | string | null | The seller's name as the listing shows it: a pseudonym, or the shop's name. |
| `seller.store_id` | string | null | The seller's store on Leboncoin (private sellers have one too). |
| `seller.siren` | string | null | French company number |
| `seller.activity_sector` | string | null | Leboncoin's id of a professional seller's sector. |
| `seller.no_salesmen` | boolean | The seller refuses canvassing. |
| `seller.fees_url` | string | null (uri) | A professional's page of fees (estate agents' scales). |
| `attributes` | array | Every attribute Leboncoin gives the listing, in its order and under its own key: the ones the page shows (brand, mileage, rooms, energy rating...), with their French labels, and the others (the seller's rating_score and rating_count, the car's price positioning...). Nothing a category adds is lost. |
| `attributes[].key` | string |  |
| `attributes[].label` | string | null | The French label the page shows, null for one it does not show. |
| `attributes[].value` | string | null |  |
| `attributes[].value_label` | string | null |  |
| `attributes[].values` | array of string | Every value of a list (equipment |
| `attributes[].values_label` | array of string | null |  |
| `calendar` | object | null | Holiday rentals only, null otherwise; the periods the seller set, open or closed, each with its price. |
| `calendar.min_price` | object | null | The lowest price of the calendar. |
| `calendar.min_price.amount` | number |  |
| `calendar.min_price.currency` | `"EUR"` | ISO 4217. |
| `calendar.periods` | array |  |
| `calendar.periods[].status` | string | null | open or closed. |
| `calendar.periods[].start_date` | string | null (date) |  |
| `calendar.periods[].end_date` | string | null (date) |  |
| `calendar.periods[].price` | object | null | The price the seller set for the period; null for a closed one. |
| `calendar.periods[].price.amount` | number |  |
| `calendar.periods[].price.currency` | `"EUR"` | ISO 4217. |
| `ids` | object | Every id Leboncoin gives with the listing. |
| `ids.listing_id` | string |  |
| `ids.user_id` | string | null |  |
| `ids.store_id` | string | null |  |
| `source_url` | string (uri) | The search page these values were read from, its page included. |
| `observed_at` | string (date-time) | When they were read |

Example:

```json
{
  "object": "listing",
  "id": "3000000001",
  "position": 1,
  "featured": false,
  "url": "https://www.leboncoin.fr/ad/ventes_immobilieres/3000000001",
  "title": "Appartement 3 pièces 64 m²",
  "description": "Lumineux, proche métro.\nLibre au 1er décembre.",
  "category": {
    "id": "9",
    "name": "Ventes immobilières"
  },
  "ad_type": "offer",
  "status": "active",
  "price": {
    "amount": 289000,
    "currency": "EUR"
  },
  "buyer_fee": null,
  "shipping": [],
  "published_at": "2026-10-21T07:14:00Z",
  "republished_at": "2026-11-02T08:30:12Z",
  "expires_at": "2027-01-01T08:30:12Z",
  "has_phone": true,
  "is_boosted": false,
  "paid_options": {
    "urgent": false,
    "gallery": false,
    "photosup": false,
    "sub_toplist": false,
    "continuous_top_ads": false,
    "highlight": false,
    "booster": false,
    "has_option": false
  },
  "photos": [
    {
      "url": "https://img.leboncoin.fr/api/v1/lbcpb1/images/00/00/00/example.jpg?rule=ad-large",
      "is_floor_plan": false
    }
  ],
  "photo_count": 1,
  "videos": [],
  "location": {
    "city": "Lyon",
    "postal_code": "69003",
    "district": null,
    "department": {
      "id": "69",
      "name": "Rhône"
    },
    "region": {
      "id": "22",
      "name": "Rhône-Alpes"
    },
    "country_code": "FR",
    "latitude": 45.75,
    "longitude": 4.85,
    "precision": null,
    "from_address": false
  },
  "seller": {
    "type": "pro",
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Acme Immobilier",
    "store_id": "1000001",
    "siren": "000000000",
    "activity_sector": "2",
    "no_salesmen": true,
    "fees_url": null
  },
  "attributes": [
    {
      "key": "real_estate_type",
      "label": "Type de bien",
      "value": "2",
      "value_label": "Appartement",
      "values": [
        "2"
      ],
      "values_label": null
    },
    {
      "key": "square",
      "label": "Surface habitable",
      "value": "64",
      "value_label": "64 m²",
      "values": [
        "64"
      ],
      "values_label": null
    },
    {
      "key": "energy_rate",
      "label": "Classe énergie",
      "value": "c",
      "value_label": "C",
      "values": [
        "c"
      ],
      "values_label": null
    }
  ],
  "calendar": null,
  "ids": {
    "listing_id": "3000000001",
    "user_id": "00000000-0000-0000-0000-000000000000",
    "store_id": "1000001"
  },
  "source_url": "https://www.leboncoin.fr/recherche?category=9&locations=Lyon__45.76_4.83_7308_5000__d69&sort=time&order=desc",
  "observed_at": "2026-11-02T09:00:00Z"
}
```

## Price

100 credits a call, whatever the page holds: a short last page costs a whole call. An empty page and a failed call are free.

## Errors

| Code | Status | Retry | Message |
|---|---|---|---|
| `invalid_url` | 422 | no | This URL is not a leboncoin.fr search this operation reads. |
| `invalid_cursor` | 422 | no | This cursor was not given by an answer; send `next` from the last answer as it is. |
| `site_challenge` | 503 | yes | Leboncoin asked to prove a person is there; retry in a minute (not charged). |
| `site_unavailable` | 503 | yes | Leboncoin did not answer in time or refused the call; retry later (not charged). |
| `unexpected_answer` | 424 | no | Leboncoin answered in a shape we do not read yet; we are told and fix it, and it is not charged. |
| `missing_api_key` | 401 | no | No API key: send it as `Authorization: Bearer <key>`. |
| `invalid_api_key` | 401 | no | The key is not valid, or not anymore. |
| `insufficient_credits` | 402 | no | The call costs more credits than are left. |
| `unknown_operation` | 404 | no | No such source and operation in the catalog. |
| `timeout` | 408 | yes | The call did not finish within its deadline (not charged). |
| `invalid_body` | 422 | no | The body is not a call: source, operation, options. |
| `invalid_options` | 422 | no | An option is missing or out of its contract; `param` names it. |
| `invalid_idempotency_key` | 400 | no | The Idempotency-Key header is not printable ASCII, or too long. |
| `concurrency_limit` | 429 | yes | The plan's calls at a time are all in progress (Free 1, Starter 2, Pro 10, Team 50); retry when one has finished (not charged, never queued). |
| `service_busy` | 503 | yes | Too many calls at once on the account; retry in a few seconds. |
| `balance_unavailable` | 503 | yes | The balance could not be read; retry in a few seconds. |

## Changelog

- **2.1.0** (2026-11-13): `next` keeps the search as it was written and goes on with `cursor`, opaque, as every paged operation of the API (Google's page tokens): copy `next` as before. The URL is no longer rewritten with the next page; its `page` still starts at any page.
- **2.0.0** (2026-11-13): `since` is gone: Leboncoin has no date filter, it was ours, and a page is now served exactly as Leboncoin serves it. To keep only the newest listings, a batch filters on `republished_at` and stops early on a search sorted by date, newest first.
- **1.0.0** (2026-11-02): First version on the API v2: one page of a leboncoin.fr search as the page shows it, featured copies in their place, with every description and attribute; `next` carries the page's cursor, so a search read page by page neither skips nor repeats a listing.

Schema: https://api.lobstr.io/v2/catalog/leboncoin/listings/search · All operations: https://api.lobstr.io/v2/catalog.md
