Search¶

Bespoke endpoint for doing searches. Returns a list of embedded SearchResult representations.

This endpoint supports both simple search via query string parameters and more complicated search via a json request placed in the request body.

Search queries support boolean clauses (via and,or keywords), and negation (via - suffix). To illustrate this consider the following advertisements

id	Title
1	new car
2	old car
3	old boat
4	new motorbike

This table lists a number of example queries along with the advertisements that would be returned from the set above

Query	Advertisements returned
car	1,2
car or boat	1,2,3
new and car	1
car -new	2
(old and car) or -old	1,2,4

Note

For performance reasons we do not support deep pagination, you will not be able to retrieve more than 5000 results for a given search query. Because this number may change in the future. The preferred way to page through a collection is to to follow the next link relation in the response

Query Parameters¶

name	required	default	constraints
categoryId	no		–
query	no		must be a non empty value when neither categoryId or sellerId is defined
withImages	no	false	–
searchDescription	no	false	–
sellerId	no		–
postCode	no		6 character postcode
distance	no		positive
sortBy	no		one of ``default``, ``location``, ``price``
sortOrder	no		one of ``ascending``, ``descending``
offset	no	0	offset * limit cannot be greater than 5000
limit	no	30	max 200
locale	no		valid language tags like ‘nl-NL’, ‘fr-BE’

categoryId

the categoryId to filter on

query

the search query.

withImages

true to indicate that indicate that only results that have images should be returned

searchDescription

true to indicate that the description field should be taken into account when doing searches

sellerId

only return advertisements belonging to the specified seller

postCode

Postcode center of area search

distance

Radius distance area of search from postcode in meters

sortBy

Which field is used for sorting

sortOrder

Order in which search results are returned

offset

0 based index of the first element to return in the response, currently has to be a multiple of the limit value eg. when the limit is 10, then 10, 20, 30 are allowed 11 is not. We do not support deep pagination. offset * limit has to be < 5000

limit

maximum number of contained elements to return in the response

locale

Comma separated list of locales to use for filtering the results

Fields¶

field	type	constraints	default	Req	W	U
query	string	–		no	yes	no
categoryId	int	–		no	yes	no
sellerId	int	–		no	yes	no
withImages	boolean	–	false	no	no	no
searchDescription	boolean	–	false	no	yes	no
offset	int	–		yes	yes	no
limit	int	–		yes	yes	no
totalCount	int	–		no	no	no
categoriesHistogram	Categories Histogram	–		no	no	no
attributesHistogram	Attributes Histogram	–		no	no	no

query

search query

categoryId

the categoryId to filter on

sellerId

only return advertisements belonging to the specified seller

withImages

true to indicate that indicate that only results that have images should be returned

searchDescription

true to indicate that the description field should be taken into account when doing searches

offset

0 based index of the first element to return in the response

limit

The category in which the advertisement is placed.

maximum number of contained elements to return in the response

totalCount

total number of elements matching your search query

categoriesHistogram

the distribution of ads per categories

attributesHistogram

the distribution of ads per attribute values

Search request fields¶

field	type	constraints	default	Req	W	U
offset	int	–		yes	yes	no
limit	int	–		yes	yes	no
query	string	–		no	yes	no
categoryId	int	–		no	yes	no
withImages	boolean	–	false	no	no	no
searchDescription	boolean	–	false	no	yes	no
sellerId	int	–		no	yes	no
filters	object	–		no	yes	no
filters.price.from	int	positive		no	yes	no
filters.price.to	int	positive		no	yes	no
filters.postCode	String	6 character postcode		no	yes	no
filters.distance	int	positive		no	yes	no
filters.{customAttributeKey}	array of strings	–		no	yes	no
filters.{customNumericAttributeKey}	object	–		no	no	no
sort.by	string	one of `default`, `location`, `price`		no	no	no
sort.order	string	one of `ascending`, `descending`		no	no	no

offset

0 based index of the first element to return in the response

limit

The category in which the advertisement is placed.

maximum number of contained elements to return in the response

query

search query

categoryId

the categoryId to filter on

withImages

true to indicate that indicate that only results that have images should be returned

searchDescription

true to indicate that the description field should be taken into account when doing searches

sellerId

only return advertisements belonging to the specified seller

filters

Search request filters object. Used to declare detailed filtering

filters.postCode

Postcode center of area search

filters.distance

Radius distance area of search from postcode in meters

filters.{customAttributeKey}

Any custom attribute can be used for filtering by setting an array of custom attribute values in case of simple or multiple attributes Ex:

// select elements with attribute “customAttributeA” equals value1 or value2 “customAttributeA” : [“value1”, “value2”]

filters.{customNumericAttributeKey}

Any custom numeric attribute can be used for filtering by setting, optionally “from” and/or “to” fields Ex:

// select elements with values between 10 and 20 inclusive “customNumericAttributeA” : {“from”: 10, “to”: 20 }

// select elements with values of 35 and more “customNumericAttributeA” : {“from”: 35 }

sort.by

Which field is used for sorting

sort.order

Order in which search results are returned

Relations¶

name	availability	embedded	cardinality
mp:search-result	always	yes	0..N

Reference¶

GET /v1/search

Errors¶

