# Facebook Marketplace API — search the public local classifieds of a US metro by keyword or category and read a full listing: price, condition, description, every photo, the city it sits in, when it was posted and whether it is still available. Marketplace is city-scoped and so is this API: 47 metros by name, or any Facebook city id.

> Search one metro's Marketplace listings by keyword: listing id, title, price (with the seller's earlier price when it was lowered), the city and state the item sits in, when it was posted, whether it is sold or pending, its photo and how it changes hands. Filter by price range, how recently it was posted, condition, delivery method and pending status; order by best match, newest, price or distance. The response always names the location Facebook actually resolved.
> ReefAPI engine `facebook-marketplace` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/facebook-marketplace/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /facebook-marketplace/v1/search — 3 credits
Search one metro's Marketplace listings by keyword: listing id, title, price (with the seller's earlier price when it was lowered), the city and state the item sits in, when it was posted, whether it is sold or pending, its photo and how it changes hands. Filter by price range, how recently it was posted, condition, delivery method and pending status; order by best match, newest, price or distance. The response always names the location Facebook actually resolved.

**Parameters:**
- `query` (string, required) — What to search for, as a shopper would type it.
- `location` (string, optional, default "nyc") — Which metro to search. Facebook Marketplace is city-scoped and the inventory really is different per city: six cities were compared against New York on the same query and none shared a single listing id. 47 US metros are supported by name; any other Facebook city can be reached by passing the numeric city id that every response returns as location.id. The response always names the location that was actually searched. [one of: albuquerque, anchorage, atlanta, austin, baltimore, boise, boston, buffalo, charlotte, chicago, cincinnati, cleveland, columbus, dallas, denver, detroit, honolulu, houston, indianapolis, jacksonville, kansascity, la, louisville, memphis, miami, milwaukee, minneapolis, nashville, neworleans, nyc, omaha, orlando, philly, phoenix, pittsburgh, portland, raleigh, richmond, saltlakecity, sanantonio, sandiego, sanfrancisco, seattle, stlouis, tampa, tucson, vegas]
- `price_min` (integer, optional) — Lowest price to include, in the market's currency.
- `price_max` (integer, optional) — Highest price to include, in the market's currency.
- `days_listed` (enum, optional) — Only listings posted within this many days. [one of: 1, 7, 30]
- `sort` (enum, optional, default "best_match") — Result order. [one of: best_match, newest, price_asc, price_desc, distance]
- `condition` (enum, optional) — The condition the seller graded the item. [one of: new, used_like_new, used_good, used_fair]
- `delivery` (enum, optional) — How the item changes hands. 'shipping' returns nationwide listings, not just the chosen metro. [one of: local_pickup, shipping]
- `availability` (enum, optional) — Restrict to listings the site marks as no longer freely available. Measured: these come back with status PENDING (a sale in progress), not sold. [one of: pending]
- `max_rotations` (integer, optional, default 4) — How many times to re-try this request before giving up.

**Returns:** results[]{listing_id, title, custom_title (vehicles carry the seller's own wording here), subtitles[] (the card's extra facts, e.g. a vehicle's mileage), url, price, price_formatted, price_was (the seller's earlier price when it was lowered), price_min, price_max, currency, city, state, city_id, posted_at, is_sold, is_pending, is_live, category_id, image, has_video, delivery_types[], listing_type}, count, total_results (null — the source publishes no count), source_has_more, location{name, id}, currency, filters_applied[], dropped_non_listing_tiles

**Example request body:**
```json
{
  "query": "iphone",
  "location": "nyc"
}
```

### POST /facebook-marketplace/v1/category — 3 credits
Browse one of Facebook Marketplace's 17 categories inside a metro — vehicles, property for sale, property rentals, electronics, apparel, free stuff and the rest — with the same row shape and the same filters as search.

