# JamesEdition Real Estate Scraper — Luxury Listings (`muhammadafzal/jamesedition-real-estate-scraper`) Actor

Scrape public JamesEdition luxury real-estate searches and listing pages. Returns prices, locations, facts, photos, and public agency metadata. $0.005 per listing.

- **URL**: https://apify.com/muhammadafzal/jamesedition-real-estate-scraper.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Real estate, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 luxury listing scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## JamesEdition Real Estate Scraper — Luxury Listings

**JamesEdition Real Estate Scraper** extracts public luxury-property listings from JamesEdition search-result and individual listing pages. Use it for international luxury-market research, brokerage inventory monitoring, investment screening, or structured AI-agent workflows. It returns one normalized record per public property with pricing, property facts, location, photos, descriptions, and public agency metadata. It is not for private dashboards, contact forms, login-only content, or non-real-estate JamesEdition categories.

### When to use it

- Monitor recent luxury listings in a city, country, or market segment.
- Export public asking prices, property types, bedrooms, bathrooms, and photos for a market comparison.
- Turn a JamesEdition search URL into clean JSON, CSV, Excel, JSONL, XML, or RSS data.
- Give an AI agent a focused real-estate listing tool with a strict result and cost cap.

JamesEdition is a global luxury marketplace with public, filterable property-search pages and public listing pages. Copy the search URL after applying any filters on the website, then give it to this Actor.

### Input

```json
{
  "startUrls": [{ "url": "https://www.jamesedition.com/real_estate?order=recent" }],
  "maxResults": 50,
  "enrichDetails": true,
  "responseFormat": "detailed"
}
```

| Field | Default | Meaning |
|---|---:|---|
| `startUrls` | Recent worldwide listings | Public JamesEdition real-estate search or listing URLs |
| `maxResults` | 10 | Hard output and result-event billing cap, 1–1,000 |
| `enrichDetails` | `true` | Visits listing pages after discovery for richer public details |
| `responseFormat` | `detailed` | `concise` limits output to core fields and one image |
| `debugHtml` | `false` | Saves raw page HTML to the key-value store for parser troubleshooting |

### Output

Each record uses a stable, MCP-friendly shape. Unavailable fields are explicit `null` values; arrays are present even when empty.

| Field group | Example fields |
|---|---|
| Identity | `listingId`, `title`, `listingUrl`, `sourceUrl` |
| Price | `price`, `currency`, `priceDisplay` |
| Property | `propertyType`, `bedrooms`, `bathrooms`, `livingArea`, `lotArea` |
| Location | `address`, `city`, `region`, `country`, `latitude`, `longitude` |
| Content | `description`, `amenities`, `imageUrls` |
| Public professionals | `agencyName`, `agentName`, `agentPhone`, `agentEmail` |
| Provenance | `scrapedAt`, `warnings` |

```json
{
  "recordType": "listing",
  "listingId": "17894003",
  "title": "Villa in Mijas, Spain",
  "listingUrl": "https://www.jamesedition.com/real_estate/mijas-spain/villa-17894003",
  "price": 2500000,
  "currency": "EUR",
  "propertyType": "Villa",
  "bedrooms": 4,
  "bathrooms": 4,
  "city": "Mijas",
  "country": "Spain",
  "imageUrls": ["https://images.example.com/villa.jpg"],
  "warnings": []
}
```

The `OUTPUT` record in the default key-value store provides final item counts, result-event charges, failed request count, and warnings.

### Pricing

The Actor has transparent pay-per-event pricing:

| Event | Price |
|---|---:|
| Actor start | $0.00005 per run, scaled by allocated memory |
| Stored public luxury listing | $0.005 per listing |

For example, a 10-listing run costs about **$0.05** and a 100-listing run about **$0.50**, plus the small start charge and any platform usage option selected in Apify. The Actor logs the maximum result-event cost before it begins and never charges more listing events than `maxResults`.

