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

Once documents are indexed, you are able to perform queries and filter results on your engine's data. This is a comprehensive guide on how to interact and use the Search API.

POST /api/as/v1/engines/{ENGINE_NAME}/search

Performing a Simple Search Query

Example - Performing a simple search query.
curl -X POST 'http://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota"
  }'

Search Fields

The search_fields parameter restricts a query to certain fields and can specify the importance of each field using weights. It must be a dictionary where the keys are the text fields to search over and the values are nested dictionaries containing optional advanced search options.

If the search_fields parameter is not given, all text fields will be searched by default with equal importance. You may change the default search fields in the Relevance Tuning section for your engine.

Example - Specifying search_fields for a given query.
curl -X POST 'http://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "search_fields": {
      "make": {},
      "model": {},
      "category": {}
    },
    "query": "toyota"
  }'

If you provide a field name to search over in the search_fields parameter that is not a text field, it will be silently ignored.

Weights

Some fields contain more important information than other fields (e.g. a query match in a blog post's title is more telling than a match in its body). The weights parameter allow you to have a field's score to have more impact on the final document score. If a search field is not given a specified weight, it will default to 1.0. You can specify weights within a nested search_fields parameter.

If a weights parameter is not given, all search_fields will be given equal weight. You may change this default in the Relevance Tuning section for your engine.

Example - Specifying weights to favor name, description, and type in descending order.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "black",
    "search_fields": {
        "name": {
            "weight": 10
        },
        "description": {
            "weight": 5
        },
        "type": {}
    }
}'

Boosts

Boosts affect the score of the entire document. It is provided in the boosts parameter.

Value Boosts

A value boost will boost the score of a document based on a direct value match. It is available on string, number, and date fields. A value boost is expressed in the following format.

type
required
Type of boost. For a value boost, this should be value.
value
required
The value to exact match on. This can provide multiple possible values to match on by providing an array.
factor
optional
Factor to alter the impact of a boost on the score of a document; defaults to 1.0.
operation
optional
The arithmetic operation perform (e.g. the final score will be {ORIGINAL DOC SCORE} + {factor} if the operation is "add"). Can be "add" or "multiply"; defaults to "add".

Example - Applying a multiplicative boost to cars that have a tag value of "on sale".
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "",
    "boosts": {
        "tags": [
            {
                "type": "value",
                "value": "on sale",
                "operation": "multiply",
                "factor": 10
            }
        ]
    }
}'

If there are multiple boost value matches (e.g. the tags field is ["on sale", "child safe", "ludicrous speed"], and the value argument is ["on sale", "child safe"]), the document's overall score will only be boosted once. If you want the boost to be applied twice if different possible values match, use multiple boosts with singular value arguments.

Functional Boosts

A functional boost will apply a function to the overall document score. It is only available on a number field. There are three types of functional boosts.

linearBoosts the overall document score by {FACTOR} * {FIELD_VALUE}.
exponentialBoosts the overall document score by {FACTOR} * e^{FIELD_VALUE})
logarithmicBoosts the overall document score by {FACTOR} * max(0.0001, log(max(1, {FIELD_VALUE})))

They are provided in the following format.

type
required
Type of boost. For a functional boost, this should be functional.
function
required
Type of function to calculate the boost value. Can be "linear", "exponential", or "logarithmic".
operation
optional
The arithmetic operation perform (e.g. the final score will be {ORIGINAL DOC SCORE} + {BOOST_VALUE} if the operation is "add"). Can be "add" or "multiply"; defaults to "add".
factor
optional
Factor to alter the impact of a boost on the score of a document; defaults to 1.0.

Example - Applying a functional boost on all document scores based on price.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "result_fields": {
        "price": {
            "raw" : {}
        }
    },
    "boosts": {
        "price": {
            "type": "functional",
            "function": "logarithmic",
            "operation": "multiply",
            "factor": 2
        }
    }
}'

If boosting on a document value that is an array, the first field value used in the boost calculation.

Proximity Boosts

Instead of calculating the boost value based on the document value, a boost value can be calculated based on the difference between the document value and a specified value from the center parameter. This is available on number, date, and geo fields.

type
required
Type of boost. For a proximity boost, this should be proximity.
center
required
The mode of the distribution.
function
required
Type of function to calculate the boost value. Can be "linear", "exponential", or "gaussian".
factor
optional
Factor to alter the impact of a boost on the score of a document; defaults to 1.0.

Example - Applying a proximity boost based on proximity to the San Francisco International Airport (coordinates of 37.6213, -122.3790).
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
        "query": "toyota",
        "boosts": {
                "current_location": {
                        "type": "proximity",
                        "function": "linear",
                        "center": "37.6213, -122.3790",
                        "factor": 8
                }
        }
}'

If boosting on a document value that is an array, the first field value used in the boost calculation.

Grouping

Results can be grouped based on field if they share the exact same field. The most relevant document will have a key of _group with the value as an array of other documents that share the same value for a field. Documents in a _group key will not appear anywhere else in the search response. This is available on text, number, and date fields.