**Parameters:**
- `category` (enum, required) — Which Marketplace category to browse. [one of: apparel, classifieds, electronics, entertainment, family, free, garden, hobbies, home, home-improvements, instruments, pets, propertyforsale, propertyrentals, sports, toys, vehicles]
- `location` (string, optional, default "nyc") — Which metro to search. Facebook Marketplace is city-scoped and the inventory really is different per city: six cities were compared against New York on the same query and none shared a single listing id. 47 US metros are supported by name; any other Facebook city can be reached by passing the numeric city id that every response returns as location.id. The response always names the location that was actually searched. [one of: albuquerque, anchorage, atlanta, austin, baltimore, boise, boston, buffalo, charlotte, chicago, cincinnati, cleveland, columbus, dallas, denver, detroit, honolulu, houston, indianapolis, jacksonville, kansascity, la, louisville, memphis, miami, milwaukee, minneapolis, nashville, neworleans, nyc, omaha, orlando, philly, phoenix, pittsburgh, portland, raleigh, richmond, saltlakecity, sanantonio, sandiego, sanfrancisco, seattle, stlouis, tampa, tucson, vegas]
- `price_min` (integer, optional) — Lowest price to include, in the market's currency.
- `price_max` (integer, optional) — Highest price to include, in the market's currency.
- `days_listed` (enum, optional) — Only listings posted within this many days. [one of: 1, 7, 30]
- `sort` (enum, optional, default "best_match") — Result order. [one of: best_match, newest, price_asc, price_desc, distance]
- `condition` (enum, optional) — The condition the seller graded the item. [one of: new, used_like_new, used_good, used_fair]
- `delivery` (enum, optional) — How the item changes hands. 'shipping' returns nationwide listings, not just the chosen metro. [one of: local_pickup, shipping]
- `availability` (enum, optional) — Restrict to listings the site marks as no longer freely available. Measured: these come back with status PENDING (a sale in progress), not sold. [one of: pending]
- `max_rotations` (integer, optional, default 4) — How many times to re-try this request before giving up.

**Returns:** results[]{listing_id, title, custom_title (vehicles carry the seller's own wording here), subtitles[] (the card's extra facts, e.g. a vehicle's mileage), url, price, price_formatted, price_was (the seller's earlier price when it was lowered), price_min, price_max, currency, city, state, city_id, posted_at, is_sold, is_pending, is_live, category_id, image, has_video, delivery_types[], listing_type}, count, total_results (null — the source publishes no count), source_has_more, location{name, id}, currency, filters_applied[], dropped_non_listing_tiles, category{slug, name, id}

**Example request body:**
```json
{
  "category": "vehicles",
  "location": "nyc"
}
```

### POST /facebook-marketplace/v1/listing — 3 credits
The full listing by id or URL: title, the seller's full description, price and currency, the condition they graded it, the category path, every photo with its dimensions, the city it sits in with the city-level coordinates the site rounds to, when it was posted, whether it is available, pending or sold, how it can be delivered, and the seller as the public listing shows them: name, profile link, profile photo, the date they joined, and their 5-star rating with its count.

**Parameters:**
- `listing_id` (string, required) — The number at the end of a Marketplace listing URL (facebook.com/marketplace/item/4511313592443983/ -> 4511313592443983). Every search row returns it as listing_id. A full URL is accepted too.
- `seller_attempts` (integer, optional, default 1) — How hard to try for the seller. Facebook includes the seller on only about one in ten of its public listing responses, at random - the same listing carries it on one read and not the next. 1 (the default) returns whatever the first response had. Raise it and the listing is read again until the seller appears, up to this many reads, which makes the call slower. Measured on 9 listings: 0 of 9 had the seller on the first read, 3 of 9 within six. The answer always reports seller_available and seller_lookups, so you can see what it cost and whether it worked.
- `max_rotations` (integer, optional, default 4) — How many times to re-try this request before giving up.

**Returns:** listing{listing_id, title, custom_title, subtitles[], url, description, price, price_formatted, price_was, currency, condition, condition_label, attributes[]{name, value, label}, category, category_slug, category_id, category_path[]{name, slug, id}, location_text, latitude, longitude (city-level, as the site rounds them), posted_at, status, is_sold, is_pending, is_live, inventory_count, photos[]{url, width, height, caption}, photo_count, has_video, delivery_types[], shipping_offered, listing_type, seller{name, profile_id, profile_url, user_token, profile_picture, joined_at, rating, rating_count, ratings_are_private, combined_rating, combined_rating_count, is_verified, type} (null when this response did not carry it — see seller_attempts), seller_type (e.g. PRIVATE_SELLER on vehicles), is_business_seller, seller_badges[], seller_badge_summary (e.g. 'Highly rated on Marketplace'), seller_shop_id, dealership_name, seller_phone, seller_website, listing_address}, seller_available, seller_lookups

## More
- Try it live, no code: https://reefapi.com/playground?engine=facebook-marketplace
- Human docs page: https://reefapi.com/docs/facebook-marketplace
- Overview page: https://reefapi.com/facebook-marketplace-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt