# Facebook Marketplace Scraper (`datascrapers/facebook-marketplace`) Actor

Facebook Marketplace listing dataset from URLs, locations, categories, and price filters, including optional listing details.

- **URL**: https://apify.com/datascrapers/facebook-marketplace.md
- **Developed by:** [Farhan Ali](https://apify.com/datascrapers) (community)
- **Categories:**
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.70 / 1,000 product scrapeds

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?

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

**Facebook Marketplace Scraper** creates a structured dataset of Marketplace listings collected from [Facebook Marketplace](https://www.facebook.com/marketplace). Each dataset item represents one listing and can include identifiers, title, price, images, location, category, delivery types, status flags, and optional description and seller name. Query the source with Marketplace search, category, or item URLs, or with keyword search plus location and filters. Control the result limit with `maxItems`, and retrieve records through the Apify Dataset API or export them as JSON, CSV, Excel, or other supported formats.

### Dataset at a glance

| Property | Value |
|---|---|
| Source | facebook.com/marketplace (public Marketplace listings) |
| Record unit | One Marketplace listing |
| Input methods | Marketplace URLs (`startUrls`) or keyword search (`searchQueries`) with `location`, category, price, condition, delivery, and listing-age filters |
| Main identifiers | `listingId`, `url` |
| Delivery | Apify Dataset and API |
| Export formats | JSON, CSV, Excel, XML, HTML (Apify dataset exports) |
| Update model | Fresh records per Actor run |
| Pricing | $2.00 per 1,000 listings; +$2.00 per 1,000 when listing details are collected |

### Coverage and available records

The Actor collects publicly listed Marketplace records from two entry points:

- **URL-based**: Pass Marketplace search, category, or item URLs in `startUrls` (for example `https://www.facebook.com/marketplace/berlin/sports` or `https://www.facebook.com/marketplace/item/123`). Filters encoded in the URL are applied. URLs can be used instead of, or together with, location and category fields.
- **Search-based**: Set `searchQueries` (for example `bike`) with `location` or `latitude`/`longitude`. `searchQueries` requires a location from the field, coordinates, or a city in the start URL.

Leave `categories` empty to collect listings near the location, or to keep the category from start URLs. Accepted slugs are listed in the input reference.

- **Listing-level records** include identifiers, title, price, images, location, category, delivery types, status flags, `creationTime`, `detailsScraped`, and `sourceQuery` when Marketplace publishes them.
- **Detail fields** are conditional: `description` and `sellerName` appear when `scrapeListingDetails` is enabled and published. `latitude`, `longitude`, and extra `imageUrls` are typically collected on the same pass.
- **Result cap**: `maxItems` limits listings (`0` = unlimited, the default; prefill `10`). `radiusKm` defaults to `80` (1–500).

Known exclusions: unpublished listing fields; historical snapshots unless you store them; Marketplace messaging and account dashboards. Full-catalog or worldwide coverage is not claimed.

### Data dictionary

Field names match dataset JSON properties exactly. Fields marked *conditional* appear when `scrapeListingDetails` is enabled and Marketplace publishes the value. Deduplicate on `listingId` or `url`.

| Field | Type | Nullable | Description | Example |
|---|---|---:|---|---|
| `listingId` | string | No | Marketplace listing identifier; recommended dedup key | `958550220194623` |
| `url` | string | No | Marketplace item URL | `https://www.facebook.com/marketplace/item/958550220194623/` |
| `title` | string | Yes | Listing headline | `Ebike Akku` |
| `price` | string | Yes | Formatted asking price as shown | `€180` |
| `priceAmount` | number | Yes | Numeric price in the listing currency | `180.0` |
| `currency` | string | Yes | Currency symbol as shown on the listing | `€` |
| `imageUrl` | string | Yes | Primary image URL | `https://scontent.fmex3-1.fna.fbcdn.net/...` |
| `imageUrls` | string\[] | Yes | Image URLs; additional photos are *conditional* | `["https://scontent.fmex3-1.fna.fbcdn.net/..."]` |
| `location` | string | Yes | Location label as shown | `Berlin, BE` |
| `city` | string | Yes | City parsed from the listing location | `Berlin` |
| `state` | string | Yes | State or region code when published | `BE` |
| `latitude` | number | Yes | Latitude (*conditional*) | — |
| `longitude` | number | Yes | Longitude (*conditional*) | — |
| `category` | string | Yes | Category label as shown | `Sporting goods` |
| `categoryId` | string | Yes | Marketplace category identifier | `1383948661922113` |
| `deliveryTypes` | string\[] | Yes | Delivery options published on the listing | `["IN_PERSON", "SHIPPING_OFFSITE"]` |
| `isSold` | boolean | Yes | Whether the listing is marked sold | `false` |
| `isPending` | boolean | Yes | Whether the listing is marked pending | `false` |
| `isLive` | boolean | Yes | Whether the listing is live | `true` |
| `creationTime` | string | Yes | Listing creation time (ISO-8601 with offset) | `2026-03-23T16:56:03+00:00` |
| `detailsScraped` | boolean | No | Whether listing details were collected for this record | `false` |
| `sourceQuery` | string | Yes | Keyword that produced the record, when applicable | `bike` |
| `description` | string | Yes | Listing body text (*conditional*) | — |
| `sellerName` | string | Yes | Seller display name when published (*conditional*) | — |

`priceAmount` is numeric in the listing currency; `price` is the formatted string. `creationTime` is ISO-8601 with a UTC offset. Values are read from Marketplace, not calculated.

### Example dataset record

Real record from the input below (`searchQueries: ["bike"]`, Berlin, `sports`, details off). Coordinate, description, and seller fields are null because details were not collected.

```json
{
  "listingId": "958550220194623",
  "url": "https://www.facebook.com/marketplace/item/958550220194623/",
  "title": "Ebike Akku",
  "price": "€180",
  "priceAmount": 180.0,
  "currency": "€",
  "imageUrl": "https://scontent.fmex3-1.fna.fbcdn.net/v/t39.84726-6/656897439_26373996142232794_8113191025035381410_n.jpg",
  "imageUrls": ["https://scontent.fmex3-1.fna.fbcdn.net/v/t39.84726-6/656897439_26373996142232794_8113191025035381410_n.jpg"],
  "location": "Berlin, BE",
  "city": "Berlin",
  "state": "BE",
  "latitude": null,
  "longitude": null,
  "category": "Sporting goods",
  "categoryId": "1383948661922113",
  "deliveryTypes": ["IN_PERSON", "SHIPPING_OFFSITE", "PUBLIC_MEETUP", "DOOR_PICKUP"],
  "isSold": false,
  "isPending": false,
  "isLive": true,
  "creationTime": "2026-03-23T16:56:03+00:00",
  "detailsScraped": false,
  "sourceQuery": "bike",
  "description": null,
  "sellerName": null
}
```

The record above was produced with this input:

```json
{
  "location": "Berlin, Germany",
  "searchQueries": ["bike"],
  "categories": ["sports"],
  "maxItems": 10,
  "scrapeListingDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

### Query and input reference

| Input | Type | Required | Default | Accepted values | Description |
|---|---|---:|---|---|---|
| `startUrls` | array (requestListSources) | No | — | Marketplace search, category, or item URLs | URL entry point. Filters encoded in the URL are applied |
| `searchQueries` | array (string) | No | — | Free-text keywords (e.g. `bike`) | Keyword search. Requires a location (field, coordinates, or city in a start URL) |
| `location` | string | Conditional | — (prefill `Berlin, Germany`) | Place text (e.g. `Berlin, Germany`) | Search location. Required for search or category runs without a city in the URL |
| `latitude` | number | No | — | Decimal degrees | Optional coordinate override. When set with `longitude`, location text is not resolved |
| `longitude` | number | No | — | Decimal degrees | Optional coordinate override. When set with `latitude`, location text is not resolved |
| `radiusKm` | integer | No | `80` | `1`–`500` | Search radius in kilometers |
| `categories` | array (string) | No | — | `vehicles`, `propertyrentals`, `propertyforsale`, `apparel`, `classifieds`, `electronics`, `entertainment`, `family`, `free`, `garden`, `hobbies`, `home`, `home-improvements`, `instruments`, `office-supplies`, `pets`, `sports`, `toys` | Marketplace category slugs. Empty = all listings near the location, or the category from start URLs |
| `minPrice` | integer | No | — | `0` or greater | Minimum listing price in the local currency |
| `maxPrice` | integer | No | — | `0` or greater | Maximum listing price in the local currency |
| `condition` | string | No | `any` | `any`, `new`, `used_like_new`, `used_good`, `used_fair` | Item condition filter |
| `deliveryMethod` | string | No | `all` | `all`, `local_pickup`, `shipping` | Delivery-method filter |
| `daysSinceListed` | string | No | `""` | `""`, `1`, `7`, `30` | Listing age: any time, last 24 hours, last 7 days, or last 30 days |
| `sortBy` | string | No | `best_match` | `best_match`, `newest`, `price_asc`, `price_desc`, `distance` | Result order |
| `scrapeListingDetails` | boolean | No | `false` | `true` / `false` | Collect description, seller name, coordinates, and additional photos when published (charges `listing-details`) |
| `maxConcurrency` | integer | No | `5` | `1`–`20` | Parallel listing-detail requests when details are enabled |
| `maxItems` | integer | No | `0` (prefill `10`) | `0` or any positive integer | Maximum listings; `0` = unlimited |
| `proxyConfiguration` | object | No | Apify proxy, `RESIDENTIAL` group | Apify proxy groups or custom proxies | Residential proxies are recommended |

Provide `startUrls` and/or a search (`searchQueries` / `categories`) with `location` or coordinates.

Minimal request:

```json
{ "location": "Berlin, Germany", "searchQueries": ["bike"], "maxItems": 10 }
```

Advanced request (filters with detail enrichment):

```json
{
  "location": "Berlin, Germany",
  "searchQueries": ["bike"],
  "categories": ["sports"],
  "minPrice": 50,
  "maxPrice": 500,
  "condition": "used_good",
  "deliveryMethod": "local_pickup",
  "daysSinceListed": "7",
  "sortBy": "newest",
  "scrapeListingDetails": true,
  "maxConcurrency": 5,
  "maxItems": 10,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}
```

### Retrieve the data through the API

The Actor is published at <https://apify.com/datascrapers/facebook-marketplace>.

1. Start the Actor with a JSON input (console or API).
2. Wait for the run to finish, or use a synchronous endpoint if you want the response inline.
3. Retrieve items from the run's default dataset.
4. Paginate or export the dataset.

Python example:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR-APIFY-TOKEN")

run_input = {
    "location": "Berlin, Germany",
    "searchQueries": ["bike"],
    "categories": ["sports"],
    "maxItems": 10,
    "scrapeListingDetails": False,
}

run = client.actor("datascrapers/facebook-marketplace").call(run_input=run_input)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["listingId"], item["title"], item["price"])
```

Apify generates Python, JavaScript, and cURL examples on the Actor's API tab. Do not put a real API token in shared code or URLs.

### Data quality and record handling

- **Conditional fields**: `description`, `sellerName`, coordinates, and extra `imageUrls` appear when `scrapeListingDetails` is enabled and published. Listing-only runs set `detailsScraped` to `false`.
- **Source changes**: unpublished fields are returned as null, not fabricated.
- **Deduplication**: each run appends fresh records. Use `listingId`, or `url` when `listingId` is unavailable, across runs.
- **Normalization**: identifiers and `price` are strings; `priceAmount` is a number; status flags and `detailsScraped` are booleans; `creationTime` is ISO-8601 when published; `deliveryTypes` and `imageUrls` are string arrays.
- **Residential proxies**: recommended for public Marketplace listings.

### Export and pipeline examples

| Destination | Recommended method | Typical use |
|---|---|---|
| PostgreSQL / Supabase | Dataset API poll or webhook consumer | Store listings alongside price-monitoring tables |
| Google Sheets | Apify Google Sheets integration | Share listing shortlists with research teams |
| CRM (HubSpot, Salesforce) | Webhook on run completion | Push new listings into outreach pipelines |
| S3 / cloud storage | Scheduled export via Apify scheduler + integration | Archival of marketplace snapshots |

### Pricing and cost examples

Pay-per-event: a `listing` charge for every dataset record, plus `listing-details` when `scrapeListingDetails` is enabled and details are collected. Actor start is $0.00005 once per run.

| Event | Trigger | Rate |
|---|---|---|
| Actor start | Once per run | $0.00005 per run |
| Listing (`listing`) | Every listing record pushed to the dataset | $2.00 per 1,000 listings |
| Listing details (`listing-details`) | `scrapeListingDetails` enabled and details collected | $2.00 per 1,000 listings |

| Records | Configuration | Estimated base cost |
|---:|---|---:|
| 1,000 | Listing only | $2.00 |
| 10,000 | Listing only | $20.00 |
| 1,000 | Listing + listing details | $4.00 |
| 10,000 | Listing + listing details | $40.00 |

Start charges round to $0.00 in the table. Compute units and proxy traffic are billed by your Apify plan. Estimates depend on the verified pricing model and selected options.

### Limitations and responsible data use

- The Actor collects publicly listed Marketplace records only.
- Field availability depends on what Marketplace renders at run time; values can be null, and site changes can alter fields.
- The Actor does not provide historical snapshots unless you store them yourself.
- Residential proxies are recommended.
- You are responsible for compliance with Facebook's terms of service, applicable privacy law, and any contractual obligations before using the data.

### Dataset questions

#### What does one dataset item represent?

One Facebook Marketplace listing. Enabling `scrapeListingDetails` adds description, seller name, coordinates, and extra photos to that record when published.

#### Which field should I use as a unique identifier?

`listingId` is the recommended deduplication key. Use `url` when `listingId` is unavailable.

#### Are fields nullable or conditional?

Yes. `description` and `sellerName` appear when `scrapeListingDetails` is enabled and published. Coordinates and extra `imageUrls` are typically collected on the same pass. Unpublished values are null.

#### Can I retrieve the records as CSV or JSON?

Yes. The dataset can be exported as JSON, CSV, Excel, XML, or HTML from the Apify Console, and queried through the Dataset API.

#### How do I search by keyword and location?

Set `searchQueries` and `location` (for example `Berlin, Germany`). Optionally pass `latitude` and `longitude` instead of location text. Category, price, condition, delivery, listing-age, and sort filters apply during the search.

#### Does the Actor return historical data?

No. Each run captures listings at run time. To track changes over time, schedule repeated runs and store the outputs yourself.

#### What counts as a billable result?

A `listing` charge for every dataset record ($2.00 per 1,000), plus `listing-details` when details are collected ($2.00 per 1,000). Listing-only runs incur only `listing`. Actor start is $0.00005 once per run.

### Related datasets from Data Scrapers

- **[Gumtree Scraper](https://apify.com/datascrapers/gumtree-scraper)** — UK classified listings with comparable title, price, and location fields.
- **[Etsy Scraper](https://apify.com/datascrapers/etsy-scraper)** — Marketplace product records for price comparison with Marketplace goods.
- **[Cars.com Scraper](https://apify.com/datascrapers/cars-scraper)** — US vehicle listings alongside Marketplace `vehicles`.
- **[Apartments.com Scraper](https://apify.com/datascrapers/apartments-scraper)** — US rental listings alongside Marketplace `propertyrentals`.
- **[Realtor.com Scraper](https://apify.com/datascrapers/realtor-scraper)** — US property listings comparable with Marketplace `propertyforsale`.

### Data Scrapers support

Need an additional field, record type, or export workflow? Contact Data Scrapers at stardustspotlight@gmail.com. Include a sample source URL, required fields, expected record volume, and preferred delivery format.

# Actor input Schema

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

Marketplace search, category, or item URLs (e.g. "https://www.facebook.com/marketplace/berlin/sports", "https://www.facebook.com/marketplace/item/123"). Filters encoded in the URL (location, category, minPrice, maxPrice) are applied. You can use this instead of, or together with, the location and category fields.

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

Keyword searches (e.g. "mountain bike", "puppies", "iPhone 15"). Requires a location (field below or a location in start URLs).

## `location` (type: `string`):

City or place to search (e.g. "Berlin, Germany", "Austin, TX"). Resolved to coordinates automatically. Required when using search queries or categories without start URLs.

## `latitude` (type: `number`):

Optional coordinate override. When set with longitude, location text is not resolved.

## `longitude` (type: `number`):

Optional coordinate override. When set with latitude, location text is not resolved.

## `radiusKm` (type: `integer`):

Distance around the location in kilometers.

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

Marketplace categories to scrape. Leave empty to scrape all listings near the location (or the category from start URLs).

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

Minimum listing price in the local currency. Leave empty for no minimum.

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

Maximum listing price in the local currency. Leave empty for no maximum.

## `condition` (type: `string`):

Item condition filter.

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

How the buyer can receive the item.

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

Only include listings created in the last N days. Leave empty for any age.

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

Result order.

## `scrapeListingDetails` (type: `boolean`):

Visit each listing to extract description, photos, seller, and extra attributes. Charges a second pay-per-event (listing-details) when enabled. Detail requests run in parallel and rotate the proxy.

## `maxConcurrency` (type: `integer`):

How many listing-detail requests to run at once (each uses a rotated proxy).

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

Maximum number of listings to scrape (0 = unlimited).

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

Residential proxies are required. The Actor opens Marketplace as a guest (no Facebook login).

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.facebook.com/marketplace/berlin/sports"
    }
  ],
  "searchQueries": [],
  "location": "Berlin, Germany",
  "radiusKm": 80,
  "condition": "any",
  "deliveryMethod": "all",
  "daysSinceListed": "",
  "sortBy": "best_match",
  "scrapeListingDetails": false,
  "maxConcurrency": 5,
  "maxItems": 10,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

JSON array of scraped Marketplace listings

## `runStats` (type: `string`):

Record count and run timestamps

# 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.facebook.com/marketplace/berlin/sports"
        }
    ],
    "searchQueries": [],
    "location": "Berlin, Germany",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascrapers/facebook-marketplace").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.facebook.com/marketplace/berlin/sports" }],
    "searchQueries": [],
    "location": "Berlin, Germany",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("datascrapers/facebook-marketplace").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.facebook.com/marketplace/berlin/sports"
    }
  ],
  "searchQueries": [],
  "location": "Berlin, Germany",
  "maxItems": 10
}' |
apify call datascrapers/facebook-marketplace --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datascrapers/facebook-marketplace"
        }
    }
}

```

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/ze8Cv9eRgqOl5RBgk/builds/hJzSrW3WbUloceI4C/openapi.json