# Compass Scraper — Public Real Estate Listings (`muhammadafzal/compass-scraper`) Actor

Extract public Compass.com property listings by location or listing URL with price, beds, baths, address, media, agents, and source provenance. $0.005 per listing.

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

## Pricing

from $5.00 / 1,000 compass listings

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

## Compass Scraper

Compass Scraper extracts public Compass.com real estate listings into one stable dataset row per property. It supports location-built searches, existing Compass search URLs, individual listing URLs, for-sale, rental, and sold pages, and optional detail-page enrichment.

Each stored listing costs **$0.005**, plus a small actor-start event and normal Apify usage. The maximum record-event cost is `maxResults × $0.005`; the actor prints that cap before crawling and charges only after a schema-valid dataset write.

### Input

Minimal location search:

```json
{
  "locations": ["Boston, MA"],
  "listingType": "for-sale",
  "maxResults": 1,
  "maxPages": 1,
  "includeDetails": false
}
```

For saved filters, neighborhoods, or a direct listing, provide a public Compass URL:

```json
{
  "startUrls": [
    { "url": "https://www.compass.com/homes-for-sale/manhattan-ny/" }
  ],
  "maxResults": 50
}
```

`locations` defaults to Boston with one result, one page, and detail enrichment disabled so the default health check finishes quickly. Increase the limits and enable details for production runs. `startUrls` are combined with location URLs, so set `locations` to an empty list when you only want custom URLs. The actor accepts only `https://www.compass.com/` URLs.

### Output

Each dataset item includes listing identity and provenance plus fields such as price, price text, beds, baths, living area, lot size, property type, address, coordinates, description, images, agent, brokerage, MLS ID, and scrape time. Compass does not publish every field for every property; missing public fields are `null` and extraction warnings stay in the `warnings` array.

The actor supports both Compass's current `cx-react-listingCard` markup and its earlier listing-card attributes. Detail pages and JSON-LD/meta tags provide enrichment fallbacks.

### Access and limitations

Compass may show JavaScript verification, rate-limit, or regional access challenges. The actor detects those pages, does not fabricate records, and reports a blocked run when no usable search page completes. An Apify residential proxy is requested by default; pass an authorized `proxyConfiguration` to change that behavior.

This actor reads public web pages only. You are responsible for complying with Compass terms, applicable law, privacy rules, MLS/data-feed restrictions, and responsible use of any public contact information. It is not affiliated with Compass.

### API example

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('YOUR_USERNAME/compass-scraper').call({
  "locations": ["Boston"],
  "maxResults": 10,
  "includeDetails": true
});
console.log(run.defaultDatasetId);
```

# Actor input Schema

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

Compass location slugs or readable names, for example \["Boston", "New York"]. The actor builds public homes-for-sale URLs. Defaults to Boston for a fast one-result health-tested run.

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

Optional public Compass.com listing/search URLs. Use this for saved filters, neighborhoods, individual listings, rentals, or sold pages. These URLs are combined with locations.

## `listingType` (type: `string`):

Used only when building URLs from locations. For custom filters, provide the complete startUrl.

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

Maximum number of unique listings stored and billed. Each schema-valid listing costs $0.005, excluding normal Apify usage and the small actor-start event. Defaults to 1; increase it for production extraction.

## `maxPages` (type: `integer`):

Maximum number of result pages per starting search URL. The actor follows Compass next-page links only. Defaults to 1; increase it for broader searches.

## `includeDetails` (type: `boolean`):

Open each discovered listing page to add structured detail fields such as description, MLS ID, agent, and photos. Defaults to false for a fast card-only run; enable it when you need enrichment.

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

Optional Apify proxy configuration. If omitted, the actor requests an Apify residential proxy for Compass access. Use only proxies you are authorized to use.

## Actor input object example

```json
{
  "locations": [
    "Boston, MA"
  ],
  "startUrls": [],
  "listingType": "for-sale",
  "maxResults": 1,
  "maxPages": 1,
  "includeDetails": false,
  "proxyConfiguration": {}
}
```

# Actor output Schema

## `results` (type: `string`):

Structured public listing records.

## `summary` (type: `string`):

Record count, access diagnostics, and event charges.

# 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 = {
    "locations": [
        "Boston, MA"
    ],
    "startUrls": [],
    "listingType": "for-sale",
    "maxResults": 1,
    "maxPages": 1,
    "includeDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/compass-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 = {
    "locations": ["Boston, MA"],
    "startUrls": [],
    "listingType": "for-sale",
    "maxResults": 1,
    "maxPages": 1,
    "includeDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/compass-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 '{
  "locations": [
    "Boston, MA"
  ],
  "startUrls": [],
  "listingType": "for-sale",
  "maxResults": 1,
  "maxPages": 1,
  "includeDetails": false
}' |
apify call muhammadafzal/compass-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/compass-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/CRMIkbGOfc7dPIXJx/builds/i5XaX7n8wR9W105Za/openapi.json