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 }