field
required
Field name that group results on.
size
optional
Number of results to be included in the _group key of the returned document.
sort
optional
A dictionary containing the field name or _score as the key and the value as "asc" or "desc". The default sort is by descending relevance.

Example - Searching for "child safe" and grouping on make of car.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "child safe",
    "result_fields": {
        "make": {
            "raw": {}
        },
        "model": {
           "raw": {}
        },
        "year": {
            "raw": {}
        },
        "tags": {
           "raw": {}
        }
    },
    "group": {
        "field": "make"
    }
}'
Example Response
{
    "meta": {
      ... # redacted
    },
    "results": [
        {
            "make": {
                "raw": "Toyota"
            },
            "model": {
                "raw": "Camry"
            },
            "year": {
                "raw": "2017"
            },
            "tags": {
                "raw": [
                    "child safe",
                    "power steering"
                ]
            },
            "id": {
                "raw": "66867a"
            },
            "_meta": {
                "score": 17.592627
            },
            "_group": [
                {
                    "make": {
                        "raw": "Toyota"
                    },
                    "model": {
                        "raw": "4RUNNER"
                    },
                    "year": {
                        "raw": "2017"
                    },
                    "tags": {
                        "raw": [
                            "child proof doors",
                            "three wheel drive",
                            "ludicrous speed",
                            "premium gas",
                            "red leather",
                            "red seats"
                        ]
                    },
                    "id": {
                        "raw": "441376183"
                    },
                    "_meta": {
                        "score": 3.0860796
                    }
                }
            ]
        },
        {
            "make": {
                "raw": "Ford"
            },
            "model": {
                "raw": "Fiesta"
            },
            "year": {
                "raw": "2018"
            },
            "tags": {
                "raw": [
                    "children approved",
                    "fuel efficient"
                ]
            },
            "id": {
                "raw": "781226450"
            },
            "_meta": {
                "score": 0.013440917
            },
            "_group": []
        }
    ]
}

Filters

Filters allow you to restrict which documents are returned by applying conditions to the value of a certain field. These can be used to further narrow the result set that a query will match.

Example - Filtering results from querying "toyota" to only blue vehicles that have the make of "RAV4" or "4RUNNER".
curl -X POST 'http://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
  "query": "toyota",
  "filters" : {
    "color": "blue",
    "model": ["RAV4", "4RUNNER"]
  }
}'

Exact Filters

To only return documents that have a field equal to a specic value, use an exact filter. It is available on text, number, and date fields. The value to match on can be either a single value or an array of values. An array of values doesn't match mean an exact match on the array, but rather a list of values that the document value can be without being filtered out.

Example - Filtering results from querying "toyota" to only blue vehicles that have the make of "RAV4" or "4RUNNER".
curl -X POST 'http://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
  "query": "toyota",
  "filters" : {
    "color": "blue",
    "model": ["RAV4", "4RUNNER"]
  }
}'

Range Filters

Range filters can be used to filter on a number or date field. The lower bound, from is inclusive and the upper bound, to, is exclusive.

Example - Filtering results to only vehicles that have a daily rate greater or equal to 80 and less than 100.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "filters": {
        "daily_rate": {
            "from": 80,
            "to": 100
        }
    }
}'

Geo Filters

Geo fields can be filtered based on their proximity to a certain point. center must be in the format "latitude, longitude" and the unit may be "mm", "cm", "m" (meters), "km", "in", "ft", "yd", or "mi" (mile).

Example - Filtering results from querying "toyota" to only vehicles within three kilometers of San Francisco International Airport.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "filters": {
        "current_location": {
            "center": "52.3760, 4.894",
            "distance": 3,
            "unit": "km"
        }
    }
}'

Combining Filters

Certain search use cases require more than basic filtering. There are three boolean clauses that are supported to allow for more flexibility when searching.

anyat least one of the filters must match
allall of the filters must match
noneall of the filters must not match

The following query will find documents that match the query string "toyota" and meet the following criteria:

  • color is "blue"
  • status is "available"
  • drivetrain is "AWD" or category is "Full-Size SUV"
  • mileage_policy is not "limited"

Example
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "filters": {
        "all": [
            { "color": "blue" },
            { "status": "available" }
        ],
        "any": [
            { "drivetrain": "AWD" },
            { "category": "Full-Size SUV" }
        ],
        "none": [
            { "mileage_policy": "limited" }
        ]
    }
}'

If there is only one condition for a none clause, a single object can be given. In the above example, the none key can have value of { "mileage_policy": "limited" } instead of [{ "mileage_policy": "limited" }] and have the same filtering behavior.

Nesting Filters

Clauses can be nested within each other to have even more expressive filtering. Any given filter can have at most 5 levels of nesting.

Example
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "filters": {
        "any": [
            {
                "all": [
                    { "make": "Toyota" },
                    { "model": "4RUNNER" }
                ]
            },
            {
                "all": [
                    { "make": "Jeep" },
                    { "model": "Grand Cherokee" }
                ]
            }
        ]
    }
}'

Result Fields

Use the result_fields parameter to only retrieve certain fields in the search response. The result_fields parameter must be a dictionary where the keys are the field names and the values are nested dictionaries containing the format of the returned field value.

