# ESPC Scotland Property Scraper (`vivid-softwares/espc-scotland-property-scraper`) Actor

Scrape ESPC.com, Scotland's property search site. Get homes for sale by area, postcode or school catchment, sold house prices, closing dates, EPC, council tax, agents, photos and floor plans.

- **URL**: https://apify.com/vivid-softwares/espc-scotland-property-scraper.md
- **Developed by:** [VividSoftwares](https://apify.com/vivid-softwares) (community)
- **Categories:** Real estate, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$14.00 / 1,000 property listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does ESPC Scotland Property Scraper do?

**ESPC Scotland Property Scraper** extracts property listings and **sold house prices** from [ESPC.com](https://espc.com), one of Scotland's most visited property search websites. Search **by area, town, neighbourhood, postcode district or school catchment** and get clean JSON with **prices, "offers over" and fixed-price terms, closing dates, EPC ratings, council tax bands, floor areas, rooms, agent contact details, photos, floor plans, videos and virtual tours**.

It is a **dedicated ESPC scraper** and a practical **Scottish property listings API**. You can run it from Apify Console, call it over the API, schedule it, or connect it to AI agents through MCP.

- 🏠 **Property for sale** across Scotland, the core of ESPC's listings
- 🏫 **School catchment** searches, the same as ESPC's Schools tab
- 💷 **Sold house prices** with full sale history for Scottish addresses
- 🔑 **Property to rent** (ESPC shows a small number of rental listings)

### Why use this ESPC scraper?

ESPC lists homes marketed by Scottish solicitor estate agents, many of them **exclusive to ESPC**. Scottish listings also carry details the big UK portals rarely structure well, such as **"Offers Over" pricing, closing dates, Home Report links and solicitor agents**. ESPC's sold prices cover **Scotland**, which HM Land Registry price-paid data (England and Wales) does not.

Common uses:

- **Property market research** for Edinburgh, the Lothians, Fife, the Borders, Glasgow and the rest of Scotland
- **Price tracking**: compare asking prices, "offers over" levels and recent sold prices by postcode
- **UK property lead generation**: build lists of active solicitor estate agents with their publicly listed phone numbers and email addresses
- **Investor deal sourcing**: find new listings, fixed-price homes, shared-ownership homes or properties with closing dates
- **School catchment analysis**: see what is for sale inside a school's catchment
- **Property data for AI agents**: give an assistant structured Scottish listings to reason over

### How to scrape ESPC property listings

#### Option 1: paste an ESPC search URL (recommended)

1. Go to [espc.com](https://espc.com) and run a search with any filters you like: location, price, bedrooms, property type, EPC, features, "added in the last 7 days" and so on.
2. Copy the results URL from your browser, for example `https://espc.com/properties?locations=edinburgh&new=7&ptype=house_13` (terraced houses in Edinburgh added in the last 7 days).
3. Paste it into **ESPC search or property URLs** on the Input tab, set **Maximum listings** and click **Start**.

The Actor reads every results page of that search and opens each property for full details. You can paste several URLs at once, including property pages, area pages such as `espc.com/property-for-sale/edinburgh/flats` and sold-price pages such as `espc.com/house-prices/eh4`.

#### Option 2: use the optional search builder

If you prefer not to copy URLs, or you are calling the Actor from code or an AI agent, pick a **Search type** and one or more **Areas and towns**, **Postcode districts** or a **School catchment**, then add filters. The builder uses exactly the same values as ESPC's search form. URLs and builder searches can be combined in one run, and duplicates are removed.

Download the results as JSON, CSV, Excel or HTML, or read them through the API.

### Supported searches

| Search type | What you get | ESPC equivalent |
|---|---|---|
| Property for sale | Every sale listing matching your filters | Buy tab and Advanced search |
| Property for sale in a school catchment | Sale listings inside one school's catchment | Schools tab |
| Sold house prices | Recorded Scottish sales with sale history | Sold Prices tab |
| Property to rent | ESPC's rental listings | Rent tab |

### Input

The main input is `startUrls`. Every other search field belongs to the optional search builder, and its dropdowns mirror ESPC's own search form, so every value is one ESPC accepts.

| Field | Description |
|---|---|
| `startUrls` | **Main input.** ESPC search result URLs (all pages are scraped), property pages, area pages or sold-price pages |
| `searchType` | `forSale`, `toRent`, `schoolCatchment` or `soldPrices` |
| `locations` | ESPC areas, towns and neighbourhoods, for example `edinburgh`, `edinburgh-city-centre/stockbridge`, `east-fife/st-andrews`. Use `scotland` for everything. |
| `postcodeDistricts` | Scottish postcode districts ESPC recognises, for example `eh4`, `ky12`, `g42` |
| `school` | School catchment ID from the list (school catchment search only) |
| `minPrice`, `maxPrice` | Sale price limits from ESPC's list (£50k to £3m) |
| `minRent`, `maxRent` | Monthly rent limits (£250 to £2,500) |
| `bedrooms` | Minimum (`2plus`) or exact (`2`) bedrooms |
| `propertyTypes` | 55 ESPC property types, from *Flat (all)* to *Flat - Top Floor*, *Bungalow - Detached*, *Cottage*, *Plot*, *Commercial*, *Retirement* |
| `features` | 78 advanced-search features: parking, gardens, heating, accessibility, energy efficiency, style, open viewings and purchase options such as *Shared ownership* or *Auction* |
| `epcRatings` | EPC ratings A to G |
| `includeUnderOffer`, `addedLast7Days`, `fixedPriceOnly`, `exclusiveOnly`, `newBuildsOnly` | ESPC's search checkboxes |
| `sortBy` | `datedesc`, `priceasc` or `pricedesc` |
| `soldWithin`, `soldPropertyType` | Sold price period (3 months to 5 years) and house or flat |
| `maxItems` | Maximum number of saved listings (default 50) |
| `scrapeDetails` | Open each property page for full details (default on) |
| `includeImages` | Include photo URLs (default on) |
| `includeDuplicates` | Include listings from previous runs (default off, so only new listings are returned and charged) |
| `proxyConfiguration` | Apify Proxy, on by default. ESPC does not respond to requests sent directly from Apify servers, so keep it enabled. |

#### Location and postcode support

- **1,333 ESPC areas, towns and neighbourhoods**, taken from ESPC's published area list. Each name includes its ESPC region, so places with the same name stay separate (for example *Stockbridge, Edinburgh City Centre*). Names with spaces, commas, ampersands and apostrophes work, such as *St Andrews, East Fife*, *Aberdour, Kinross & West Fife* and *St. John's Town of Dalry, Stewartry*.
- **441 Scottish postcode districts** from AB to ZE, each checked against ESPC.
- **570 school catchments**. Schools with the same name show their town.
- To search a single street or postcode sector, run the search on ESPC and paste the results URL into `startUrls`.

#### Example input: search URL

```json
{
  "startUrls": [{ "url": "https://espc.com/properties?locations=edinburgh&new=7&ptype=house_13" }],
  "maxItems": 100
}
```

#### Example input: search builder

```json
{
  "searchType": "forSale",
  "locations": ["edinburgh-city-centre/stockbridge", "edinburgh-south/morningside"],
  "postcodeDistricts": ["eh4"],
  "minPrice": "200000",
  "maxPrice": "450000",
  "bedrooms": "2plus",
  "propertyTypes": ["flat"],
  "includeUnderOffer": false,
  "sortBy": "datedesc",
  "maxItems": 100,
  "scrapeDetails": true,
  "includeImages": true
}
```

### Output

Each property listing is one dataset item. Fields that ESPC does not show for a listing are left out rather than filled with guesses. You can download the dataset in various formats such as **JSON, CSV, Excel, XML or HTML**.

#### Example property listing

```json
{
  "listing_id": "36412955",
  "url": "https://espc.com/property/3f2-5-comely-bank-row-edinburgh-eh4-1dz/36412955",
  "search_type": "forSale",
  "title": "1 bed third floor flat for sale in Comely Bank",
  "listing_status": "for_sale",
  "price_text": "Offers Over £259,950",
  "price": 259950,
  "price_qualifier": "Offers Over",
  "currency": "GBP",
  "address": "3F2, 5 Comely Bank Row, EDINBURGH, EH4 1DZ",
  "street_address": "3F2, 5 Comely Bank Row",
  "locality": "Comely Bank",
  "city": "Edinburgh",
  "region": "Edinburgh City Centre",
  "postcode": "EH4 1DZ",
  "outcode": "EH4",
  "country": "Scotland",
  "latitude": 55.95815658569336,
  "longitude": -3.2160985469818115,
  "property_type": "Third Floor Flat",
  "bedrooms": 1,
  "bathrooms": 1,
  "reception_rooms": 1,
  "floor_area_sqm": 45,
  "floor_area_sqft": 484,
  "tenure": "Freehold",
  "council_tax_band": "C",
  "epc_rating": "C",
  "description": "Situated in the highly sought-after residential area of Comely Bank, this delightfully bright one-bedroom third-floor apartment is presented in excellent order throughout. The prop…",
  "key_features": [
    "No onward chain",
    "ideal first time buy or investment",
    "A stones throw from Leith Walk and Stockbridge's local amenities"
  ],
  "rooms": [
    {
      "name": "Hall",
      "width_m": 1.12,
      "length_m": 2.92
    },
    {
      "name": "Box Room/Office",
      "width_m": 2.28,
      "length_m": 1.98
    }
  ],
  "viewing_arrangements": "By apt with selling agents 0131 556 0159",
  "is_new": true,
  "is_exclusive": true,
  "is_new_build": false,
  "is_featured": false,
  "has_video": true,
  "has_virtual_tour": false,
  "agent_id": "37965",
  "agent_name": "Sturrock, Armstrong & Thomson - Property Department",
  "agent_phone": "0131 253 2726",
  "agent_email": "property@satsolicitors.co.uk",
  "agent_address": "7a Dundas Street, Edinburgh, EH3 6QG",
  "agent_website": "http://www.satsolicitors.co.uk",
  "agent_logo_url": "https://images.espc.com/espc/org-logo/ZGFtOi8vLzJiZWQ1NjJkLTkzNGEtNDE0Ni04ZjFiLWFkN2I1NjcwYWRhMA==.png",
  "property_reference": "E513936",
  "home_report_request_url": "https://espc.com/property/home-report?propertyId=36412955",
  "schedule_pdf_url": "https://media.scottishhomereports.com/MediaServer/PropertyMarketing/587935/Schedule/11233474.pdf",
  "floorplans": [
    "https://media.scottishhomereports.com/MediaServer/PropertyMarketing/587935/FloorPlan/fp11233474.jpg"
  ],
  "video_url": "https://player.vimeo.com/video/1222371175?byline=0&title=0&owner=0&name=0&logos=0&profile=0&profilepicture=0&vimeologo=0&portrait=0",
  "main_image_url": "https://espc.com/images?i=https://media.scottishhomereports.com/MediaServer/PropertyMarketing/587935/MainImage/587935_0.202609251136.jpg&width=1200&height=800",
  "images": [
    "https://espc.com/images?i=https://media.scottishhomereports.com/MediaServer/PropertyMarketing/587935/MainImage/587935_0.202609251136.jpg&width=1200&height=800",
    "https://espc.com/images?i=https://media.scottishhomereports.com/MediaServer/PropertyMarketing/587935/AdditionalImage/587935_1.202609251136.jpg&width=1200&height=800",
    "…"
  ],
  "image_count": 16,
  "schools": [
    {
      "school_id": "5523826",
      "name": "Flora Stevenson Primary School",
      "address": "Comely Bank, Edinburgh EH4 1BG",
      "latitude": 55.9584704480838,
      "longitude": -3.22496653518364,
      "catchment_search_url": "https://espc.com/properties?school=5523826"
    }
  ],
  "sold_prices_nearby_urls": [
    "https://espc.com/house-prices/eh4",
    "https://espc.com/house-prices/edinburgh-north",
    "https://espc.com/house-prices/edinburgh-city-centre"
  ],
  "detail_page_complete": true,
  "scraped_at": "2026-09-27T16:42:04.825500+00:00"
}
```

#### Example sold house price

```json
{
  "listing_id": "35985955",
  "url": "https://espc.com/property/21-2-learmonth-gardens-edinburgh-eh4-1ha/35985955",
  "search_type": "soldPrices",
  "listing_status": "sold",
  "price": 520000,
  "currency": "GBP",
  "address": "21/2 Learmonth Gardens, Edinburgh, EH4 1HA",
  "street_address": "21/2, Learmonth Gardens",
  "city": "Edinburgh",
  "postcode": "EH4 1HA",
  "outcode": "EH4",
  "country": "Scotland",
  "latitude": 55.957052098327516,
  "longitude": -3.2206767480561913,
  "property_type": "Flat",
  "last_sold_price": 520000,
  "last_sold_date": "2026-03-02",
  "sale_history": [
    {
      "date": "2026-03-02",
      "price": 520000,
      "change_percent": 0.0
    },
    {
      "date": "2026-02-26",
      "price": 520000
    }
  ],
  "detail_page_complete": true,
  "scraped_at": "2026-09-27T16:40:02.844570+00:00"
}
```

#### Output fields

| Group | Fields |
|---|---|
| Listing | `listing_id`, `url`, `search_type`, `title`, `headline`, `listing_status` (`for_sale`, `under_offer`, `to_let`, `sold`), `property_reference`, `is_new`, `is_exclusive`, `is_new_build`, `is_featured` |
| Price | `price_text`, `price`, `price_qualifier` (Offers Over, Fixed Price, Price Guide, In The Region Of…), `price_frequency`, `currency`, `closing_date`, `closing_date_text` |
| Address | `address`, `street_address`, `locality`, `city`, `region`, `postcode`, `outcode`, `country`, `latitude`, `longitude`, `google_maps_url`, `street_view_url` |
| Property | `property_type`, `bedrooms`, `bathrooms`, `reception_rooms`, `floor_area_sqm`, `floor_area_sqft`, `tenure`, `council_tax_band`, `epc_rating`, `service_charge`, `ground_rent`, `shared_ownership_percent`, `lease_length`, `deposit`, `landlord_registration`, `letting_agent_registration` |
| Description | `highlight`, `summary`, `description`, `key_features`, `rooms` (name and dimensions in metres), `viewing_arrangements` |
| Agent | `agent_id`, `agent_name`, `agent_phone`, `agent_email`, `agent_address`, `agent_website`, `agent_logo_url`, `agent_contact_name`, `agent_contact_phone`, `agent_contact_email` |
| Documents and media | `home_report_request_url`, `schedule_pdf_url`, `floorplan_url`, `floorplans`, `video_url`, `virtual_tour_url`, `main_image_url`, `images`, `image_count`, `has_video`, `has_virtual_tour` |
| Area | `schools` (catchment schools with address, coordinates and catchment search link), `sold_prices_nearby_urls` |
| Sold prices | `last_sold_price`, `last_sold_date`, `sale_history` (date, price and percentage change) |
| Run | `detail_page_complete`, `scraped_at` |

The Output tab has four views: **Property listings**, **Photos, floor plans and media**, **Agent contacts** and **Sold house prices**. Map and Street View links are built from the listing coordinates, the same point ESPC's Map and Street view buttons show. A `RUN_SUMMARY` record in the key-value store lists property URLs that ESPC no longer shows (`unavailable_urls`) and any that could not be loaded after several attempts (`failed_urls`).

### Duplicate prevention and new-listing monitoring

- **Within a run**, each listing is saved once, even if it appears in several of your URLs, areas or postcode districts.
- **Across runs**, the Actor remembers the listings it has already saved for your account. By default it skips them and does not charge for them, so a scheduled daily or weekly run only returns **new ESPC listings**. Turn on **Include listings from previous runs** (`includeDuplicates`) to get every matching listing again. Each item has `seen_in_previous_run` so you can tell them apart.
- Sold prices count as new when the same property sells again.
- The history is kept in a dataset named `espc-history-<your user ID>` in your own Apify account. Delete it to start fresh.

### Search pagination

The Actor reads every results page (50 listings per page) until it reaches the number of results ESPC reports or your **Maximum listings** limit. Listings are de-duplicated by ESPC listing ID, so a property that appears in two of your searches, or in a search and a pasted URL, is saved once. ESPC's sold-price search shows at most 10,000 sales per search; narrow it by postcode district, area or period to go further.

### Use the ESPC scraper through the API

Run the Actor and fetch the results with a single HTTP request:

```bash
curl -X POST "https://api.apify.com/v2/acts/vivid-softwares~espc-scotland-property-scraper/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls": [{"url": "https://espc.com/properties?locations=edinburgh&minbeds=2plus"}], "maxItems": 20}'
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("vivid-softwares/espc-scotland-property-scraper").call(run_input={
    "searchType": "forSale",
    "postcodeDistricts": ["eh4", "eh10"],
    "maxItems": 50,
})
for listing in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(listing["price_text"], listing["address"], listing.get("agent_phone"))
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });
const run = await client.actor('vivid-softwares/espc-scotland-property-scraper').call({
    searchType: 'soldPrices',
    postcodeDistricts: ['eh4'],
    soldWithin: '12',
    maxItems: 200,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.map((sale) => `${sale.address}: £${sale.last_sold_price} on ${sale.last_sold_date}`));
```

### Property data for AI agents and MCP

The Actor works with the [Apify MCP server](https://mcp.apify.com), so assistants such as Claude, ChatGPT or Cursor can call it as a tool. Add the Actor `vivid-softwares/espc-scotland-property-scraper` to your MCP configuration and ask questions such as:

- "Find 2-bedroom flats under £250,000 in EH6 and list the closing dates."
- "Which solicitor agents have the most new listings in Morningside this week?"
- "Compare recent sold prices in St Andrews with current asking prices."

The input uses fixed values and the output uses consistent field names, which makes it easy for AI agents to build searches and read results.

### How much does it cost to scrape ESPC?

This Actor uses **pay-per-event** pricing: **$14 per 1,000 property listings**, which is $0.014 for each listing saved to the dataset. You are not charged for search pages, retries, invalid input or property pages that are no longer available. For example, 200 Edinburgh listings cost $2.80. You can set a maximum cost per run in Apify Console, and the Actor stops cleanly when that limit is reached.

### Tips

- Use **postcode districts** for precise coverage and **areas** for neighbourhood-level searches.
- Turn off **Open every listing page** when you only need search-card data (price, address, bedrooms, agent name, photos). It is much faster, though fields such as EPC, council tax, description and agent contact details need the listing page.
- Use **Added in the last 7 days** with a schedule to monitor new ESPC listings daily or weekly.
- For large sold-price exports, run one postcode district at a time.

### Data limitations

- ESPC does not publish a listing date, so there is no exact date added or updated. `is_new` shows ESPC's NEW badge. ESPC's own *Added in the last 7 days* filter can also include recently updated listings that have no NEW badge, and the Actor returns exactly what that filter returns.
- Council tax band, EPC rating, landlord registration and letting agent registration (LARN) are taken from ESPC's structured fields, or from the listing description only when it states them explicitly.
- **Home Reports** are only available by request on ESPC. The Actor returns the public request link (`home_report_request_url`) and never submits the request form. EPC certificates are part of the Home Report, so there is no separate EPC document link.
- ESPC's rental section is small and mostly comes from Citylets. For Scottish rentals, see our [Citylets Scotland Property Scraper](https://apify.com/vivid-softwares/citylets-scotland-property-scraper).
- ESPC's radius search is drawn on a map, so it is not offered. Use areas, postcode districts or a pasted URL instead.
- Sold price records show what ESPC shows: address, property type, coordinates and sale history. Bedrooms are often not recorded.
- Transport, amenities and area statistics are not shown on ESPC listing pages. School catchments are included.

### Public contact data policy

The Actor only returns contact details that ESPC displays publicly on a listing page. When ESPC shows a named contact for a listing, the Actor returns that person's name, phone number and email address, and does not return the firm's email address (ESPC does not display it in that case). The firm's phone number shown on the "Call agent" button is always returned. The Actor does not guess, infer or enrich contact details. If you use agent contact data for outreach, follow UK GDPR and PECR rules.

### FAQ

**Is there an official ESPC API?** No public API is offered. This Actor gives you structured ESPC data through the Apify API.

**Is it legal to scrape ESPC?** The Actor only collects publicly available information and follows ESPC's robots.txt. You are responsible for how you use the data, including data protection rules for personal data. If in doubt, ask a lawyer.

**Can I scrape properties by postcode?** Yes. Choose one or more postcode districts, or paste an ESPC search URL for a postcode sector such as EH10 5.

**How fresh is the data?** Every run reads ESPC live. ESPC typically adds several hundred new listings each week.

**Does it return duplicate listings?** No. Listings are de-duplicated by ESPC listing ID within a run, and listings from your previous runs are skipped by default, so repeat and scheduled runs only return new listings.

**What happens with removed listings?** Property URLs that ESPC no longer shows are skipped, logged, listed in `RUN_SUMMARY` and not charged. Pages that fail to load are retried on a fresh proxy session first.

**Can you add a field or a custom version?** Open an issue on the Issues tab and we will take a look.

*This Actor is not affiliated with, endorsed by or connected to ESPC (UK) Ltd.*

# Actor input Schema

## `startUrls` (type: `array`):

The easiest way to use this Actor: run a search on <a href="https://espc.com" target="_blank">espc.com</a> with any filters, then paste the results URL here. Every results page is scraped. You can also paste property pages, area pages (for example espc.com/property-for-sale/edinburgh/flats) and sold-price pages (espc.com/house-prices/eh4). Leave empty to use the search builder below.

## `searchType` (type: `string`):

Optional search builder, used instead of or as well as URLs. <b>Property for sale</b> is ESPC's main search. <b>School catchment</b> finds homes for sale inside one school's catchment. <b>Sold house prices</b> returns recorded Scottish sale prices with sale history.

## `locations` (type: `array`):

The search builder runs only when you pick at least one area, postcode district or school. Names include their ESPC region so places with the same name are kept apart, for example <i>Stockbridge, Edinburgh City Centre</i>.

## `postcodeDistricts` (type: `array`):

Pick one or more Scottish postcode districts that ESPC recognises, for example EH4, KY12 or G42. They are searched together with any areas above.

## `school` (type: `string`):

Used only by the <b>School catchment</b> search type. Schools with the same name show their town in brackets.

## `minPrice` (type: `string`):

Minimum asking price for sale searches.

## `maxPrice` (type: `string`):

Maximum asking price for sale searches.

## `minRent` (type: `string`):

Minimum monthly rent for rental searches.

## `maxRent` (type: `string`):

Maximum monthly rent for rental searches.

## `bedrooms` (type: `string`):

Minimum (for example 2+) or exact number of bedrooms, as offered by ESPC.

## `propertyTypes` (type: `array`):

Choose broad types such as <i>Flat (all)</i> or detailed types such as <i>Flat - Top Floor</i>. Leave empty for every type.

## `includeUnderOffer` (type: `boolean`):

Also return sale listings that are already under offer.

## `addedLast7Days` (type: `boolean`):

Only return listings ESPC marks as new this week.

## `fixedPriceOnly` (type: `boolean`):

Only return fixed-price sale listings.

## `exclusiveOnly` (type: `boolean`):

Only return listings marketed exclusively on ESPC.

## `newBuildsOnly` (type: `boolean`):

Only return new-build homes.

## `features` (type: `array`):

Optional ESPC advanced-search features such as parking, gardens, heating, accessibility or purchase options. Listings must match every selected feature.

## `epcRatings` (type: `array`):

Only return listings with these energy performance ratings.

## `sortBy` (type: `string`):

Order of search results.

## `soldWithin` (type: `string`):

Used only by the <b>Sold house prices</b> search type.

## `soldPropertyType` (type: `string`):

Used only by the <b>Sold house prices</b> search type.

## `maxItems` (type: `integer`):

Stop after saving this many listings. Each saved listing is one billable result.

## `includeDuplicates` (type: `boolean`):

Off by default: listings you already received in an earlier run are skipped and not charged, so scheduled runs only return new listings. Turn on to get every matching listing again. Sold prices count as new when the property sells again.

## `scrapeDetails` (type: `boolean`):

Visit each property page for the full description, rooms, EPC, council tax, agent contact, schools, floor plans and media. Turn off for faster, search-card-only results. Sold price results do not need this.

## `includeImages` (type: `boolean`):

Return full-size photo URLs for each listing.

## `proxyConfiguration` (type: `object`):

Apify Proxy is required on the Apify platform because ESPC does not respond to requests sent directly from Apify servers. The default datacenter proxy is fast and inexpensive.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://espc.com/properties?locations=edinburgh&new=7&ptype=house_13"
    }
  ],
  "searchType": "forSale",
  "school": "",
  "minPrice": "",
  "maxPrice": "",
  "minRent": "",
  "maxRent": "",
  "bedrooms": "",
  "includeUnderOffer": false,
  "addedLast7Days": false,
  "fixedPriceOnly": false,
  "exclusiveOnly": false,
  "newBuildsOnly": false,
  "sortBy": "datedesc",
  "soldWithin": "",
  "soldPropertyType": "",
  "maxItems": 50,
  "includeDuplicates": false,
  "scrapeDetails": true,
  "includeImages": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `listings` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://espc.com/properties?locations=edinburgh&new=7&ptype=house_13"
        }
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("vivid-softwares/espc-scotland-property-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": [{ "url": "https://espc.com/properties?locations=edinburgh&new=7&ptype=house_13" }],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("vivid-softwares/espc-scotland-property-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://espc.com/properties?locations=edinburgh&new=7&ptype=house_13"
    }
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call vivid-softwares/espc-scotland-property-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vivid-softwares/espc-scotland-property-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/EVfSh0NY3TW1UpWMw/builds/zMCVvTno683FXJirf/openapi.json