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.

Create a new API Engine. The callout is under text box for URL entry.

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

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

If you're already signed up, you can also use the API to create a new Engine:

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

We will use a bookstore as an example Engine.

2. Create a Foundation

We will create a DocumentType for each type of object we'd like to make searchable.

In other words, a DocumentType is a top-level directory for different segments of search engine content.

Since this is a bookstore, we'll create DocumentTypes 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!