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

We have a conceptual Facets guide, too.


Create value and range facets.

Type Value Facet Range Facet
text Yes No
number Yes Yes
date Yes Yes
geolocation No Yes

Value Facet

Provides the counts of each value for a field.

When faceting on an array field, each unique value will be included in the response.

Each value is only counted once.

Available on text, number, date fields.

query
required
Each request is considered a query against your engine. The query provides scope for the facet.
facets
required
The facets key opens up the object where you define your facet field.
field key
required
The field from your schema upon which to apply your facet.
type
required
Type of facet, in this case it will be value.
name
optional
Name given to facet.
size
optional
How many facets would you like to return? Can be between 1 and 250. 10 facets is the default.
sort
optional
JSON 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 states which have matches on the query "parks" in a facet named "top-five-states".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "states": [
      {
        "type": "value",
        "name": "top-five-states",
        "sort": { "count": "desc" },
        "size": 5
      }
    ]
  }
}'
Example Response
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "c98ba1eaa5c8bbc098e0be36644b04f7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "states": [
      {
        "type": "value",
        "name": "top-five-states",
        "data": [
          {
            "value": "California",
            "count": 8
          },
          {
            "value": "Alaska",
            "count": 5
          },
          {
            "value": "Utah",
            "count": 4
          },
          {
            "value": "Colorado",
            "count": 3
          },
          {
            "value": "Washington",
            "count": 3
          }
        ]
      }
    ]
  }
}

Example - Getting the top five states which have matches on the query "parks" in a facet named "top-five-states".
import com.swiftype.appsearch.Client;
import com.swiftype.appsearch.ClientException;
import java.util.*;

Client client = new Client("host-2376rb", "search-soaewu2ye6uc45dr8mcd54v8");

String engineName = "national-parks-demo"; String query = "park";

Map<String, Object> sort = new HashMap<>(); sort.put("count", "desc");

Map<String, Object> statesFacet = new HashMap<>(); statesFacet.put("type", "value"); statesFacet.put("name", "top-five-states"); statesFacet.put("sort", sort); statesFacet.put("size", 5);

Map<String, Object> facets = new HashMap<>(); facets.put("states", Arrays.asList(statesFacet));

Map<String, Object> options = new HashMap<>(); options.put("facets", facets);

try { Map<String, Object> response = client.search(engineName, query, options); System.out.println(response); } catch (ClientException e) { System.out.println(e); }

Example Response
Map<String, Object>: {
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "c98ba1eaa5c8bbc098e0be36644b04f7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "states": [
      {
        "type": "value",
        "name": "top-five-states",
        "data": [
          {
            "value": "California",
            "count": 8
          },
          {
            "value": "Alaska",
            "count": 5
          },
          {
            "value": "Utah",
            "count": 4
          },
          {
            "value": "Colorado",
            "count": 3
          },
          {
            "value": "Washington",
            "count": 3
          }
        ]
      }
    ]
  }
}

Example - Getting the top five states which have matches on the query "parks" in a facet named "top-five-states".
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const client = new SwiftypeAppSearchClient('host-2376rb', 'search-soaewu2ye6uc45dr8mcd54v8')

const engineName = 'national-parks-demo' const query = 'park'

const options = { facets: { states: [ { type: 'value', name: 'top-five-states', sort: { count: 'desc' }, size: 5 } ] } }

client .search(engineName, query, options) .then(response => console.log(response)) .catch(error => console.log(error))

Example Response
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "c98ba1eaa5c8bbc098e0be36644b04f7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "states": [
      {
        "type": "value",
        "name": "top-five-states",
        "data": [
          {
            "value": "California",
            "count": 8
          },
          {
            "value": "Alaska",
            "count": 5
          },
          {
            "value": "Utah",
            "count": 4
          },
          {
            "value": "Colorado",
            "count": 3
          },
          {
            "value": "Washington",
            "count": 3
          }
        ]
      }
    ]
  }
}

Example - Getting the top five states which have matches on the query "parks" in a facet named "top-five-states".
require 'swiftype-app-search'

host_identifier = 'host-2376rb' api_key = 'search-soaewu2ye6uc45dr8mcd54v8' client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'national-parks-demo' query = 'park'

options = { facets: { states: [ { type: 'value', name: 'top-fix-states', sort: { count: 'desc' }, size: 5 } ] } }

