# Wallapop API — second-hand listings from Wallapop Spain, Italy and Portugal: search by keyword, place and radius, full listings with reserved/sold status, shipping prices and seller rating, cars search, seller listings, categories and suggestions. No account, no browser.

> Search Wallapop listings in Spain, Italy or Portugal by keyword or category around a point: listing id, title, description, price in EUR (null when the site shows 0), previous price and discount, category path, city and postal code, distance from the search point, created and modified time, reserved flag, whether the seller ships, refurbished/warranty flags, car and real-estate facts, photos. Filter by radius, price, condition, shipping, category, refurbished and warranty; sort by relevance, newest, closest or price. Paid bumped rows are dropped and counted unless include_sponsored.
> ReefAPI engine `wallapop` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/wallapop/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 /wallapop/v1/search — 1 credit
Search Wallapop listings in Spain, Italy or Portugal by keyword or category around a point: listing id, title, description, price in EUR (null when the site shows 0), previous price and discount, category path, city and postal code, distance from the search point, created and modified time, reserved flag, whether the seller ships, refurbished/warranty flags, car and real-estate facts, photos. Filter by radius, price, condition, shipping, category, refurbished and warranty; sort by relevance, newest, closest or price. Paid bumped rows are dropped and counted unless include_sponsored.

**Parameters:**
- `query` (string, optional) — Keyword. Optional when `category` is given.
- `country` (enum, optional, default "es") — Which Wallapop country: es (Spain), it (Italy) or pt (Portugal). Sets the language of labels and the default search point (Madrid, Rome, Lisbon). Prices are in EUR everywhere. [one of: es, it, pt]
- `latitude` (number, optional) — Search point latitude (with longitude). Wallapop ranks and filters by distance from this point; default is the country's capital.
- `longitude` (number, optional) — Search point longitude (with latitude).
- `distance_km` (integer, optional) — Only listings within this many km of the search point (1-500).
- `category` (integer, optional) — Top-level category id from `categories` (e.g. 17000 bicycles, 24200 electronics, 12465 fashion).
- `subcategory` (integer, optional) — A deeper category id from `categories` (children of `category`); needs `category`.
- `price_min` (number, optional) — Lowest price, EUR.
- `price_max` (number, optional) — Highest price, EUR.
- `condition` (enum, optional) — Item condition. un_opened / in_box exist for electronics, un_worn for fashion. [one of: new, as_good_as_new, good, fair, has_given_it_all, un_opened, in_box, un_worn]
- `shipping_only` (boolean, optional) — Only listings whose seller offers shipping.
- `refurbished_only` (boolean, optional) — Only refurbished listings (professional refurbishers).
- `warranty_only` (boolean, optional) — Only listings with at least one year of warranty.
- `sort` (enum, optional) — Order of results. [one of: relevance, newest, closest, price_asc, price_desc]
- `cursor` (string, optional) — `next_cursor` from the previous page. When given, the other search parameters are taken from the cursor and ignored.
- `include_sponsored` (boolean, optional, default false) — Also return the paid bumped ('destacado') rows the site mixes into relevance results, flagged sponsored:true. Off by default.
- `country_only` (boolean, optional, default false) — Drop listings located in another Wallapop country. The site's search is cross-border: from Italy or Portugal, newest and price orders are mostly Spanish listings. Off by default (the site shows them, flagged cross_border); dropped rows are counted in other_country_dropped.
- `include_fallback_results` (boolean, optional, default false) — When no listing mentions the query (the site sometimes answers nonsense with unrelated rows), the page comes back empty with fallback_results_dropped; true also returns those rows in fallback_results.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{listing_id, title, description, url, slug, price (null when 0), currency, price_is_zero, was_price, discount_percent, category_id, category_path[]{id, name}, location{city, postal_code, region, country_code, lat, lon (include_pii only)}, distance_km (from the search point), cross_border (listed in another Wallapop country), text_is_translated (title/description are the site's translation; listing has the original), created_at, modified_at, reserved, shipping_available (seller ships), shipping_eligible_category, is_refurbished, has_warranty, seller_id, seller_is_top_profile, sponsored (injected paid slot), is_bumped, bump_type, vehicle{brand, model, year, version, km, engine, horsepower}, real_estate{operation, type, surface, rooms, bathrooms}, attributes, image, images[], image_count}, count (organic rows), sponsored_dropped, sponsored_count, other_country_count, other_country_dropped, fallback_results_dropped, fallback_results[] (include_fallback_results only), total_results (null: not published), has_more, next_cursor, sort_applied, filters_applied_count, location_country, country, currency, query

**Example request body:**
```json
{
  "query": "bici",
  "country": "es"
}
```

### POST /wallapop/v1/cars/search — 1 credit
Search used cars on Wallapop (Spain, Italy, Portugal) around a point: the listing rows of search plus vehicle{brand, model, year, version, km, engine, horsepower}. Filter by brand, model, year, mileage, fuel, gearbox, body type, private or professional seller, price and radius.

**Parameters:**
- `query` (string, optional) — Keyword. Optional when `category` is given.
- `country` (enum, optional, default "es") — Which Wallapop country: es (Spain), it (Italy) or pt (Portugal). Sets the language of labels and the default search point (Madrid, Rome, Lisbon). Prices are in EUR everywhere. [one of: es, it, pt]
- `latitude` (number, optional) — Search point latitude (with longitude). Wallapop ranks and filters by distance from this point; default is the country's capital.
- `longitude` (number, optional) — Search point longitude (with latitude).
- `distance_km` (integer, optional) — Only listings within this many km of the search point (1-500).
- `brand` (string, optional) — Car brand as Wallapop lists it (case-insensitive), e.g. Seat, BMW.
- `model` (string, optional) — Model of that brand (needs brand).
- `year_min` (integer, optional) — Oldest registration year.
- `year_max` (integer, optional) — Newest registration year.
- `km_min` (integer, optional) — Lowest mileage.
- `km_max` (integer, optional) — Highest mileage.
- `engine` (enum, optional) — Fuel / drive. [one of: gasoline, diesel, electric, hybrid, plug_in_hybrid, lpg, cng, other]
- `gearbox` (enum, optional) — Gearbox. [one of: manual, automatic, semiautomatic]
- `body_type` (enum, optional) — Body type. [one of: small, coupe, sedan, estate, minivan, suv, van, convertible, pickup, other]
- `seller_type` (enum, optional) — Private sellers or professionals. [one of: private, professional]
- `price_min` (number, optional) — Lowest price, EUR.
- `price_max` (number, optional) — Highest price, EUR.
- `warranty_only` (boolean, optional) — Only listings with at least one year of warranty.
- `sort` (enum, optional) — Order of results. [one of: relevance, newest, closest, price_asc, price_desc]
- `cursor` (string, optional) — `next_cursor` from the previous page. When given, the other search parameters are taken from the cursor and ignored.
- `include_sponsored` (boolean, optional, default false) — Also return the paid bumped ('destacado') rows the site mixes into relevance results, flagged sponsored:true. Off by default.
- `country_only` (boolean, optional, default false) — Drop listings located in another Wallapop country. The site's search is cross-border: from Italy or Portugal, newest and price orders are mostly Spanish listings. Off by default (the site shows them, flagged cross_border); dropped rows are counted in other_country_dropped.
- `include_fallback_results` (boolean, optional, default false) — When no listing mentions the query (the site sometimes answers nonsense with unrelated rows), the page comes back empty with fallback_results_dropped; true also returns those rows in fallback_results.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{listing_id, title, description, url, slug, price (null when 0), currency, price_is_zero, was_price, discount_percent, category_id, category_path[]{id, name}, location{city, postal_code, region, country_code, lat, lon (include_pii only)}, distance_km (from the search point), cross_border (listed in another Wallapop country), text_is_translated (title/description are the site's translation; listing has the original), created_at, modified_at, reserved, shipping_available (seller ships), shipping_eligible_category, is_refurbished, has_warranty, seller_id, seller_is_top_profile, sponsored (injected paid slot), is_bumped, bump_type, vehicle{brand, model, year, version, km, engine, horsepower}, real_estate{operation, type, surface, rooms, bathrooms}, attributes, image, images[], image_count}, count (organic rows), sponsored_dropped, sponsored_count, other_country_count, other_country_dropped, fallback_results_dropped, fallback_results[] (include_fallback_results only), total_results (null: not published), has_more, next_cursor, sort_applied, filters_applied_count, location_country, country, currency, query

### POST /wallapop/v1/listing — 1 credit
The full Wallapop listing by id, slug or URL: title and description as written, status (active, reserved, sold, expired), price, previous price and discount, condition, brand and model, category path, attributes, car or property facts, every photo, city and postal code, last modified, views, favourites and chats, bump flag, shipping availability with each delivery option's price and delivery days, and the seller: type (private, pro, shop), rating on a 5-point scale, review count, sold count, member since, verified; name and business address for PRO and shop sellers.

**Parameters:**
- `listing_id` (string, required) — The listing id from a search row (e.g. pzpk03moy9j3), the slug (bicicletas-btwin-paseo-1302091802) or the full listing URL.
- `country` (enum, optional, default "es") — Which Wallapop country: es (Spain), it (Italy) or pt (Portugal). Sets the language of labels and the default search point (Madrid, Rome, Lisbon). Prices are in EUR everywhere. [one of: es, it, pt]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** listing{listing_id, slug, title, description, url, status (active|reserved|on_hold|sold|expired), reserved, sold, expired, price (null when 0), currency, price_is_zero, was_price, discount_percent, condition{code, label}, brand, model, size, color, isbn, category_path[]{id, name}, item_type, attributes[]{id, label, value, code}, vehicle{km, year, version, gear_box, engine, horse_power, body_type, doors, seats, …}, real_estate{…}, images[]{url, medium_url, small_url}, image_count, location{city, postal_code, country_code, approximate, lat, lon (PRO/shop or include_pii)}, modified_at, views, favorites, conversations, is_bumped, bump_type, is_refurbished, stock, shipping{shipping_available, shipping_eligible_category, cheapest_shipping_price, delivery_options[]{carrier, method, price, currency, discounted_price}, delivery_days_min, delivery_days_max, is_bulky}, seller{id, type (private|pro|shop), name, profile_url, avatar_url (PRO/shop or include_pii), rating, rating_scale, review_count, sold_count, sales_count, purchases_count, published_count, member_since, verified, is_top_profile, vacation_mode, city, postal_code, shipping_on_time_days, official_store_url, business{description, address, opening_hours, website, lat, lon, has_phone, phone (include_pii)}}, country, detail_source}

### POST /wallapop/v1/seller_listings — 1 credit
One Wallapop seller's profile and current listings: rating on a 5-point scale with the star breakdown, review, sold, sales and purchase counts, member since, city — and 40 listings per page with id, title, price, previous price, reserved flag, shipping, condition and photos.

**Parameters:**
- `seller_id` (string, required) — The seller id from a search row (seller_id) or a listing (seller.id).
- `country` (enum, optional, default "es") — Which Wallapop country: es (Spain), it (Italy) or pt (Portugal). Sets the language of labels and the default search point (Madrid, Rome, Lisbon). Prices are in EUR everywhere. [one of: es, it, pt]
- `cursor` (string, optional) — `next_cursor` from the previous page of this seller.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** seller{id, type (private|professional), name, profile_url, avatar_url (professional or include_pii), rating, rating_scale, review_count, review_breakdown_percent{1..5}, sold_count, sales_count, purchases_count, published_count, member_since, is_top_profile, city, postal_code, country_code}, results[]{listing_id, title, description, url, slug, price, currency, price_is_zero, was_price, discount_percent, category_id, reserved, shipping_available, is_refurbished, has_warranty, is_bumped, bump_type, vehicle, real_estate, attributes, image, images[], image_count}, count, has_more, next_cursor

### POST /wallapop/v1/categories — 1 credit
Wallapop's category tree for one country in its language: up to four levels, every node with the id to pass as `category` (top level) or `subcategory` to search.

**Parameters:**
- `country` (enum, optional, default "es") — Which Wallapop country: es (Spain), it (Italy) or pt (Portugal). Sets the language of labels and the default search point (Madrid, Rome, Lisbon). Prices are in EUR everywhere. [one of: es, it, pt]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** categories[]{id, name, level, search_param (category|subcategory), vertical (top level: cars|real_estate|consumer_goods), children[]}, count (top level), node_count, country

### POST /wallapop/v1/suggest — 1 credit
Wallapop search autocomplete in the country's language: completed keywords for a partial term.

**Parameters:**
- `query` (string, required) — The partial keyword.
- `country` (enum, optional, default "es") — Which Wallapop country: es (Spain), it (Italy) or pt (Portugal). Sets the language of labels and the default search point (Madrid, Rome, Lisbon). Prices are in EUR everywhere. [one of: es, it, pt]
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** suggestions[]{keyword, subtitle, kind}, count, query, country

**Example request body:**
```json
{
  "query": "bici"
}
```

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