shopping24 documentation
s is for shopping
API product search
Use this API endpoint to implement onsite search capabilities. When submitting a term to search for, you can refine your search result supplying filter information, e.g in the brand or color parameter.
You can only request up to 150 characters as searchterm!
GET /v3/:appid/search/?q=:term
Sort & Pagination
In order to sort the result list you’ll just have to add the parameter sort
to the request.
All current sort types are listed in link
tags in the result.
<link href="/v3/:appid/search?q=:term&sort=standard&ascending=true"
rel="sort-standard-ascending"/>
Available sort criteria are
standard
- Sorts search results by relevance and category pages by popularity.
price
- Sorts by product price.
sale
- Sorts by
standard
and boosts sale products to the beginning of the result list.
Pagination
Response of search returns a paged results. In order to customize a paged response just add the parameters listed below.
page
- page index. Only if the page parameter is set, the response will be returned with pagination enabled. Per default the page index is set to
1
. pageElements
- number of elements returned on one page. The number of page elements is limited by the server side (max. number of page elements = 1000) per default the number of page elements is set to
40
.
Filter
There are several filter types, listed in filters
of the result. Each results is equipped with
matching filters. Non-matching filters are not returned. Each filter value has name
attribute,
who’s value can be used as request parameter to enable the filter. You’ll find a displayable name
in the label
attribute.
<filters>
<filter name="color" label="Farbe">
<item count="3" name="Blau" id="1"/>
<item count="2" name="Grün" id="2"/>
</filter>
</filters>
To filter for product for a specific color, append the filter’s name
attribute and the item’s id
:
GET /v3/:appid/search/?q=:term&color=1
You can use multiple ids for every filter, just separate them with comma. To exclude products matching a filter,
add a -
in front of every id for this filter. Mixing in- and exclusions is not possible.
GET /v3/:appid/search/?q=:term&color=1,2
GET /v3/:appid/search/?q=:term&color=-1,-2
Available Filters
Each result is equipped with matching filters. Over time, more filters may appear and filter coverage may increase. The following filters are applicable on (almost) every search result - double check with the available filter section in the response body:
shop
: The shop product is offered by
genderAge
: The gender a product belongs to (male, female, children)
brand
: The products brand
color
: The products color
minPrice
and maxPrice
: Filter in cents for defining a price range.
Unfortunately a full list of available filters is currently not available! A dedicated api endpoint is planned.
Extended Results
The following mechanisms are built into the product search api to either quickly reduce a huge search result or expand rather small (or zero result) results.
Related products
If a search query returns less than about 10 products, the search result contains related products.
They are encapsulated in a <related>
block as <products>
element and are somewhat related to the products matching the
search query.
<productSearchResult>
<products>
<product>...</product>
</products>
<related>
<products>
<product>...</product>
</products>
</related>
</productSearchResult>
Related brands
Related brands are available if a brand could be recognized in the search query. They are also
encapsulated in the <related>
block as <brands>
element with a source
element <source>
.
The brand in <source>
is the currently selected one, all others are related brands.
<productSearchResult>
<products>
<product>...</product>
</products>
<related>
<brands>
<source>
<ns3:brand id="42">
<name>Adidas</name>
<link href="/v3/:appid/products?brand=42" rel="products"/>
<imageResource type="logo" base="..." id="111111">
<link href="..." rel="self"/>
</imageResource>
</ns3:brand>
</source>
<ns3:brand id="43">
<name>Nike</name>
<link href="/v3/:appid/products?brand=43" rel="products"/>
<imageResource type="logo" base="..." id="111111">
<link href="..." rel="self"/>
</imageResource>
</ns3:brand>
...
</brands>
</related>
</productSearchResult>
Spellchecking
If a spelling error is detected in the query term, a <didyoumean>
element of type spellcheck
is added to
the search result. Those hints (and the following below) are encapsulated in a <reformulations>
block.
For each spellcheck hint a rough product count is supplied.
<reformulations>
<ns2:didyoumean source="spellcheck" count="757">
<query type="search">
<search>klein esprit</search>
</query>
</ns2:didyoumean>
</reformulations>
If your search hits zero results and a spellcheck hint is available for the current query term,
a querycorrection is executed automatically. This is marked in the search result page as a
<querycorrection>
element inside the <reformulations>
block. The <original>
element contains
the input query term, the <correction>
the executed query.
<reformulations>
<ns2:querycorrection>
<correction>
<query type="search">
<search>esprit</search>
</query>
</correction>
<original>
<query type="search">
<search>esprt</search>
</query>
</original>
</ns2:querycorrection>
</reformulations>
Reduced alternate searches
If a search hits zero or less than 10 results and no automatic spell correction could be applied (see above), a query reduction algorithm is applied to the query term (if it contains more than one word). Single words are removed from the query and the “reduced” query is executed.
The results are available inside the <reformulations>
container as <reducedquery>
elements
of source query-reduction
. Inside, the following elements are available
<query>
- The reduced query compiled from the input query term
<highlightedQuery>
- The input query term with the removed words highlighted using a
<strike>
tag. <products>
- The products matching the reduced query, maximum of 5.
<reformulations>
<ns2:reducedquery source="query-reduction" count="57">
<query type="search">
<search>esprit kleid 38</search>
</query>
<highlightedQuery>esprit kleid 38 <strike>wurst</strike></highlightedQuery>
<products size="5">...</products>
</ns2:reducedquery>
</reformulations>
Related queries
Related search queries are available for most issued product searches. They are also
encapsulated in the <reformulations>
block as <didyoumean>
element with a source
attribute related-query
. The product count is roughly estimated.
<reformulations>
<ns2:didyoumean source="related-query" count="2768">
<query type="search">
<search>jeans blau</search>
</query>
</ns2:didyoumean>
</reformulations>
Autocomplete
An autocomplete API endpoint is available at You can only request up to 50 characters as searchterm!
GET http://api.s24.com/v3/:appid/autocomplete?q=:term
Results are sorted by approx. result size. The following is the autocomplete result for query term kleid
:
<ns2:autocompletionResult xmlns:ns2="http://api.s24.com/v3/1.0/autocomplete">
<suggestions>
<suggest hits="18364">kleid</suggest>
<suggest hits="5505">kleid damen</suggest>
<suggest hits="4422">kleiderschrank</suggest>
<suggest hits="1840">kleid schwarz</suggest>
<suggest hits="684">kleid grau</suggest>
<suggest hits="481">kleid blau</suggest>
<suggest hits="361">kleid mädchen</suggest>
<suggest hits="344">kleid rot</suggest>
<suggest hits="324">kleid arm</suggest>
<suggest hits="298">kleid bodyflirt</suggest>
</suggestions>
</ns2:autocompletionResult>
Personal Shopping Context
You are able to individualize the product search experience by supplying a personal shopping context
for each user. This can be done by adding comma separated keywords in the parameter psc
. Keywords could be
brand names or items related to user. Those will be boosted in product searches.
If you supply male,diesel
as psc
and search for jeans
, you’ll find male jeans by diesel (if available)
on the first search result pages. Results are not filtered just individually sorted.
Those keywords could be extracted from connected Facebook profiles or a personal user history.