# Marktplaats Search API Documentation

Search Marktplaats.nl classifieds by keyword, category, price range and distance. Each listing has id, title, description, url, price in euros with currency, price type, category id, location, seller, images and attributes. Page with offset and limit; offset plus limit may not pass 3000. A valid empty result is a successful response. For cars use the Marktplaats Auto's API.

- **Documentation:** [https://scrappa.co/docs/marktplaats-api/marktplaats_search](https://scrappa.co/docs/marktplaats-api/marktplaats_search)
- **API group:** Marktplaats API
- **Endpoint:** `GET https://scrappa.co/api/marktplaats/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Search keywords, e.g. fiets. Required unless category_id is set. |
| `category_id` | integer | No | Top-level category id from the categories endpoint, e.g. 445 for Fietsen en Brommers. |
| `subcategory_ids` | string | No | Comma-separated subcategory ids, up to 10, e.g. 447. Needs category_id. |
| `limit` | integer | No | Listings per page, 1 to 100. Defaults to 30. |
| `offset` | integer | No | Number of listings to skip. Use next_offset from the previous response. Defaults to 0. Offset plus limit must be 3000 or less. |
| `sort_by` | string | No | relevance, price or date. Defaults to relevance. |
| `sort_order` | string | No | asc or desc. Defaults to asc for price and desc for date. |
| `min_price` | integer | No | Minimum price in whole euros. |
| `max_price` | integer | No | Maximum price in whole euros. |
| `postcode` | string | No | Dutch postcode, e.g. 1011AB. Needs distance_meters. |
| `distance_meters` | integer | No | Search radius around the postcode, 1000 to 1000000. Needs postcode. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/marktplaats/search?query=fiets&limit=3"
```

## Example response

```json
{
    "success": true,
    "data": {
        "query": "fiets",
        "total_count": 230794,
        "listings": [
            {
                "id": "m2119107775",
                "title": "Dames fietsen heren fietsen oma fietsen",
                "description": "Zeer grote voorraad bij 020 fietsen amsterdam dames fietsen heren fietsen oma fietsen transport fietsen elke week nieuwe aanvoer!! Fietsen hebben wij al vanaf \u20ac99,- kom snel langs! \u2022 - onze",
                "url": "https://www.marktplaats.nl/v/fietsen-en-brommers/fietsen-dames-damesfietsen/m2119107775-dames-fietsen-heren-fietsen-oma-fietsen",
                "price": 99,
                "currency": "EUR",
                "price_type": "fixed",
                "category_id": 447,
                "location": {
                    "city": "Amsterdam",
                    "country": "Nederland",
                    "latitude": 52.374477671822,
                    "longitude": 4.8580343858334
                },
                "seller": {
                    "id": 19190757,
                    "name": "020-Fietsen B.V.",
                    "verified": true
                },
                "images": [
                    "https://images.marktplaats.com/api/v1/hz-mp-pro-listing/images/23/232cb473-a61d-45c8-b7ad-355f3d3e6ce1?rule=ecg_mp_eps$_82.jpg",
                    "https://images.marktplaats.com/api/v1/hz-mp-pro-listing/images/79/79ba9263-de8a-4af5-b869-55a4a36e1ac7?rule=ecg_mp_eps$_82.jpg",
                    "https://images.marktplaats.com/api/v1/hz-mp-pro-listing/images/51/5192c45d-61c9-4f63-a55f-7964556666de?rule=ecg_mp_eps$_82.jpg"
                ],
                "attributes": {
                    "condition": "Gebruikt",
                    "delivery": "Ophalen of Verzenden"
                }
            },
            {
                "id": "m2452040121",
                "title": "Batavus quip elektrische dames fiets transport fiets",
                "description": "Zeer nette zo goed als nieuwe batavus elektrische fiets 49cm frame bosch middenmotor hydraulische schijf remmen voor en achter stevige voor en achter drager fiets word verkocht met 1 jaar garantie fie",
                "url": "https://www.marktplaats.nl/v/fietsen-en-brommers/fietsen-dames-damesfietsen/m2452040121-batavus-quip-elektrische-dames-fiets-transport-fiets",
                "price": 1195,
                "currency": "EUR",
                "price_type": "fixed",
                "category_id": 447,
                "location": {
                    "city": "Utrecht",
                    "country": "Nederland",
                    "latitude": 52.093055771437,
                    "longitude": 5.1234611252344
                },
                "seller": {
                    "id": 39689712,
                    "name": "030 fietsen"
                },
                "images": [
                    "https://images.marktplaats.com/api/v1/hz-mp-pro-listing/images/df2845f5-b560-413d-b046-3ee82870805c?rule=ecg_mp_eps$_82.jpg"
                ],
                "attributes": {
                    "condition": "Zo goed als nieuw",
                    "delivery": "Ophalen of Verzenden"
                }
            }
        ],
        "offset": 0,
        "limit": 3,
        "has_more": true,
        "next_offset": 3
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. This response is not billable and makes no upstream request. |
| 404 | Resource Not Found | The requested Marktplaats category does not exist. This response is not billable. |
| 503 | Invalid Source Response | Marktplaats answered with a shape that no longer matches the documented contract. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)