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

Perform relevant search over documents within your Engine.

The search-related API endpoints accept 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 simply POST the request instead and the API will respond identically.

The following search operations are done with your API Key (private search) or your Engine Key (public search). Read the API Overview before proceeding so that you may choose the right method for your needs.

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

Search Concepts

There are many key concepts that will arise when performing search via the API.

If you have not read it yet, the API Overview introduces much of the terminology.

Search Results

Search results will contain an object with the following key/value parameters.

Key Value Description
records Hash of DocumentType slug to Array of result objects Contains the search results for each DocumentType.
info Hash of DocumentType slug to a result info object Contains query metadata like number of results and facet counts.
errors Hash of option name to Hash or Array of errors Contains details about query options that were used incorrectly. See Error messages for more details.

In application, a response will appear as such:

{
"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": {}
}

Default Search Behavior

When you search an Engine, it will search each DocumentType by default and return a set of matches for each DocumentType in the response. You can search just a single DocumentType by using the search endpoint for that DocumentType or by specifying the document_types parameter within the request body.

By default, when you search a DocumentType, the search is performed over every text field and string field in your schema. That means that if any of your documents contain matching terms in any of those fields then those documents will be returned. If you would rather search specific fields within a DocumentType, you may pass an array of those fields in the search_fields parameter.

Similarly, any text or string field that matches your query will be returned as part of the result set. If you would rather we only return specific fields, you may pass an array of those fields in the fetch_fields parameter.

Snippets and Highlighting

Any fields that are queried during a search will return the concise match in the highlight property of the results. All snippets in this form have HTML entities from the original text encoded. Actual highlighting is specified using unencoded <em> tags.

Free-text Query Syntax

Text searches support a basic subset of the standard Lucene query syntax. The supported functions are: double quoted strings, + and -, AND, OR, and NOT.

Visit the Lucene documentation for more information.

Field Weights

At query time you can apply weights to different fields to control how each field affects the result rankings. For example, if you want string matches in the title of a book to be weighted more heavily than matches in the author field, you would send a weight on the title field in the search_fields option using the ^(weight) notation.

Field weight set during query time will take precedence over field weights defined in the dashboard. Weight is measured between 1-10, with 10 being the most heavily weighed. You can apply weights to numeric fields by using Functional Boosts.

Example - Return books matching the query "brothers", and weight matches in the title field three times as highly as matches in the author field.
curl -X GET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "search_fields":{
          "books":["title^3","author"]
        }
      }'

URL Parameter Encoding

As mentioned in the API Overview, this endpoint will accept parameters as a JSON-encoded request body. This is the recommended method and is shown in the examples in this documentation. However, you can also submit parameters using form encoding in accordance with Ruby on Rails conventions.

curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers"
      }'

... is the same as...

curl -X GET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json?q=brothers&auth_token=YOUR_API_KEY'

Conduct full-text search against your Engine using your private API Key.

See search options for a full list of available parameters.

q
required
The query used for a prefix match. Queries shorter than a few characters may not return results.
auth_token
required
The Engine Key used to look up the search engine to search.
GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
Example - Using the private method, search the books DocumentType for the query "brothers".
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_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": {}
}
GET https://search-api.swiftype.com/api/v1/public/engines/search.json
POST https://search-api.swiftype.com/api/v1/public/engines/search.json


Conduct read-only full-text search against your Engine. The Site Search public API is read-only, so it is appropriate for using from client-side JavaScript or a mobile app where you do not want to expose your read-write API key.

To use the public API, find the Engine Key for your Engine. The Engine Keys for each of your Engines are located within your Site Search dashboard. You do not need to use your API Key -- keeping it hidden from these requests is what makes this endpoint safe for public cases.

Using the Engine Key means that searches are done at the Engine level by default. To specify a DocumentType, see the DocumentType search option.

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 - Using the public method, search the books DocumentType 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": {}
}

Public, Autocomplete API

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


To perform a prefix search, use the suggest endpoint. The parameters are the same as the private autocomplete endpoint and are scoped by Engine.

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.

Public, Cross-domain requests with JSONP

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


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.

Public, Security

