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

An API-based Engine does not use the crawler to index documents.

Instead, you index documents via an API endpoint.

Engines created using this quick start are API-based Engines.

Endpoint Supported?
Document Indexing Yes.
Crawler Operations No.
Engines Engines are account level.
Search Yes.
Autocomplete Yes.
Analytics Yes.


1. Create an Account

Before getting started, you'll need to create a Site Search account and confirm your email address.

The Site Search API uses an API Key to authenticate requests.

You can find it in the corner of your Account Settings page.

2. Create the Search Engine

First, create a new Engine.

We will use a bookstore as an example.

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

Your Engine is prepared!

Now to index a few documents in the books DocumentType.

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

We only used the string and enum field types, but the API supports many additional types.

See API Overview, Field Types for details.

The documents are in the Engine -- now, time to search.

4. Searching

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

What next?

We have plenty of resources to help you get the most out of your Engine:


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