shop.product.search

Returns the list of products matching the specified search criteria.

Parameters

  • hash GET Optional

    Product search condition hash encoded for safe use in URLs.

    Hash examples & tips:
    — array(12,23,34) or 'id/12,23,34': required products’ IDs.
    — 'related/cross_selling/12': cross-selling products selected for product with id = 12.
    — 'related/upselling/12': upselling products selected for product with id = 12.
    — 'category/27': products contained in category with id = 27.
    — 'search/query=qwerty': search by the 'qwerty' query in product names, SKU names and SKU codes.
    — 'search/name=qwerty': exact search for the 'qwerty' word in product field 'name'; instead of of the comparison operator '=' you can use others supported by SQL ­— '>', '<', '>=', '<=', '!='; instead of standard product fields, you can also use the word 'tag' to perform similar search by product tags. Search products by several fields is supported; e.g., 'search/name*=style&tag=fashion'.
    — 'search/name*=qwerty': search by word part 'qwerty' in field property 'name'; supported operators are '*=' (search by any parts of words), '^=' (search by the beginnings of words), '$=' (search by the endings of words).
    — 'search/tag=style' or 'tag/style': exact search by product tag 'style'; format 'search/tag=style' can be used to search by several tags separated by the OR condition operator '||'; e.g., 'search/tag=style||fashion'.
    — 'search/type_id=1': example of search by an arbitrary product field.
    — 'search/color.value_id=4,5,6': search for products associated with specified value IDs of a feature (in this example feature with the 'color' identifier).
    — 'search/sku_id=11,22,33': search for products by product variant IDs; to get only the variants with specified IDs in the returned result, add the 'skus_filtered' field to the 'fields' parameter..
    — 'search/category_id=7,8,9': search for products whose main categories’ IDs are in the specified list.
    — 'type/1': search by product type ID; synonym for 'search/type_id=1'.
    — 'bestsellers/2592000' — search for best-selling products for the specified number of seconds (in this example 30 days = 60*60*24*30).
    — 'bestsellers' — search for best-selling products for the entire sales period.

  • offset GET Optional

    Position from which the resulting product list should begin. Non-negative values are accepted. If not specified, 0 is used by default (i.e. begin the list with the first found product).

  • limit GET Optional

    Maximum number of products which should be returned. Acceptable value range is from 0 to 1000. If not specified, 100 is used by default.

  • fields GET Optional

    The list of product properties which must be returned. May contain either only the names of all fields of the 'shop_product' table specified with the '*' syntax or also extra fields listed below, which can be added with a comma; e.g., '*,skus,stock_counts'.

    Available extra fields:
    - images: items with the 'images' key are added to the returned result, containing detailed information about all product images, including 3 URLs of each image — with sizes '970', '96x96' and '270x0';
    - images2x: similar to the 'images' field with the difference that the images-related information contains URLs of image thumbnails generated for devices with high pixel density displays;
    - image: items with the 'image' key are added to the returned result, containing URLs of 3 thumbnails of the main product image with the sizes '970', '96x96' and '270x0';
    - image_crop_small: items with the 'image_crop_small' key are added to the returned result, containing the URL of the main product image thumbnail with the size '48x48';
    - image_count: items with the 'image_count' key are added to the returned result, containing the number of images of the current product;
    - skus: items with the 'skus' key are added to the returned result, containing detailed information about product variants; if the 'stock_counts' field is requested, too, then the sub-array of each variant’s properties also contains an item with the 'stock' key, containing stock counts of the corresponding product variants; if the 'skus_image' field is requested, too, then then the sub-array of each product variant’s properties also contains items with the 'ext', 'image_filename' and 'image_description' keys, containing information about the product images displayed in the storefront for the corresponding product variants;
    - skus_filtered: similar to the 'sku' field with the difference that the 'skus' sub-array of each returned product contains only the product variants matching the product filter conditions;
    - sku_filtered: similar to the 'skus_filtered' field with the difference that the 'skus' sub-array of each returned product contains only one variants matching the product filter conditions;
    - sku: items with the 'sku' are added to the returned result, containing the names of products’ main variants;
    - frontend_url: items with the 'frontend_url' are added to the returned result, containing the products’ page URLs relative to the common storefront URL;
    - sales_30days: items with the 'sales_30days' key are added to the returned result, containing the total cost of the products’ purchased product variants counted only for paid orders, expressed in numbers corresponding to the main store currency, and items with the 'sales_30days_html' key containing similar values including the main store currency name prepared for safe use in HTML markup;
    - stock_worth: items with the 'stock_worth' key are added to the returned result, containing the total cost of the product
    variants available on stock expressed in numbers corresponding to the main store currency, and items with the 'stock_worth_html' key containing similar values including the main store currency name prepared for safe use in HTML markup.
    - params: items with the 'params' key are added to the returned result , containing an array of a product’s custom parameters in the “key→value” format.

  • filters GET Optional

    URL-encoded array of product filtering parameters with the following keys:
    - in_stock_only: (int) 1 if you need to obtain only products with positive or infinite stock quantity.
    - out_of_stock_only: (int) 1, if you need to obtain only products with zero stock quantity (not null and below 1).
    - price_min: (float) Lowest product price expressed in the main store currency.
    - price_max: (float) Highest product price expressed in the main store currency.
    - unit: (int) ID of the stock or the base quantity unit which must be selected in the obtained products’ properties.
    - stock_unit_id: (int) ID of the stock quantity unit which must be selected in the obtained products’ properties.
    - base_unit_id: (int) ID of the base quantity unit which must be selected in the obtained products’ properties.
    - string feature identifier: (array) Information about the values of the specified feature, which must be selected in the obtained products’ properties. Array items must be either sub-arrays of numeric feature value IDs, or sub-arrays with the keys 'min' (minimum value), 'max' (maximum value), 'unit' (string identifier of a feature measurement unit from the dimension.php file).

  • escape GET Optional

    Flag (0 or 1) denoting whether 'name' and 'url' properties’ values of the obtained products must be escaped for safe use in HTML code. Default value is 1.

  • format GET Optional

    Sets response format. Available options: json (default), xml.