begin puts client.search(engine_name, query, options) rescue SwiftypeAppSearch::ClientException => e puts e end

Example Response
{
  'meta' => {
    'page' => {
      'current' => 1,
      'total_pages' => 5,
      'total_results' => 46,
      'size' => 10
    },
    'request_id' => 'b052faa06792f1874808ddbc8805a52c'
  },
  'results' => [
    ## Truncated!
  ],
  'facets' => {
    'states' => [
      {
        'type' => 'value',
        'name' => 'top-five-states',
        'data' => [
          {
            'value' => 'California',
            'count' => 8
          },
          {
            'value' => 'Alaska',
            'count' => 5
          },
          {
            'value' => 'Utah',
            'count' => 4
          },
          {
            'value' => 'Colorado',
            'count' => 3
          },
          {
            'value' => 'Washington',
            'count' => 3
          }
        ]
      }
    ]
  }
}

Example - Getting the top five states which have matches on the query "parks" in a facet named "top-five-states".
from swiftype_app_search import Client
from swiftype_app_search.exceptions import SwiftypeAppSearchError

host_identifier = 'host-2376rb' api_key = 'search-soaewu2ye6uc45dr8mcd54v8' client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo' query = 'park'

options = { 'facets': { 'states': [ { 'type': 'value', 'name': 'top-five-states', 'sort': {'count': 'desc'}, 'size': 5 } ] } }

try: print(client.search(engine_name, query, options)) except SwiftypeAppSearchError as e: print(e)

Example Response
{
    'meta': {
        'page': {
            'current': 1,
            'total_pages': 5,
            'total_results': 46,
            'size': 10
        },
        'request_id': 'b052faa06792f1874808ddbc8805a52c'
    },
    'results': [
        ## Truncated!
    ],
    'facets': {
        'states': [
            {
                'type': 'value',
                'name': 'top-five-states',
                'data': [
                    {
                        'value': 'California',
                        'count': 8
                    },
                    {
                        'value': 'Alaska',
                        'count': 5
                    },
                    {
                        'value': 'Utah',
                        'count': 4
                    },
                    {
                        'value': 'Colorado',
                        'count': 3
                    },
                    {
                        'value': 'Washington',
                        'count': 3
                    }
                ]
            }
        ]
    }
}

Example - Getting the top five states which have matches on the query "parks" in a facet named "top-five-states".
const client = SwiftypeAppSearch.createClient({
  hostIdentifier: 'host-2376rb',
  searchKey: 'search-soaewu2ye6uc45dr8mcd54v8',
  engineName: 'national-parks-demo'
})

const query = 'everglade'

const options = { facets: { states: [ { type: 'value', name: 'top-five-states', sort: { count: 'desc' }, size: 5 } ] } }

client .search(query, options) .then(function(response){ console.log(response) }) .catch(function(error){ console.log(error) })

Example Response
ResultList {
  "rawResults": [
    ## Truncated!
  ],
  "rawInfo": {
    ## Truncated! Same as ResultList.info.
  },
  "results": [
    ## Truncated!
  ],
  "info": {
    "meta": {
      "alerts": [],
      "warnings": [],
      "page": {
        "current": 1,
        "total_pages": 5,
        "total_results": 46,
        "size": 10
      },
      "request_id": "f039b12b767d1aaa0e7aea7b33d7871c"
    },
    "facets": {
      "states": [
        {
          "type": "value",
          "name": "top-five-states",
          "data": [
            {
              "value": "California",
              "count": 8
            },
            {
              "value": "Alaska",
              "count": 5
            },
            {
              "value": "Utah",
              "count": 4
            },
            {
              "value": "Colorado",
              "count": 3
            },
            {
              "value": "Washington",
              "count": 3
            }
          ]
        }
      ]
    }
  }
}

Range Facet

Returns counts of documents within the provided ranges.

Each number is only counted once.

Dates match RFC3339 format.

Available on number, date, geolocation fields.

