API Reference

Aggregation

This document describes how to use aggregation through the API

Range filter

Let's say we have an aggregation like this returned in the API response:

{
  "suggestion": {},
  "product": {
    "items": [
      {
        "id": "1",
        "fields": {
          "title": "Samsung s7 edge",
          "manufacturer": "samsung",
          "price": 5.99
        }
      },
      {
        "id": "2",
        "fields": {
          "title": "Iphone 14 Pro max",
          "manufacturer": "apple",
          "price": 49.99
        }
      }
    ],
    "aggregations": {
      "price": {
        "title": "Price",
        "key": "price",
        "type": "range_slider",
        "values": null,
        "min": 0,
        "max": 1599,
        "selectedValues": null,
        "position": 999,
        "showDocCount": null
      }
    },
    "additionalData": []
  },
  "snippets": {},
  "banners": []
}

We can now use this to filter down to products that have prices from 1 to 10 by putting aggregations into the API request body:

{
    // Other fields like searchPhrase, isSearch, constraints,...
    "enableAggregations": true, // This must be true in order to use aggregations
    "aggregations": {
        "price_from": 1,
        "price_to": 10
    }
}

The response will look a little bit different from before, selectedValues will be set accordingly

and also items will be filtered down to 1 item

{
  "product": {
    "items": [
      {
        "id": "1",
        "fields": {
          "title": "Samsung s7 edge",
          "manufacturer": "samsung",
          "price": 5.99
        }
      }
    ],
    "aggregations": {
      "price": {
        "title": "Price",
        "key": "price",
        "type": "range_slider",
        "values": null,
        "min": 0,
        "max": 1599,
        "selectedValues": {
          "from": 1,
          "to": 5
        },
        "position": 999,
        "showDocCount": null
      }
    },
    "additionalData": []
  }
}

List filter

Let's say we have an aggregation like this returned in the API response:

{
  "suggestion": {},
  "product": {
    "items": [
      {
        "id": "1",
        "fields": {
          "title": "Samsung s7 edge",
          "manufacturer": "samsung",
          "price": 5.99
        }
      },
      {
        "id": "2",
        "fields": {
          "title": "Iphone 14 Pro max",
          "manufacturer": "apple",
          "price": 49.99
        }
      }
    ],
    "aggregations": {
      "manufacturer": {
        "title": "Manufacturer",
        "key": "manufacturer",
        "type": "list",
        "values": {
          "samsung": {
            "key": "samsung",
            "count": 1
          },
          "apple": {
            "key": "apple",
            "count": 1
          }
        },
        "min": null,
        "max": null,
        "selectedValues": null,
        "position": 999,
        "showDocCount": true
      }
    },
    "additionalData": []
  },
  "snippets": {},
  "banners": []
}

We can now use this to filter down to products made by apple by putting aggregations into the API request body:

{
    // Other fields like searchPhrase, isSearch, constraints,...
    "enableAggregations": true, // This must be true in order to use aggregations
    "aggregations": {
        "manufacturer": [
            "apple"
        ]
    }
}

The response will look a little bit different from before, selectedValues will be set accordingly

and also items will also be filtered down to 1 item

{
  "product": {
    "items": [
      {
        "id": "2",
        "fields": {
          "title": "Iphone 14 Pro max",
          "manufacturer": "apple",
          "price": 49.99
        }
      }
    ],
    "aggregations": {
      "manufacturer": {
        "title": "Manufacturer",
        "key": "manufacturer",
        "type": "list",
        "values": {
          "apple": {
            "key": "apple",
            "count": 1
          }
        },
        "min": null,
        "max": null,
        "selectedValues": [
        	"apple"
        ],
        "position": 999,
        "showDocCount": true
      }
    },
    "additionalData": []
  }
}

List multi-select filter

Let's say we have an aggregation like this returned in the API response:

{
  "suggestion": {},
  "product": {
    "items": [
      {
        "id": "1",
        "fields": {
          "title": "Samsung s7 edge",
          "manufacturer": "samsung",
          "price": 5.99
        }
      },
      {
        "id": "2",
        "fields": {
          "title": "Iphone 14 Pro max",
          "manufacturer": "apple",
          "price": 49.99
        }
      },
      {
        "id": "3",
        "fields": {
          "title": "Sony Xperia 5",
          "manufacturer": "sony",
          "price": 19.99
        }
      }
    ],
    "aggregations": {
      "manufacturer": {
        "title": "Manufacturer",
        "key": "manufacturer",
        "type": "list_multiselect",
        "values": {
          "samsung": {
            "key": "samsung",
            "count": 1
          },
          "apple": {
            "key": "apple",
            "count": 1
          },
          "sony": {
            "key": "sony",
            "count": 1
          }
        },
        "min": null,
        "max": null,
        "selectedValues": null,
        "position": 999,
        "showDocCount": true
      }
    },
    "additionalData": []
  },
  "snippets": {},
  "banners": []
}

We can now use this to filter down to products made by apple and/or (depends on how you set up the operator of the aggregation) sony by putting aggregations into the API request body:

{
    // Other fields like searchPhrase, isSearch, constraints,...
    "enableAggregations": true, // This must be true in order to use aggregations
    "aggregations": {
        "manufacturer": [
            "apple",
            "sony"
        ]
    }
}

The response will look a little bit different from before, selectedValues will be set accordingly

and also items will also be filtered down to 1 item

{
  "product": {
    "items": [
      {
        "id": "2",
        "fields": {
          "title": "Iphone 14 Pro max",
          "manufacturer": "apple",
          "price": 49.99
        }
      },
      {
        "id": "3",
        "fields": {
          "title": "Sony Xperia 5",
          "manufacturer": "sony",
          "price": 19.99
        }
      }
    ],
    "aggregations": {
      "manufacturer": {
        "title": "Manufacturer",
        "key": "manufacturer",
        "type": "list_multiselect",
        "values": {
          "apple": {
            "key": "apple",
            "count": 1
          },
          "sony": {
            "key": "sony",
            "count": 1
          }
        },
        "min": null,
        "max": null,
        "selectedValues": [
          "apple",
          "sony"
        ],
        "position": 999,
        "showDocCount": true
      }
    },
    "additionalData": []
  }
}