# OnTheMarket Search API Documentation

<p><strong>OnTheMarket Search API</strong> returns current UK property listings from OnTheMarket as JSON. Filter for-sale or to-rent homes by location, price, bedrooms, property type and radius, sort by price or update date, and page through the results. Each listing carries the id, title, display price with a numeric GBP value, bedrooms, bathrooms, address, postcode, features, tenure, coordinates, images, labels and the estate-agent branch summary. <code>total_results</code> is a cap (OnTheMarket surfaces at most 34 pages of 30 listings) and a valid empty result is a successful response.</p>

- **Documentation:** [https://scrappa.co/docs/onthemarket-api/onthemarket_search](https://scrappa.co/docs/onthemarket-api/onthemarket_search)
- **API group:** OnTheMarket API
- **Endpoint:** `GET https://scrappa.co/api/onthemarket/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `search_type` | string | Yes | for-sale or to-rent. |
| `location_id` | string | Yes | Location slug, e.g. nottingham. |
| `page` | integer | No | One-based page number, 1 to 34. 30 listings per page. Defaults to 1. |
| `sort_field` | string | No | recommended, price or update_date. Defaults to recommended. |
| `direction` | string | No | asc or desc. Defaults to desc. |
| `prop_types` | string | No | Comma-separated property types, e.g. detached,flats. |
| `min_price` | integer | No | Minimum price in GBP. |
| `max_price` | integer | No | Maximum price in GBP. |
| `min_bedrooms` | integer | No | Minimum number of bedrooms. |
| `max_bedrooms` | integer | No | Maximum number of bedrooms. |
| `radius` | number | No | Search radius in miles. |
| `under_offer` | boolean | No | Include under-offer properties. |
| `let_agreed` | boolean | No | Include let-agreed properties (to-rent only). |
| `exclusive_first` | boolean | No | List exclusive properties first. |
| `new_home_flag` | boolean | No | List new homes first. |

## Example response

```json
{
    "data": {
        "facets": [
            {
                "name": "property-features[]",
                "text": "Outside space",
                "terms": [
                    {
                        "id": "garden",
                        "text": "Garden"
                    }
                ]
            }
        ],
        "listings": [
            {
                "id": "20035804",
                "agent": {
                    "name": "Frank Innes - Mapperley",
                    "logo_url": "https://media.onthemarket.com/agents/companies/14665/260126142222870/logo-190x100.jpg",
                    "branch_id": 73818,
                    "telephone": "0115 691 4648",
                    "details_url": "https://www.onthemarket.com/agents/branch/frank-innes-mapperley/"
                },
                "price": "\u00a3275,000",
                "images": [
                    {
                        "url": "https://media.onthemarket.com/properties/20035804/1651432388/image-0-480x320.jpg",
                        "webp_url": "https://media.onthemarket.com/properties/20035804/1651432388/image-0-480x320.webp"
                    }
                ],
                "tenure": "Freehold",
                "address": "Marshall Road, Nottingham, Nottinghamshire, NG3",
                "reduced": true,
                "bedrooms": 2,
                "features": [
                    "Tenure: Freehold",
                    "Detached Bungalow",
                    "Two Bedrooms",
                    "Modernised Throughout"
                ],
                "for_sale": true,
                "location": {
                    "lat": 52.977144,
                    "lon": -1.115554
                },
                "postcode": "NG3",
                "bathrooms": 1,
                "spotlight": true,
                "main_label": "Reduced",
                "cover_image": {
                    "url": "https://media.onthemarket.com/properties/20035804/1651432388/image-0-480x320.jpg",
                    "webp_url": "https://media.onthemarket.com/properties/20035804/1651432388/image-0-480x320.webp"
                },
                "price_value": 275000,
                "images_count": 17,
                "property_url": "https://www.onthemarket.com/details/20035804/",
                "virtual_tour": true,
                "data_label_id": "reduced",
                "online_viewing": true,
                "property_title": "2 bedroom bungalow for sale",
                "address_locality": "Nottinghamshire",
                "floorplans_count": 1,
                "days_since_added_reduced": "Reduced < 7 days"
            }
        ],
        "search_metadata": {
            "page": 1,
            "has_more": true,
            "direction": "desc",
            "last_page": 34,
            "frame_size": 30,
            "sort_field": "recommended",
            "location_id": "nottingham",
            "search_type": "for-sale",
            "location_name": "Nottingham",
            "location_type": "town",
            "total_results": 3049,
            "total_results_display": "3,049"
        }
    },
    "meta": {
        "billable": true,
        "endpoint_family": "search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A public parameter is missing or invalid. This response is not billable. |
| 503 | Service Unavailable | The upstream source is temporarily unavailable. This response is not billable and can be retried. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)