Facebook Marketplace, one metro at a time - as JSON
The Facebook Marketplace API returns Marketplace's public local classifieds as clean JSON, one metro at a time.
3 active endpoints. Every call is 3 credits.
- POST/facebook-marketplace/v1/search
- POST/facebook-marketplace/v1/category
- POST/facebook-marketplace/v1/listing
What Facebook Marketplace endpoints does ReefAPI ship?
3 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Facebook Marketplace API
3 of 3 endpoints, ready to run
Listings in one metro for a keyword: id, title, price as a number next to the price the site prints, the earlier price when it was lowered, city and state, posting date, sold and pending flags, photo and delivery methods.
// Press "Try it" and this pane shows exactly what the // live site returned this second — including an empty // result, if that is the truth. No key, no account.
How the Facebook Marketplace API works
Facebook Marketplace is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 280 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Compare what the same thing costs in five metros, without accidentally reading the wrong city
Marketplace inventory is local, so a price series only means something if each call really searched the metro you meant. The API reports the location it resolved on every response, so you can key your series on location.id instead of on the name you sent.
{"query": "iphone 15", "location": "nyc", "sort": "newest", "condition": "used_like_new"}Like-new iPhone 15 listings in New York, newest first. Key the results on location.id, and use price with price_was to see who lowered their asking price. Repeat with la, chicago, houston and philly - the same query in those five returned no listing ids in common with New York.
{"listing_id": <listing_id from above>}The seller's full description, the condition they graded it, every photo and the current status. A listing that has gone PENDING or sold is no longer an offer, so drop it from the series rather than carrying the last price forward.
A like-for-like local asking-price series per metro with condition and availability attached - three credits per call.
curl -X POST https://api.reefapi.com/facebook-marketplace/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"iphone","location":"nyc"}'{
"ok": true,
"data": { … },
"meta": {
"api": "facebook-marketplace",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}What an unknown city gives you - and why this API refuses it
Facebook does not reject a place it does not recognise. It quietly answers with a different metro's listings, and nothing in the page says so. The spelling philadelphia is a real example: it is not the Marketplace slug, and it resolves somewhere else - differently on different days. This API verifies the location Facebook resolved against the one you asked for, and returns nothing rather than another city's inventory. Every response names the location that was actually searched.
| Location asked for (measured 2026-09-23) | What Facebook answered with | What this API does |
|---|---|---|
| philly | Philadelphia, Pennsylvania | Returns Philadelphia listings - this is the working slug |
| philadelphia | Chicago, Illinois on one run, Greenwood, Mississippi on another | Rejected as an unknown location, with philly suggested |
| sacramento | Wesley Chapel, Florida | Rejected as an unknown location |
| a misspelt or invented city | A full page of real listings from whichever metro it landed on | Rejected as an unknown location |
| nyc, la, chicago, houston, vegas and 42 more | The metro itself, confirmed by its own city id | Returns the listings, and reports location.name and location.id |
The same iphone search in la, chicago, houston, philly and vegas returned zero listing ids in common with New York, and the cities on the rows were local to each metro. 47 metros were each verified against the city id Facebook itself reports; any other Facebook city can be passed as that numeric id and is checked the same way.
47 metros, 17 categories, and the four things this API will not pretend to know
Measured on 2026-09-23 with 42 live calls across the three actions, 8 listings checked against their own pages, 13 filter arms each compared with an unfiltered control in the same run, 6 categories counted field by field and 9 listings checked for the seller. Four of these lines go against us.
nyc, la, chicago, houston, philly, vegas, sanfrancisco, seattle, miami, boston, denver, atlanta, dallas, phoenix, sandiego, austin, portland, detroit, minneapolis, sanantonio, baltimore, charlotte, nashville, orlando, tampa, pittsburgh, stlouis, kansascity, columbus, indianapolis, milwaukee, neworleans, saltlakecity, cleveland, cincinnati, raleigh, richmond, buffalo, memphis, louisville, jacksonville, albuquerque, tucson, omaha, boise, honolulu and anchorage. Any other Facebook city works by its numeric id.
Facebook answers an unrecognised place with a real page of listings from somewhere else and does not say so - philadelphia resolved to Chicago on one run and Greenwood, Mississippi on another. This API checks the resolved location against the one you asked for and errors instead. The same query in five metros shared zero listing ids with New York.
On 8 listings taken from search and category results, the id, the price, the title and the sold flag matched the listing's own page 8 of 8. Every parsed string is checked for stray markup: 0 were found across every row and listing in the run.
A 500-2000 price range returned 13 of 13 listings inside it where the unfiltered page had 6 of 15; a 100 maximum returned 13 of 13 against 1 of 15; a one-day recency filter returned 15 of 15 posted within two days against 3 of 15; price ordering came back strictly monotonic; and the shipped filter spread results across 22 cities against 10.
Across vehicles, electronics, home sales, apparel, home goods and free stuff, 24 rows each, title, price, city, posting date and photo were present on 24 of 24 every time.
Marketplace does not publish a distance for a listing and its public pages offer no radius control - radius was tested in five different forms and changed nothing beyond the page's own variation. Listings carry their own city and state, and the full listing adds city-level coordinates, but there is no 'within 10 miles' filter to give you.
A search returns 8 to 25 listings and a category page 24; Marketplace's public pages offer no next page to follow, so one page is returned per call. Facebook publishes no result count either, so total_results is null rather than an invented number - source_has_more reports whether Facebook indicates more exist.
Name, Marketplace profile link, profile photo, join date, 5-star rating and rating count, plus the combined buyer-and-seller score. Every one of those was filled on every listing that carried the block.
Facebook publishes a seller who keeps their rating private as 0 stars from 0 ratings rather than leaving the field out, so reading it literally turns a private seller into a zero-star seller. Here a zero over zero ratings comes back as rating null with ratings_are_private true, and the combined buyer-and-seller score is returned separately when it is public. On one measured seller that combined score was a real 4.9 from 18 ratings while their seller-only score was hidden - so a 0 would have been wrong by the whole scale.
Facebook ships the seller block on roughly 9% of public listing responses, at random - the same listing carries it on one read and not the next, and nothing in the page predicts which. 0 of 9 listings had it on a single read and 3 of 9 within six reads using seller_attempts. seller_available and seller_lookups tell you which you got. Feed rows never carry a seller at all (0 of 15), so it is a listing-level field only.
price_was only exists when the seller lowered the price (1 to 7 of 24 rows per category); the extra card facts such as a vehicle's mileage are published for vehicles and property only (22 of 24 and 24 of 24) and not at all for electronics, apparel or home goods; and a seller's phone, website, dealership name and street address were empty on all 30 listings checked. Seller badges are the reliable signal, present on 7 of 9.
What people build with Facebook Marketplace
The jobs this data is most often used for.
endpoints
credits per call
Resale and reseller tools track local second-hand prices for phones, consoles, furniture and bikes across several metros at once, using the same keyword per city and the price the listing actually publishes.
Used-car and property teams browse the vehicles, home sales and property rentals categories in one metro and read each listing's description, photos and posting date.
Deal-hunting and arbitrage products watch newly posted listings with sort newest and a one-day recency filter, then re-check each id later to see whether it went pending or sold.
Local-market researchers measure how supply and asking prices differ between metros, using the resolved location every response reports rather than assuming the city they asked for.
What Facebook Marketplace data costs
The cheapest call here is 3 credits, so $15/mo (Pro) buys 3,333 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 280 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/facebook-marketplace/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"iphone","location":"nyc"}'import requests
r = requests.post(
"https://api.reefapi.com/facebook-marketplace/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "iphone",
"location": "nyc"
},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up Facebook Marketplace.
Get a free key →Which locations does the API cover?▾
47 US metros by name - nyc, la, chicago, houston, philly, vegas, sanfrancisco, seattle, miami, boston, denver, atlanta, dallas, phoenix, sandiego, austin, portland, detroit, minneapolis, sanantonio and 27 more - plus any other Facebook Marketplace city by its numeric id, which every response returns as location.id. Each of the 47 was checked against the city id Facebook reports for it.
Why does an unknown city return an error instead of results?▾
Because the alternative is worse. Facebook answers a city it does not recognise with a full page of real listings from somewhere else, and says nothing about the substitution. Measured on 2026-09-23, philadelphia resolved to Chicago on one run and to Greenwood, Mississippi on another. This API checks the location Facebook resolved against the one you asked for and returns an error rather than another metro's inventory.
How many listings come back per call?▾
Between 8 and 25 for a keyword search and 24 for a category page, depending on the metro and the query; asking for a non-default order such as newest tends to return the fuller page. One page is returned per call - Marketplace's public pages do not offer a next page to follow, and the response says with source_has_more whether Facebook indicates more exist.
Can I filter by distance or radius?▾
No, and the honest reason is that Marketplace does not offer it on its public pages. Radius was tested in five different forms and none of them changed the results beyond the page's own run-to-run variation, because the radius is a per-viewer setting rather than part of the address. The location is the geographic control, and it works: five metros returned zero listing ids in common with New York. Listings do carry their own city and state, and the full listing adds city-level coordinates.
Which filters actually work?▾
Price range, how recently a listing was posted (1, 7 or 30 days), condition (new, like new, good, fair), delivery method (local pickup or shipped), pending status, and ordering by best match, newest, price or distance. Each was checked on the values returned: a 500-2000 range gave 13 of 13 listings inside it against 6 of 15 unfiltered, a one-day filter gave 15 of 15 posted within two days against 3 of 15, and price ordering came back strictly monotonic.
Does it tell me whether a listing is still available?▾
Yes. Every row carries is_sold, is_pending and is_live, and the full listing adds the status Facebook shows, such as AVAILABLE or PENDING. Note that Facebook's own pending filter means a sale is in progress, not that the item is sold - the two are returned as separate fields so you do not have to infer one from the other.
Does it return the seller?▾
Yes, whatever the public listing shows: their name, a link to their Marketplace profile, their profile photo, the date they joined and their 5-star rating with the number of ratings behind it. The catch is how often Facebook includes it - measured on 2026-09-23, only about one public listing response in ten carries the seller, at random, and the same listing can carry it on one read and not the next. seller_attempts asks the API to read the listing again until it appears (0 of 9 listings had it on the first read, 3 of 9 within six), and every answer reports seller_available and how many reads it used, so you are never guessing.
Why is a seller's rating sometimes null instead of a number?▾
Because a seller can keep their score private, and Facebook publishes a hidden score as 0 out of 0 ratings rather than leaving it out. Passing that through would label a seller who simply hides their rating as a zero-star seller, so a zero over zero ratings comes back as null with ratings_are_private true. Where the same person's combined buyer-and-seller score is still public it is returned as combined_rating - on one measured seller that was a genuine 4.9 from 18 ratings while their seller-only score was hidden.
What about a seller's phone number or address?▾
Not published on this surface. dealership_name, seller_phone, seller_website and listing_address are dealer fields that exist on the listing and were empty on all 30 listings checked, including 5 vehicles, so they come back null rather than being hidden from you. Badges are more useful and far more common: seller_badge_summary, such as 'Very Responsive on Marketplace' or 'Highly rated on Marketplace', was present on 7 of 9 listings.
How many results are there in total?▾
Facebook does not publish a result count anywhere on these pages, so total_results is null rather than a number we invented. count tells you how many rows this call returned, and source_has_more reports whether Facebook indicates there are more beyond them.
What is the Facebook Marketplace API?▾
Facebook Marketplace API is a ReefAPI endpoint group for local classifieds in 47 us metros: prices, condition, photos, the seller and whether it is still available. It returns live JSON through POST requests under /facebook-marketplace/v1.
Is the Facebook Marketplace API free to try?▾
Yes. ReefAPI starts with 1,000 free credits, no card required. Facebook Marketplace calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Facebook Marketplace login or account?▾
No login to Facebook Marketplace is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Facebook Marketplace data?▾
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
116 E-commerce & Marketplaces APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Facebook Marketplace, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 279 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-09-23.