> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Listings

> Search Wallapop second-hand listings in Spain, Italy, or Portugal with Wallapop's own filters — price, condition, brand, model, colour, distance, listing age, shipping, and car filters.

Search Wallapop listings, **40 per page**, with the same filters the Wallapop app offers. Send a `query`, a `category_id`, or both.

**Credits:** 5 per page. Empty results are not charged.

## Authorization

**X-API-Key** `string` *required*

Your ScrapeBadger API key.

## Query Parameters

**query** `string`

Search text, e.g. `iphone 14`, `bicicleta montaña`. Required unless you pass `category_id`; requests with neither return `422`.

**market** `string` (default: es)

`es` (Spain), `it` (Italy), or `pt` (Portugal). Sets the default search location (Madrid, Rome, or Lisbon) and the language of category and attribute text. Any other value returns `422`. See [`/v1/wallapop/markets`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/list-markets).

**latitude** `number`

Search centre latitude, `-90` to `90`. Defaults to the market's capital. The country searched follows the coordinates, not the market.

**longitude** `number`

Search centre longitude, `-180` to `180`. Defaults to the market's capital.

**distance\_km** `integer`

Radius around the search centre in kilometres, `1` to `500`. Omit to search without a radius limit.

**category\_id** `integer`

Category id from [`/v1/wallapop/categories`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/list-categories), e.g. `24200` (Technology & electronics) or `100` (Cars). Required unless you pass `query`.

**min\_price** `number`

Minimum price in EUR, `0` or more.

**max\_price** `number`

Maximum price in EUR, `0` or more.

**condition** `string`

Comma-separated conditions: `un_opened`, `in_box`, `new`, `as_good_as_new`, `good`, `fair`, `has_given_it_all`. Example: `new,as_good_as_new`.

**brand** `string`

Brand option id, e.g. `Apple`. Get valid ids from [`/v1/wallapop/filters/brand/options`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/list-filter-options) for your category or query.

**model** `string`

Model option id, e.g. `iPhone 14`. Get valid ids from [`/v1/wallapop/filters/model/options`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/list-filter-options).

**color** `string`

Colour option id, e.g. `black`. Valid ids are listed under the `color` filter in [`/v1/wallapop/filters`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/list-filters).

**time\_filter** `string`

Only listings published within: `today`, `lastWeek`, or `lastMonth`.

**shippable** `boolean` (default: false)

`true` returns only listings that can be shipped.

**has\_warranty** `boolean` (default: false)

`true` returns only listings with a warranty.

**refurbished** `boolean` (default: false)

`true` returns only refurbished listings.

**order\_by** `string` (default: most\_relevance)

Sort order: `most_relevance`, `newest`, `closest`, `price_low_to_high`, or `price_high_to_low`.

**next\_page** `string`

Cursor from the previous response's `next_page`. Send it on its own (with the same `market`): the cursor carries the original query and filters, and all other search parameters are ignored.

### Car filters

These filters apply when you search cars with `category_id=100`.

**min\_year** `integer`

Earliest model year, e.g. `2015`.

**max\_year** `integer`

Latest model year.

**min\_km** `integer`

Minimum mileage in km, `0` or more.

**max\_km** `integer`

Maximum mileage in km, `0` or more.

**gearbox** `string`

`manual` or `automatic`.

**min\_horsepower** `integer`

Minimum engine power in hp, `0` or more.

**max\_horsepower** `integer`

Maximum engine power in hp, `0` or more.

> [!NOTE]
>
> For car searches, `brand` and `model` take the car make and model option ids from [`/v1/wallapop/filters/brand/options?category_id=100`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/list-filter-options) and `/v1/wallapop/filters/model/options?category_id=100`.

> [!NOTE]
>
> There is no sold-listings search: Wallapop search only returns live listings. To see what a seller has sold, read their [reviews](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/get-user-reviews.md) — reviews with `type: "sell"` name the listing they sold.

## Response

**items** `SearchItem[]`

Matching listings, up to 40 per page.

**SearchItem**