It is important to note that all search requests executed with the public API from your user's web browser are visible to the user. You can use filters to restrict the data returned, but your users will be able to examine those filters and change them.

Therefore, if you have search data you need to keep separate from different users, we recommend routing all search requests through your own servers.

Read more about protecting sensitive data.

Search Options, Public & Private

All search options are available using both private and public methods.

See the private and public multiple search option examples to understand the differences.

Henceforth, examples are shown as private.

page
optional
An integer of the page of results you want (maximum: 100). Defaults to 1. Supports autocomplete.
Read more.
per_page
optional
An integer of the number of results you want from each page (maximum: 100). Defaults to 20. Supports autocomplete.
Read more.
fetch_fields
optional
A hash containing arrays of the fields you want to have returned for each object of each DocumentType. Supports autocomplete.
highlight_fields
optional
A hash containing the fields you want to have highlighted for each object of each DocumentType. For each field, specify size as the maximum number of characters to include in the snippet. Set fallback to true to force inclusion of a non-highlighted snippet if a highlight is not available for that field. Supports autocomplete.
Read more.
search_fields
optional
A hash containing arrays of the fields you want to match your query against for each object of each DocumentType. Defaults to all text fields. Supports autocomplete.
Read more.
document_types
optional
A JSON object containing field names as keys and facet options as values. Defaults to requesting no facets. Searches all DocumentTypes by default. Supports autocomplete.
Read More
functional_boosts
optional
A hash containing boosts that are to be applied to numerically valued fields. Supports autocomplete.
Read more.
filters
optional
A hash specifying additional conditions that should be applied to your query for each DocumentType. Supports autocomplete.
Read more.
precise_expiration
optional
A hash of DocumentType slugs to true or false specifying whether or not filter out expired Documents from the results. Supports autocomplete.
sort_field
optional
A hash of DocumentType slug to field name (field must be of type enum, float, integer, or date). Supports autocomplete.
Read more.
sort_direction
optional
A hash of DocumentType slug to asc or desc. Defaults to descending. Supports autocomplete.
Read more.
facets
optional
A hash of DocumentType slug an array of fields to provide result counts for.
Read more.
spelling
optional
A string of the type of spelling you want for your query, strict, always, or retry.
Read more.

Multiple Search Options, Private Example

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
Example - A private search for "brothers" within the books DocumentType within the bookstore Engine with various options.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_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"]
        }
      }'

Multple Search Options, Public Example

GET https://search-api.swiftype.com/api/v1/public/engines/search.json
POST https://search-api.swiftype.com/api/v1/public/engines/search.json
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"]
        }
      }'

Filters

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


Filters allow you to restrict a result set by applying conditions to fields on matching documents.

q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
filters
optional
Provide the filters parameter with a DocumentType key, and then provide that key with fields from your schema. To filter, provide the fields with a value to filter upon.

Basic Filtering

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


The simplest filter requires a field - or set of fields - on each matching document to be equal to a specified value.

Example - Return books matching the query "brothers" that are in_stock and in the fiction genre only.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "filters":{
          "books":{
            "genre":"fiction",
            "in_stock":true
          }
        }
      }'

Filters can also have multiple values. For example, to limit search results to just the "mystery" OR "science fiction" genres, use an array as the value for the filter.

Example - Return books matching the query "brothers" that are in the mystery OR science fiction genres.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "filters":{
          "books":{
            "genre": ["mystery", "science fiction"]
          }
        }
      }'

Filters with AND semantics

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


By default, if you pass multiple values to a filter (as shown in the previous example), we apply OR semantics to the match. To apply AND semantics, in which case matching Documents must match every value passed to with filter, you may use the AND filter as follows.

type
optional
The type of filter. Within the field being filtered, provide the type as and.
values
optional
Within the field being filtered, provide the values to and between.
Example - Return books matching the query brothers that are in both the mystery AND science fiction genres.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "filters":{
          "books":{
            "genre":{
              "type": "and",
              "values": ["mystery","science fiction"]
            }
          }
        }
      }'

Range Queries

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


Filters also support range queries. You may apply range filters to date, integer, and float fields. If you want the filter unbounded at the low or the high end, just leave off the from or the to parameter.

