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

Consider reading the API Overview before you begin.


Perform relevant search over documents within your Engine.

The search API endpoint accepts both the GET and POST verbs in order to accommodate HTTP clients that do not allow request bodies to be sent with GET requests. If your client will not send a request body on GET, then POST the request instead and the API will respond as expected.

The following search operations are done with your Engine Key (public search).

Engine Type Supported?
Crawler-based Engine YES
API-based Engine YES

Conduct read-only full-text search against all DocumentTypes within your Engine.

To specify a DocumentType, see the DocumentType API Reference.

GET https://search-api.swiftype.com/api/v1/public/engines/search.json
POST https://search-api.swiftype.com/api/v1/public/engines/search.json


q
required
The query used for a prefix match. Queries shorter than a few characters may not return results.
engine_key
required
The Engine Key used to look up the search engine to search.
callback
optional
The name of a callback function in your client-side JavaScript. If provided, the results will be sent in JSONP format.
Example - Search an Engine for the query "brothers".
curl -X GET 'https://search-api.swiftype.com/api/v1/public/engines/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "engine_key": "YOUR_ENGINE_KEY",
        "q": "brothers"
      }'
Example Response
{
  "records": {
    "books": [
      {
        "title": "The Brothers Karamazov",
        "author": "Fyodor Dostoyevsky",
        "price": "14.95"
      },
      ...
    ]
  },
  "info": {
    "books": {
      "query": "brothers",
      "current_page": 1,
      "num_pages": 1,
      "per_page": 20,
      "total_result_count": 18,
      "facets": {}
    }
  },
  "errors": {}
}

Multiple Search Options

The /search endpoint has many different options. You can combine them together at query time, however you see fit.

Example - A public search for "brothers" against the Engine Key associated with the bookstore Engine with various options.
curl -XGET 'https://search-api.swiftype.com/api/v1/public/engines/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "engine_key": "YOUR_ENGINE_KEY",
        "q": "brothers",
        "filters":{"books":{"in_stock":true,"genre":"fiction"}},
        "per_page":5,
        "page":1,
        "fetch_fields":{
          "books":["author","price"]
        },
        "highlight_fields":{
          "books":{"title":{"size":60,"fallback":true}}
        },
        "search_fields":{
          "books":["title"]
        }
      }'

Cross-domain requests with JSONP

The public API supports JSONP, making it easy to execute searches and autocompletions directly from client-side JavaScript. To use JSONP, set the format to JSON by specifying the .json extension and add a callback parameter specifying the name of the function in your code to call with the results.

Example - JSONP search request
curl -X GET "https://search-api.swiftype.com/api/v1/public/engines/search.json"
  -H 'Content-Type: application/json' \
  -d '{
        "engine_key": "YOUR_ENGINE_KEY"",
        "q": "brothers",
        "callback": "yourCallbackFunction"
      }'
Example Response
yourCallbackFunction({
  "records": {
    "page": [
      {
        "body": "Band of Brothers DVD",
        "external_id": "9508ace2e1ba669854eb49fbe9429952ff1a6d4c",
        "sections": "",
        "title": "Band of Brothers",
        "updated_at": "2013-02-04T19:09:40Z",
        "image": "",
        "type": "post",
        "url": "http://yoursite.com/band-of-brothers",
        "popularity": 1,
        "published_at": "2012-01-01T08:00:00Z",
        "info": "",
        "id": "5025a3036052f6b650000006",
        "score": 3.1224604,
        "highlight": {
          "title": "Band of <em>Brothers</em>",
          "body": "Band of <em>Brothers</em> DVD"
        },
      }
    ]
  },
  "info": {
    "page": {
      "query": "brothers",
      "current_page": 1,
      "num_pages": 1,
      "per_page": 20,
      "total_result_count": 1,
      "facets": {}
    }
  }
})

To see more examples of cross-domain requests, see our jQuery customization tutorial or review our jQuery search or autocomplete plugins.

Supported Field Types

Type Searching
string Yes
text Yes
enum Yes
integer No
float No
date No
location No

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