Facebook Marketplace AI Scraper

Search Facebook Marketplace with a natural-language request and optionally filter listing images with AI.

1. Use AI as the main input

Describe what you want to find, including the item and location:

{
  "aiSearchDescription": "Find Toyota cars near New York",
  "maxItems": 100
}

The Actor uses the description to identify the search keyword and Facebook Marketplace location.

The AI can also expand a broad geographic request into multiple locations in any supported language or country. For example, Cerca auto Toyota in tutte le città d'Italia asks the AI to create an Italian city list, then each city is resolved to a Facebook Marketplace location before searching. The same works for states, provinces, regions, countries, and capitals.

How location matching works

Use a specific location when you want one area:

{
  "aiSearchDescription": "Find Toyota cars in Brooklyn, New York",
  "maxItems": 100
}

The AI reads the location from your sentence, finds the matching Facebook Marketplace location, and searches that area.

The same approach supports requests such as Tìm sản phẩm ở tất cả tỉnh thành Việt Nam, Cerca auto in tutte le città d'Italia, or Rechercher des produits dans toutes les régions de France. The AI understands the language of the request, creates a concrete location list, and the Actor resolves each location independently. Locations that Facebook cannot resolve are reported as unresolved and do not stop locations that were resolved successfully.

For large lists, set locationExpansionLimit (default 10, maximum 500). This controls how many locations the AI expands from a broad request; maxItems is the maximum number of listings returned for each location. For example, two locations with maxItems: 100 can return up to 200 listings.

For a single location, use a clear city, state, or country name. For guaranteed control over a large location list, provide the Marketplace URLs directly in marketplaceUrls or startUrls.

You can also list specific locations in one sentence. For example, Find Toyota in New York, California, and Florida creates three independent location searches. The same works with comma-separated locations and equivalent words in other languages.

To filter the listing images too, add aiImageFilterDescription:

{
  "aiSearchDescription": "Find Toyota cars near New York",
  "aiImageFilterDescription": "keep black Toyota cars",
  "maxItems": 100
}

Short image descriptions are accepted. For example, keep black toyota is expanded into a clearer visual rule before images are checked.

2. Search several locations

For multiple locations, provide one Marketplace search URL per location in marketplaceUrls:

{
  "marketplaceUrls": [
    "https://www.facebook.com/marketplace/LOCATION_ID_1/search/?query=Toyota",
    "https://www.facebook.com/marketplace/LOCATION_ID_2/search/?query=Toyota",
    "https://www.facebook.com/marketplace/LOCATION_ID_3/search/?query=Toyota"
  ],
  "aiImageFilterDescription": "keep black Toyota cars",
  "maxItems": 100
}

Replace each LOCATION_ID with the Facebook Marketplace location ID for the city or area you want. You can add as many location URLs as needed. The same format is available through startUrls:

{
  "startUrls": [
    { "url": "https://www.facebook.com/marketplace/LOCATION_ID_1/search/?query=Toyota" },
    { "url": "https://www.facebook.com/marketplace/LOCATION_ID_2/search/?query=Toyota" }
  ],
  "maxItems": 100
}

When URLs are provided, they take priority over aiSearchDescription, searchQuery, and country settings.

Main input fields

Field	Description
aiSearchDescription	Natural-language request with the item and location scope, in any language. It can describe one location or a group such as all cities in a country.
aiImageFilterDescription	Optional description of what the listing image must show.
marketplaceUrls	Array of Marketplace search or item URLs, useful for multiple locations.
startUrls	Same URL approach using { "url": "..." }.
searchQuery	Search keyword when not using AI search.
countryCode	Two-letter country code such as us, gb, or vn.
marketplaceLocation	Marketplace location ID or slug.
maxItems	Maximum listings to inspect per location. Default: 100.
locationExpansionLimit	Maximum locations created from a broad AI location request. Default: 10, maximum: 500.

How image AI works

1. The image description is refined if needed.
2. Each listing image is checked in its own AI request.
3. Matching listings are written to the Dataset immediately.

The primary image model is thuonghongthai97/gemini-3.6-flash-high. If it fails, the Actor uses gpt-5.4 as fallback. Listings whose images do not match are not included when AI filtering is enabled.

Output

Each Dataset item is a Marketplace listing. Common fields are:

• id: Marketplace listing ID.
• itemUrl: Direct listing URL.
• listingTitle: Listing title.
• description: Listing description, when available.
• locationName: Facebook Marketplace location used for this search.
• locationText: Listing location.
• listingPhotos: Listing image URLs and IDs.
• seller: Seller information, when available.
• isSold: Whether the listing is sold.

With AI filtering enabled, matching items also contain:

{
  "aiImageFilter": {
    "matches": true,
    "originalCriteria": "keep black Toyota cars",
    "criteria": "The image must show a real Toyota vehicle with a clearly black exterior color. Reject unclear or ambiguous images.",
    "verificationModel": "sypham98/gpt-5.4",
    "confidence": 0.95
  }
}

Important AI fields:

Field	Description
aiImageFilter.matches	Whether the image matched the request.
aiImageFilter.originalCriteria	Original client image description.
aiImageFilter.criteria	Refined description used by AI.
aiImageFilter.verificationModel	Model used for the image check.
aiImageFilter.confidence	Confidence score from 0 to 1.
aiImageFilter.reason	Short reason explaining why the image was selected, limited to 20 words.

Billing events

When monetization is enabled, listing is charged once for every unique Marketplace listing fetched, whether or not it matches the AI filter. ai-image-filter is charged once for every listing sent to the AI image preflight. The second verification step is internal and does not create a second AI charge for the same listing.

If aiImageFilterDescription is not provided, all collected listings are returned without AI fields.

The Dataset display shows the product image, title, location, item URL, and search URL. Price is not shown as a display column, although listingPrice remains available in the raw Dataset item when Facebook provides it.