type
optional
The type of filter. Within the field being filtered, provide the type as range.
from
optional
The bottom end of the range, where the range begins.
to
optional
The top end of the range, where the range ends.
Example - Return books matching the query "brothers" with a price between 3.00 and 12.00.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "filters":{
          "books":{
            "price":{
              "type": "range",
              "from": 3.00,
              "to": 12.00
            }
          }
        }
      }'

Geospatial Queries

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


You can do geospatial queries by providing latitude and longitude coordinates. Units can be miles (mi) or kilometers (km).

type
optional
The type of filter. Within the field being filtered, provide the type as distance.
max
optional
Toggle the amount of distance from your specific co-ordindates wherein results are considered within proximity. Requires latitude and longitude.
lat
optional
The latitude of the location. Requires longitude.
lon
optional
The longitude of the location. Requires latitude.
Example - Return books matching the query "brothers" within 5km of the geographic location (37.75,-122.42).
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "filters":{
          "books":{
            "publisher_location":{
              "type": "distance",
              "max": "5km",
              "lat": 37.75,
              "lon": -122.42
            }
          }
        }
      }'

Specifying DocumentTypes

When using the private endpoint, you choose whether or not to include document_types within the query string or the request body. With the public endpoint, you must apply the example seen in multiple DocumentTypes, entering one or more document_types in the request body.

Single DocumentType

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/document_types/{document_type_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/document_types/{document_type_id}/search.json


Searching for a single DocumentType. This particular formatting only applies to the private method, given that it requires the statement of DocumentType within the URL parameters, relative to the Engine id.

q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
Example - An example when searching one document_type_id. The document_type_id will be the only DocumentType searched upon.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/{engine_id}/document_types/{document_type_id}/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
      }'

Multiple DocumentTypes

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


Searching against one or more DocumentTypes using the private method.

q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
document_types
optional
The Engine Key used to look up the search engine to search.
Example - Return results matching "brothers" in the magazines and comics DocumentTypes only
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "document_types": ["magazines", "comics"]
      }'
Public
GET https://search-api.swiftype.com/api/v1/public/engines/search.json


Searching against one of more DocumentTypes using the public method.

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 associated with your Engine. Found within your dashboard.
document_types
optional
The DocumentTypes within which you would like to search. See the API Overview for more information on DocumentTypes.
Example - Return results matching "brothers" in the magazines and comics DocumentTypes using a Public search query.
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",
        "document_types": ["magazines", "comics"]
      }'

Faceting

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


You can use faceting to give you a count of results for each value of a particular field.

q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
facets
optional
Count the results of a given field within a DocumentType. As such, the facet parameter requires both a DocumentType and a field belonging to that DocumentType.
Example - Return the total number of books within each book genre that match your search query
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "facets":{
          "books":["genre"]
        }
      }'
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": {
        "genre": {
           "fiction": 11,
           "non-fiction": 7
        }
      }
    }
  },
  "errors": {}
}

Sorting

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


By default, results are sorted by relevance (the _score field). The relevance calculation can be affected by weighting fields or applying functional boosts. You can also sort search results by a specific field.

Note: Fields used for sorting must be of type enum, float, integer, or date. If you need to sort by a string field, we recommend indexing a second version of that field as an enum and sorting by the enum version.

q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
sort_field
optional
Selects the field over which to sort. Must be in relation to the fields in your Engine schema.
sort_direction
optional
Can be either asc or desc, ascending or descending.
Example - Return the books that match your search query, ordered by price from lowest to highest
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"the",
        "sort_field":{"books":"price"},
        "sort_direction":{"books":"asc"}
      }'

Spelling

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


A spelling parameter can be added to your search request. The language used in your spelling correction will match the language of your indexed documents. We adjust the return value of the spelling functions to ensure the score for a result is not negative or zero.

There are 3 different spelling options:

Spelling Options Description
strict Returns a spelling correction value when there are no results matching the submitted query
always Returns a possible spelling correction even if there are query matched results
retry Automatically retries the search request with the spelling corrected value if there are no results, but there is a spelling correction. Note that retry can lead to a slight decline in performance as a result of running 2 queries.
q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
spelling
optional
Values can be strict, always, or try. See the above table for more information.
Example - Return books matching the query "brthers". Adding the spelling parameter will add correct the spelling of "brthers" to "brothers"
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brthers",
        "spelling": "retry"
      }'

