GET /catalog/v4/search

The searchresults operation returns product information by supplying keywords or ISBN/EAN. The operation has filtering and paging options.

Request URL structure:

https://api.bol.com/catalog/v4/search

Request HTTP method:

GET

Request requires session:

No

Request parameters:

Name Location Data type Description

q

Query

Text

The search query, e.g., “Harry Potter” should return. This can be one or more keywords or an EAN/ISBN. You can use the quotation mark operator to do an exact search. For example including quotation marks with “waits tom” is an exact search and waits tom is a normal search.

pids

Query

Number

You can request more than one product at a time by using this parameter.

ids

Query

Number

The category id to use for filtering. More than one id can be provided, separated with a comma (only “1 category + X refinements” can be used to filter.). CategoryId’s can be 1 to 512 characters long. Most of the time, they are 4 or 10 characters long. Example: 87,8293. Valid ids can be retrieved with operation GET /catalog/v4/lists with categories and refinemets a dataoutput.

dataoutput

Query

Data Output

choose to return refinements,categories, and or products. Mutiple values are allowed, use comma to separate. Default is products.

offers

Query

Text

all, cheapest, secondhand, newoffers, bolcom, bestoffer – default: bestoffer. The parameters can be combined using a comma, for instance offers=cheapest,secondhand returns the cheapest 2nd hand offer. Note that bestoffer returns only the best offer, making further filtering pointless

sort

Query

Sorting method

The way the products are sorted, e.g., by price.

offset

Query

Number

The number of results to skip before returning any results. This can be used for paging purposes. E.g. offset 3 will skip the first 3 results.

limit

Query

Number

Number of products that is returned by the operation. The default is 10 products

includeattributes

Query

Boolean

Return the full set of attributes for the products as key-value pairs. Note that by using the key-value pairs, more attributes are available as key-value pair than as elements.

– true: return key-value pair attributes
– false: return no key-value pair attributes

searchfield

Query

Text

Specify the search within a field. Possible values: author, artist, title, brand, songtitle, actor, director. Default = none. For example a search with author=potter returns only products (in this case books) for which an author is potter

format

Query

Text

json (default): the response is returned in JSON. xml: the response is returned in XML

country

Query

Text

Signifies whether the shopping context is Dutch (NL; default) or Belgium (BE). This can influence search ranking, and whether some products and offers are returned

Response:

Element Min Max Description

Products

0

100

List of products found, max. 100 (with a search on EAN/ISBN this is limited to max 3 results)

TotalResultSize

1

1

Total number of products found by search, before clipping to max 100 products (see element product).

Categories

0

One or more categories in which the found products occur. Category consists of the following elements:
– id: the number indicating the category id
– name: the category name
– productCount: the number of products found in this category

RefinementGroups

0

One or more groups of refinements that are available to narrow down (refine) the search response.

OriginalRequest

0

1

If the request was made within a category or with refinements, this node describes the names and id’s from the categories and refinements from the request

Request / Response example:

Request: https://api.bol.com/catalog/v4/search/?q=harry&offset=0&limit=2&dataoutput=products,categories&apikey={apikey}&format=json

Example response: JSONXML