# SeLoger: Search listings

`seloger/listings/search` · version 2.0.0 · pilot · 15 credits a call

One page of a seloger.com search, 30 listings, as the page shows them, the agency's phone included.

Categories: Real estate

## When to use

You need the property listings of a seloger.com search (to buy or to rent): price, previous price and its change, rooms, surfaces, energy class, photos with their room, transport nearby, and the seller (agency, agent, developer or private owner) with its phone numbers, SIREN and SIRET. Set the search up on seloger.com (place, property type, filters, sort), then pass its URL.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "seloger", "operation": "listings/search", "options": {"url": "https://www.seloger.com/classified-search?distributionTypes=Buy&estateTypes=House,Apartment&locations=AD08FR31096&order=DateDesc"}}'
```

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 seloger.com search, exactly as the browser shows it once the search is set up (place, property types, filters, sort), its `page` the page to start at (page=2 is the second page). Sort by date, newest first, with order=DateDesc. Every filter SeLoger reads is read; a parameter SeLoger does not filter on is refused, never ignored. SeLoger serves the first 9,990 results of a search (333 pages): narrow it (a price range, a smaller place) for more. |
| `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. |

## 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 | SeLoger's listing id (26IBQQJTVUFB); repeated in ids.listing_id. |
| `position` | integer | Its place among the results, across pages (30 a page): 31 is the first of page 2. |
| `url` | string (uri) | The listing on seloger.com. |
| `transaction` | string | null | buy or rent, as SeLoger files the listing. |
| `property_type` | string | null | SeLoger's type, in its own words: apartment, house, parking, plot, building, gastronomy_hotel... |
| `property_subtype` | string | null | studio, multi_storey, villa, restaurant...; null when SeLoger gives none. |
| `property_label` | string | null | The type as the page names it, in French: Appartement. |
| `title` | string | null | The card's title: Appartement à vendre. |
| `headline` | string | null | The line under it: T3 neuf de 69 m² avec extérieur de 5 m². |
| `description` | string | null | The listing's text as the search shows it; SeLoger cuts it at about 500 characters (it ends with "..."). |
| `status` | string | null | SeLoger's status: published on a search page. |
| `price` | object | null | The price: a sale's, a month's rent, a life annuity's lump sum (its monthly rent in price_note). |
| `price.amount` | number |  |
| `price.currency` | string | ISO 4217 |
| `price_period` | `month`, null | month for a rent; null for a sale. |
| `price_note` | string | null | What the card writes under the price, as written: the price per m² (12 294 €/m²), charges comprises or hors charges for a rent, a life annuity's monthly rent (et 596 €/mois). |
| `price_per_m2` | number | null | The price per m² the card shows, in the price's currency. |
| `previous_price` | object | null | The price before its last change, when SeLoger shows one (a crossed-out price). |
| `previous_price.amount` | number |  |
| `previous_price.currency` | string | ISO 4217 |
| `price_change_percent` | number | null | The change from previous_price, in percent of it: -8.55 is a drop (SeLoger's down arrow). |
| `charges_included` | boolean | null | A rent with its charges (cc) or without (hc); null for a sale. |
| `rooms` | integer | null |  |
| `bedrooms` | integer | null |  |
| `living_area` | number | null | m². |
| `plot_area` | number | null | m², a house's land. |
| `facts` | array | The facts the card lists, in its order and words: the floor (4ème étage, Étage 3/5), the availability (disponible dès maintenant), the rooms and surfaces said as text. |
| `facts[].type` | string | null | numberOfRooms, numberOfBedrooms, livingSpace, numberOfFloors, availability, overallSpace, plotSpace... |
| `facts[].text` | string | null |  |
| `energy_class` | string | null | The energy performance class (DPE), A to G. |
| `building_state` | string | null | SeLoger's state of the building: first_time_use, mint_condition, well_kept, refurbished, need_of_renovation, to_refurbish. |
| `year_built` | integer | null | The year of construction SeLoger gives (a new build's: its completion year). |
| `is_new` | boolean | SeLoger's Nouveau badge: put online recently. |
| `is_exclusive` | boolean | Offered by this seller alone (the Exclusivité badge). |
| `has_3d_visit` | boolean | The listing has a 3D or virtual visit. |
| `has_brokerage_fee` | boolean | SeLoger's flag of an agency fee shown apart; false on every listing of the 11/11 captures. |
| `new_build` | object | null | The new-build programme a lot belongs to (a developer's listing); null otherwise. |
| `new_build.name` | string | null |  |
| `new_build.description` | string | null |  |
| `new_build.url` | string | null (uri) | The programme on selogerneuf.com. |
| `photos` | array | Every photo, in the listing's order. |
| `photos[].url` | string (uri) |  |
| `photos[].room` | string | null | SeLoger's reading of the photo: living_room, kitchen, bedroom, bathroom, balcony, building_facade, logo (the agency's)... |
| `floor_plans` | array |  |
| `floor_plans[].url` | string (uri) |  |
| `location` | object |  |
| `location.city` | string | null | As SeLoger names it: Paris 18ème arrondissement. |
| `location.postal_code` | string | null |  |
| `location.district` | string | null | The neighbourhood: Raspail-Montparnasse. |
| `location.department` | string | null | Rhône, Paris. |
| `location.region` | string | null |  |
| `location.country` | string | null |  |
| `location.address_published` | boolean | The seller shows the street on the listing's page (a search never gives it). |
| `location.place_ids` | array | SeLoger's places the listing is in, from the smallest: each id can be a search's `locations=`. |
| `location.place_ids[].id` | string | null | AD08FR31096: Paris. |
| `location.place_ids[].level` | string | null | SeLoger's level of the place: AD08 a city, AD06 a department, AD02 the country, NBH2 a neighbourhood... |
| `location.transport` | array | The lines nearby the card shows, by kind. |
| `location.transport[].type` | string | null | metro, rer, tram, bus, train. |
| `location.transport[].lines` | array | Their names: 4, 6, B. |
| `published_at` | string | null (date-time) | When the listing was put online on SeLoger, UTC. |
| `updated_at` | string | null (date-time) | Its last change, UTC. |
| `seller` | object |  |
| `seller.type` | `private`, `pro` |  |
| `seller.kind` | string | null | agency, real_estate_agent, real_estate_developer; null for a private owner. |
| `seller.id` | string | null | SeLoger's id of the seller: RC-1887530. |
| `seller.name` | string | null | The agency's or developer's name; null for a private owner. |
| `seller.contact_name` | string | null | The person to contact the card names (an agent, a private owner's first name). |
| `seller.phones` | array | The seller's numbers the listing gives (an agency's; a private owner's number is not in a search). |
| `seller.phones[].number` | string | null | E.164 (+33626412481); a national number is French. |
| `seller.phones[].as_written` | string |  |
| `seller.address` | string | null | The seller's address. |
| `seller.city` | string | null |  |
| `seller.postal_code` | string | null |  |
| `seller.website` | string | null (uri) |  |
| `seller.profile_url` | string | null (uri) | The seller's page on seloger.com. |
| `seller.logo_url` | string | null (uri) |  |
| `seller.fees_url` | string | null (uri) | An agency's scale of fees. |
| `seller.siren` | string | null | The RCS number the seller gives: its SIREN. |
| `seller.siret` | string | null |  |
| `seller.legal` | array of string | The legal lines the listing shows, as text: the company's name and capital, its seat, RCS, SIRET, its financial guarantee. |
| `ids` | object | Every id SeLoger gives with the listing. |
| `ids.listing_id` | string |  |
| `ids.legacy_id` | string | null | The listing's former numeric id (SeLoger's older addresses). |
| `ids.client_id` | string | null | The seller's id: seller.id. |
| `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": "26EXAMPLE001",
  "position": 1,
  "url": "https://www.seloger.com/annonce/achat/ile-de-france/paris-75/paris-75000/26EXAMPLE001",
  "transaction": "buy",
  "property_type": "apartment",
  "property_subtype": null,
  "property_label": "Appartement",
  "title": "Appartement à vendre",
  "headline": "T3 lumineux de 68 m² avec balcon",
  "description": "À Paris, dans le 18ème arrondissement, ce T3 de 68 m² au 4ème étage...",
  "status": "published",
  "price": {
    "amount": 836000,
    "currency": "EUR"
  },
  "price_period": null,
  "price_note": "12 294 €/m²",
  "price_per_m2": 12294,
  "previous_price": {
    "amount": 865000,
    "currency": "EUR"
  },
  "price_change_percent": -3.35,
  "charges_included": null,
  "rooms": 3,
  "bedrooms": 2,
  "living_area": 68,
  "plot_area": null,
  "facts": [
    {
      "type": "numberOfRooms",
      "text": "3 pièces"
    },
    {
      "type": "livingSpace",
      "text": "68 m²"
    },
    {
      "type": "numberOfFloors",
      "text": "4ème étage"
    }
  ],
  "energy_class": "C",
  "building_state": "well_kept",
  "year_built": 1930,
  "is_new": true,
  "is_exclusive": false,
  "has_3d_visit": true,
  "has_brokerage_fee": false,
  "new_build": null,
  "photos": [
    {
      "url": "https://cdnihddipa.cloudimg.io/0/0/0/0/example.jpg",
      "room": "living_room"
    }
  ],
  "floor_plans": [],
  "location": {
    "city": "Paris 18ème arrondissement",
    "postal_code": "75018",
    "district": "Grandes-Carrières",
    "department": "Paris",
    "region": "Ile-de-France",
    "country": "France",
    "address_published": false,
    "place_ids": [
      {
        "id": "AD08FR31096",
        "level": "AD08"
      },
      {
        "id": "AD02FR1",
        "level": "AD02"
      }
    ],
    "transport": [
      {
        "type": "metro",
        "lines": [
          "13"
        ]
      }
    ]
  },
  "published_at": "2026-11-11T19:55:00Z",
  "updated_at": "2026-11-11T19:56:09Z",
  "seller": {
    "type": "pro",
    "kind": "agency",
    "id": "RC-0000001",
    "name": "Acme Immobilier",
    "contact_name": "Jeanne Martin",
    "phones": [
      {
        "number": "+33612345678",
        "as_written": "0612345678"
      }
    ],
    "address": "1 rue Exemple, 75018 Paris",
    "city": "Paris",
    "postal_code": "75018",
    "website": "https://www.example-agency.fr/",
    "profile_url": "https://www.seloger.com/professionnels-immobilier/example",
    "logo_url": null,
    "fees_url": null,
    "siren": "000000000",
    "siret": "00000000000000",
    "legal": [
      "Acme Immobilier",
      "Siège: 1 rue Exemple, 75018 Paris",
      "RCS: 000000000",
      "SIRET: 00000000000000"
    ]
  },
  "ids": {
    "listing_id": "26EXAMPLE001",
    "legacy_id": "200000000",
    "client_id": "RC-0000001"
  },
  "source_url": "https://www.seloger.com/classified-search?distributionTypes=Buy&estateTypes=House,Apartment&locations=AD08FR31096&order=DateDesc",
  "observed_at": "2026-11-12T09:00:00Z"
}
```

## Price

15 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 seloger.com search this operation reads. |
| `invalid_search` | 422 | no | SeLoger refuses this `search`; send it as the previous answer's `next` gives it, or the search's `url` alone. |
| `site_challenge` | 503 | yes | SeLoger asked to prove a person is there; retry in a minute (not charged). |
| `site_unavailable` | 503 | yes | SeLoger did not answer in time or refused the call; retry later (not charged). |
| `unexpected_answer` | 424 | no | SeLoger 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.0.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. `search` is no longer an option: the criteria SeLoger's page reads for a search by travel time or with no place travel inside the cursor. The URL's `page` still starts at any page.
- **1.2.0** (2026-11-12): Every page as fresh as SeLoger's search, the first included, and lighter: a search URL is read as SeLoger's own page reads it, then asked of its search service (about 47 KB a page instead of 170 KB). SeLoger's page is kept up to 15 minutes by its CDN: its newest listings came late, and the last of page 1 came again on page 2. `next` is a URL again; `search` only follows a search by travel time or with no place, read from its page.
- **1.1.0** (2026-11-12): A next page is lighter: `next` now holds `search`, the search as SeLoger reads its URL, and a call with it asks SeLoger's search service, as the site does from page 2 (about 47 KB instead of 170 KB). Same listings, same fields, same price; a URL alone, any page, is read as before.
- **1.0.0** (2026-11-12): First version on the API v2: one page of a seloger.com search as the page shows it, 30 listings with their previous price and its change, photos with their room, transport nearby, and the seller with its phone numbers, SIREN and SIRET; a filter SeLoger does not read is refused, never ignored.

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