query
required
Each request is considered a query against your engine. The query provides scope for the facet.
facets
required
The facets key opens up the object where you define your facet field.
field key
required
The field from your schema upon which to apply your facet.
type
required
Type of facet, in this case it will be range.
name
optional
Name given to facet.
ranges
required
An array of range objects.
from
optional
Inclusive lower bound of the range. Is required if to is not given.
to
optional
Exclusive upper bound of the range. Is required if from is not given.
name
optional
Name given to the range.
Range Facet on a Number Field
Example - Getting the counts for small and large parks, based on acreage, for the "park" query, within a facet named "min-and-max-range".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "acres": [
      {
        "type": "range",
        "name": "min-and-max-range",
        "ranges": [
          { "from": 1, "to": 10000 },
          { "from": 10000 }
        ]
      }
    ]
  }
}'
Example Response
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "92bfcf6d-307c-4ca6-b12c-ac21283244e3"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "acres": [
      {
        "type": "range",
        "name": "min-and-max-range",
        "data": [
          {
            "to": 10000,
            "from": 1,
            "count": 2
          },
          {
            "from": 10000,
            "count": 44
          }
        ]
      }
    ]
  }
}

Example - Getting the counts for small and large parks, based on acreage, for the "park" query, within a facet named "min-and-max-range".
import com.swiftype.appsearch.Client;
import com.swiftype.appsearch.ClientException;
import java.util.*;

Client client = new Client("host-2376rb", "search-soaewu2ye6uc45dr8mcd54v8");

String engineName = "national-parks-demo"; String query = "park";

Map<String, Object> range1 = new HashMap<>(); range1.put("from", 1); range1.put("to", 10000); Map<String, Object> range2 = new HashMap<>(); range2.put("from", 10000);

Map<String, Object> acresFacet = new HashMap<>(); acresFacet.put("type", "range"); acresFacet.put("name", "min-and-max-range"); acresFacet.put("ranges", Arrays.asList(range1, range2));

Map<String, Object> facets = new HashMap<>(); facets.put("acres", Arrays.asList(acresFacet));

Map<String, Object> options = new HashMap<>(); options.put("facets", facets);

try { Map<String, Object> response = client.search(engineName, query, options); System.out.println(response); } catch (ClientException e) { System.out.println(e); }

Example Response
Map<String, Object>: {
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "92bfcf6d-307c-4ca6-b12c-ac21283244e3"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "acres": [
      {
        "type": "range",
        "name": "min-and-max-range",
        "data": [
          {
            "to": 10000,
            "from": 1,
            "count": 2
          },
          {
            "from": 10000,
            "count": 44
          }
        ]
      }
    ]
  }
}

Example - Getting the counts for small and large parks, based on acreage, for the "park" query, within a facet named "min-and-max-range".
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const client = new SwiftypeAppSearchClient('host-2376rb', 'search-soaewu2ye6uc45dr8mcd54v8')

const engineName = 'national-parks-demo' const query = 'park'

const options = { facets: { acres: [ { type: 'range', name: 'min-and-max-range', ranges: [ { from: 1, to: 10000 }, { from: 10000 } ] } ] } }

client .search(engineName, query, options) .then(response => console.log(response)) .catch(error => console.log(error))

Example Response
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "92bfcf6d-307c-4ca6-b12c-ac21283244e3"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "acres": [
      {
        "type": "range",
        "name": "min-and-max-range",
        "data": [
          {
            "to": 10000,
            "from": 1,
            "count": 2
          },
          {
            "from": 10000,
            "count": 44
          }
        ]
      }
    ]
  }
}

Example - Getting the counts for small and large parks, based on acreage, for the "park" query, within a facet named "min-and-max-range".
require 'swiftype-app-search'

host_identifier = 'host-2376rb' api_key = 'search-soaewu2ye6uc45dr8mcd54v8' client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'national-parks-demo' query = 'park' options = { facets: { acres: [ { type: 'range', name: 'min-and-max-range', ranges: [ { from: 1, to: 10000 }, { from: 10000 } ] } ] } }

begin puts client.search(engine_name, query, options) rescue SwiftypeAppSearch::ClientException => e puts e end

Example Response
{
  'meta' => {
    'warnings' => [],
    'page' => {
      'current' => 1,
      'total_pages' => 5,
      'total_results' => 46,
      'size' => 10
    },
    'request_id' => 'f8b005f719c6a34de76f92968190e308'
  },
  'results' => [
    ## Truncated!
  ],
  'facets' => {
    'acres' => [
      {
        'type' => 'range',
        'name' => 'min-and-max-range',
        'data' => [
          {
            'to' => 10_000,
            'from' => 1,
            'count' => 2
          },
          {
            'from' => 10_000,
            'count' => 44
          }
        ]
      }
    ]
  }
}