Functional Boosts

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


Functional boosts allow you to boost result scores based on the value of an integer or float field.

There are 3 types of functional boosts:

Boost Type Description
logarithmic Multiplies the original score by ln(field value)
exponential Multiplies the original score by efield value
linear Multiplies the original score by field value
q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
functional_boosts
optional
Values can be logarithmic, exponential, or linear. See the above table for more information.
Example - Return the most popular books first by boosting the total_purchases field with a logarithmic boost, which contains an integer representing the total_purchases of a book.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/document_types/books/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "functional_boosts":{
          "books":{
            "total_purchases":"logarithmic"
          }
        }
      }'

Pagination

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


Use the per_page and page parameters to paginate results. The info attribute of the result JSON will contain information about the current page and how many pages there are in the results. If you advance past the total number of pages, the records attribute will be empty.

q
required
The query used within your search.
auth_token
required
The private API Key associated with your Engine. Found within your dashboard.
page
optional
Set the page, with respect to the total number of pages.
per_page
optional
Set the number of results per page. Must be between 1 and 100. Defaults to 20.
Example - Fetching page 2, with 25 results per_page.
curl -XGET 'https://search-api.swiftype.com/api/v1/engines/bookstore/search.json'
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "q":"brothers",
        "page": 2,
        "per_page": 25
      }'
Example Response
{
  "records":{
    "books":[...]
  },
  "info":{
    "books":{
      "query":"title",
      "current_page":2,
      "num_pages":4,
      "per_page":25,
      "total_result_count":76,
      "facets":{
      }
    }
  }
}

Error messages

If there are no problems, the response object will contain an an errors key with an empty object. However, if search options were used incorrectly, these problems will be noted in the errors object.

Note that a 200 response code will still return in the result of errors - you will need to monitor the response body and not the error code in order to fully capture the health of your API requests.

Example - Errors for limiting DocumentTypes searched to a DocumentType that doesn't exist
{
  "auth_token": "YOUR_API_KEY",
  "q":"brothers",
  "document_types": ["books", "folios"]
}
Example Response
{
  "records": {
    "books": [...]
  },
  "info": {...},
  "errors": {
    "document_types": ["DocumentType 'folios' does not exist in this Engine."]
  }
}
Example - Errors for fetching a field that doesn't exist in a DocumentType.
{
  "auth_token": "YOUR_API_KEY",
  "q":"brothers",
  "fetch_fields": {"books": ["title", "publisher"]}
}
Example Response
{
  "records": {
    "books": [...]
  },
  "info": {...},
  "errors": {
    "fetch_fields": {
      "books": ["DocumentType 'books' does not have a field 'publisher'."]
    }
  }
}
Example - Errors for specifying search fields for a DocumentType that doesn't exist in the Engine
{
  "auth_token": "YOUR_API_KEY",
  "q":"brothers",
  "search_fields": {"folios": ["title"]}
}
Example Response
{
  "records": {
    "books": [...]
  },
  "info": {...},
  "errors": {
    "search_fields": {
      "folios": ["DocumentType 'folios' does not exist in this Engine."]
    }
  }
}
Example - Errors for specifying search fields for a DocumentType that exists in the Engine but is excluded
{
  "auth_token": "YOUR_API_KEY",
  "q":"brothers",
  "search_fields": {"magazines": ["title"]},
  "document_types": ["books"]
}
Example Response
{
  "records": {
    "books": [...]
  },
  "info": {...},
  "errors": {
    "search_fields": {
      "magazines": ["DocumentType 'magazines' exists in this Engine but is not included in the list of DocumentTypes to search."]
    }
  }
}
Example - Errors for sorting on an unsortable field
{
  "auth_token": "YOUR_API_KEY",
  "q":"brothers",
  "sort_field": {"books": "title"}
}
Example Response
{
  "records": {
    "books": [...]
  },
  "info": {...},
  "errors": {
    "sort_field": {
      "books": ["Cannot sort by 'title'. Only enum, numeric, and date fields can be sorted."]
    }
  }
}

Stuck? Looking for help? Contact Support!