ItemExtend

Search and FilterSets

Our search is powered by ElasticSearch on the backend. This endpoint is a simplified way of querying this search backend so you don't have to handle the complexities of ElasticSearch queries.

In an effort to streamline development, you can define FilterSets in the administrative backend of ItemExtend that can be used to sort and filter various aspects of your queries.

Search Endpoints

List

GET /api/search/?q=Brown

GET /api/search/?fs=1

This is the search endpoint. It requires either a q or fs query parameter

Search Parameters

q - Query

The search term you you would like to search for.

fs - FilterSet

the id of the filterset you would like to use.

p - Page

The page of results you would like. This is 1 indexed

rc - ResultsCount

the number of results per page you'd like returned. This defaults to 30.

rt - ResultsType

The type of item you'd like returned from search. current options are 'stock_item' and 'mxcategory'

o - Order

The order of the results based on the available sorting options in your FilterSet. Multiple sorting options should be passed as a comma delimited string.

Filters

If using a FilterSet, any of the filters can be used by adding the filter's attribute field and using the bucket's key value from the returned facets of the search. See Examples

Search Result Fields

params

This will return the parameters passed into the search for easy reference

facets

If you have provided a FilterSet to the search, this will return an object with keys that match the names of your filters. Each key will be an object containing the following:

  • buckets: Array of Objects
    • each object will have a key and doc_count
    • key is the value used to filter by this type.
    • doc_count is the number of results in this filter
  • sum_other_doc_count: the doc_count of all of the facets that are too small to be considered their own bucket. Only applies to Choice and MultiChoice Filters.
  • interval: The difference between each bucketOnly applies to Range Filters

results_total

This is a count of the total number of results in this search.

results

An array of search results. Each result object will have the following:

  • _id
    • This is the object's id.
  • _type
    • This will be either 'mxcategory'or 'stock_item'.
  • _source
    • This will be a flattened version of either a StockItem or an MxCategory. StockItems will need to be matched against the Price endpoint.

filters

This is an object of the currently active filters (if any).

Filterset Endpoints

List

GET /api/search/filtersets/

lists ALL available FilterSets for search fs query param

FilterSet Fields

id

  • Type: Number

the ID of the filterset. To be used with the fs query param.

sort_fields

  • Type: Array of Objects

a sort_field is used with the o search parameter.

A sort_field is composed of the following:

  • name - Display name of the sort field.
  • value - the value to be used with the o search parameter

filters

  • Type: Array of Object

Each filter has the following fields:

  • id - an identifier
  • visible - a boolean to denote if this filter is seen by the user
  • name - a User Facing name of the filter
  • attribute - the identifier used as a parameter for filtering
  • widget_type - the type of widget to be used this can be range, choice, multichoice, or special
  • value_prefix - string to be appended to the front of the value (useful for cost)
  • value_suffix - string to be appened to the end of the value (useful for cost)

name

  • Type: String

an identifier string for this filter.

Example Search pattern

First we will query the FilterSets to find out what our filtersets are

GET /api/search/filtersets/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Cache-Control: no-cache, no-store, must-revalidate, max-age=0
Content-Type: application/json
Expires: Thu, 12 Jul 2018 20:02:44 GMT
Last-Modified: Thu, 12 Jul 2018 20:02:44 GMT
Vary: Accept

[
    {
        "id": 1,
        "sort_fields": [
            {
                "name": "Relevancy",
                "value": "_score"
            },
            {
                "name": "Cost (low to high)",
                "value": "average_cost"
            },
            {
                "name": "Cost (high to low)",
                "value": "-average_cost"
            },
        ],
        "filters": [
            {
                "id": 1,
                "visible": true,
                "name": "Brand",
                "attribute": "brand",
                "widget_type": "multichoice",
                "value_prefix": "",
                "value_suffix": ""
            },
            {
                "id": 6,
                "visible": false,
                "name": "mxcategory",
                "attribute": "mxcategory",
                "widget_type": "choice",
                "value_prefix": "",
                "value_suffix": ""
            },
            {
                "id": 3,
                "visible": true,
                "name": "Cost",
                "attribute": "average_cost",
                "widget_type": "range",
                "value_prefix": "$",
                "value_suffix": ".00"
            },
        ],
        "name": "basic_filter"
    }
]

GET /api/search/?fs=1&rt=stock_item&rc=10

← StockItems →