# Rightmove API scraper — UK property data: for-sale, to-rent, commercial and student listings with full filters (price, beds, baths, property type, size, radius, added-within, sort, furnishing), complete property detail (price, EPC, floorplans, key features, nearest stations, agent), estate-agent branch profiles, Land-Registry sold prices and location autocomplete — no API key required

> resolve a text location to a Rightmove locationIdentifier (LOS typeahead)
> ReefAPI engine `rightmove` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/rightmove/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 or blocked calls are free.
- **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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /rightmove/v1/location_search — 0 credits
resolve a text location to a Rightmove locationIdentifier (LOS typeahead)

**Parameters:**
- `query` (string, required) — Free-text place to resolve (town, postcode, station, region).
- `limit` (integer, optional, default 10) — Max location matches to return.

**Returns:** matches[] (location_identifier/id/type/display_name), count

**Example request body:**
```json
{
  "query": "London"
}
```

### POST /rightmove/v1/search — 2 credits
Search UK property listings by location (for sale / to rent / commercial / student) with structured filters: price, beds, baths, property type, size, radius, added-within, sort, and (rent) furnishing & let-type. Paginate with index/max_pages.

**Parameters:**
- `location` (string, optional) — Free-text location (auto-resolved to a Rightmove locationIdentifier). Provide this OR location_identifier.
- `location_identifier` (string, optional) — A Rightmove locationIdentifier from location_search (e.g. REGION^87490, OUTCODE^2522, BRANCH^45021). Provide this OR location.
- `channel` (enum, optional, default "buy") — Rightmove channel to search (default buy). Canonical values + the listed aliases are accepted; any other value is rejected with this list. [one of: buy, rent, new_homes, commercial_sale, commercial_rent, student, for_sale, sale, to_rent, lettings, commercial, new_build]
- `for_rent` (boolean, optional) — Shortcut: true selects the rent channel when `channel` is not set.
- `price_min` (integer, optional) — Minimum price in GBP (sale price, or monthly rent for channel=rent).
- `price_max` (integer, optional) — Maximum price in GBP (sale price, or monthly rent for channel=rent).
- `beds_min` (integer, optional) — Minimum bedrooms (2 = 2+; use 0 for studios).
- `beds_max` (integer, optional) — Maximum bedrooms.
- `baths_min` (integer, optional) — Minimum bathrooms (2 = 2+).
- `property_type` (string, optional) — Property type — one or several comma-separated. One of: detached, semi-detached, terraced, flat, bungalow, land, park-home (e.g. 'detached,semi-detached'). 'apartment'=flat.
- `sqft_min` (integer, optional) — Minimum floor area in square FEET.
- `sqft_max` (integer, optional) — Maximum floor area in square feet.
- `radius` (number, optional) — Search radius in MILES around the location (0=this area only; 0.25/0.5/1/3/5/10/15/20/30/40).
- `added_within_days` (integer, optional) — Only listings added within the last N days (1=last 24h, 7=this week, 14, 30...).
- `sort` (enum, optional) — Result ordering (default = Rightmove's relevance/featured order). [one of: newest, oldest, price_high, price_low]
- `furnished` (enum, optional) — RENT only: furnishing type. [one of: furnished, unfurnished, partFurnished, furnishedOrUnfurnished]
- `let_type` (enum, optional) — RENT only: let duration. [one of: longTerm, shortTerm]
- `must_have` (enum, optional) — Require a feature (one of garden/parking/newHome/retirement/auction). [one of: garden, parking, newHome, retirement, auction]
- `dont_show` (enum, optional) — Exclude a listing class (newHome/retirement/sharedOwnership/auction). [one of: newHome, retirement, sharedOwnership, auction]
- `include_sstc` (boolean, optional) — Include Sold STC / Under Offer listings (buy channel). Default false.
- `max_pages` (integer, optional, default 1) — How many 24-result pages to fetch and merge (ignored when fetch_all=true).
- `fetch_all` (boolean, optional) — Fetch every page up to Rightmove's ~1,000-result cap (overrides max_pages).
- `index` (integer, optional, default 0) — Starting result offset; increments by 24 per page (0, 24, 48, ...).
- `filters` (object, optional) — Advanced escape-hatch: extra raw Rightmove query params as a key->value map, merged AFTER (and overriding) the typed filters above. Only needed for niche params not exposed as first-class fields.

**Returns:** items[] (property_id/price_amount/price_display/bedrooms/bathrooms/lat/lon/agent/...), count, channel, result_count (true market total), filters_applied, pages_fetched, stop_reason

**Example request body:**
```json
{
  "location": "London"
}
```

### POST /rightmove/v1/property_detail — 3 credits
Full property record: price (+£/sqft), description, key features, tenure & lease years, living costs (council tax band, service charge, ground rent), structured features (utilities/heating/parking/garden/flood-risk), images, floorplans, EPC graphs, sizings, nearest stations, street-view coords and the listing agent.

**Parameters:**
- `property_id` (string, required) — Rightmove property id (the digits in a /properties/<id> URL or a search result's property_id).

**Returns:** listing{} — description, key_features[], price(+£/sqft), tenure, years_remaining_on_lease, living_costs{council_tax_band, annual_service_charge, annual_ground_rent}, features{}, images[], floorplans[], epc_graphs[], sizings[], nearest_stations[], street_view{}, shared_ownership{}, agent{}

**Example request body:**
```json
{
  "property_id": "148711631"
}
```

### POST /rightmove/v1/agent — 1 credit
estate-agent branch profile (+ that branch's live listings via BRANCH^id)

**Parameters:**
- `branch_url` (string, optional) — An estate-agent branch landing-page URL (full or path). Provide this OR branch_id.
- `branch_id` (integer, optional) — Rightmove branch id — lists that branch's live stock via BRANCH^id. Provide this OR branch_url.
- `max_pages` (integer, optional, default 1) — How many 24-result pages to fetch and merge (ignored when fetch_all=true).

**Returns:** agent{} (branch_display_name/company_name/telephones/total_properties_for_sale/...); with branch_id also returns that branch's listings[]

**Example request body:**
```json
{
  "branch_url": "/estate-agents/agent/Aspire/Clapham-45021.html"
}
```

### POST /rightmove/v1/similar — 2 credits
listings similar to a property (same area + price/bedroom band)

**Parameters:**
- `property_id` (string, required) — Rightmove property id (the digits in a /properties/<id> URL or a search result's property_id).

**Returns:** items[] (comparable listings, same shape as search), count, source_property_id, similar_url

**Example request body:**
```json
{
  "property_id": "148711631"
}
```

### POST /rightmove/v1/sold_prices — 2 credits
sold/transaction history: by location (search) or per-property (detail_url|uuid). Land-Registry sold data with full per-address transaction history.

**Parameters:**
- `location` (string, optional) — Area for sold-price history (postcode/outcode/town, e.g. 'SW9', 'KT2 5HF'). Provide this OR detail_url/uuid.
- `detail_url` (string, optional) — A house-prices detail URL for one property's sold history (alternative to location).
- `uuid` (string, optional) — A house-prices detail uuid for one property's sold history (alternative to location).
- `page` (integer, optional, default 1) — 1-based page of sold-price results (area mode).

**Returns:** area mode: items[] (address/property_type/transactions[]/latest_price/lat/lon), count, total_reported; per-property mode (detail_url|uuid): listing{} with full transactions[]

**Example request body:**
```json
{
  "location": "SW9"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=rightmove
- Human docs page: https://reefapi.com/docs/rightmove
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt