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
App Search Documentation / app search: Overview
Overview

From Zero to Search

Guides

API Reference

App Search API Clients

Self-Managed App Search

Resources

Overview, API References

App Search provides you with a variety of endpoints to craft intuitive, relevant and useful search experiences.

However you choose to wield these APIs, it will be valuable to first explore...

Schema Design, Field Type Overview

When it comes to schema design, remember four key points:

  1. Always index new fields as the same type as existing documents.
    • eg. An existing date field should not receive geolocation data.
  2. Nested objects are not supported. You must flatten them.
  3. Arrays are supported.
  4. Fields cannot be deleted once they have been created.

App Search fields can be one of four different types:

  1. Text
  2. Number
  3. Date
  4. Geolocation

text fields

Text fields are at the heart of search.

They enable deeply analyzed full text search.

This is the default type for all new fields.

Any group of characters or text that you want to search over should be text.

Text can be in many languages, with intelligence respective of the configured Engine language.

eg. A description of an object, the name of a product, the content of a review.

number fields

A finite double-precision floating point value: 3.14 or 42.

Number fields enable fine grained sorting, filtering, faceting, and boosting.

eg. A price, a review score, the number of visitors, or a size.

date fields

Dates must be in ISO 8601 format, eg: "2013-02-27T18:09:19".

eg. A product release or publish date, birth date, an air date.

geolocation fields

Geographic coordinates can leverage the location field.

The location field allows filtering by distance from a specified point.

A location is specified using a JSON object containing the longitude and latitude, such as:"37.7894758, -122.3940638".

The separating space after the comma may be omitted: "37.7894758,-122.3940638".

eg. A store where a product is located, location of a venue.

Supported Features, By Field Type

Each field type has its own feature compatibility.

Queries

Type Search Queries Query Suggestions Result Fields Search Fields
text Yes Yes Yes Yes
number No No No No
date No No No No
geolocation No No No No

Boosts

Type Value Boosts Functional Boosts Proximity Boosts Recency Boosts
text Yes No No No
number Yes Yes Yes No
date Yes No No Yes
geolocation Yes No Yes No

Filters, Facets, Grouping, Sorting

Type Value Facet Range Facet Value Filter Range Filter Geo Filter Grouping Sorting
text Yes No Yes No No Yes Yes
number Yes Yes Yes Yes No Yes Yes
date Yes Yes Yes Yes No Yes Yes
geolocation No Yes No No Yes No No

Parameter Encoding

All App Search endpoints accept parameters as a JSON-encoded request body.

This is the recommended method and the one you will see in all of our examples.

However, you can also submit query parameters using form encoding.

For example:

Example - JSON request body 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Java example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Node example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Ruby example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Python example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

Example - JSON request body
No Javascript example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

... compared with:

Example - Rails-style query parameters 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Java example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Node example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Ruby example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Python example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Example - Rails-style query parameters
No Javascript example available, showing cURL 
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

Both options will return the same response, which is the second page of results with 15 pages per result:

Example - Same response! 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Java example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Node example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Ruby example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Python example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Example - Same response!
No Javascript example available, showing cURL 
{
  "meta": {
    "page": {
      "current": 2,
      "total_pages": 3,
      "total_results": 41,
      "size": 15
    }
  },
  "results": [
    {
       "nps_link": {
         "raw": "https://www.nps.gov/wrst/index.htm"
       },
       "title": {
         "raw": "Wrangell–St. Elias"
       },
       "date_established": {
         "raw": "1980-12-02T06:00:00+00:00"
       },
       "world_heritage_site": {
         "raw": "true"
       },
       "states": {
         "raw": [
           "Alaska"
         ]
       },
       "description": {
         "raw": "An over 8 million acres (32,375 km2) plot of mountainous country—the largest National Park in the system—protects the convergence of the Alaska, Chugach, and Wrangell-Saint Elias Ranges, which include many of the continent's tallest mountains and volcanoes, including the 18,008-foot Mount Saint Elias. More than a quarter of the park is covered with glaciers, including the tidewater Hubbard Glacier, piedmont Malaspina Glacier, and valley Nabesna Glacier."
       },
       "visitors": {
         "raw": 79047
       },
       "id": {
         "raw": "park_wrangell–st.-elias"
       },
       "location": {
         "raw": "61,-142"
       },
       "square_km": {
         "raw": 33682.6
       },
       "acres": {
         "raw": 8323146.48
       },
       "_meta": {
         "score": 0.00437395
       }
    },
    # ... Truncated!
  ]
}

Query Syntax

When performing queries using the Search API, you may apply select Lucene Query Syntax functions.

The supported functions are: double quoted strings, + and -, AND, OR, and NOT.

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

Example - Performing a single query search using Lucene Query Syntax.
No Java example available, showing cURL 
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"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Node example available, showing cURL 
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"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Ruby example available, showing cURL 
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"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Python example available, showing cURL 
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"
}'

Example - Performing a single query search using Lucene Query Syntax.
No Javascript example available, showing cURL 
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"
}'

Compression, gzip

The API supports gzip.

Your requests to App Search can contain an Accept-Encoding header.

Use the header to notify the API that you are capable of accepting and unpacking responses that are compressed via gzip.

curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Accept-Encoding: gzip' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "everglade"
}'

Error Handling

There are three types of errors that you might run into when creating API requests:

Invalid Keys

Your choice of Key will depend on the endpoint you choose to access:

Key Name Key Prefix Endpoint
Public Search Key public- Search endpoint only.
Private API Key private- All endpoints except Credentials.
It is recommended that you use the Public Search Key when using the Search endpoint.
Private Admin Key admin- Credentials endpoint only.

If you use the incorrect key or format the key in an incorrect way, then you will receive a 400 error akin to:

{
  "error": "Invalid authentication token."
}

Decoding Error, Malformed Requests

If you happen to make a mistake with your formatting, you will receive a 400 error:

{
  "errors": [
    "There was a decoding error. Please ensure your request is valid."
  ]
}

To address this, ensure that your any JSON objects or URL parameters are formatted in the correct manner.

Endpoint Specific Errors

Each API Reference will show you how to structure your requests.

If you happen to make a mistake, there are a variety of helpful errors that will inform you upon what to fix.

Despite receiving a status code of 200, you will not succeed in making your request.

Look for the Errors section at the end of each endpoint.

Errors might look like this:

{
  "errors": [
    "Missing required parameter: filters[date][from]"
  ]
}

{
  "errors": [
    "curation must include either promoted or hidden"
  ]
}

Rate Limiting

The App Search API is rate limited to prevent abuse.

The limits are high enough that typical use should rarely be rate limited.

Rate limits are calculated by requests over an hour.

Rate Limiting Example

Requests that have been rate limited will respond with HTTP 429 Too Many Requests.

Example - Rate limited JSON resource 
curl -i -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
        }
      }'
Example Response 
HTTP/1.1 429
Content-Type: application/json; charset=utf-8
Content-Length: 32

{ "error": "Rate limit exceeded." }

Rate Limiting Headers

There are two response headers which provide a guideline towards the rate limit:

X-RateLimit-Limit: xxxx
X-RateLimit-Remaining: xxxx

The header values and their refresh interval vary depending on your plan and which endpoint you are sending requests against.

Additionally, a Retry-After header will be present on 429 responses which indicates how long to wait before submitting your next request.

Due to a variety of network and API influences, these headers are for guidance and are not an exact measure.

Values are expressed in 60 minute intervals.

Rate Limit Mitigation

If your application is being affected by rate limiting, please use the headers described above as a guide to limit your API usage accordingly.

If the problem persists, contact support@swiftype.com for assistance.

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