IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Schema Boosts »

› ›

Search

edit

Search

edit

Want 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...

edit

Before 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

edit

The 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

edit

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 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

edit

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"
}'

Performing a Multiple Search Query

edit

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.

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

edit

Allows 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

edit

You will experience errors if...

`query`	The parameter is missing from the request. The parameter value is not a string or a number.
`page`	The parameter is not a JSON object. The size argument is not greater than or equal to `1` and less than `100`. The page argument is not greater than or equal to `1` and less than `500`.

« Schema Boosts »