Example - Getting the counts for small and large parks, based on acreage, for the "park" query, within a facet named "min-and-max-range".
from swiftype_app_search import Client
from swiftype_app_search.exceptions import SwiftypeAppSearchError

host_identifier = 'host-2376rb' api_key = 'search-soaewu2ye6uc45dr8mcd54v8' client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo' query = 'park'

options = { 'facets': { 'acres': [ { 'type': 'range', 'name': 'min-and-max-range', 'ranges': [ {'from': 1, 'to': 10000}, {'from': 10000} ] } ] } }

try: print(client.search(engine_name, query, options)) except SwiftypeAppSearchError as e: print(e)

Example Response
{
    'meta': {
        'warnings': [],
        'page': {
            'current': 1,
            'total_pages': 5,
            'total_results': 46,
            'size': 10
        },
        'request_id': 'f8b005f719c6a34de76f92968190e308'
    },
    'results': [
        ## Truncated!
    ],
    'facets': {
        'acres': [
            {
                'type': 'range',
                'name': 'min-and-max-range',
                'data': [
                    {
                        'to': 10000,
                        'from': 1,
                        'count': 2
                    },
                    {
                        'from': 10000,
                        'count': 44
                    }
                ]
            }
        ]
    }
}

Example - Getting the counts for small and large parks, based on acreage, for the "park" query, within a facet named "min-and-max-range".
const client = SwiftypeAppSearch.createClient({
  hostIdentifier: 'host-2376rb',
  searchKey: 'search-soaewu2ye6uc45dr8mcd54v8',
  engineName: 'national-parks-demo'
})

const query = 'park'

const options = { facets: { acres: [ { type: 'range', name: 'min-and-max-range', ranges: [ { from: 1, to: 10000 }, { from: 10000 } ] } ] } }

client .search(query, options) .then(function(response){ console.log(response) }) .catch(function(error){ console.log(error) })

Example Response
ResultList {
  "rawResults": [
    ## Truncated!
  ],
  "rawInfo": {
    ## Truncated! Same as ResultList.info.
  },
  "results": [
    ## Truncated!
  ],
  "info": {
    "meta": {
      "alerts": [],
      "warnings": [],
      "page": {
        "current": 1,
        "total_pages": 5,
        "total_results": 46,
        "size": 10
      },
      "request_id": "ee7a34ce9383d2674df559e587d9ea4b"
    },
    "facets": {
      "acres": [
        {
          "type": "range",
          "name": "min-and-max-range",
          "data": [
            {
              "to": 10000,
              "from": 1,
              "count": 2
            },
            {
              "from": 10000,
              "count": 44
            }
          ]
        }
      ]
    }
  }
}

Range Facet on a Date Field
Example - Getting a list of "parks" that were established between 1900 and 1950. RFC3339 formatted dates. The facet is named "half-century".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "ranges": [
          { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" }
        ]
      }
    ]
  }
}'
Example Response
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "bb038d5920f65692ccafd569ce86c3a7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "data": [
          {
            "to": "1950-01-01T00:00:00.000Z",
            "from": "1900-01-01T12:00:00.000Z",
            "count": 15
          }
        ]
      }
    ]
  }
}

Example - Getting a list of "parks" that were established between 1900 and 1950. RFC3339 formatted dates. The facet is named "half-century".
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "ranges": [
          { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" }
        ]
      }
    ]
  }
}'
Example Response
No Java example available, showing cURL
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "bb038d5920f65692ccafd569ce86c3a7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "data": [
          {
            "to": "1950-01-01T00:00:00.000Z",
            "from": "1900-01-01T12:00:00.000Z",
            "count": 15
          }
        ]
      }
    ]
  }
}

Example - Getting a list of "parks" that were established between 1900 and 1950. RFC3339 formatted dates. The facet is named "half-century".
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "ranges": [
          { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" }
        ]
      }
    ]
  }
}'
Example Response
No Node example available, showing cURL
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "bb038d5920f65692ccafd569ce86c3a7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "data": [
          {
            "to": "1950-01-01T00:00:00.000Z",
            "from": "1900-01-01T12:00:00.000Z",
            "count": 15
          }
        ]
      }
    ]
  }
}

