# OnTheMarket API scraper — UK property data: for-sale and to-rent listings with full filters (price, beds, property type, radius, keywords, added-within, sort), complete property detail (price, beds/baths, description, key features, tenure & council-tax, photos, floorplans, nearby stations & schools, area stats, agent) and location autocomplete from OnTheMarket.com — the UK's #3 property portal — no API key required

> Resolve a text location (town, postcode, borough, area) to OnTheMarket location slug(s). Returns multiple ranked matches; use a result's location_id in search.
> ReefAPI engine `onthemarket` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/onthemarket/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 /onthemarket/v1/location_search — 0 credits
Resolve a text location (town, postcode, borough, area) to OnTheMarket location slug(s). Returns multiple ranked matches; use a result's location_id in search.

**Parameters:**
- `query` (string, required) — Free-text place to resolve (town, city, postcode, borough, area).
- `channel` (enum, optional, default "for-sale") — Which market to search/resolve (default for-sale). Canonical values + the listed aliases are accepted; any other value is rejected with this list. [one of: for-sale, to-rent, buy, sale, rent, lettings]
- `limit` (integer, optional, default 10) — Max location matches to return.

**Returns:** matches[]{location_id, name, display_name}, count

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

### POST /onthemarket/v1/search — 2 credits
Search UK property listings by location (for sale / to rent) with structured filters: price, beds, property type, radius, keywords, added-within and sort. Paginate with page/max_pages (30 per page).

**Parameters:**
- `location` (string, optional) — Free-text location OR an OnTheMarket location slug (e.g. 'london', 'sw9', 'manchester'). Provide this OR location_id. Use location_search for the exact slug.
- `location_id` (string, optional) — An OnTheMarket location slug from location_search (its `location_id`/seo_id, e.g. 'notting-hill', 'bs1'). Most precise. Provide this OR location.
- `channel` (enum, optional, default "for-sale") — Which market to search/resolve (default for-sale). Canonical values + the listed aliases are accepted; any other value is rejected with this list. [one of: for-sale, to-rent, buy, sale, rent, lettings]
- `for_rent` (boolean, optional) — Shortcut: true selects the to-rent channel when `channel` is unset.
- `price_min` (integer, optional) — Minimum price in GBP (sale price, or monthly rent £pcm for to-rent).
- `price_max` (integer, optional) — Maximum price in GBP (sale price, or monthly rent £pcm for to-rent).
- `beds_min` (integer, optional) — Minimum bedrooms (2 = 2+; 0 for studios).
- `beds_max` (integer, optional) — Maximum bedrooms.
- `property_type` (string, optional) — Property type(s), comma-separated. One or more of: flat, apartment, houses, detached, semi-detached, terraced, bungalow, studio, cottage, mews, park-home, land (e.g. 'detached,semi-detached'). 'house'=houses.
- `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).
- `added_within_days` (integer, optional) — Only listings added recently; mapped to the nearest supported window (1, 3, 7 or 14 days).
- `sort` (enum, optional) — Result ordering (default = OnTheMarket's recommended order). [one of: recommended, newest, price_high, price_low]
- `keywords` (string, optional) — Free-text keyword filter (e.g. 'garden', 'garage', 'parking').
- `retirement_only` (boolean, optional) — Only retirement properties.
- `shared_ownership_only` (boolean, optional) — Only shared-ownership properties.
- `auction_only` (boolean, optional) — Only auction properties.
- `new_homes_only` (boolean, optional) — Only new-build homes.
- `include_under_offer` (boolean, optional) — Include Under Offer / Sold STC listings (for-sale).
- `page` (integer, optional, default 1) — 1-based result page (30 listings per page).
- `max_pages` (integer, optional, default 1) — How many 30-result pages to fetch and merge, starting at `page`.
- `filters` (object, optional) — Advanced escape-hatch: extra raw OnTheMarket query params as a key->value map, merged after the typed filters above.

**Returns:** items[]{property_id, title, price_display, price_amount?, bedrooms, property_type, address, latitude, longitude, features[], images[], details_url, agent{}}, count, channel, total_results (market total), filters_applied, pages_fetched, stop_reason

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

### POST /onthemarket/v1/property_detail — 3 credits
Full property record: price (+qualifier), beds/baths, description, key features, key-info (tenure, council-tax band), images, floorplans, virtual/video tours, documents, nearby stations & schools, area stats (avg price, crime level), breadcrumbs and the listing agent.

**Parameters:**
- `property_id` (string, required) — OnTheMarket property id (the digits in a /details/<id>/ URL or a search result's property_id).
- `url` (string, optional) — Alternatively a full OnTheMarket property detail URL.

**Returns:** listing{} — title, price_display, price_amount, price_qualifier, bedrooms, bathrooms, description, features[], key_info[], images[], floorplans[], virtual_tours[], stations[], schools[], area_stats{}, breadcrumbs[], agent{}

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

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