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

Site Search API Quick Start

Before digging deeper into the Site Search API, we would encourage you to check-out App Search. It is a wise choice for web developers.


You can consider the Site Search API as being composed of two parts. One part is Private. The other is Public. Each one uses a separate key, the intention being to limit the scope of operations within each half. Each one accesses the same engine, but they do so in a different way. The result is a more secure and intentional development expression across the various Site Search API endpoints.

The Private indexing functionality of the API replaces the functionality of the crawler. You can index your engines on your own terms, with your schema of choice. In addition, there are endpoints for powerful features like Autocomplete and access to your Analytics.

Private functions are done with your API Key, which is to be kept secret. With Private functions you can control various endpoints and manipulate engine resources in an administrative way.

Public functions are accessed using your Engine Key. This key can be included within client libraries. It only allows operations that return results from your engine. You are unable to change - to control - result values or engine resources, only Search them - read them.

1. Create an Account

Before getting started, you'll need to create a Swiftype account and confirm your email address. The Swiftype API uses an API Key to authenticate requests, which you can find on your Account Settings page.

2. Create the Search Engine

First, create a new Engine. This is the top-level container for all of your search engine's content.

curl -XPOST 'https://api.swiftype.com/api/v1/engines.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token":"YOUR_API_KEY",
        "engine":{"name":"bookstore"}
      }'

Next, create a DocumentType for each type of object you wish to make searchable. Since this is a bookstore, we'll create types for both books and magazines.

curl -XPOST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token":"YOUR_API_KEY",
        "document_type":{"name":"books"}
      }'
curl -XPOST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token":"YOUR_API_KEY",
        "document_type":{"name":"magazines"}
      }'

3. Indexing

Now that your search engine is created, index a few Documents in the books DocumentType. We only use the string and enum field types below, but the API supports many additional types. See the API overview for details.

curl -XPOST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/books/documents.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token":"YOUR_API_KEY",
        "document": {
          "external_id": "1",
          "fields": [
            {"name": "title", "value": "The Great Gatsby", "type": "string"},
            {"name": "author", "value": "F. Scott Fitzgerald", "type": "string"},
            {"name": "genre", "value": "fiction", "type": "enum"}
          ]
        }
      }'

curl -XPOST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/books/documents.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token":"YOUR_API_KEY",
        "document": {
          "external_id": "2",
          "fields": [
            {"name": "title", "value": "The Brothers Karamazov", "type": "string"},
            {"name": "author", "value": "Fyodor Dostoevsky", "type": "string"},
            {"name": "genre", "value": "fiction", "type": "enum"}
          ]
        }
      }'

And a few Documents in the magazines DocumentType.

curl -XPOST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/magazines/documents.json' \

-H 'Content-Type: application/json' \
-d '{
      "auth_token":"YOUR_API_KEY",
      "document": {
        "external_id": "1",
        "fields": [
          {"name": "name", "value": "The Economist", "type": "string"},
          {"name": "category", "value": "news-current-affairs", "type": "enum"},
          {"name": "periodicity", "value": "weekly", "type": "enum"}
        ]
      }
    }'

curl -XPOST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/magazines/documents.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token":"YOUR_API_KEY",
      "document": {
        "external_id": "2",
        "fields": [
          {"name": "name", "value": "Dwell", "type": "string"},
          {"name": "category", "value": "interior-design", "type": "enum"},
          {"name": "periodicity", "value": "weekly", "type": "enum"}
        ]
      }
    }'

4. Searching

Now you're ready to issue queries to your search engine. By default, search queries will match any fields that are of the type string or text. You may search each DocumentType individually:

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

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

Or you may search the entire engine, over all DocumentTypes at once:

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

5. Autocomplete Searches

Finally, as with full-text searches, you may perform autocomplete-style (prefix match) searches as well:

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

Stuck? Looking for help? Contact Support!