Return value

Found products list. Each list item is an array with the following keys:

  • products[]['id'] int
  • products[]['name'] string
  • products[]['summary'] string
  • products[]['meta_title'] string TITLE tag value.
  • products[]['meta_keywords'] string Value of the 'keywords' meta tag.
  • products[]['meta_description'] string Value of the 'description' meta tag.
  • products[]['description'] string
  • products[]['contact_id'] int ID of the user who has added the product.
  • products[]['create_datetime'] datetime.
  • products[]['edit_datetime'] datetime.
  • products[]['status'] int Product status: -1 (unpublished), 0 (hidden), 1 (published).
  • products[]['type_id'] int.
  • products[]['image_id'] int Main image ID.
  • products[]['image_url'] string Main product image thumbnail’s URL with the '200x0' size, if available.
  • products[]['video_url'] string.
  • products[]['sku_id'] int Main product variant ID.
  • products[]['url'] int Editable part of the product page URL.
  • products[]['rating'] float Average product rating as it was rated by customers.
  • products[]['price'] float Price in the decimal(15,4) format.
  • products[]['compare_price'] float Strike-through price in the decimal(15,4) format.
  • products[]['currency'] string Product currency in the ISO 4217 format.
  • products[]['min_price'] float Lowest product variant price in the decimal(15,4) format.
  • products[]['max_price'] float Highest product variant price in the decimal(15,4) format.
  • products[]['tax_id'] int ID of the selected tax rule, or 0 if no rule is selected.
  • products[]['count'] float|null Total stock quantity of all product variants in the decimal(15,3) format or null if some of product variants’ quantity is inifinite.
  • products[]['count_denominator'] int Available precision for stock quantities. Acceptable values: 1 (whole pieces), 10 (precision to tenths), 100 (precision to hundredths), 1000 (precision to thousandths).
  • products[]['order_multiplicity_factor'] float Add-to-cart step (multiplicity factor) in the decimal(15,3) format.
  • products[]['stock_unit_id'] int ID of the selected stock quantity unit.
  • products[]['base_unit_id'] int ID of the selected base quantity unit.
  • products[]['stock_base_ratio'] float Conversion ratio between the stock unit and the base quantity unit.
  • products[]['order_count_min'] float Minimum orderable product quantity in the decimal(15,3) format.
  • products[]['order_count_step'] float Quantity adjustment value with “+/-” buttons in the decimal(15,3) format.
  • products[]['cross_selling'] int Cross-selling products display mode: 0 (disabled), 1 (enabled to show in accordance with the product type settings), 2 (enabled to show manually selected recommended products).
  • products[]['upselling'] int Upselling products display mode: 0 (disabled), 1 (enabled to show in accordance with the product type settings), 2 (enabled to show manually selected recommended products).
  • products[]['rating_count'] int Number of product ratings submitted by customers.
  • products[]['total_sales'] float Total amount of product sales, expressed in the main store currency, in the decimal(15,4) format.
  • products[]['category_id'] int Main category ID.
  • products[]['badge'] string One of default image badges’ IDs or HTML code of a custom badge.
  • products[]['sku_type'] int Product variants selection mode — 0 (by SKU names), 1 (by feature values).
  • products[]['sku_count'] int Total number of the product’s variants.
  • products[]['skus'] array Product variants data array. Is available in the response if the fields указано одно из значений skus, skus_filtered, sku_filtered. Each variant’s sub-array contains values with the following keys:
  • products[]['skus'][]['id'] int.
  • products[]['skus'][]['product_id'] int.
  • products[]['skus'][]['sku'] int SKU code.
  • products[]['skus'][]['sort'] int.
  • products[]['skus'][]['name'] string SKU name.
  • products[]['skus'][]['image_id'] int Selected image ID.
  • products[]['skus'][]['price'] float Price in the decimal(15,4) format.
  • products[]['skus'][]['purchase_price'] float Purchase price in the decimal(15,4) format.
  • products[]['skus'][]['compare_price'] float Strike-through price in the decimal(15,4) format.
  • products[]['skus'][]['count'] float|null Total stock quantity in the decimal(15,3) format or null if quantity on some stocks is inifinite.
  • products[]['skus'][]['available'] int Flag (0 or 1) denoting the variant’s availability for purchase.
  • products[]['skus'][]['stock_base_ratio'] float Conversion ratio between the stock unit and the base quantity unit.
  • products[]['skus'][]['order_count_min'] float Minimum orderable product quantity in the decimal(15,3) format.
  • products[]['skus'][]['order_count_step'] float float Quantity adjustment value with “+/-” buttons in the decimal(15,3) format.
  • products[]['skus'][]['status'] int Visibility in the storefront.
  • products[]['skus'][]['file_name'] string Attached file’s name.
  • products[]['skus'][]['file_size'] int Attached file’s size in bytes.
  • products[]['skus'][]['file_description'] string Attached file’s description.
  • products[]['skus'][]['stocks'][''] array Variant’s stock quantities data array. Is available in the response if the fields parameter contains the stock_counts value. Array keys are stock IDs and values are product variant’s quantities available on each of the stocks, in the decimal(15,3) format.
  • products[]['images'] array Product images data array. Is available in the response if the fields parameter contains the images value. Each image’s sub-array contains values with the following keys:
  • products[]['images'][]['id'] int.
  • products[]['images'][]['product_id'] int ID of the product to which the image belongs.
  • products[]['images'][]['upload_datetime'] datetime.
  • products[]['images'][]['sort'] int.
  • products[]['images'][]['width'] int Width in pixels.
  • products[]['images'][]['height'] int Height in pixels.
  • products[]['images'][]['size'] int File size in bytes.
  • products[]['images'][]['original_filename'] string Original name of the uploaded image file.
  • products[]['images'][]['ext'] string File name extension.
  • products[]['images'][]['url_thumb'] string Image thumbnail URL with the '200x0' size.
  • products[]['images'][]['url_crop'] string Image thumbnail URL with the '96x96' size.
  • products[]['images'][]['url_big'] string Image thumbnail URL with the '970' size.

Example

https://demo1.webasyst.com/api.php/shop.product.search?