Example - Getting a list of "parks" that were established between 1900 and 1950. RFC3339 formatted dates. The facet is named "half-century".
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "ranges": [
          { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" }
        ]
      }
    ]
  }
}'
Example Response
No Ruby example available, showing cURL
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "bb038d5920f65692ccafd569ce86c3a7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "data": [
          {
            "to": "1950-01-01T00:00:00.000Z",
            "from": "1900-01-01T12:00:00.000Z",
            "count": 15
          }
        ]
      }
    ]
  }
}

Example - Getting a list of "parks" that were established between 1900 and 1950. RFC3339 formatted dates. The facet is named "half-century".
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "ranges": [
          { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" }
        ]
      }
    ]
  }
}'
Example Response
No Python example available, showing cURL
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "bb038d5920f65692ccafd569ce86c3a7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "data": [
          {
            "to": "1950-01-01T00:00:00.000Z",
            "from": "1900-01-01T12:00:00.000Z",
            "count": 15
          }
        ]
      }
    ]
  }
}

Example - Getting a list of "parks" that were established between 1900 and 1950. RFC3339 formatted dates. The facet is named "half-century".
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "park",
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "ranges": [
          { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" }
        ]
      }
    ]
  }
}'
Example Response
No Javascript example available, showing cURL
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "bb038d5920f65692ccafd569ce86c3a7"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "date_established": [
      {
        "type": "range",
        "name": "half-century",
        "data": [
          {
            "to": "1950-01-01T00:00:00.000Z",
            "from": "1900-01-01T12:00:00.000Z",
            "count": 15
          }
        ]
      }
    ]
  }
}

Range Facet on a Geolocation Field
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 a facet count of "parks" relative to their location in meters to the Elastic San Francisco office. The three ranged 'buckets' are labelled: "Nearby", "A Longer Drive", and "Perhaps fly?". The facet is named "geo-range-from-san-francisco".
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "parks",
  "facets": {
    "location": [
      {
        "type": "range",
        "name": "geo-range-from-san-francisco",
        "center": "37.386483, -122.083842",
        "unit": "m",
        "ranges": [
          { "from": 0, "to": 100000, "name": "Nearby" },
          { "from": 100000, "to": 300000, "name": "A longer drive." },
          { "from": 300000, "name": "Perhaps fly?" }
        ]
      }
    ]
  }
}'
Example Response
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "afd0b735-85e8-4705-94d6-faea30eb1d63"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "location": [
      {
        "type": "range",
        "name": "geo-range-from-san-francisco",
        "data": [
          {
            "to": 100000,
            "from": 0,
            "name": "Nearby",
            "count": 0
          },
          {
            "to": 300000,
            "from": 100000,
            "name": "A longer drive.",
            "count": 2
          },
          {
            "from": 300000,
            "name": "Perhaps fly?",
            "count": 44
          }
        ]
      }
    ]
  }
}

Example - Getting a facet count of "parks" relative to their location in meters to the Elastic San Francisco office. The three ranged 'buckets' are labelled: "Nearby", "A Longer Drive", and "Perhaps fly?". The facet is named "geo-range-from-san-francisco".
import com.swiftype.appsearch.Client;
import com.swiftype.appsearch.ClientException;
import java.util.*;

Client client = new Client("host-2376rb", "search-soaewu2ye6uc45dr8mcd54v8");

String engineName = "national-parks-demo"; String query = "parks";

Map<String, Object> range1 = new HashMap<>(); range1.put("from", 0); range1.put("to", 100000); range1.put("name", "Nearby"); Map<String, Object> range2 = new HashMap<>(); range2.put("from", 100000); range2.put("to", 300000); range2.put("name", "A longer drive.") Map<String, Object> range3 = new HashMap<>(); range3.put("from", 300000); range3.put("name", "Perhaps fly?")

Map<String, Object> locationFacet = new HashMap<>(); locationFacet.put("type", "range"); locationFacet.put("name", "geo-range-from-san-francisco"); locationFacet.put("center", "37.386483, -122.083842"); locationFacet.put("unit", "m"); locationFacet.put("ranges", Arrays.asList(range1, range2, range3));

