search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Facets

Facets partition and provides counts of your data, allowing you to summarize large amounts of data. The two facet types provided are the value facet and the range facet.

Value Facet

A value facet provides the counts of each value for a field. Facets request objects are in the following format.

When faceting on a field that contains an array of values, each unique value in the array will be included in the response. A document value of ["green", "blue", "green"] will only be counted once for the value "green" and the value "blue".

type
required
Type of facet, in this case it will be value.
size
optional
Number of facets to return. Defaults to 10; max of 250.
sort
optional
Object where the key is either count or value and the value is asc or desc. The default is sorting by descending count.

Example - Getting the top five colors of vehicles matching the query "toyota".
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "facets": {
        "color": [
            {
                "type": "value",
                "sort": { "count": "desc" },
                "size": 5
            }
        ]
    }
}'
Example Response
{
    "meta": {
        "page": {
            "current": 1,
            "total_pages": 3,
            "total_results": 25,
            "size": 10
        },
        "request_id": "b052faa06792f1874808ddbc8805a52c"
    },
    "results": [
      ... # redacted
    ],
    "facets": {
        "color": [
            {
                "type": "value",
                "data": [
                    {
                        "value": "blue",
                        "count": 5
                    },
                    {
                        "value": "black",
                        "count": 4
                    },
                    {
                        "value": "red",
                        "count": 2
                    },
                    {
                        "value": "green",
                        "count": 2
                    },
                    {
                        "value": "beige",
                        "count": 1
                    }
                ]
            }
        ]
    }
}

If you only require one facet per field, you may format the facets parameter as a dictionary with the field name as the key and a dictionary representing the facet request object (instead of a list of facet request objects). The response will not change.

Range Facet

The range facet is available on number and location fields. It returns counts of documents within the provided ranges.

When faceting on a field that contains an array of values, the document can only be added to a bucket once. A document value of [1, 3, 8, 10] will only be counted once for each bucket if the given buckets are { "from": 1, "to": 5 } and { "from": 5, "to" 10 }.

Ranges are specified with a ranges dictionary. It follows the format:

from
optional
Inclusive lower bound of the range. Is required if from is not given.
to
optional
Exclusive upper bound of the range. Is required if to is not given.
name
optional
Name given to the range.

Range Facet on a Number Field

type
required
Type of facet, in this case it will be range.
ranges
required
Ranges dictionary specifying ranges to get counts for. It must contain a to and from key.

Example - Getting the top ten colors of vehicles matching the query "toyota".
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "facets": {
        "daily_rate": [
            {
                "type": "range",
                "ranges": [
                    { "from": 50, "to": 100 },
                    { "from": 100, "to": 150 }
                ]
            }
        ]
    }
}'
Example Response
{
    "meta": {
        "page": {
            "current": 1,
            "total_pages": 3,
            "total_results": 25,
            "size": 10
        },
        "request_id": "b052faa06792f1874808ddbc8805a52c"
    },
    "results": [
      ... # redacted
    ],
    "facets": {
        "daily_rate": [
            {
                "type": "range",
                "data": [
                    {
                        "to": 100.0,
                        "from": 50.0,
                        "count": 7
                    },
                    {
                        "to": 150.0,
                        "from": 100.0,
                        "count": 9
                    }
                ]
            }
        ]
    }
}

Range Facet on a Geo Field

type
required
Type of facet, in this case it will be range.
ranges
required
Ranges dictionary specifying ranges to get counts for. It must contain at least a from or to key. When specifying the range from is inclusive and to is exclusive.
center
required
The mode of the distribution as a string in "[latitude], [longitude]" format.
unit
required
The base unit of measurement: mm, cm, m (meters), km, in, ft, yd, or mi (mile).

Example - Getting the counts of vehicles within the provided ranges.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "",
    "facets": {
        "current_location": [
            {
                "type": "range",
                "center": "52.3760, 4.894",
                "unit": "m",
                "ranges": [
                    { "from": 0, "to": 100000, "name": "close by" },
                    { "from": 100000, "to": 300000 },
                    { "from": 300000 }
                ]
            }
        ]
    }
}'
Example Response
{
    "meta": {
        "page": {
            "current": 1,
            "total_pages": 3,
            "total_results": 25,
            "size": 10
        },
        "request_id": "b052faa06792f1874808ddbc8805a52c"
    },
    "results": [
        ... # redacted
    ],
    "facets": {
         "current_location": [
             {
                 "type": "range",
                 "data": [
                     {
                         "to": 100000.0,
                         "from": 0.0,
                         "count": 8,
                         "name": "close by"
                     },
                     {
                         "to": 300000.0,
                         "from": 100000.0,
                         "count": 3
                     },
                     {
                         "from": 300000.0,
                         "count": 2
                     }
                 ]
             }
         ]
    }

}