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

Search

Want to start with the conceptual information? Give our Search Guide a read.


The Search endpoint allows you to search over, facet and filter your data. Any operation within your application that enables search over your documents will do so using this endpoint.

You can use your Public Search Key or your Private API Key to query the Search endpoint. In most cases, you will want to use the Public Search Key, as it is scoped to only access public-friendly parameters.

The search endpoint responds to GET and POST requests. The payload you receive will include meta-data and results. There are two different endpoints that you can query when making search requests: search or multi-search. They both accept the same arguments. The key difference is whether or not you would like to attach one or more query parameters.

query
required
A string or number used to find related documents. To match all documents, use an empty string "". You may also apply select Lucene Query Syntax functions. The supported functions are: double quoted strings, + and -, AND, OR, and NOT.
View Example
page
optional
A JSON object with optional keys of size and current. Specifies the number of results per page and which page the API should return.
View Example

Performing a Single Search Query

POST /api/as/v1/engines/{ENGINE_NAME}/search
GET /api/as/v1/engines/{ENGINE_NAME}/search
Example - Performing a single query search.
curl -X POST '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": "everglade"
}'

Example - Performing a single query search.
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 = "everglade";

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

Example - Performing a single query search.
const SwiftypeAppSearchClient = require('swiftype-app-search-node')

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

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

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

Example - Performing a single query search.
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 = 'everglade'

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

Example - Performing a single query search.
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 = 'everglade'

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

Example - Performing a single query search.
const client = SwiftypeAppSearch.createClient({
  hostIdentifier: 'host-2376rb',
  searchKey: 'search-soaewu2ye6uc45dr8mcd54v8',
  engineName: 'national-parks-demo'
})

const query = 'everglade'

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

Performing a Single Search Query with Lucene Query Syntax
Example - Performing a single query search using Lucene Query Syntax.
curl -X POST '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": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Java example available, showing cURL
curl -X POST '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": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Node example available, showing cURL
curl -X POST '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": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Ruby example available, showing cURL
curl -X POST '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": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Python example available, showing cURL
curl -X POST '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": "wyoming AND montana OR california NOT washington"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Javascript example available, showing cURL
curl -X POST '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": "wyoming AND montana OR california NOT washington"
}'

Performing a Multiple Search Query

You can add multiple queries to a single search request.

Note that the multi-search queries have a fixed limit of 10 queries per request.

POST /api/as/v1/engines/{ENGINE_NAME}/multi_search
GET /api/as/v1/engines/{ENGINE_NAME}/multi_search
Example - Performing a multiple query search.
curl -X POST 'http://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/multi_search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "queries": [
    {"query": "california"},
    {"query": "florida"}
  ]
}'

Example - Performing a multiple query search.
No Java example available, showing cURL
curl -X POST 'http://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/multi_search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "queries": [
    {"query": "california"},
    {"query": "florida"}
  ]
}'

Example - Performing a multiple query search.
No Node example available, showing cURL
curl -X POST 'http://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/multi_search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "queries": [
    {"query": "california"},
    {"query": "florida"}
  ]
}'

Example - Performing a multiple query 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'

queries = [ { query: 'california' }, { query: 'florida' } ]

puts client.multi_search(engine_name, queries)

Example - Performing a multiple query search.
No Python example available, showing cURL
curl -X POST 'http://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/multi_search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "queries": [
    {"query": "california"},
    {"query": "florida"}
  ]
}'

Example - Performing a multiple query search.
const client = SwiftypeAppSearch.createClient({
  hostIdentifier: 'host-2376rb',
  searchKey: 'search-soaewu2ye6uc45dr8mcd54v8',
  engineName: 'sample-engine'
})

const query = 'everglade'

queries = [ { query: "california" }, { query: "florida" } ]

client .multiSearch(queries) .then(function(response){ console.log(response) }) .catch(function(error){ console.log(error) })

Page

The page parameter is used to get the next set of results and/or limit the number of results returned.

size
optional
Number of results per page. Must be between 1 and 1,000; defaults to 20.
current
optional
Page number to return. Must be greater or equal to 1; defaults to 1.
Example - Getting the second page of results with a page size of 5. The API will return documents #5 through #10 by document score in the response.
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",
  "page": {
    "size": 5,
    "current": 2
  }
}'

Example - Getting the second page of results with a page size of 5. The API will return documents #5 through #10 by document score in the response.
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> page = new HashMap<>(); page.put("size", 5); page.put("current", 2);

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

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

Example - Getting the second page of results with a page size of 5. The API will return documents #5 through #10 by document score in the response.
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 = { page: { size: 5, current: 2 } }

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

Example - Getting the second page of results with a page size of 5. The API will return documents #5 through #10 by document score in the response.
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 = { page: { size: 5, current: 2 } }

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

Example - Getting the second page of results with a page size of 5. The API will return documents #5 through #10 by document score in the response.
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 = { 'page': { 'size': 5, 'current': 2 } }

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

Example - Getting the second page of results with a page size of 5. The API will return documents #5 through #10 by document score in the response.
const client = SwiftypeAppSearch.createClient({
  hostIdentifier: 'host-2376rb',
  searchKey: 'search-soaewu2ye6uc45dr8mcd54v8',
  engineName: 'national-parks-demo'
})

const query = 'park'

const options = { page: { size: 5, current: 2 } }

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

Common Errors

There are many ways that a query request can fail. The error message returned by the API will have detailed information regarding what should be changed to ensure a successful request and will return a 400 response.

queryIf the parameter is missing from the request.
If the parameter value is not a string or a number.
pageIf the parameter is not a JSON object.
If the size argument is not greater than or equal to 1 and less than 1,000.
If the page argument is not greater than or equal to 1 and less than 500.

What's Next?

Check out the other API Reference documentation to get deeper into more robust search functionality.


Stuck? Looking for help? Contact Support!