Map<String, Object> facets = new HashMap<>(); facets.put("location", Arrays.asList(locationFacet));

Map<String, Object> options = new HashMap<>(); options.put("facets", facets);

try { Map<String, Object> response = client.search(engineName, query, options); System.out.println(response); } catch (ClientException e) { System.out.println(e); }

Example Response
Map<String, Object>: {
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "afd0b735-85e8-4705-94d6-faea30eb1d63"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "location": [
      {
        "type": "range",
        "name": "geo-range-from-san-francisco",
        "data": [
          {
            "to": 100000,
            "from": 0,
            "name": "Nearby",
            "count": 0
          },
          {
            "to": 300000,
            "from": 100000,
            "name": "A longer drive.",
            "count": 2
          },
          {
            "from": 300000,
            "name": "Perhaps fly?",
            "count": 44
          }
        ]
      }
    ]
  }
}

Example - Getting a facet count of "parks" relative to their location in meters to the Elastic San Francisco office. The three ranged 'buckets' are labelled: "Nearby", "A Longer Drive", and "Perhaps fly?". The facet is named "geo-range-from-san-francisco".
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

const client = new SwiftypeAppSearchClient('host-2376rb', 'search-soaewu2ye6uc45dr8mcd54v8')

const engineName = 'national-parks-demo' const query = 'parks'

const options = { facets: { location: [ { type: 'range', name: 'geo-range-from-san-francisco', center: '37.386483, -122.083842', unit: 'm', ranges: [ { from: 0, to: 100000, name: 'Nearby' }, { from: 100000, to: 300000, name: 'A longer drive.' }, { from: 300000, name: 'Perhaps fly?' } ] } ] } }

client .search(engineName, query, options) .then(response => console.log(response)) .catch(error => console.log(error))

Example Response
{
  "meta": {
    "alerts": [],
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 5,
      "total_results": 46,
      "size": 10
    },
    "request_id": "1e99a0e913b8ac3c7b3b10df8cf563b1"
  },
  "results": [
    ## Truncated!
  ],
  "facets": {
    "location": [
      {
        "type": "range",
        "name": "geo-range-from-san-francisco",
        "data": [
          {
            "to": 100000,
            "from": 0,
            "name": "Nearby",
            "count": 0
          },
          {
            "to": 300000,
            "from": 100000,
            "name": "A longer drive.",
            "count": 2
          },
          {
            "from": 300000,
            "name": "Perhaps fly?",
            "count": 44
          }
        ]
      }
    ]
  }
}

Example - Getting a facet count of "parks" relative to their location in meters to the Elastic San Francisco office. The three ranged 'buckets' are labelled: "Nearby", "A Longer Drive", and "Perhaps fly?". The facet is named "geo-range-from-san-francisco".
require 'swiftype-app-search'

host_identifier = 'host-2376rb' api_key = 'search-soaewu2ye6uc45dr8mcd54v8' client = SwiftypeAppSearch::Client.new(host_identifier: host_identifier, api_key: api_key)

engine_name = 'national-parks-demo' query = 'parks'

options = { facets: { location: [ { type: 'range', name: 'geo-range-from-san-francisco', center: '37.386483, -122.083842', unit: 'm', ranges: [ { from: 0, to: 100_000, name: 'Nearby.' }, { from: 100_000, to: 300_000, name: 'A longer drive.' }, { from: 300_000, name: 'Perhaps fly?' } ] } ] } }

begin puts client.search(engine_name, query, options) rescue SwiftypeAppSearch::ClientException => e puts e end

Example Response
{
  'meta' => {
    'warnings' => [],
    'page' => {
      'current' => 1,
      'total_pages' => 5,
      'total_results' => 46,
      'size' => 10
    },
    'request_id' => 'a4a0cd0311c73d7292ceaa25a3c74a6d'
  },
  'results' => [
    ## Truncated!
  ],
  'facets' => {
    'location' => [
      {
        'type' => 'range',
        'name' => 'geo-range-from-san-francisco',
        'data' => [
          {
            'to' => 100_000,
            'from' => 0,
            'count' => 0,
            'name' => 'Nearby.'
          },
          {
            'to' => 300_000,
            'from' => 100_000,
            'count' => 2,
            'name': 'A longer drive.',
          },
          {
            'from' => 300_000,
            'count' => 44
            'name': 'Perhaps fly?'
          }
        ]
      }
    ]
  }
}

