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 search term!

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 result is equipped with matching filters. Non-matching filters are not returned. Each filter value has a name attribute, whose 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. Bear in mind that the number of results will shrink or even yield a null result, especially when combining multiple filters. Below you find an example of useful filters.

shop: The shop product is offered by

brand: The products brand

minPrice and maxPrice: Filter in cents for defining a price range.

Product attributes are also eligible for filtering:

color: The products color

genderAge: The gender a product belongs to (male, female, children)

More attribute tags are presented in the FAQ section.

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.

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

GET http://api.s24.com/v3/:appid/autocomplete?q=:term

You can only request up to 50 characters as a search term!

Results are sorted by approx. result size. The following is the autocomplete result for query term kleid:

<ns4:autocompletionResult>
<suggestions>
    <suggest>kleid</suggest>
    <suggest>kleidung</suggest>
    <suggest>kleider</suggest>
    <suggest>kleiderschuhe</suggest>
    <suggest>kleiden</suggest>
    <suggest>kleider-größe</suggest>
    <suggest>kleidschuhe</suggest>
    <suggest>kleid 3</suggest>
    <suggest>kleid 3 4-arm</suggest>
    <suggest>kleidersack</suggest>
</suggestions>
<products/>
</ns4:autocompletionResult>