# MLS Scraper & Real Estate Search API (`convertfleetdotonline/mls-property-finder`) Actor

MLS scraper & real estate API: send a plain-English search (city, price, beds, pool, status) and get matching MLS listings as JSON — photos, price, listing status & agent contact. Live Matrix MLS, no MLS login or IDX feed. Southeast Florida (Miami, Broward, Palm Beach).

- **URL**: https://apify.com/convertfleetdotonline/mls-property-finder.md
- **Developed by:** [Hasnain Nisar](https://apify.com/convertfleetdotonline) (community)
- **Categories:** Real estate
- **Stats:** 2 total users, 1 monthly users, 57.1% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / property search

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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

## MLS Property Scraper & Real Estate Search API 🏠

**Scrape MLS listings by plain‑English search — no MLS login, no IDX feed, no HTML parsing.**
Type what a buyer wants ("3 bed 2 bath condo in Coral Springs with a pool under $300k, active only")
and this actor runs it against a **live CoreLogic Matrix MLS** session and returns the matching
listings as clean JSON: price, beds/baths/sqft, photos, listing status, and the listing‑agent contact.

It's the fastest way to get **real estate data / MLS data via API** for Southeast Florida
(Miami‑Dade, Broward, Palm Beach) without becoming a licensed MLS subscriber yourself.

> 🔎 Need one specific listing instead of a search? Use the companion
> **[MLS Property Detail](https://apify.com/convertfleetdotonline/mls-property-detail)** actor
> (MLS number → full property record).

---

### Why use this MLS scraper?

- **Plain‑English search** — no query language. It parses price, beds, baths, city/county, pool,
  waterfront, HOA cap, property type, and listing status from your prompt automatically.
- **Real MLS data** — sourced from a live Matrix MLS session, not a stale public portal. You get
  fields the consumer sites hide: listing‑agent name/phone/email, days on market, price history.
- **Structured JSON** — ready for your CRM, spreadsheet, lead pipeline, or AI agent.
- **Photos included** — hero image + full gallery per listing.
- **Status‑aware** — every listing is tagged Active / Under contract / Pending / Sold, so you never
  pitch a property that's already gone.
- **Pay per search** — one flat price per prompt. No subscription, no per‑record metering.

### Use cases

- Real estate **lead generation** and buyer/investor matching
- Feeding an **AI real estate agent** or chatbot with live inventory
- Building a **property search app / IDX alternative** without MLS membership
- **Comparable sales (comps)** and market research
- Wholesaling / investor deal‑flow automation
- Populating a CRM with matching listings for a client

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `prompt` | string (required) | – | The search, in plain English. e.g. `waterfront single family in Fort Lauderdale, 4+ beds, budget 1.5M` |
| `maxResults` | integer | 25 | How many matching listings to return (1–50). |
| `enrichDetail` | boolean | false | Also open each listing's full record (all fields, room dimensions, price history, agent contact). Slower, richest output. |
| `maxPhotos` | integer | 5 | Max photos per listing (0–30). |

#### Example input

```json
{
  "prompt": "3 bed 2 bath condo in Coral Springs with a pool, under $300k, active only",
  "maxResults": 25,
  "enrichDetail": false,
  "maxPhotos": 5
}
````

### Output

Each dataset item is one listing:

```json
{
  "mls_number": "F10544476",
  "address": "8101 NW 27th St # 4",
  "city": "Coral Springs", "state": "FL", "zip": "33065",
  "price": 269000,
  "beds": 3, "baths": 2, "sqft": 1365,
  "property_type": "Condo", "year_built": 1974,
  "status": "Active", "availability": "active",
  "image": "https://…/hero.jpg",
  "images": ["https://…", "…"]
}
```

Turn on `enrichDetail` to also get a `detail` object with **curated highlights** (HOA/tax/assessed
value, amenities, restrictions, maintenance), **room dimensions**, **price history**, and the
**listing‑agent contact**. The run's key‑value store holds `SEARCH_META` (parsed criteria, Matrix
form used, total match count, and any review caveats).

### How it works

1. You give a natural‑language buy‑box `prompt`.
2. The actor parses it into MLS search criteria (price range, beds/baths, city→county, features,
   listing status).
3. It runs that search against a live **Matrix MLS** session and reads the results grid.
4. It returns the matched listings — with photos, status, and (optionally) full detail — as JSON.

### FAQ

**What is an MLS scraper / MLS API?**
An MLS scraper programmatically pulls listing data (price, beds, photos, agent, status) from a
Multiple Listing Service. This actor gives you that as a simple API: send a search prompt, get
structured listings back — without holding an MLS license or wiring up an IDX/RETS/RESO feed.

**Which area does it cover?**
The Southeast Florida MLS footprint — Miami‑Dade, Broward, and Palm Beach counties (plus the
Tampa‑Bay counties). Out‑of‑area markets are flagged in `SEARCH_META.needsReview`.

**Do I need an MLS login or IDX feed?**
No. The actor drives its own live Matrix MLS session, so you don't need MLS membership, an IDX
provider, or RESO Web API credentials.

**How much does it cost?**
Pay per event — **$0.50 per completed search** (one prompt). Failed searches aren't charged. No
monthly subscription.

**Can I get the full details of one listing by MLS number?**
Yes — use the companion **[MLS Property Detail](https://apify.com/convertfleetdotonline/mls-property-detail)**
actor.

**Is this legal?**
The actor returns MLS listing data for legitimate real‑estate business use (lead gen, comps, CRM,
market research). You are responsible for complying with your local MLS rules and display
requirements when you republish listing data.

### Related

- **[MLS Property Detail](https://apify.com/convertfleetdotonline/mls-property-detail)** — MLS number → full property record.

***

*Keywords: MLS scraper, MLS API, real estate API, real estate data API, property data API, MLS
listings scraper, real estate scraper, Florida MLS data, property search API, MLS data extraction,
Matrix MLS, real estate lead generation.*

# Actor input Schema

## `prompt` (type: `string`):

Plain-English criteria. Examples: '3 bed 2 bath condo in Coral Springs with a pool under $300k, active only'; 'waterfront single family in Miami Beach, 4+ beds, budget 1.5M'; 'duplex in Fort Lauderdale, include pending'.

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

How many matching listings to return (1–50).

## `enrichDetail` (type: `boolean`):

Open each listing's full Agent-Full record (all fields, room dimensions, price history, listing-agent contact). Slower, but the richest output.

## `maxPhotos` (type: `integer`):

Max hero photos to attach per listing (0–30).

## Actor input object example

```json
{
  "prompt": "3 bed 2 bath condo in Coral Springs with a pool, under $300k, active only",
  "maxResults": 25,
  "enrichDetail": false,
  "maxPhotos": 5
}
```

# 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 = {
    "prompt": "3 bed 2 bath condo in Coral Springs with a pool, under $300k, active only"
};

// Run the Actor and wait for it to finish
const run = await client.actor("convertfleetdotonline/mls-property-finder").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 = { "prompt": "3 bed 2 bath condo in Coral Springs with a pool, under $300k, active only" }

# Run the Actor and wait for it to finish
run = client.actor("convertfleetdotonline/mls-property-finder").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 '{
  "prompt": "3 bed 2 bath condo in Coral Springs with a pool, under $300k, active only"
}' |
apify call convertfleetdotonline/mls-property-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=convertfleetdotonline/mls-property-finder",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "MLS Scraper & Real Estate Search API",
        "description": "MLS scraper & real estate API: send a plain-English search (city, price, beds, pool, status) and get matching MLS listings as JSON — photos, price, listing status & agent contact. Live Matrix MLS, no MLS login or IDX feed. Southeast Florida (Miami, Broward, Palm Beach).",
        "version": "0.1",
        "x-build-id": "FJAxQkOslCSXQkaUK"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/convertfleetdotonline~mls-property-finder/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-convertfleetdotonline-mls-property-finder",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/convertfleetdotonline~mls-property-finder/runs": {
            "post": {
                "operationId": "runs-sync-convertfleetdotonline-mls-property-finder",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/convertfleetdotonline~mls-property-finder/run-sync": {
            "post": {
                "operationId": "run-sync-convertfleetdotonline-mls-property-finder",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "prompt"
                ],
                "properties": {
                    "prompt": {
                        "title": "Search prompt (buy-box)",
                        "type": "string",
                        "description": "Plain-English criteria. Examples: '3 bed 2 bath condo in Coral Springs with a pool under $300k, active only'; 'waterfront single family in Miami Beach, 4+ beds, budget 1.5M'; 'duplex in Fort Lauderdale, include pending'."
                    },
                    "maxResults": {
                        "title": "Max results",
                        "minimum": 1,
                        "maximum": 50,
                        "type": "integer",
                        "description": "How many matching listings to return (1–50).",
                        "default": 25
                    },
                    "enrichDetail": {
                        "title": "Full detail per listing",
                        "type": "boolean",
                        "description": "Open each listing's full Agent-Full record (all fields, room dimensions, price history, listing-agent contact). Slower, but the richest output.",
                        "default": false
                    },
                    "maxPhotos": {
                        "title": "Photos per listing",
                        "minimum": 0,
                        "maximum": 30,
                        "type": "integer",
                        "description": "Max hero photos to attach per listing (0–30).",
                        "default": 5
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```