**id** `string`

Listing id, e.g. `nzxeknm5x562`. Use it with [`/v1/wallapop/items/{item_id}`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/get-item).

**user\_id** `string | null`

Seller id. Use it with [`/v1/wallapop/users/{user_id}`](https://docs.scrapebadger.com/api-reference/endpoint/wallapop/get-user).

**title** `string | null`

Listing title.

**description** `string | null`

Listing description.

**price** `number | null`

Asking price.

**currency** `string | null`

ISO 4217 currency code, `EUR`.

**category\_id** `integer | null`

Category id as Wallapop reports it in search (often the top-level category). See `taxonomy` for the full path.

**taxonomy** `TaxonomyNode[]`

Category path from top level to leaf.

**TaxonomyNode**

**id** `integer`

Category id.

**name** `string | null`

Localised category name.

**condition** `string | null`

Condition id, e.g. `good`, when the seller set one.

**brand** `string | null`

Brand (or car make), when set.

**model** `string | null`

Model, when set.

**attributes** `object`

Category-specific attributes as flat key/value pairs. Cars include `brand`, `model`, `year`, `version`, `km`, `engine`, `gearbox`, and `horsepower`.

**images** `Image[]`

Listing photos.

**Image**

**id** `string | null`

Image id.

**small** `string | null`

320 px wide URL.

**medium** `string | null`

640 px wide URL.

**large** `string | null`

800 px wide URL.

**average\_color** `string | null`

Average colour as a hex string, e.g. `13C1AC`.

**location** `Location | null`

Where the listing is.

**Location**

**latitude** `number | null`

**longitude** `number | null`

**postal\_code** `string | null`

**city** `string | null`

**region** `string | null`

Region, e.g. `Comunidad de Madrid`.

**region2** `string | null`

Province, e.g. `Madrid`.

**country\_code** `string | null`

ISO 3166-1 alpha-2 country code.

**approximated** `boolean | null`

`true` when the coordinates are approximate.

**shippable** `boolean | null`

Whether the item can be shipped.

**user\_allows\_shipping** `boolean | null`

Whether the seller accepts shipping.

**reserved** `boolean | null`

Whether the seller marked the listing as reserved.

**bumped** `boolean`

Whether the listing is currently promoted.

**bump\_type** `string | null`

Promotion type, e.g. `city`, when bumped.

**is\_top\_profile** `boolean | null`

Whether the seller is a Wallapop top profile.

**is\_refurbished** `boolean | null`

Whether the item is refurbished.

**has\_warranty** `boolean | null`

Whether the item comes with a warranty.

**slug** `string | null`

Listing slug, e.g. `iphone-14-128gb-1311318554`.

**url** `string | null`

Full listing URL on wallapop.com.

**created\_utc** `number | null`

Publication time, Unix seconds.

**created\_at** `string | null`

Publication time, ISO 8601 UTC.

**modified\_utc** `number | null`

Last modification time, Unix seconds.

**modified\_at** `string | null`

Last modification time, ISO 8601 UTC.

**result\_count** `integer`

Number of listings on this page.

**total\_results** `integer | null`

Wallapop's own estimate of how many listings match the search. `null` on the last page.

**next\_page** `string | null`

Cursor for the next page. Pass it back as `next_page`; `null` when there are no more results.

**order\_by** `string | null`

The sort order Wallapop applied.

**market** `string`

The market used for the request.

**country\_code** `string | null`

The country Wallapop searched in, which follows the search coordinates.

**search\_id** `string | null`

Wallapop's id for this search.

## Example

```bash cURL theme={null}
curl "https://scrapebadger.com/v1/wallapop/search?query=iphone&market=es&shippable=true" \
  -H "X-API-Key: YOUR_API_KEY"
```

```python Python theme={null}
import requests

res = requests.get(
    "https://scrapebadger.com/v1/wallapop/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"query": "iphone", "market": "es", "shippable": "true"},
)
data = res.json()
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://scrapebadger.com/v1/wallapop/search?" +
    new URLSearchParams({ query: "iphone", market: "es", shippable: "true" }),
  { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } },
);
const data = await res.json();
```

```bash CLI theme={null}
scrapebadger wallapop search "iphone" --market es --shippable
```

Car search — manual cars from 2015 on with under 100,000 km, closest to Madrid first:

```bash theme={null}
curl "https://scrapebadger.com/v1/wallapop/search?category_id=100&min_year=2015&max_km=100000&gearbox=manual&order_by=closest" \
  -H "X-API-Key: YOUR_API_KEY"
```

Car listings carry their specs in `attributes`:

```json theme={null}
"attributes": {
  "brand": "SEAT",
  "model": "Leon",
  "year": 2017,
  "version": "1.4 TSI ACT 150 FR Plus 5p S/S",
  "km": 83000,
  "engine": "Gasoline",
  "gearbox": "Manual",
  "horsepower": 150.0
}
```

```json Response theme={null}
{
  "items": [
    {
      "id": "nzxeknm5x562",
      "user_id": "dqjwdd53wwzo",
      "title": "iPhone 14 128GB Negro",
      "description": "iPhone 14 de color negro, con 128GB de almacenamiento.\nEn perfectas condiciones, y la pantalla impecable, siempre usado con cristal protector y funda desde el primer día.",
      "price": 250.0,
      "currency": "EUR",
      "category_id": 24200,
      "taxonomy": [
        { "id": 24200, "name": "Tecnología y electrónica" },
        { "id": 24201, "name": "Telefonía: móviles y smartwatches" },
        { "id": 9447, "name": "Smartphones" }
      ],
      "condition": null,
      "brand": null,
      "model": null,
      "attributes": {},
      "images": [
        {
          "id": "e65ve2rg0l2j",
          "small": "https://cdn.wallapop.com/images/10420/lo/q3/__/c10420p1311318554/i6787540572.jpg?pictureSize=W320",
          "medium": "https://cdn.wallapop.com/images/10420/lo/q3/__/c10420p1311318554/i6787540572.jpg?pictureSize=W640",
          "large": "https://cdn.wallapop.com/images/10420/lo/q3/__/c10420p1311318554/i6787540572.jpg?pictureSize=W800",
          "average_color": "13C1AC"
        }
      ],
      "location": {
        "latitude": 40.47122907944395,
        "longitude": -3.8786801592876357,
        "postal_code": "28222",
        "city": "Majadahonda",
        "region": "Comunidad de Madrid",
        "region2": "Madrid",
        "country_code": "ES",
        "approximated": null
      },
      "shippable": true,
      "user_allows_shipping": true,
      "reserved": false,
      "bumped": true,
      "bump_type": "city",
      "is_top_profile": true,
      "is_refurbished": false,
      "has_warranty": false,
      "slug": "iphone-14-128gb-1311318554",
      "url": "https://es.wallapop.com/item/iphone-14-128gb-1311318554",
      "created_utc": 1791580490.949,
      "created_at": "2026-10-09T21:14:50.949000Z",
      "modified_utc": 1791753563.082,
      "modified_at": "2026-10-11T21:19:23.082000Z"
    }
  ],
  "result_count": 40,
  "total_results": 49371,
  "next_page": "eyJhbGciOiJIUzI1NiJ9.eyJwYXJhbXMiOnsic2VhcmNoUmVxdWVzdFBhcmFtcyI6eyJrZXl3b3JkcyI6ImlwaG9uZSIs...",
  "order_by": "most_relevance",
  "market": "es",
  "country_code": "ES",
  "search_id": "a6e9213a-8d01-481f-8f3d-bd6ffaf2a61c"
}
```

## Errors

| Status | Cause |
| - | - |
| `422` | Neither `query` nor `category_id` was sent, a value is out of range, or `market` is not `es`, `it`, or `pt`. |
| `502` | Wallapop did not answer after retries. Not charged — retry the request. |

> [!NOTE]
>
> Each search request costs **8 credits**. Pages with no results and failed requests are not charged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.