Facebook Marketplace Search API

Facebook Marketplace Search

Features

• Keyword and geographic listing searchCombine one non-empty query with required latitude and longitude coordinates, then narrow public listings with radius, price, sort, delivery, condition, date, and availability controls.
• Structured listing and price recordsReturn listing IDs, public URLs, titles, available descriptions, price amounts, currencies, formatted prices, and strikethrough values in a consistent shape.
• Location, media, and classification contextKeep available location labels, city and state values, image references, category IDs, attributes, delivery types, and listing-date text with each result.
• Public search-card depthPreserve exposed seller fields and live, pending, sold, shipping, buy-now, and messaging flags while leaving search-card details empty when the public result does not provide them.

Parameters

How to Use

Submit a keyword and geographic center with optional listing filters, track the asynchronous task, and read normalized listings with cursor pagination.

1. Prepare a non-empty query, latitude from -90 through 90, longitude from -180 through 180, and any optional filters.
2. POST the request to /v1/facebook-marketplace/search, then store the returned task_id.
3. Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
4. Read data.results.items and request the returned next_cursor while has_more remains true.

curl -X POST "https://api.socq.ai/v1/facebook-marketplace/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"bike","latitude":30.2677,"longitude":-97.7475,"results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

• Local asking-price comparison: Compare normalized price amounts, currencies, titles, query context, and locations for similar public listings inside a defined search area.
• Regional inventory and category research: Use category IDs, attributes, delivery types, availability fields, images, and location context to assemble a bounded local listing dataset.
• Repeatable market snapshots: Retain listing IDs, prices, state fields, search_query, and collected_at to compare independently collected results for the same search over time.
• Listing shortlist preparation: Use public listing URLs, titles, prices, images, and availability context to select records for item-level follow-up.

Pro Tips

• When a search starts with a place name instead of coordinates, resolve and verify a Location Search candidate before submitting latitude and longitude.
• Validate coordinate ranges, keep radius_km above 0, use non-negative prices, and ensure min_price does not exceed max_price before submission.
• Follow next_cursor until has_more is false when stored results exceed the first response page; results_limit controls collection, not the task response page size.
• Key repeated snapshots by listing ID and retain collected_at because duplicate IDs are stored once per task and public listings can change or disappear.
• Treat descriptions, seller fields, precise coordinates, attributes, and creation times as optional; use a returned listing URL with Marketplace Item when deeper public detail is required.

Related APIs