# Bien'ici API scraper — French real-estate portal: property search by town or postcode, price, surface, rooms, transaction and property type, and the full listing (price, price per m², surface, rooms, energy and GHG class, heating, charges, fees, photos, agency). No account, no browser.

> Search Bien'ici (bienici.com) property listings for sale or rent in France: price (from-price on new-build programmes), price per m², surface, land, rooms, bedrooms, floor, energy and GHG class, heating, building year, charges and deposit, agency fees, town, postcode, district and map position, agency, photos and description. Filter by transaction, property type, town or postcode, price, surface, rooms, bedrooms, new build and keywords; sort by relevance, newest, price or surface; paginated.
> ReefAPI engine `bienici` · 2 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/bienici/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/bienici/v1/search — 1 credit
Search Bien'ici (bienici.com) property listings for sale or rent in France: price (from-price on new-build programmes), price per m², surface, land, rooms, bedrooms, floor, energy and GHG class, heating, building year, charges and deposit, agency fees, town, postcode, district and map position, agency, photos and description. Filter by transaction, property type, town or postcode, price, surface, rooms, bedrooms, new build and keywords; sort by relevance, newest, price or surface; paginated.

**Parameters:**
- `transaction` (enum, required) — sale or rent. [one of: sale, rent]
- `query` (string, optional) — Keywords that must all appear in the title or description (accents and case ignored). bienici has no keyword search of its own, so the engine scans results for matches; total is then null and next_page_token resumes the scan.
- `property_type` (array, optional) — One or more of apartment, house, land, parking, building, office, commercial, loft, townhouse, castle, new_build_programme, other. Default: all. [one of: apartment, house, land, parking, building, office, commercial, loft, townhouse, castle, new_build_programme, other]
- `city` (string, optional) — Town name, e.g. Lyon, Bordeaux, Paris.
- `zipcode` (string, optional) — 5-digit French postcode (alone or with city).
- `price_min` (number, optional) — Lowest price in EUR (monthly rent, charges included, for rentals).
- `price_max` (number, optional) — Highest price in EUR (monthly rent, charges included, for rentals).
- `surface_min` (number, optional) — Smallest living surface, m².
- `surface_max` (number, optional) — Largest living surface, m².
- `rooms_min` (integer, optional) — Fewest rooms (pièces).
- `rooms_max` (integer, optional) — Most rooms (pièces).
- `bedrooms_min` (integer, optional) — Fewest bedrooms.
- `new_build` (boolean, optional) — true: new-build only; false: existing homes only.
- `sort` (enum, optional, default "relevance") — relevance, newest, price_asc, price_desc, surface_asc or surface_desc. [one of: relevance, newest, price_asc, price_desc, surface_asc, surface_desc]
- `page` (integer, optional, default 1) — Result page (bienici serves the first 2,500 results of a search).
- `limit` (integer, optional, default 24) — Rows per page, up to 100.
- `page_token` (string, optional) — With query (or a postcode inside a multi-postcode town): the next_page_token of the previous page, to continue the scan.
- `include_pii` (boolean, optional, default false) — Also return the contact person's name/phone and an independent agent's name.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** listings[]{ad_id, reference, title, url, status, price, currency, price_is_from, price_max, price_not_published, price_has_decreased, published_at, updated_at, location{city, zipcode, district, department_id, country, latitude, longitude, coordinates_precision, coordinates_radius_m}, seller{type, account_type, name, siren, has_phone}, thumbnail, image_count, images[], description, property{property_type, transaction, is_new_build, surface_m2, surface_max_m2, land_surface_m2, rooms, bedrooms, bathrooms, shower_rooms, toilets, floor, floors_in_building, elevator, balcony, terrace, garden, pool, cellar, parking_spaces, features[], energy_class, ghg_class, energy_consumption_kwh_m2, ghg_emissions_kg_m2, annual_energy_cost_min, annual_energy_cost_max, heating_type, building_year, orientation, furnished, available_from, price_per_m2, rent_excluding_charges, monthly_charges, charges_included, security_deposit, rental_fees, agency_fees_paid_by, agency_fees_pct, price_excluding_fees, annual_condo_charges, rent_control{…}, virtual_tour_url, …}}, count, total, page, limit, has_more, next_page_token, sort_applied, location_applied{name, type, postal_codes}, text_match{mode, scanned, matched}

**Example request body:**
```json
{
  "transaction": "sale",
  "city": "Lyon"
}
```

### POST https://api.reefapi.com/bienici/v1/listing — 1 credit
One Bien'ici listing by id or URL: price, price per m², surface, land, rooms, bedrooms, bathrooms, floor, elevator, energy (DPE) and GHG class with kWh and CO2 figures and the annual energy bill range, heating, building year, charges, deposit, fees, rent control, transaction and property type, town, postcode, district, map position and its precision, photos, description, publication date and the agency (name, RCS).

**Parameters:**
- `ad_id` (string, required) — The bienici ad id (the last part of an ad URL, e.g. ag691943-549827780) or the full ad URL.
- `include_pii` (boolean, optional, default false) — Also return the contact person's name/phone and an independent agent's name.
- `max_rotations` (integer, optional, default 3) — Upstream attempts on fresh exits before giving up.

**Returns:** listing{ad_id, reference, title, url, status, price, currency, price_is_from, price_max, price_not_published, price_has_decreased, published_at, updated_at, location{city, zipcode, district, department_id, country, latitude, longitude, coordinates_precision, coordinates_radius_m}, seller{type, account_type, name, siren, has_phone}, thumbnail, image_count, images[], description, property{property_type, transaction, is_new_build, surface_m2, surface_max_m2, land_surface_m2, rooms, bedrooms, bathrooms, shower_rooms, toilets, floor, floors_in_building, elevator, balcony, terrace, garden, pool, cellar, parking_spaces, features[], energy_class, ghg_class, energy_consumption_kwh_m2, ghg_emissions_kg_m2, annual_energy_cost_min, annual_energy_cost_max, heating_type, building_year, orientation, furnished, available_from, price_per_m2, rent_excluding_charges, monthly_charges, charges_included, security_deposit, rental_fees, agency_fees_paid_by, agency_fees_pct, price_excluding_fees, annual_condo_charges, rent_control{…}, virtual_tour_url, …}}

**Example request body:**
```json
{
  "ad_id": "ag691943-549827780"
}
```

## 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=bienici
- Human docs page: https://reefapi.com/docs/bienici
- Overview page: https://reefapi.com/bienici-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt