Search API Documentation

You can use our Search API if you wish to build and maintain your own UI or integrating into an existing search framework.

Search for products

Returns a list of products. The results are returned in sorted order, with the most relevant products to the search term appearing first.

GET https://aix.salesfire.co.uk/api/search

General Parameters

  • client_id - (string: required) - Site ID (This can be found within your Salesfire Dashboard).
  • query - (string: optional) - Search term that you want to find products for. If there's no query string provided products are returned in sorted order, with the most purchased products appearing first.
  • limit - (int: optional, default 100) - A limit on the number of products to be returned, between 1 and 100.
  • page - (int: optional, default 1) - Requested page. When specified, will retrieve a specific page; should be used in conjunction with limit to achieve a paginated set of results.
  • query_spellchecker - (bool: optional, default false) Make adjustments to the way spelling is calculated to potentially improve search results.
  • sort_by - (string: optional, default null) Determines what to sort by. Can be the following values purchases, views, price, savings, null.
  • sort_dir - (string: optional, default null) Determines the direction of sort. Can be the following values asc, desc, null.

Filter Parameters

  • show_out_of_stock - (boolean: optional, default true) If enabled, products that are out of stock will not be returned.
  • categories - (array: optional) Return products that only belong to the provided categories
  • brands - (array: optional) Return products that only belong to the provided brands
  • attributes - (array: optional) Return products that only have the provided attributes (colour)

The array of categories, brands and attributes are the IDs of those returned in the response.

Weighting Parameters

All values must be between 0 and 2.0, the higher the weighting the more the matching products will be boosted by.

  • title - (float: optional, default 1.2) - Weight results higher where title contains search term.
  • brand - (float: optional, default 1.2) - Weight results higher where brand contains search term.
  • category - (float: optional, default 0.4) - Weight results higher where category contains search term.
  • description - (float: optional, default 0.2) - Weight results higher where description contains search term.
  • synonyms - (float: optional, default 0.1) - Weight results higher where synonyms contains search term.
  • colour - (float: optional, default 1.0) - Weight results higher where colour contains search term.
  • size - (float: optional, default 1.0) - Weight results higher where size contains search term.
  • gender - (float: optional, default 2.0) - Weight results higher where gender contains search term.
  • age_group - (float: optional, default 1.2) - Weight results higher where age group contains search term.
  • stock_availability - (float: optional, default 1.0) - Weight results higher if they are in stock.
  • image_tag - (float: optional, default 1.0) - Weight results higher where images match the search term.

Example

curl -G -X GET https://aix.salesfire.co.uk/api/search \
  -d client_id={YOUR_CLIENT_ID} \
  -d query=chronograph \
  -d "filters[attributes][]=1ffd9e" \
  -d "weights[title]=0.12" \
  -d "weights[brand]=0.12" \
  -d "weights[description]=0.180" \
  -d limit=10
{
    "client": "3f32397c-21c6-47e5-9ebd-e9865ea03470",
    "original_query": "chronograph",
    "corrected_query": "chronograph",
    "products": [
        {
            "id": "s26369",
            "title": "AR2447 Emporio Black Leather Mens Chronograph Watch",
            "brand": "Armani",
            "price": {
                "min": 119.95,
                "max": 119.95,
                "savings": 130.05,
                "currency": "GBP",
                "unit": null
            },
            "image_url": "https://www.ticwatches.co.uk/images/armani-ar2447-emporio-black-leather-mens-chronograph-watch-p26010-13572_image.jpg",
            "images": {
                "black": "https://www.ticwatches.co.uk/images/armani-ar2447-emporio-black-leather-mens-chronograph-watch-p26010-13572_image.jpg"
            },
            "link": "https://www.ticwatches.co.uk/armani-ar2447-emporio-black-leather-mens-chronograph-watch-p26010/s26369?cid=GBP&glCurrency=GBP&glCountry=GB",
            "links": {
                "black": "https://www.ticwatches.co.uk/armani-ar2447-emporio-black-leather-mens-chronograph-watch-p26010/s26369?cid=GBP&glCurrency=GBP&glCountry=GB"
            },
            "in_stock": true,
            "docid": 5646,
            "score": 402.1394080193016
        }
        ...
    ],
    "suggested": [],
    "filters": [
        {
            "key": "categories",
            "items": [
                {
                    "id": "02b009",
                    "name": "Black Watches",
                    "breadcrumb": "Black Watches",
                    "link": "",
                    "count": 19
                },
                {
                    "id": "32df2c",
                    "name": "Mens Watches",
                    "breadcrumb": "Mens Watches",
                    "link": "",
                    "count": 108
                }
                ...
            ]
        },
        {
            "key": "brands",
            "items": [
                {
                    "id": "10b224",
                    "name": "Armani",
                    "count": 51
                },
                {
                    "id": "1428e3",
                    "name": "Tommy Hilfiger",
                    "count": 6
                }
                ...
            ]
        },
        {
            "key": "attributes",
            "items": [
                {
                    "id": "1ffd9e",
                    "name": "black",
                    "count": 81,
                    "type": "colour"
                },
                {
                    "id": "48d621",
                    "name": "blue",
                    "count": 29,
                    "type": "colour"
                }
                ...
            ]
        }
    ],
    "total_pages": 2,
    "promotions": [],
    "redirect": null,
    "time": 0.004701137542724609,
    "timestamp": 1611288637
}

Errors

500: Internal Server Error - The client may not exist or we had a problem responding to your request.

{
    "status": 500,
    "error": "500 Internal Server Error",
    "message": "No client given",
    "class": "Exception"
}