If the result_fields parameter is not given, the API will return the raw values for all fields.

rawThe exact value that was indexed. Depending on the type of the field, this can be returned as either a string, number, or an array of strings/numbers.
snippetOnly available on the text field type. Will return the value of the field with highlights designated by <em> tags.

Raw Result Field

Requests the exact value that was indexed. Depending on the type of the field, this can be returned as either a string, number, or an array of strings/numbers. It is expressed in the following format.

size
optional
Length of the return value. Only can be used on text fields. Must be at least 20; defaults to the entire text field. If given for a different field type other than text, it will be silently ignored.

Example - Specifying result_fields of make and description.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "result_fields": {
        "make": {
            "raw": {}
        },
        "description": {
            "raw": {
                "size": 50
            }
        }
    }
}'
Example Response
{
    "meta": {
        ... # redacted
    },
    "results": [
        {
            "id": {
                "raw": "441376183"
            },
            "make": {
            "description": {
                "raw": "A gorgeous three wheel drive that handles rapid"
            },
                "raw": "Toyota"
            },
            "_meta": {
                "score": 3.3440964
            }
        }
    ]
}

Snippet Result Field

Requests a snippet of a text field. Snippets are requested in the following format.

size
optional
Length of the snippet returned. Must be at least 25; defaults to 100.
fallback
optional
Boolean that specifies whether to return the raw text field if no snippet is found.

Example - Specifying result_fields of make, color, description, and tags.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "red",
    "result_fields": {
        "make": {
            "snippet": {
                "size": 20,
                "fallback": true
            }
        },
        "color": {
          "raw": {},
          "snippet": {
              "size": 20
          }
        },
        "description": {
            "raw": {
                "size": 200
            },
            "snippet": {
                "size": 100
            }
        },
        "tags": {
            "raw" : {},
            "snippet": {
                "size": 20,
                "fallback": true
            }
        }
    }
}'
Example Response
{
    "meta": {
        ... # redacted
    },
    "results": [
        {
            "color": {
                "raw": "blue",
                "snippet": null
            },
            "tags": {
                "raw": [
                    "child safe",
                    "three wheel drive",
                    "ludicrous speed",
                    "premium gas",
                    "red leather",
                    "red seats"
                ],
                "snippet": "<em>red</em> leather"
            },
            "description": {
                "raw": "A gorgeous three wheel drive that handles rapid stops, highway speeding, and cruising through red stop signs with ease.",
                "snippet": "rapid stops, highway speeding, and cruising through <em>red</em> stop signs with ease."
            },
            "id": {
                "raw": "441376183"
            },
            "make": {
                "snippet": "Toyota"
            },
            "_meta": {
                "score": 4.211307
            }
        },
        {
            "color": {
                "raw": "red",
                "snippet": "<em>red</em>"
            },
            "tags": {
                "raw": [
                    "child safe",
                    "fuel efficient"
                ],
                "snippet": null
            },
            "description": {
                "raw": "For when you want to party. Fiesta means \"festival\" or \"party\" in Spanish. Who wants a car that is a party pooper?",
                "snippet": null
            },
            "id": {
                "raw": "781226450"
            },
            "make": {
                "snippet": "Ford"
            },
            "_meta": {
                "score": 3.3153284
            }
        }
    ]
}

Snippets in API Response

If requesting a snippet on a non-text field or if there is no match for your query, the snippet field will be null.

Snippets on an array value will return the first match, or null (as shown in the tags field for the document with an id of "441376183"). There is no fallback support.

Sorting

The sort parameter allows you to sort your results in an order other than document score. The sort parameter is expressed as a dictionary containing the field name as the key and the value as "asc" or "desc". A special sorting field name is available, "_score", to order by relevance.

If a sort parameter is not given, results will be ordered by descending relevance.

Example - Sorting alphabetically by the make of the vehicle.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "sort": {
        "make": "desc"
    }
}'

Sorting on Multiple Fields

More fields can be used to sort. Instead of a single dictionary sort parameter, use a list of dictionaries. Sorting is applied in the order it is declared in the list of dictionaries.

Example - Sorting by document score and tie-breaking by the make of the vehicle.
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
    "query": "toyota",
    "sort": [
        { "_score": "desc" },
        { "make": "desc" }
    ]
}'

Paging

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; default to 10.
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-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
        "query": "toyota",
        "page": {
                "size": 5,
                "current": 2
        }
}'

Analytics

The analytics parameter allows you to submit tags representing additional information you wish to track about a query. You can view and filter by these tags in the Analytics tab of the App Search dashboard.

tags
required
Array of strings representing the tags you'd like to apply to this query. You may submit up to 16 tags, and each may be up to 64 characters in length.

Example - Submitting a query with the analytics tags "user", "mobile", and "dealer".
curl -X GET 'https://host-7s23ap.api.swiftype.com/api/as/v1/engines/rent-a-car/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer api-3958sdlfjadsf' \
-d '{
        "query": "toyota",
        "analytics": {
            "tags": [
                "user",
                "mobile",
                "dealer"
            ]
        }
}'