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.

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 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 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.