http	error code	description
500	internal-server-error	Oops! Sorry, something went wrong on our side.
400	limit-invalid	The specified limit is invalid
400	pagination-invalid	The pagination offset and limit need to match, offset should be a multitude of limit.
400	pagination-too-deep	limit * offset cannot be > 5000
400	query-missing	When not specifying a category id the query cannot be empty or missing

Examples¶

Performing a search

Request :

GET /v1/search?categoryId=92&query=car&offset=0&limit=10 HTTP/1.1
Host: api.marktplaats.nl

Performing an advanced search by specifying the query in the body

Request :

GET /v1/search?categoryId=92&query=car&offset=0&limit=10 HTTP/1.1
Host: api.marktplaats.nl

{
  "query": "phone",
  "categoryId": 2,
  "sellerId": 4,
  "filters": {
     "price": {
        "from": 10,
        "to": 20
      },
     "postCode": "1000AB",
     "distance": 1000,
     "condition": [ "Nieuw" ],
     "color": [ "Rood", "Blauw" ],
     "searchOnDescription": true
  }
}

Response :

HTTP/1.1 200 OK
Content-Type: application/json

{
  "_links": {
    "self": {
      "href": "/v1/search?query=batmobile&offset=0&limit=30"
    },
    "curies": [
      {
        "href": "https://api.marktplaats.nl/docs/v1/rels/{rel}.html",
        "templated": true,
        "name": "mp"
      }
    ]
  },
  "_embedded": {
    "mp:search-result": [
      {
        "_links": {
          "mp:advertisement": {
            "href": "/v1/advertisements/m459"
          },
          "mp:category": {
            "href": "/v1/categories/1/2"
          },
          "mp:seller": {
            "href": "/v1/users/231"
          },
          "mp:advertisement-website-link": {
            "href": "http://link.marktplaats.nl/m459",
            "type": "text/html"
          }
        },
        "_embedded": {
          "mp:advertisement-image": {
            "_links": {
              "self": {
                "href": "/v1/images/857ca3aa-da33-4faf-b7eb-2eca6068d609"
              },
              "mp:image-blob": {
                "href": "/v1/images/857ca3aa-da33-4faf-b7eb-2eca6068d609/{size}/blob",
                "templated": true
              },
              "mp:image-meta": {
                "href": "/v1/images/857ca3aa-da33-4faf-b7eb-2eca6068d609/{size}/meta",
                "templated": true
              }
            },
            "imageId": 19,
            "mediaId": "857ca3aa-da33-4faf-b7eb-2eca6068d609",
            "status": "available"
          }
        },
        "itemId": "m459",
        "title": "batmobile",
        "description": "batmobile",
        "categoryId": 2,
        "priceModel": {
          "modelType": "fixed",
          "askingPrice": 34200
        },
        "seller": {
          "sellerId": 231,
          "sellerName": "Batman"
        }
      }
    ]
  },
  "query": "batmobile",
  "offset": 0,
  "limit": 10,
  "totalCount": 1
}

Performing an advanced search by specifying the query in the body

Request :

GET /v1/search?categoryId=92&query=car&offset=0&limit=10 HTTP/1.1
Host: api.marktplaats.nl

{
  "query": "phone",
  "categoryId": 2,
  "sellerId": 4,
  "filters": {
     "price": {
        "from": 10,
        "to": 20
      },
     "postCode": "1000AB",
     "distance": 1000,
     "condition": [ "Nieuw" ],
     "color": [ "Rood", "Blauw" ],
     "searchOnDescription": true
  },
  sort: {
     "by": "default",
     "order": "descending"

  }
}

Response :

HTTP/1.1 200 OK
Content-Type: application/json

{
  "_links": {
    "self": {
      "href": "/v1/search?query=batmobile&offset=0&limit=30"
    },
    "curies": [
      {
        "href": "https://api.marktplaats.nl/docs/v1/rels/{rel}.html",
        "templated": true,
        "name": "mp"
      }
    ]
  },
  "_embedded": {
    "mp:search-result": [
      {
        "_links": {
          "mp:advertisement": {
            "href": "/v1/advertisements/m459"
          },
          "mp:category": {
            "href": "/v1/categories/1/2"
          },
          "mp:seller": {
            "href": "/v1/users/231"
          },
          "mp:advertisement-website-link": {
            "href": "http://link.marktplaats.nl/m459",
            "type": "text/html"
          }
        },
        "_embedded": {
          "mp:advertisement-image": {
            "_links": {
              "self": {
                "href": "/v1/images/857ca3aa-da33-4faf-b7eb-2eca6068d609"
              },
              "mp:image-blob": {
                "href": "/v1/images/857ca3aa-da33-4faf-b7eb-2eca6068d609/{size}/blob",
                "templated": true
              },
              "mp:image-meta": {
                "href": "/v1/images/857ca3aa-da33-4faf-b7eb-2eca6068d609/{size}/meta",
                "templated": true
              }
            },
            "imageId": 19,
            "mediaId": "857ca3aa-da33-4faf-b7eb-2eca6068d609",
            "status": "available"
          }
        },
        "itemId": "m459",
        "title": "batmobile",
        "description": "batmobile",
        "categoryId": 2,
        "priceModel": {
          "modelType": "fixed",
          "askingPrice": 34200
        },
        "seller": {
          "sellerId": 231,
          "sellerName": "Batman"
        }
      }
    ]
  },
  "query": "batmobile",
  "offset": 0,
  "limit": 10,
  "totalCount": 1
}