# Facebook Marketplace Scraper ($0.44/1K): ZIP & Strict Radius (`tsutseisoftware/facebook-marketplace-scraper`) Actor

Scrape Facebook Marketplace by keyword around any town, ZIP code or coordinates with a strict radius (distance on every row). Price, place, photos, seller, date; details, deal score, sold listings, vehicles, monitoring of new, cheaper and sold items, alerts. No login.

- **URL**: https://apify.com/tsutseisoftware/facebook-marketplace-scraper.md
- **Developed by:** [Tsutsei Software](https://apify.com/tsutseisoftware) (community)
- **Categories:** E-commerce
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 93.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Facebook Marketplace Scraper: Any Town, ZIP & Strict Radius

Scrape **Facebook Marketplace** listings by keywords and categories around **any town, postal code or coordinates in the world**, with a radius the actor really keeps to. No login and no cookies. You get title, price, place, distance, photos, seller and date, and optionally the full details: description, all photos, exact location, condition and vehicle data.

**$0.44 per 1 000 listings ($0.35 on Gold plans), $2.44 with full details.**

Facebook ignores the radius for logged-out visitors and mixes in listings from far away; with a 20 km search around Ostrava we measured listings from 140 and 280 km. This scraper measures the distance of every listing and **leaves out, and does not charge, what is outside your radius**. Every row says how far the listing is (`distanceKm`, `distanceMiles`).

### Why use this Facebook Marketplace scraper?

- 📍 **Search anywhere, the way people say it.** Use a town ("Ostrava", "Austin, TX, US", "Paris, France"), a postal code with its country ("70200, CZ", "10001, US", "SW1A, GB") or coordinates. When a town name exists in several countries ("Cambridge"), the run stops and asks for the country instead of guessing. It never falls back to San Francisco without telling you.
- 🎯 **Strict radius in km or miles, free of charge.** Facebook does not keep to the radius; the actor measures every listing's distance from your location and leaves out the rest. For a radius over about 60 km (up to 500 km), turn on **Cover the whole radius**; duplicates are removed.
- 💸 **Deal score.** Every listing is compared with **similar listings of the same search** (same item, not its accessories, so "iPhone 13" is not compared with "iPhone 13 case"). You get the usual price (`comparableMedianPrice`), the difference in % (`priceVsMedianPercent`) and a `dealScore` from 0 to 100. Filter by **"at least 20 % below the usual price"** or by a minimum deal score.
- 🔎 **All of Facebook's filters:** price from/to, condition, listed in the last 24 h / 7 / 30 days, local pickup or shipping, sort (newest, price, distance), exact match, 17 categories. You can also search **sold listings**, to see what items really sold for.
- 🚗 **Vehicles:** vehicle type, body style, year from/to, mileage from/to, transmission. Details add make, model, trim, mileage, fuel, colours, owners, title status and VIN.
- 🧮 **Filters Facebook doesn't have:** words the title (or description) must or must not contain, title must contain all search words, posted in the last N hours, posted between two dates, only reduced listings, only free items, placeholder and implausible prices out, duplicate posts of one seller out, excluded sellers or a seller watch-list, seller type, and your own rules on any field. Listings left out are not charged.
- 📬 **Monitoring for scheduled runs.** Only new listings and listings whose price or status changed come back, with the previous price and the change in %. You can ask for **only price drops** (optionally at least X %), and for listings that were **sold or removed** since the last run. Reposted listings are detected, and you can choose a silent first run and stop at known listings (cheap checks every few minutes).
- 🔔 **Alerts:** Telegram, Slack, Discord, WhatsApp or your own webhook (Zapier, Make, n8n) after each run.
- 📊 **Free market summary** (SUMMARY record): price quartiles by currency and condition, towns with most listings, shares of shipping, sold and reduced listings, how old and how far the listings are, for every search.
- 💱 **Prices in one currency:** Facebook's own USD price on every row, plus **Convert prices to** any currency (daily ECB rates).
- 🧾 **Clean, flat output.** Named columns (`title`, `price`, `currency`, `city`, `distanceKm`, `postedAt`…) instead of Facebook's raw structure, ready for Excel and CSV. Choose compact output, chosen fields or no empty fields.
- 🧑‍💼 **Seller** name and ID on every row (Facebook hides the seller of sold listings). With details you also get the Marketplace profile link, rating and join date, and with the **seller profile photo** add-on the seller's profile picture.
- 🔒 **No login, no cookies, no Facebook account.** E-mails and phone numbers (local and international formats) are removed from titles and descriptions.

### What data can you get?

| Group | Fields |
|---|---|
| Listing | `id`, `url`, `title`, `price`, `currency`, `priceText`, `priceUsd`, `originalPrice`, `discountPercent`, `isFree`, `postedAt`, `listingAgeHours`, `categoryName`, `status`, `isSold`, `isPending` |
| Place | `city`, `state`, `locationName`, `country`, `latitude`, `longitude`, `locationPrecision`, `distanceKm`, `distanceMiles`, `withinRadius` |
| Seller | `sellerName`, `sellerId`; with details `sellerProfileUrl`, `sellerRating`, `sellerRatingCount`, `sellerJoinedAt`, `sellerType`; with the seller photo add-on `sellerPhotoUrl` |
| Photos | `imageUrl`; with details `imageUrls` (all), `imageCount` |
| Details | `description`, `condition`, `conditionLabel`, `attributes`, `deliveryTypes`, `shippingOffered`, `shippingPrice` |
| Vehicles | `vehicleYear`, `vehicleMileage`, `vehicleMileageUnit`; with details `vehicleMake`, `vehicleModel`, `vehicleTrim`, `vehicleTransmission`, `vehicleFuelType`, `vehicleExteriorColor`, `vehicleInteriorColor`, `vehicleOwners`, `vehicleTitleStatus`, `vehicleVin`, `vehicleFeatures` |
| Deal | `comparableCount`, `comparableMedianPrice`, `priceVsMedianPercent`, `dealScore`, `priceConverted`, `convertedCurrency` |
| Search | `searchQuery`, `searchLocation`, `searchCategory`, `searchRadiusKm`, `searchUrl`, `position` |
| Monitoring | `changeType`, `changedFields`, `previousPrice`, `priceChange`, `priceChangePercent`, `firstSeenAt`, `removedAt`, `removedReason`, `isRepost`, `repostOf` |

### How to scrape Facebook Marketplace

1. Enter **Search keywords** (e.g. `iphone 13`) and **Locations** (e.g. `70200, CZ` or `Ostrava, CZ`).
2. Set the **Radius** (km or miles) and, if you like, Facebook's filters and the actor's filters.
3. Turn on **Add listing details** if you need descriptions, all photos and exact places.
4. Click **Start**. Download the results as Excel, CSV or JSON, or get them through the API.
5. For alerts, schedule the run (e.g. every 15 minutes), turn on **Monitoring: only new or changed listings** and add a Telegram, Slack, Discord or WhatsApp channel.

### Use cases

#### Used iPhones within 20 km of a postal code

```json
{
  "searchQueries": ["iphone 13", "iphone 14"],
  "locations": ["70200, CZ"],
  "radius": 20,
  "excludeKeywords": ["case", "kryt", "obal", "broken"],
  "maxItems": 200
}
```

#### Deals: at least 25 % under the usual price, to Telegram every 15 minutes

```json
{
  "searchQueries": ["ps5", "nintendo switch"],
  "locations": ["Austin, TX, US"],
  "radius": 30,
  "radiusUnit": "mi",
  "sortBy": "newest",
  "maxPriceVsMedianPercent": -25,
  "onlyNewOrChanged": true,
  "monitoringKey": "austin-consoles",
  "monitoringEarlyStop": true,
  "telegramBotToken": "123456:ABC...",
  "telegramChatId": "123456789"
}
```

#### Cars: automatic SUVs from 2015, under 150 000 km, with details

```json
{
  "categories": ["vehicles"],
  "locations": ["Munich, DE"],
  "radius": 50,
  "vehicleTypes": ["car_truck"],
  "bodyStyles": ["suv"],
  "vehicleMinYear": 2015,
  "vehicleMaxMileage": 150000,
  "vehicleTransmission": "automatic",
  "includeDetails": true,
  "maxItems": 100
}
```

#### What things really sell for (sold listings)

```json
{
  "searchQueries": ["dyson v15"],
  "locations": ["London, GB"],
  "radius": 25,
  "availability": "sold",
  "maxItems": 300
}
```

The SUMMARY record then has the median and quartiles of the sold prices. Facebook returns pending (reserved) listings with the sold ones; they have `isPending: true`.

#### Price drops and sold items of a saved search

```json
{
  "searchQueries": ["road bike"],
  "locations": ["Seattle, WA, US"],
  "radius": 15,
  "radiusUnit": "mi",
  "onlyNewOrChanged": true,
  "monitoringKey": "seattle-road-bikes",
  "onlyPriceDrops": true,
  "minPriceDropPercent": 10,
  "includeRemovedListings": true
}
```

#### A whole region: radius up to 500 km

```json
{
  "searchQueries": ["tractor"],
  "locations": ["Brno, CZ"],
  "radius": 150,
  "coverWholeRadius": true,
  "maxItems": 0
}
```

#### A search copied from the browser, and single listings

```json
{
  "startUrls": [
    { "url": "https://www.facebook.com/marketplace/berlin/search?query=fahrrad&maxPrice=200" },
    { "url": "https://www.facebook.com/marketplace/item/1156777293589139/" }
  ]
}
```

Each search URL costs about $0.003 extra (charged as extra pages). When Facebook does not know the town in the URL (it would quietly search around San Francisco), the URL is skipped and the status says so: use **Locations** for that place.

#### Strict radius, explained

Facebook answers a logged-out search with listings from its own area around the point, and adds some from much farther away, whatever radius you ask for. The actor measures every listing's distance from your location and leaves out what is outside the radius. A listing's town is a point (its centre), so a listing at the edge of a big town may be a few km closer or farther than its `distanceKm`; `withinRadius` always agrees with `distanceKm`. With **Add listing details**, the distance is measured from the listing's own coordinates (`locationPrecision: listing`). A listing whose town can't be placed (a small village, or a name Facebook spells differently) has an empty distance and is kept, unless you turn off **Keep listings whose town is unknown**.

#### Deal score, explained

Each listing is compared with similar listings of the same search (same item, not its accessories, same currency). `comparableMedianPrice` is their median price and `priceVsMedianPercent` is how much cheaper (negative) or dearer this one is. `dealScore` 50 = the usual price, higher = cheaper, 100 = free. All three are `null` when there are too few comparable listings. More listings read means a better comparison.

#### Monitoring mode, explained

With **Monitoring: only new or changed listings**, the actor remembers the listings of each **Monitoring key** and returns only new ones and listings whose price, title, sold or pending status changed (`changeType: updated`, `previousPrice`, `priceChangePercent`). With **Report sold and removed listings**, listings of the last run that are gone are checked one by one. They come back with `removedReason` `sold`, `pending`, `removed` or `noLongerMatches` (still listed, but no longer found by the search). This check runs only when every search was read to its end, not when a limit stopped it. Turned on for a monitoring key that already exists, it reports from the following run (the first one remembers the listings to report). Changing **Monitoring: ignore changes in** does not report the listings again. Every page read in monitoring mode is charged as a "Monitoring page", unchanged listings are not charged.

### How much does it cost to scrape Facebook Marketplace?

| | Price |
|---|---|
| Listing | **$0.44 per 1 000** (Bronze $0.44, Silver $0.40, Gold and higher $0.35) |
| Add listing details | **+$2.00 per 1 000** (= $2.44 per 1 000 with details) |
| Add seller profile photo | +$0.50 per 1 000 listings that have one (with details) |
| Run start | $0.005 per run |
| Extra page | $0.30 per 1 000 pages read beyond what the saved listings explain (pages full of listings outside your radius, narrow filters, **Cover the whole radius**; a search URL counts as ~10). Requests that got no answer are not charged |
| Monitoring page | $0.30 per 1 000 pages read in monitoring mode, and per sold/removed check |
| New IP retry | $0.001 per new IP address after Facebook refused a request (on by default, can be turned off) |
| Notification | $0.001 per run that sent a notification |

Examples: 1 000 listings cost about **$0.45**, 1 000 listings with full details about **$2.45**. A monitoring check of a local search every 15 minutes that finds 2 new listings costs about **$0.007**. With the $5 of free monthly credit on the Apify free plan you get about **11 000 listings**, or 2 000 with details.

Listings outside the radius, listings left out by your filters and unchanged listings in monitoring are never charged as listings. With details, a filter that needs them (**Text must contain / must not contain**, condition, seller type, custom rules on detail fields) can only judge a listing after its details are read, so a listing it leaves out is charged its details ($0.002), not as a listing. You can set a **maximum cost per run**; the run then stops before it is spent.

### Input example

```json
{
  "searchQueries": ["iphone"],
  "locations": ["Ostrava, CZ"],
  "radius": 20,
  "maxItems": 20
}
```

### Output example

```json
{
  "id": "1156777293589139",
  "source": "facebook-marketplace",
  "url": "https://www.facebook.com/marketplace/item/1156777293589139/",
  "title": "iPhone 15 PRO",
  "price": 10900,
  "currency": "CZK",
  "priceText": "CZK10,900",
  "priceUsd": 497.96,
  "originalPrice": null,
  "isFree": false,
  "city": "Ostrava",
  "locationName": "Ostrava, Czech Republic",
  "country": "CZ",
  "latitude": 49.835,
  "longitude": 18.282,
  "locationPrecision": "town",
  "distanceKm": 1.7,
  "distanceMiles": 1.1,
  "withinRadius": true,
  "postedAt": "2026-11-11T17:58:56Z",
  "listingAgeHours": 2.8,
  "categoryName": "Electronics",
  "deliveryTypes": ["local_pickup"],
  "status": "available",
  "sellerName": "Example Seller",
  "sellerId": "pfbid02dRSo4PeD...",
  "imageUrl": "https://scontent.xx.fbcdn.net/v/t39.84726-6/...jpg",
  "comparableCount": 6,
  "comparableMedianPrice": 12000,
  "priceVsMedianPercent": -9.2,
  "dealScore": 55,
  "searchQuery": "iphone",
  "searchLocation": "Ostrava, Czechia",
  "searchRadiusKm": 20,
  "position": 1,
  "detailsIncluded": false,
  "scrapedAt": "2026-11-11T20:00:00Z"
}
```

All fields are always present (empty ones as `null` or `[]`), unless you choose compact output, output fields or **Leave out empty fields**.

### Limitations

- **Logged out.** The actor sees what any visitor without an account sees. Facebook may change what it shows to logged-out visitors at any time; the actor then reports the problem instead of returning an empty "success".
- **Residential proxy.** Facebook needs a residential proxy. It is set by default and its cost is included in the price.
- **How far one search reaches.** About 60 km around a point. Use **Cover the whole radius** for more, up to 500 km.
- **Exact coordinates** are Facebook's own (rounded to the neighbourhood), not the seller's address.
- **Photo links expire** after some days (Facebook's links). Download the photos you need.
- **Seller ratings** are often private; `sellerRating` is then empty.
- **Vehicle filters** (year, mileage, transmission) are applied by Facebook; the actor also leaves out listings whose year or mileage it knows and that are outside your range. Listings without vehicle data (parts, many listings outside the US) stay in.
- **A run that gets too slow** (Facebook answering slowly or refusing) stops and saves the listings it has already read, without their details. When it could not save anything, the run fails instead of ending empty.
- Property filters (bedrooms…) are not available to logged-out visitors.

### For AI agents and API users

- Call the actor with the input above through the Apify API, the Apify MCP server or any integration; results are in the default dataset, the market summary in the `SUMMARY` record of the key-value store.
- For small answers use `"compact": true` or `"fields": ["title", "price", "currency", "distanceKm", "url"]`, and `"maxItems"`.
- Input errors (an unknown town, a postal code without a country, a filter that needs details) end the run with a message that says what to change.

### Troubleshooting

- **"Facebook refused the requests"**: keep the default proxy and keep **Retry refused requests from a new IP address** on.
- **"is a town in several countries"**: add the country, e.g. `"Cambridge, GB"`, or fill in **Country**.
- **Few results with a small radius:** that is how many listings Facebook has there. The status message says how many listings were outside the radius.
- **Listings from other towns:** turn off **Strict radius** only if you want them; otherwise they are already left out.

Need another field, another marketplace or a custom integration? Open an issue on the actor's page. We read every one.

### Integrations

Connect the results to the tools you already use with the built-in integrations of Apify (the **Integrations** tab of the actor or of a saved task), with no code:

- **Google Sheets or Google Drive:** the results of every run in a spreadsheet or a file.
- **Zapier, Make and n8n:** start a workflow when a run finishes, or start the actor from one.
- **Slack or e-mail:** a message from Apify when a run finishes or fails.
- **Webhooks:** your own address gets the details of each run.
- **API and MCP:** run the actor from your code, or let an AI assistant run it through the Apify MCP server.

The results also download as Excel, CSV, JSON or XML from the **Output** tab.

### Privacy and error reports

When a run fails, the actor sends its developer a short error report: the error, the run ID and your input with secrets left out (tokens, webhooks, e-mails and similar values are hidden). Your results are never sent. Reports are deleted after at most 120 hours (5 days). To send nothing, turn off **Send error reports** (`sendErrorReports: false`). Questions about your data: open an issue in the **Issues** tab of this actor.

### More classified-ad scrapers

The same deal score, monitoring and alerts for another classified-ad site:

- [Bazoš Scraper & New Ad Monitor](https://apify.com/tsutseisoftware/bazos-scraper): Bazoš.cz, .sk, .pl and .at: any section or search, deal score, car fields, new and cheaper ads with alerts
- [Vinted Scraper](https://apify.com/tsutseisoftware/vinted-scraper): 24 Vinted country sites in one run: price, brand, size, condition in English, deal score, sold items, alerts
- [AutoScout24 Scraper](https://apify.com/tsutseisoftware/autoscout24-scraper): used and new cars from all 8 AutoScout24 countries: price rating, deal score, full specs, dealer stocks, sold listings, alerts
- [Kleinanzeigen Scraper & New Ad Monitor](https://apify.com/tsutseisoftware/kleinanzeigen-scraper): Germany's biggest classifieds: searches past 1,250 ads, deal score, vehicle and electronics fields, price check, new and cheaper ads with alerts
- [Craigslist Scraper](https://apify.com/tsutseisoftware/craigslist-scraper): any Craigslist site, a whole state or country in one run: up to 10,000 ads per search, deal score, removed ads, new ad alerts

### WhatsApp notifications: setup

The actor sends the message from your own WhatsApp business number through the WhatsApp Cloud API of your Meta business account. You need a Meta business account; the actor uses only the values you enter in the **Notifications** section (the token and the numbers are stored encrypted and never written to the log).

1. **Create an app.** In Meta for Developers open **My Apps → Create app** and choose the use case **Connect with customers through WhatsApp**.
2. **Get a sending number.** In the app open **WhatsApp → API Setup**. You can start with the test number Meta gives you and add your own business number there later. Copy the **Phone number ID** (not the number itself) into **WhatsApp phone number ID**.
3. **Confirm the recipients (test number only).** A test number sends only to numbers on its list: in **API Setup**, under **To**, add each recipient's number and confirm it with the code WhatsApp sends to it.
4. **Create a permanent access token.** The token shown in API Setup expires within hours. In **Business settings → System users** add a system user, use **Assign assets** to give it your app (and your WhatsApp account), then **Generate token** for the app with the permissions `whatsapp_business_messaging` and `whatsapp_business_management` and the expiry you want. Paste it into **WhatsApp access token**.
5. **Create a message template (recommended).** In **WhatsApp Manager → Message templates → Create template** choose the category **Utility**, a name (e.g. `apify_results`) and a language, and write a body with two variables, for example: `New results of your Apify task: {{1}} Open the dataset: {{2}} (sent automatically after each run).` Meta does not accept a body that starts or ends with a variable and asks for sample values (e.g. `3 new jobs` and a dataset link); keep the text factual, a promotional text is moved to the Marketing category. Approval can take up to 24 hours. Enter the name in **WhatsApp template name** and its language code (e.g. `en_US`, `cs`, `pl`, `de`, as WhatsApp Manager shows it) in **WhatsApp template language**.
6. **Enter the recipients.** **WhatsApp recipient number** takes up to 5 numbers with the country code (e.g. `+420601234567`), separated by commas or new lines. Each number gets its own message.

**What the message contains.** With a template: `{{1}}` is the run summary with the first results on one line (title, company or price, place; never descriptions or contacts) and `{{2}}` the link to the dataset. A template with only `{{1}}` works too, it then gets the link at the end. Without a template the actor sends a text message with one link per result, like in Slack or Telegram.

**Without a template** WhatsApp delivers the message only when the recipient wrote to your business number in the last 24 hours (the customer service window), so a daily or hourly schedule needs a template. The run log says so once per run.

**What it costs.** Meta bills your business account, not this actor: per delivered message, by the message category (a template of the Utility category, or a service message for text in the 24-hour window, with a monthly free allowance per business number) and by the recipient's country. The current rates are in Meta's pricing of the WhatsApp Business Platform. The actor's own notification charge (see the **Pricing** tab) is once per run that delivered its notification, whatever the number of channels and recipients.

**Checked at the start.** When the run starts, the actor checks the token, the phone number ID and, when the token shows its WhatsApp account, the template (name, language, approval), without sending anything. Settings that can't work stop the run with a message that says what to fix, before anything is read from the website.

**When nothing arrives**, the run log names the WhatsApp error and what to do: a template that does not exist in that language or is not approved yet, a template with another number of variables, a recipient missing from the test number's list, an expired token, or the 24-hour window. A failed notification never fails the run and is not charged. Meta can accept a message and still not deliver it later (for example when the recipient's phone is not on WhatsApp); such a run counts as notified.

### FAQ

#### Is it legal to scrape Facebook Marketplace?

It reads only publicly available data that Facebook shows to any visitor without an account, without logging in or using cookies, at most 120 requests per minute, slows down when the website asks and never solves captchas or other challenges. A refused request is asked again from a new IP address only with **Retry refused requests from a new IP address** (on by default, charged as New IP retry). Listings include the seller's public profile name; you are responsible for processing such personal data lawfully (e.g. GDPR in the EU: a legitimate purpose, no spam, deletion on request). E-mails and phone numbers are removed from descriptions. The seller profile photo is an opt-in add-on; a photo of a person is personal data, so use it only where you have a lawful reason. This actor is not affiliated with Meta or Facebook.

#### How is it different from other Marketplace scrapers?

Many Marketplace scrapers have no postal code or radius input, quietly search around San Francisco when they don't know a place, or keep to the radius only with details. This one takes any town, postal code or coordinates, keeps to your radius on every listing for free, needs no login or cookies, adds a deal score and monitoring with alerts, and costs $0.44 per 1 000 listings with the proxy included.

#### Do I need a Facebook account or cookies?

No. Nothing is logged in.

#### Why are some listings outside my radius missing?

That is the strict radius: Facebook adds listings from far away and the actor leaves them out (free of charge). Turn off **Strict radius** to keep them with their distance.

#### How does it know where a postal code is?

Your postal code is sent to the public geocoders Zippopotam.us and OpenStreetMap Nominatim. Place data © GeoNames (CC BY 4.0).

#### Can I search in miles?

Yes, set **Radius unit** to miles. Every row has both `distanceKm` and `distanceMiles`.

#### Which countries work?

Every country where Facebook Marketplace is available. Prices come in the local currency. Facebook adds its own USD value on every row (`priceUsd`), and **Convert prices to** gives any currency.

#### Can I use it from an AI agent or through MCP?

Yes. The actor works with the Apify MCP server and API, and a small output (compact or chosen fields) keeps agent answers short.

***

More scrapers from the same developer: [tsutseisoftware on Apify](https://apify.com/tsutseisoftware).

Also known as a Facebook Marketplace API, FB Marketplace scraper, Marketplace price tracker or deal finder.

# Changelog

This Actor's version history is a separate document: https://apify.com/tsutseisoftware/facebook-marketplace-scraper/changelog.md

# Actor input Schema

## `searchQueries` (type: `array`):

Words to search for, as typed into the search box of Marketplace ("iphone 15", "mountain bike", "skoda octavia"). Each line is a separate search around every location. Empty = browse the chosen categories.

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

Where to search, one per line: a town ("Ostrava", "Austin, TX, US", "Paris, France"), a postal code with its country ("70200, CZ", "10001, US", "SW1A, GB") or coordinates ("49.8407, 18.2787"). Towns of every country are known; when a name exists in several countries, the actor stops and asks you to add the country instead of guessing. The resolved place is written to the log.

## `country` (type: `string`):

Default country for the locations that do not name one: a two-letter code (CZ, US, DE, GB) or the English name. Needed for postal codes without a country.

## `radius` (type: `integer`):

How far from each location to search (in the unit below). Facebook itself does not keep to the radius for logged-out visitors; with "Strict radius" the actor measures every listing and leaves out (and does not charge) those farther away.

## `radiusUnit` (type: `string`):

Unit of the radius.

## `strictRadius` (type: `boolean`):

Leave out listings farther than the radius. Distance is measured from the listing's town (from its exact coordinates with "Add listing details"); every row has distanceKm and distanceMiles. Listings left out are not charged.

## `includeUnknownDistance` (type: `boolean`):

A listing whose town can't be placed (a small village, a misspelled name) has no distance. On = keep it (distance empty), off = leave it out.

## `coverWholeRadius` (type: `boolean`):

One search reaches about 60 km around a point. For a bigger radius (up to 500 km), turn this on: the whole area is searched and duplicates are removed. Takes longer; pages without a listing inside the radius are charged as "Extra page".

## `categories` (type: `array`):

Search only in these categories (combined with the keywords), or browse them when there are no keywords. "Vehicles" without keywords uses the vehicle filters below.

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

Search or category pages copied from the browser, with their place and filters (e.g. https://www.facebook.com/marketplace/prague/search?query=bike\&maxPrice=5000), and listing URLs (https://www.facebook.com/marketplace/item/123456789/, read with their details). Each search URL costs about $0.003 extra (charged as extra pages). A URL whose town Facebook does not know (it would search around San Francisco) is skipped.

## `minPrice` (type: `integer`):

In the currency of the place (CZK in Czechia, USD in the US...).

## `maxPrice` (type: `integer`):

In the currency of the place.

## `conditions` (type: `array`):

Only listings in these conditions. Empty = any.

## `daysSinceListed` (type: `string`):

Age of the listings.

## `deliveryMethod` (type: `string`):

How the item can be handed over.

## `availability` (type: `string`):

"Sold" returns listings marked as sold or pending (reserved; `isPending`): what items really sold for. Facebook does not show the seller of sold listings.

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

Order of the results (as on Facebook).

## `exactMatch` (type: `boolean`):

Facebook's own "exact match": no loosely related results.

## `vehicleTypes` (type: `array`):

Kinds of vehicles.

## `bodyStyles` (type: `array`):

Body styles of cars.

## `vehicleMinYear` (type: `integer`):

Model year from. Facebook filters by it; the actor also leaves out listings whose year it knows (from the title or the details) outside the range. Listings without vehicle data (parts, many listings outside the US) stay in.

## `vehicleMaxYear` (type: `integer`):

Model year up to (see Year from).

## `vehicleMinMileage` (type: `integer`):

In the unit of the country (km or miles). Like the year: listings without a known mileage stay in.

## `vehicleMaxMileage` (type: `integer`):

In the unit of the country (km or miles).

## `vehicleTransmission` (type: `string`):

Gearbox.

## `titleKeywords` (type: `array`):

Only listings whose title contains these words (without diacritics, any case). See "Keywords must match".

## `keywordsMode` (type: `string`):

For "Title must contain" and "Text must contain".

## `excludeKeywords` (type: `array`):

Leave out listings whose title contains any of these words ("case", "broken", "parts", "wanted").

## `titleMustContainQuery` (type: `boolean`):

Leave out listings whose title does not contain every word of their search keyword (Facebook adds loosely related items).

## `descriptionKeywords` (type: `array`):

Only listings whose title or description contains these words. Needs "Add listing details"; the details of a listing it leaves out are read and charged (as details, not as a listing). A listing whose details could not be read is left out (the filter cannot be checked).

## `excludeDescriptionKeywords` (type: `array`):

Leave out listings whose title or description contains any of these words. Needs "Add listing details"; the details of a listing it leaves out are read and charged (as details, not as a listing).

## `postedWithinHours` (type: `integer`):

Only listings created at most this many hours ago (precise; with "Sort by" newest the run stops at older listings).

## `postedFrom` (type: `string`):

Only listings created on this day or later.

## `postedTo` (type: `string`):

Only listings created on this day or earlier.

## `freeOnly` (type: `boolean`):

Only listings with the price 0 / "Free".

## `onlyDiscounted` (type: `boolean`):

Only listings whose seller lowered the price (Facebook shows the old price crossed out).

## `excludePlaceholderPrices` (type: `boolean`):

Leave out listings with prices sellers type instead of a real one (1, 123, 1234, 999 999...).

## `excludeOutlierPrices` (type: `boolean`):

Leave out listings priced below 20 % or above 500 % of the usual price of comparable listings.

## `maxPriceVsMedianPercent` (type: `integer`):

Only listings priced at most this much above (positive) or below (negative) the median price of comparable listings of the same search, e.g. -20 = at least 20 % cheaper than usual.

## `minDealScore` (type: `integer`):

Only listings with at least this deal score (50 = the usual price, higher = cheaper, 100 = free).

## `hideDuplicateListings` (type: `boolean`):

The same seller posting the same title several times: keep the first only.

## `excludeSellers` (type: `array`):

Seller names or seller IDs (sellerId of a row) to leave out.

## `onlySellers` (type: `array`):

Watch-list: only listings of these seller names or IDs.

## `sellerTypes` (type: `array`):

Needs "Add listing details".

## `customFilters` (type: `array`):

Rules on any output field, all must hold, e.g. \[{"field": "distanceKm", "op": "lte", "value": 10}, {"field": "imageCount", "op": "gte", "value": 3}]. Ops: includes, notIncludes, equals, notEquals, gt, gte, lt, lte, exists, notExists.

## `skipListingsFromDataset` (type: `string`):

Run ID or dataset ID of an earlier run of this actor: its listings are left out.

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

Reads the listing page: description, all photos, exact coordinates (and the distance from them), condition, attributes, vehicle data (make, model, mileage, fuel, transmission, colour, owners, VIN), shipping, the seller's rating and profile. Off = what the search shows (title, price, town, photo, seller, date).

## `includeSellerPhoto` (type: `boolean`):

With "Add listing details": the seller's profile picture (sellerPhotoUrl). Extra charge "Seller photo" per saved listing that has one. The photo is personal data of the seller: use it lawfully (see the FAQ).

## `includeAllPhotos` (type: `boolean`):

With details: every photo of the listing.

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

Keep at most this many photo URLs per listing. 0 = all.

## `descriptionMaxLength` (type: `integer`):

Cut descriptions after this many characters. 0 = the whole text.

## `convertCurrency` (type: `string`):

Adds priceConverted in this currency (daily rates of the European Central Bank). Empty = no conversion.

## `compact` (type: `boolean`):

Only the main fields: title, price, place, distance, date, condition, photo, seller, deal score, URL.

## `fields` (type: `array`):

Only these fields (plus id, url, title, source, scrapedAt). Empty = all.

## `excludeEmptyFields` (type: `boolean`):

Drop fields without a value from every row (smaller exports).

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

Maximum number of listings saved. You pay per saved listing. 0 = no limit.

## `maxItemsPerSearch` (type: `integer`):

Limit for each keyword × location (or URL) separately. 0 = no limit.

## `maxPagesPerSearch` (type: `integer`):

Read at most this many pages (about 24 listings each) of every search. 0 = no limit.

## `onlyNewOrChanged` (type: `boolean`):

Return new listings, and listings whose price, title or status changed (with previousPrice and the change in %).

## `monitoringKey` (type: `string`):

Name of the remembered state; use a different key for every saved search. Empty = "default".

## `onlyPriceDrops` (type: `boolean`):

Of the changed listings, return only those whose price went down.

## `minPriceDropPercent` (type: `integer`):

Of the changed listings, return only those whose price went down by at least this many %.

## `includeRemovedListings` (type: `boolean`):

Listings of the previous run that are gone: the actor checks each one and returns it with removedReason sold, pending, removed or noLongerMatches. Turned on for an existing monitoring key, it reports from the run after: the first run remembers what to report the listings with.

## `includeUnchanged` (type: `boolean`):

Return unchanged listings too (changeType "unchanged"; charged as listings).

## `onlyNew` (type: `boolean`):

Return new listings only, not changed ones.

## `skipReposts` (type: `boolean`):

A listing the seller posted again (seen before under another ID) is marked isRepost; on = leave it out.

## `skipFirstRun` (type: `boolean`):

The first run only remembers the listings and returns nothing; later runs return what is new.

## `monitoringEarlyStop` (type: `boolean`):

With "Sort by" newest: stop a search at the first page of listings that are all known (fast, cheap checks every few minutes).

## `ignoreChangesIn` (type: `array`):

Changes of these fields do not count.

## `resetMonitoring` (type: `boolean`):

Forget the remembered listings of this Monitoring key.

## `telegramBotToken` (type: `string`):

Token of your bot from @BotFather.

## `telegramChatId` (type: `string`):

Chat to send to.

## `slackWebhookUrl` (type: `string`):

Incoming webhook (https://hooks.slack.com/...).

## `discordWebhookUrl` (type: `string`):

Webhook of your Discord channel (https://discord.com/api/webhooks/...). In Discord: channel settings → Integrations → Webhooks → Copy Webhook URL. Stored encrypted.

## `webhookUrl` (type: `string`):

Any HTTPS URL (Zapier, Make, n8n, your server): receives the listings as JSON.

## `whatsappAccessToken` (type: `string`):

Access token of the WhatsApp Cloud API of your Meta business account, used with "WhatsApp phone number ID" and "WhatsApp recipient number" (step by step in the README, section "WhatsApp notifications: setup"). For scheduled runs use a permanent token of a system user: Business settings → System users → Generate token, with the permissions whatsapp_business_messaging and whatsapp_business_management; the token of WhatsApp → API Setup expires within hours. Stored encrypted.

## `whatsappPhoneNumberId` (type: `string`):

ID of your WhatsApp business number that sends the message (not the number itself), e.g. 106540352242922. In your Meta app: WhatsApp → API Setup → Phone number ID.

## `whatsappTo` (type: `string`):

Phone number that gets the message, in international format with the country code (e.g. +420601234567); up to 5 numbers separated by commas or new lines, each gets its own message and the notification is charged once per run. A test number of Meta sends only to numbers you added and confirmed under API Setup → To. Stored encrypted.

## `whatsappTemplateName` (type: `string`):

Name of your approved message template (WhatsApp Manager → Message templates, e.g. apify_results), recommended: WhatsApp delivers a template message at any time. Its body gets the run summary with the first results in {{1}} and the dataset link in {{2}} (a template with only {{1}} gets both in {{1}}). Empty: a plain text message, which WhatsApp delivers only when the recipient wrote to your business number in the last 24 hours, so a scheduled run usually needs a template. Meta charges your business account for template messages (step by step in the README, section "WhatsApp notifications: setup").

## `whatsappTemplateLanguage` (type: `string`):

Language code of the template exactly as WhatsApp Manager → Message templates shows it next to the template, e.g. en_US, en_GB, cs, sk, pl or de. Used only with "WhatsApp template name".

## `notificationLimit` (type: `integer`):

How many listings the message lists.

## `notifyOnlyChanges` (type: `boolean`):

No message after a run that saved nothing.

## `retryFromNewIp` (type: `boolean`):

When Facebook keeps refusing a request, ask again from a new IP address (up to 3 per request). Each new address is charged as "New IP retry". Off = a refused request is skipped.

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

Facebook needs a residential proxy. It is set by default and its cost is included in the price. Any country works: the place is set by the location, not by the proxy.

## `sendErrorReports` (type: `boolean`):

When a run fails, send the developer a short error report: the error and your input with secrets left out (tokens, webhooks and e-mails are hidden). Your results are never sent. Reports are deleted after at most 120 hours. Turn off to send nothing.

## Actor input object example

```json
{
  "searchQueries": [
    "iphone"
  ],
  "locations": [
    "Ostrava, CZ"
  ],
  "radius": 20,
  "radiusUnit": "km",
  "strictRadius": true,
  "includeUnknownDistance": true,
  "coverWholeRadius": false,
  "daysSinceListed": "any",
  "deliveryMethod": "all",
  "availability": "available",
  "sortBy": "best_match",
  "exactMatch": false,
  "vehicleTransmission": "any",
  "keywordsMode": "any",
  "titleMustContainQuery": false,
  "freeOnly": false,
  "onlyDiscounted": false,
  "excludePlaceholderPrices": false,
  "excludeOutlierPrices": false,
  "hideDuplicateListings": false,
  "includeDetails": false,
  "includeSellerPhoto": false,
  "includeAllPhotos": true,
  "maxPhotos": 0,
  "descriptionMaxLength": 0,
  "convertCurrency": "",
  "compact": false,
  "excludeEmptyFields": false,
  "maxItems": 20,
  "maxItemsPerSearch": 0,
  "maxPagesPerSearch": 0,
  "onlyNewOrChanged": false,
  "onlyPriceDrops": false,
  "includeRemovedListings": false,
  "includeUnchanged": false,
  "onlyNew": false,
  "skipReposts": false,
  "skipFirstRun": false,
  "monitoringEarlyStop": false,
  "resetMonitoring": false,
  "whatsappTemplateLanguage": "en_US",
  "notificationLimit": 10,
  "notifyOnlyChanges": true,
  "retryFromNewIp": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "sendErrorReports": true
}
```

# 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 = {
    "searchQueries": [
        "iphone"
    ],
    "locations": [
        "Ostrava, CZ"
    ],
    "radius": 20,
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("tsutseisoftware/facebook-marketplace-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 = {
    "searchQueries": ["iphone"],
    "locations": ["Ostrava, CZ"],
    "radius": 20,
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("tsutseisoftware/facebook-marketplace-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 '{
  "searchQueries": [
    "iphone"
  ],
  "locations": [
    "Ostrava, CZ"
  ],
  "radius": 20,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call tsutseisoftware/facebook-marketplace-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tsutseisoftware/facebook-marketplace-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/uWtARCvUEdsAADx7v/builds/82pq1xcS3bbDgSLsl/openapi.json