Example - Getting a facet count of "parks" relative to their location in meters to the Elastic San Francisco office. The three ranged 'buckets' are labelled: "Nearby", "A Longer Drive", and "Perhaps fly?". The facet is named "geo-range-from-san-francisco".
from swiftype_app_search import Client
from swiftype_app_search.exceptions import SwiftypeAppSearchError

host_identifier = 'host-2376rb' api_key = 'search-soaewu2ye6uc45dr8mcd54v8' client = Client(host_identifier, api_key)

engine_name = 'national-parks-demo' query = 'parks'

options = { 'facets': { 'location': [ { 'type': 'range', 'name': 'geo-range-from-san-francisco', 'center': '37.386483, -122.083842', 'unit': 'm', 'ranges': [ {'from': 0, 'to': 100000, 'name': 'Nearby'}, {'from': 100000, 'to': 300000, 'name': 'A longer drive.'}, {'from': 300000, 'name': 'Perhaps fly?'} ] } ] } }

try: print(client.search(engine_name, query, options)) except SwiftypeAppSearchError as e: print(e)

Example Response
{
    'meta': {
        'warnings': [],
        'page': {
            'current': 1,
            'total_pages': 5,
            'total_results': 46,
            'size': 10
        },
        'request_id': 'a4a0cd0311c73d7292ceaa25a3c74a6d'
    },
    'results': [
        ## Truncated!
    ],
    'facets': {
        'location': [
            {
                'type': 'range',
                'name': 'geo-range-from-san-francisco',
                'data': [
                    {
                        'to': 100000,
                        'from': 0,
                        'count': 0,
                        'name': 'Nearby'
                    },
                    {
                        'to': 300000,
                        'from': 100000,
                        'count': 2,
                        'name': 'A longer drive.'
                    },
                    {
                        'from': 300000,
                        'count': 44,
                        'name': 'Perhaps fly?'
                    }
                ]
            }
        ]
    }
}

Example - Getting a facet count of "parks" relative to their location in meters to the Elastic San Francisco office. The three ranged 'buckets' are labelled: "Nearby", "A Longer Drive", and "Perhaps fly?". The facet is named "geo-range-from-san-francisco".
const client = SwiftypeAppSearch.createClient({
  hostIdentifier: 'host-2376rb',
  searchKey: 'search-soaewu2ye6uc45dr8mcd54v8',
  engineName: 'national-parks-demo'
})

const query = 'parks'

const options = { facets: { location: [ { type: 'range', name: 'geo-range-from-san-francisco', center: '37.386483, -122.083842', unit: 'm', ranges: [ { from: 0, to: 100000, name: 'Nearby.' }, { from: 100000, to: 300000, name: 'A longer drive.' }, { from: 300000, name: 'Perhaps fly?' } ] } ] } }

client .search(query, options) .then(function(response){ console.log(response) }) .catch(function(error){ console.log(error) })

Example Response
ResultList {
  "rawResults": [
    ## Truncated!
  ],
  "rawInfo": {
    ## Truncated!... Same as ResultList.info.
  },
  "results": [
    ## Truncated!
  ],
  "info": {
    "meta": {
      "alerts": [],
      "warnings": [],
      "page": {
        "current": 1,
        "total_pages": 5,
        "total_results": 46,
        "size": 10
      },
      "request_id": "1a57eed39741cfd10bd3af7bb4964a4f"
    },
    "facets": {
      "location": [
        {
          "type": "range",
          "name": "geo-range-from-san-francisco",
          "data": [
            {
              "to": 100000,
              "from": 0,
              "name": "Nearby",
              "count": 0
            },
            {
              "to": 300000,
              "from": 100000,
              "name": "A longer drive.",
              "count": 2
            },
            {
              "from": 300000,
              "name": "Perhaps fly?",
              "count": 44
            }
          ]
        }
      ]
    }
  }
}

Errors

facetsIf the faceting field is not in the schema.
If the requested facets JSON object is malformed.
If a value facet is on a field type that is not text, number, or date.
If a range facet is on a field type that is not number, date, or geolocation.
If a range facet does not provide ranges in an acceptable format for the field type.

Stuck? Looking for help? Contact support or check out the App Search community forum!