Search
editSearch
editWant to start with the concepts? Explore the Search guide.
Search, facet, filter, and curate your documents.
Change the default search behaviour using the Search Settings API or the Result Settings UI in the dashboard.
See the sidebar for further reference on deeper search parameters.
Before You Search...
editBefore you send a query, it helps to know:
- Are there any Search Settings configured?
- Are there any Result Settings configured?
By default a search result will include all fields as raw, unlimited values. But you can choose to add character limits or return snippet field values.
The Search Settings API and the Result Settings feature can change these defaults.
You can also change it per API call with the Result Fields API.
It’s good to experiment to see how the Result Field parameters impact your results.
After you perform some basic queries with result fields, check out the other API Reference documentation to get even deeper:
Search Queries
editThe search endpoint responds to GET
and POST
requests.
There are two different endpoints that you can query:
They are similar, except multi_search
allows up to 10 queries in a single API call.
-
query
(required) - A string or number used to find related documents. To match all documents, use an empty string "". You may also apply the following Lucene Query Syntax functions: double quoted strings, + and -, AND, OR, and NOT. View Example
-
page
(optional) - Provides 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
editPOST /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 Response
{ "meta": { "warnings": [], "request_id": "2992570ab570b581ac6c457bddf68835", "page": { "total_pages": 1, "size": 10, "current": 1, "total_results": 3 }, "alerts": [] }, "results": [ { "world_heritage_site": { "raw": "true" }, "states": { "raw": [ "Florida" ] }, "location": { "raw": "25.32,-80.93" }, "nps_link": { "raw": "https://www.nps.gov/ever/index.htm" }, "acres": { "raw": 1508968.1 }, "date_established": { "raw": "1934-05-30T05:00:00+00:00" }, "title": { "raw": "Everglades" }, "visitors": { "raw": 930907 }, "square_km": { "raw": 6106.6 }, "description": { "raw": "The Everglades are the largest tropical wilderness in the United States. This mangrove and tropical rainforest ecosystem and marine estuary is home to 36 protected species, including the Florida panther, American crocodile, and West Indian manatee. Some areas have been drained and developed; restoration projects aim to restore the ecology." }, "_meta": { "score": 1396363.1 }, "id": { "raw": "park_everglades" } }, # ... More documents (truncated) ] }
Performing a Single Search Query with Lucene Query Syntax
editExample - 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" }'
Performing a Multiple Search Query
editYou can add multiple queries to a single search request.
Note that the multi_search
queries have a fixed limit of 10 queries per request.
Note: Each query inside of a multi_search
is counted as a separate analytic event. For example, issuing a multi_search
with 4 queries will increase the analytics query count by 4.
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 Response
[ # First query result { "meta": { "alerts": [], "warnings": [], "page": { "current": 1, "size": 10, "total_pages": 1, "total_results": 4 } }, "results": [ { "nps_link": { "raw": "https://www.nps.gov/yose/index.htm" }, "id": { "raw": "park_yosemite" }, "visitors": { "raw": 5028868 }, "title": { "raw": "Yosemite" }, "date_established": { "raw": "1890-10-01T05:00:00+00:00" }, "world_heritage_site": { "raw": "true" }, "_meta": { "score": 7543316 }, "description": { "raw": "Yosemite features sheer granite cliffs, exceptionally tall waterfalls, and old-growth forests at a unique intersection of geology and hydrology. Half Dome and El Capitan rise from the park's centerpiece, the glacier-carved Yosemite Valley, and from its vertical walls drop Yosemite Falls, one of North America's tallest waterfalls at 2,425 feet (739 m) high. Three giant sequoia groves, along with a pristine wilderness in the heart of the Sierra Nevada, are home to a wide variety of rare plant and animal species." }, "states": { "raw": [ "California" ] }, "acres": { "raw": 761747.5 }, "location": { "raw": "37.83,-119.5" }, "square_km": { "raw": 3082.7 } }, # ... More documents (truncated) ] }, # ... Second query result (truncated) ]
Page
editAllows for the adjustments to pagination.
-
size
(optional) - Number of results per page. Must be between 1 and 100; 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 } }'
Common Errors
editYou will experience errors if...
|
The parameter is missing from the request. The parameter value is not a string or a number. |
|
The parameter is not a JSON object. The size argument is not greater than or equal to |