ProductSearch - Searching the product database

This is a read-only resource that allows you to retrieve everything that would usually be displayed on a search results page including:

  • The search query itself
  • A list of products that are returned by the search
  • Each product has a list of all product information required to display it including:
    • General information: sku; title; image/thumb
    • Link to the product page
    • The calculated price of the product. Note: if a _session_token has been passed, if the user is logged in, this price will reflect any user or group discounts as well as anything else that would affect the pricing on the website (including multi-currency, applied coupon codes etc).
      • @TODO: there currently is no way to request quantity pricing for a product.
      • Pricing is one of the more expensive things to calculate, so to avoid sluggish responses from the API, make sure you utilise the pagination feature if you are expecting large recordsets to be returned, or finding the API response a bit slow for your requirements.
    • Any promotion information - discount & featured message
    • Any options, detail about each option, default selected settings
  • If the website uses access control, only products that the user would usually have access to will be visible. If the website requires login to access certain products a _session_token will need to be passed in the querystring to ensure that users logged in state is carried across to your request. See the API session documentation for more information.
@TODO: Login capability has not yet been implemented. Contact us if you need this.

Summary

Supported HTTP "verbs"

VERB HTTP Method Description
fetch GET /api/v3/ProductSearch/$search_string Search String to search for
list NOT SUPPORTED
create/update NOT SUPPORTED
update NOT SUPPORTED

Supported parameters

Parameter Values Description
_with_prices 0 (default) or 1 Include prices.
_with_product_fields Colon seperated list of product fields Product fields to include
_start integer index to start from (zero-based). ProductSearch is built for pages of results, so this number should be divisible by _results (it will round to the nearest page number) Standard API Pagination
_results Number of results to return - MAX 200 Standard API Pagination

Standard search result retrieval

To pull data from this resource submit a GET request to /API/V3/ProductSearch/$query where $query is the search query.

Retrieving results with price data

By default product data contained in the search results will not contain price data. This is because prices can be complex & expensive to calculate so we will only provide them when needed.

To include price data in the search results, include the argument _with_prices=1 in the querystring. E.g. /API/V3/ProductSearch/red+tshirt?_with_prices=1.

Pagination

By default only the first page of search results will be returned - with the page size defaulting to 50 products.

This resource supports the standard API pagination fields (_start and _results) to allow you to select which page of results to retrieve.

The maximum page size you can request is 200 products. Attempting to specify a page size large than this will result in a 400 Bad Request error. Please be careful in using large page sizes - especially when requesting price data. Depending on the complexity of the pricing algorithms used on the website this can result in sluggish API response times.

So /API/V3/ProductSearch/red+tshirt?_with_pricing=1&_start=0&_results=20 would retrieve the first 20 products for the product search for 'red tshirt' including pricing data.

Example response

The following response is an example response from a website selling linen products using a fake url:

https://www.mysite.net/API/V3/ProductSearch/sheet+comfort?_with_pricing=1&_start=0&_results=2

<?xml version="1.0" encoding="utf-8" ?>
<ResultSet page="1" session="yjipIL8BeUWxrFq" totalResults="42" totalResultsReturned="2" xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://www.mysite.net/API/V3/ProductSearch.xsd">
    <Search href="https://www.mysite.net/API/V3/API/V3/ProductSearch/sheet comfort" id="Ecommerce::ProductSearch::sheet comfort">
        <Product href="https://www.mysite.net/API/V3/EcommerceProduct/03984" id="Ecommerce::Product::03984">
            <default_options></default_options>
            <discount></discount>
            <featured></featured>
            <inactive>0</inactive>
            <link>https://www.mysite.net/shop/Sheets/Double/Blossom_Comforter/x_sku/03984.html</link>
            <option>
                <code>101260</code>
                <description></description>
                <group>Sizes</group>
                <height></height>
                <label>Sizes</label>
                <sort>10</sort>
                <value>
                    <code>Cushion</code>
                    <label>Cushion (60cmx40cm) each</label>
                </value>
                <value>
                    <code>Comforter</code>
                    <label>Comforter (200cmx150cm)</label>
                </value>
                <widget>select</widget>
                <width></width>
            </option>
            <option_display_type>seperate</option_display_type>
            <option_type>Simple</option_type>
            <sku>03984</sku>
            <image>https://www.mydomain.nz/images/items/blossom-comforter-LR.jpg</image>
            <thumb>https://www.mydomain.nz/images/thumb/blossom-comforter-LR.jpg</thumb>
            <title>Rabo Sheets - Blossom Cushion and Comforter</title>
        </Product>
        <Product href="https://www.mysite.net/API/V3/EcommerceProduct/04238" id="Ecommerce::Product::04238">
            <default_options></default_options>
            <discount></discount>
            <featured></featured>
            <inactive>0</inactive>
            <link>https://www.mysite.net/shop/Sheets/Double+-+Ocean+Comforter++Pillowcases+and+Euros+sold+separately/x_sku/04238.html</link>
            <option>
                <code>04238-Sizes</code>
                <description></description>
                <group>sizes</group>
                <height></height>
                <label>Sizes</label>
                <sort>10</sort>
                <value>
                    <code>EuropeanPillowcase</code>
                    <label>European Pillowcase (65 x 65cm) (Each)</label>
                </value>
                <value>
                    <code>Cushion</code>
                    <label>Cushion (60cmx40cm) each</label>
                </value>
                <value>
                    <code>Comforter200</code>
                    <label>Comforter (200cmx150cm)</label>
                </value>
                <value>
                    <code>Comforter240</code>
                    <label>Comforter (240cmx150cm)</label>
                </value>
                <widget>select</widget>
                <width></width>
            </option>
            <option>
                <code>04238-Colour</code>
                <description></description>
                <group>colour</group>
                <height></height>
                <label>Colour</label>
                <sort>20</sort>
                <value>
                    <code>R</code>
                    <label>Red</label>
                </value>
                <value>
                    <code>B</code>
                    <label>Blue</label>
                </value>
                <widget>select</widget>
                <width></width>
            </option>
            <option_display_type>seperate</option_display_type>
            <option_type>Simple</option_type>
            <sku>04238</sku>
            <image>https://www.mydomain.nz/images/items/Black large comforter and cushion LR-222.1.jpg</image>
            <thumb>https://www.mydomain.nz/images/thumb/Black large comforter and cushion LR-222.1.jpg</thumb>
            <title>Rabo Sheets - Black large Comforter</title>
        </Product>
    </Search>
</ResultSet>