### API examples

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('muhammadafzal/jamesedition-real-estate-scraper').call({
  startUrls: [{ url: 'https://www.jamesedition.com/real_estate?order=recent' }],
  maxResults: 25,
  enrichDetails: true,
  responseFormat: 'concise',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient(token='YOUR_APIFY_TOKEN')
run = client.actor('muhammadafzal/jamesedition-real-estate-scraper').call(run_input={
    'startUrls': [{'url': 'https://www.jamesedition.com/real_estate?order=recent'}],
    'maxResults': 25,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
```

For Apify MCP, add `https://mcp.apify.com/?tools=muhammadafzal/jamesedition-real-estate-scraper`. Use `concise` when an agent needs to compare many listings; use `detailed` for a smaller due-diligence sample.

### Reliability and limitations

JamesEdition may use Cloudflare bot protection. The Actor uses low concurrency, consistent residential proxy sessions, a real Chromium browser fingerprint, retries, and session retirement on challenge pages. It parses the public `ListingCard` elements on search pages and the structured listing sections on detail pages, with JSON-LD as a fallback. Partial results are retained when individual pages fail.

If every attempt is blocked, the Actor fails with an explicit diagnostic instead of reporting a misleading empty success. Fields vary by agency and country; this Actor preserves missing values as `null` rather than inferring them. It does not bypass access controls, solve CAPTCHAs, or access authenticated pages.

### Responsible use

Use only public data you are authorized to collect and process. JamesEdition listing content can include agency and professional contact details; handle any personal data lawfully, minimize retention, honor valid removal requests, and follow applicable privacy, database-rights, copyright, contract, and real-estate regulations. This Actor does not grant permission from JamesEdition, a listing agency, a property owner, or a listing agent.

# Actor input Schema

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

Use this when you have a public JamesEdition real-estate search or individual listing URL. Enter URLs such as 'https://www.jamesedition.com/real\_estate?order=recent' or a public listing URL. Defaults to the newest worldwide listings search. Do not provide login pages, agency dashboards, cars, yachts, watches, or any non-JamesEdition domain.

## `maxResults` (type: `integer`):

Use this to set the maximum number of schema-valid property records and the result-event billing ceiling. Enter an integer from 1 to 1,000, for example 50. Defaults to 10 and applies across all URLs in this run. It is not a page number and does not bypass the website's result pagination.

## `enrichDetails` (type: `boolean`):

Use this to visit each discovered public listing page for fuller facts, descriptions, and image URLs. Set true for the richest output or false for faster search-card-only collection. Defaults to true. It does not access private, login-only, or agent-dashboard content.

## `responseFormat` (type: `string`):

Use this to balance output size and detail for exports or AI agents. Choose 'concise' for identity, price, location, and one image, or 'detailed' for public descriptions and up to 20 images. Defaults to detailed. It does not change the number of listings charged.

## `debugHtml` (type: `boolean`):

Use this to store each fetched page's raw HTML in the key-value store for parser debugging. Set true only when investigating extraction issues; it adds storage usage. Defaults to false.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.jamesedition.com/real_estate?order=recent"
    }
  ],
  "maxResults": 50,
  "enrichDetails": true,
  "responseFormat": "detailed",
  "debugHtml": false
}
```

# Actor output Schema

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

No description

## `summary` (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://www.jamesedition.com/real_estate?order=recent"
        }
    ],
    "maxResults": 10,
    "enrichDetails": true,
    "responseFormat": "detailed",
    "debugHtml": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/jamesedition-real-estate-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://www.jamesedition.com/real_estate?order=recent" }],
    "maxResults": 10,
    "enrichDetails": True,
    "responseFormat": "detailed",
    "debugHtml": False,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/jamesedition-real-estate-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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://www.jamesedition.com/real_estate?order=recent"
    }
  ],
  "maxResults": 10,
  "enrichDetails": true,
  "responseFormat": "detailed",
  "debugHtml": false
}' |
apify call muhammadafzal/jamesedition-real-estate-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=muhammadafzal/jamesedition-real-estate-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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