Facebook Marketplace Search
Facebook Marketplace Search listings are public local-commerce offers with titles, prices, locations, images, seller context, delivery options, and availability signals. These fields support local inventory research, asking-price comparison, category analysis, and repeatable market snapshots.
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
| Parameters | Required | Description |
|---|---|---|
query | Required | Required non-empty listing keyword; leading and trailing whitespace is removed before submission. |
latitude | Required | Required latitude for the search center, expressed as a number from -90 through 90. |
longitude | Required | Required longitude for the search center, expressed as a number from -180 through 180. |
results_limit | Optional | Maximum listings to save across search pages; defaults to 100 and accepts integers from 1 through 2,000. |
radius_km | Optional | Optional search radius in kilometers; when supplied, it must be a number greater than 0. |
min_price | Optional | Optional minimum listing price; it must be non-negative and cannot exceed max_price. |
max_price | Optional | Optional maximum listing price; it must be non-negative and cannot be lower than min_price. |
sort_by | Optional | Optional order: suggested, distance_ascend, creation_time_descend, price_ascend, or price_descend. |
delivery_method | Optional | Optional delivery filter: all, local_pickup, or shipping. |
condition | Optional | Optional condition filter: new, used_like_new, used_good, or used_fair. |
date_listed | Optional | Optional listing-age filter: all, 1, 7, 30, last_24_hours, last_7_days, or last_30_days. |
availability | Optional | Optional availability filter: available, sold, or all. |
How to Use
Submit a keyword and geographic center with optional listing filters, track the asynchronous task, and read normalized listings with cursor pagination.
- Prepare a non-empty query, latitude from -90 through 90, longitude from -180 through 180, and any optional filters.
- POST the request to /v1/facebook-marketplace/search, then store the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- 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 trueBest 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
Use these APIs when you need a different type of public Facebook Marketplace data.
- Facebook Marketplace Location Search API — Resolve city, region, neighborhood, or place-name queries into Marketplace location candidates and coordinates.
- Facebook Marketplace Item API — Collect detailed public Marketplace listings from known item URLs with seller, price, location, media, attributes, delivery, and availability fields.