Facebook local listings
GET /v1/facebook/listings searches US Facebook Marketplace listings near a ZIP code or exact point, with radius, price, condition, delivery and sort filters.
https://api.soldgraph.com/v1/facebook/listingsSearch active Facebook Marketplace listings near a place. Give a five-digit zip, or lat and lon for an exact point, and optionally a radius in miles. One request returns one source page of up to about 24 listings. Sold search and completed sale prices are not supported; /v1/facebook/sold is not an API endpoint.
displayed_price is the seller's ask in USD. It is not a sale price, and buyers on Facebook Marketplace often negotiate. A price of 0 means the seller listed the item as free.
| Parameter | Type | Default | Description |
|---|---|---|---|
q | string | Required | Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition. |
page | integer, 1–1 | 1 | Always 1. Facebook serves one page per search, so there is no page 2. Optional. |
min_price | integer, 0–1000000 | Lowest price, in whole units of the country's currency (US dollars for us). Optional. Must not be more than max_price. You can send it without max_price. | |
max_price | integer, 0–1000000 | Highest price, in whole units of the country's currency (US dollars for us). Optional. You can send it without min_price. | |
marketplace | facebook | facebook | Optional. If sent, it must be facebook. |
country | us | us | Only us is supported here. eBay, Vinted, Poshmark, Depop and Whatnot endpoints also take other countries. Mercari, OfferUp, Facebook Marketplace and TCGplayer are US only. |
zip | string | Five-digit US ZIP code to search around. Send zip, or both lat and lon. Unknown ZIP codes, and places more than 75 miles from any Facebook Marketplace city, return 422. | |
lat | number, 17–72 | Latitude of the search center in decimal degrees. Use with lon instead of zip. Rounded to 4 decimals (about 11 m). | |
lon | number, -180–-64 | Longitude of the search center in decimal degrees. Use with lat. | |
radius | integer, 1–100 | Search radius in miles, 1 to 100. Default is Facebook's own, about 40 miles. Rows whose city is farther than the radius plus 10 miles are dropped. | |
sort | best_match, newest, price_asc or price_desc | best_match | Facebook ranking, newest listed first, or asking price low to high or high to low. Sorted searches return up to 24 rows; best match often returns about 15. |
condition | One or more of new, used_like_new, used_good, used_fair, comma-separated | One condition, or several separated by commas, such as used_like_new,used_good. | |
delivery | local_pickup or shipping | Only listings offering local pickup, or only listings that ship. | |
days_since_listed | 1, 7 or 30 | Only listings posted in the last 1, 7 or 30 days. |
curl -G https://api.soldgraph.com/v1/facebook/listings \ -H "Authorization: Bearer $SOLDGRAPH_KEY" \ --data-urlencode "q=mountain bike" \ -d zip=28202 \ -d radius=25 \ -d max_price=800A cache miss returns 202 with a job to poll. A completed search costs one request, including a cached result. Failed searches are free. Results are cached for 15 minutes. See search jobs.
#Location and radius
Facebook Marketplace searches around a city, not an arbitrary point. We search from the Facebook city closest to your zip or point, and show it as result.location.source_city, with its distance from your point.
zipuses the US Census center point of that ZIP code. A ZIP code with no Census area returns422. Uselatandloninstead.- Places more than 75 miles from any Facebook Marketplace city return
422. This is under 1% of US ZIP codes, mostly in remote areas. radiusis 1 to 100 miles. Without it, Facebook uses its own default of about 40 miles.- When the city is a few miles from your point, we widen the radius sent to Facebook so it still covers your whole circle.
result.location.source_radius_kmis the radius Facebook applied. - Listing rows carry only their city.
approx_distance_milesis the distance to that city, not to the item. Rows whose city is farther than your radius plus 10 miles are dropped. Use the item endpoint for a listing's approximate coordinates.
#Filters
sorttakesbest_match,newest,price_ascorprice_desc. In our tests, sorted searches returned up to 24 rows and best match about 15.conditiontakes one or more ofnew,used_like_new,used_goodandused_fair, separated by commas.deliverytakeslocal_pickuporshipping.days_since_listedtakes1,7or30.min_priceandmax_priceare whole US dollars. Either can be sent alone.- Facebook reports the filters it applied on every page. If it didn't apply one you sent, the search fails with
filter_not_appliedand costs nothing. We never return unfiltered results as if they were filtered. - If no Facebook city page near your location is working, the search fails with
location_not_servedand costs nothing. Try a nearby ZIP code.
#One page per search
Facebook serves one page of results to logged-out visitors, so next_page is always null and there is no cursor. To reach more listings, run several narrower searches. Different sort orders, price bands such as 0-50, 50-150 and 150+, and days_since_listed=1 each return a different slice. Remove repeats by id.
Image links are signed by Facebook and expire after some days. Save the image itself if you need it later.
#Price summary
summary is plain maths over the rows on the page: how many show a price, the median asking price, the lowest and the highest.
- A free item is priced
0, solowcan be0. - Listings marked
pendingare counted like any other row. - Nothing is removed from
data. The summary counts rows; it never filters them. - It covers the one page Facebook serves. Run narrower searches to cover more listings.
#Example response
{ "request_id": "example-facebook-listings", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "facebook", "country": "us", "query": "mountain bike", "page": 1, "page_size": 14, "count": 14, "reported_total": null, "next_page": null, "next_cursor": null, "collected_at": "2026-10-01T20:47:19.890286+00:00", "schema_version": 1, "completeness": "provider_page_only", "location": { "zip": "28202", "latitude": 35.2273, "longitude": -80.8442, "radius_miles": 25, "source_city": { "id": "105715936129053", "name": "Charlotte", "state": "NC", "latitude": 35.2269, "longitude": -80.8433, "distance_miles": 0.1 }, "source_radius_km": 41 }, "summary": { "priced_count": 2, "currency": "USD", "median": 47.5, "low": 25, "high": 70, "p25": 25, "p75": 70 }, "data": [ { "id": "2796090964120499", "title": "Mountain bike", "link": "https://www.facebook.com/marketplace/item/2796090964120499/", "pending": false, "displayed_price": { "amount": 25, "currency": "USD" }, "displayed_price_text": "$25.00", "original_price": null, "condition": null, "city": "Belmont", "state": "NC", "city_id": "106100896087214", "approx_distance_miles": 11.3, "listed_at": "2026-09-27T12:26:17+00:00", "delivery": { "local_pickup": true, "shipping": false }, "category_id": "1658310421102081", "image": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.84726-6/825268359_3678580222299961_2039901778140218879_n.jpg?stp=c0.87.526.526a_dst-jpg_p526x395_tt6&_nc_cat=110&ccb=1-7&_nc_sid=92e707&_nc_ohc=joVdZ7b0uZ4Q7kNvwEyWUUA&_nc_oc=AdqPTGtXbSvNGMNgFG96X88jHAsPYDrRArzo8hogkbQatErRWDmcGqzbxtKmRAwDNa0&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=kRjS6reyBV6qgDtQ1jeR3Q&_nc_ss=7b289&oh=00_AQPON8uJttwDPhZ58RwJJmfkQMz0PbiJ6mUde-RsizTBCg&oe=6AC487BD" }, { "id": "2104457877105943", "title": "Mountain Bike For SALE!!🔥📲🌟✅", "link": "https://www.facebook.com/marketplace/item/2104457877105943/", "pending": false, "displayed_price": { "amount": 70, "currency": "USD" }, "displayed_price_text": "$70.00", "original_price": null, "condition": null, "city": "Charlotte", "state": "NC", "city_id": "105715936129053", "approx_distance_miles": 0.1, "listed_at": "2026-09-30T01:10:57+00:00", "delivery": { "local_pickup": true, "shipping": false }, "category_id": "1658310421102081", "image": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.84726-6/825266442_1141005175266806_3972953768091373864_n.jpg?stp=c29.0.540.540a_dst-jpg_p180x540_tt6&_nc_cat=109&ccb=1-7&_nc_sid=92e707&_nc_ohc=wgRLiMrF__YQ7kNvwHsnEnm&_nc_oc=AdqGggELeIUc_xd13ChmfJiWbh9pg5zNnZ1EPZTqXdvCUb_Nu5HjrfVGlyf6yC948RY&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=kRjS6reyBV6qgDtQ1jeR3Q&_nc_ss=7b289&oh=00_AQO_F7vt91i1R7-kxeIjnCjkSUrNDCS2uQW0Cy4O9tM_Ow&oe=6AC49ED3" } ], "field_notes": "Active local listings around the requested point, from the nearest Facebook Marketplace city. Prices are seller asks, not sale prices. city and state are the seller-chosen area; approx_distance_miles is measured to that city, not to the item. One source page, not complete coverage: narrow with sort, price or days_since_listed to reach more listings. Image links are signed by Facebook and expire. No sold search or final sale prices are provided." }}| Field | Type | Description |
|---|---|---|
request_id | string | ID of this request. Poll it at /v1/jobs/{request_id}. |
status | string | pending, complete or failed. Always check it, even on HTTP 200. |
credits | integer | Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed. |
cached | boolean | True when the result came from the 15-minute cache. |
poll_url | string | Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL. |
error.code | string | Only when failed. See failed job codes. |
error.message | string | Only when failed. What the code means, in plain words. |
result | object | Only when complete. One source page from the marketplace. |
result.provider | string | Marketplace ID, like ebay or poshmark. |
result.country | string | The country searched: us, or on eBay the country you sent. |
result.query | string | The q you sent, with extra spaces removed. |
result.page | integer | The page you asked for. |
result.count | integer | Rows in result.data on this page. |
result.reported_total | integer | Total matches the marketplace reports for the search. It may be rounded or capped. |
result.next_page | integer | null | Send this as page to get the next page. Null on the last page, and on page 100, the deepest page served. |
result.collected_at | string | When we collected the page, as an ISO 8601 timestamp. |
result.schema_version | integer | Version of the result's shape for that marketplace: 1 or 2. It only rises when a field changes meaning. |
result.completeness | string | provider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only. |
result.field_notes | string | Plain-text notes on how to read this page's fields. |
result.location | object | The search center as zip, latitude and longitude, your radius_miles, the Facebook city searched as source_city (id, name, state, latitude, longitude, distance_miles from your point), and source_radius_km, the radius sent to Facebook, widened to cover your circle from that city. |
result.page_size | integer | Listing rows on the source page. |
result.summary | object | Price maths over the rows on this page: priced_count, currency, median, low, high. No row is removed from data. Rows with no single readable price are left out of the maths. |
result.count | integer | Rows returned: the page minus sold or hidden listings and listings outside your radius. |
result.next_page | null | Always null. Facebook serves one page to logged-out visitors; narrow with sort, prices or days_since_listed to reach more listings. |
result.reported_total | null | Always null: Facebook does not report a total. |
result.data[].id | string | Facebook Marketplace item ID. Pass it to /v1/facebook/item for full details. |
result.data[].title | string | Seller title, up to 2,000 characters. |
result.data[].link | string | Public Facebook Marketplace listing URL. |
result.data[].pending | boolean | True when the seller marked a sale in progress. Sold listings are left out. |
result.data[].displayed_price | object | USD asking price as { amount, currency }. 0 means free. Never a sale price. |
result.data[].displayed_price_text | string | Formatted USD asking price. |
result.data[].original_price | object | null | Earlier asking price shown struck through when the seller lowered it, else null. |
result.data[].condition | null | Always null: Facebook search pages don't show condition. Use /v1/facebook/item, or filter with condition. |
result.data[].city | string | null | Seller-chosen city. |
result.data[].state | string | null | Two-letter state code. |
result.data[].city_id | string | null | Facebook city page ID for that city. |
result.data[].approx_distance_miles | number | null | Miles from your search point to the listing's city, not to the item. Null when the city is not in our place table. |
result.data[].listed_at | string | null | When the listing was posted, in UTC. |
result.data[].delivery | object | local_pickup and shipping booleans from the listing's delivery options. |
result.data[].category_id | string | null | Facebook Marketplace category ID. |
result.data[].image | string | null | Primary photo on Facebook's CDN. The link is signed and expires after some days. |
Overviews: eBay sold listings API · findCompletedItems alternative · Poshmark sold listings API · Mercari sold listings API · Pokémon card price API · Sold comps API for reseller apps