API Overview

The Site Search API can be used to programmatically alter how your...

• pages are crawled
• documents are indexed
• searches are completed
• analytics are generated
• ... and more!

This overview covers:

• Language Optimization
• Authentication
• Engine Types: Crawler-based v. API-based
• Search: Public v. Private
• Response Object
• Free-text Query Syntax
• Parameter Encoding
• Summary of API endpoints
• API Resources

Language Optimization

Each Engine can be optimized for a specific language.

By default, an Engine is considered Universal, or null according to the Engine's language parameter.

You can specify a language when creating an Engine via the dashboard or the API.

A language will match with its respective Language Code.

The codes adhere to an IETF subset: RFC 5646, which coincide with ISO 639-1 and ISO 3166-1.

Note that once a language has been configured, it cannot be reconfigured -- you will need to create a new Engine and transport your data.

Authentication

You may authenticate requests to the API using the following method:

In addition to your secret credential, an Engine Slug or Engine Key is needed to make private API calls.

When you name an Engine we will assign your Engine a slug based on the name you provided.

eg: An Engine named "Bookstore Search Engine" would get the slug "bookstore-search-engine".

You will use the slug as the engine_id to reference a particular Engine when sending requests to the API.

Engine Types: Crawler-based v. API-based

All Engine's are crawler Engines unless they are created via the Engines API.

You are unable to change the Engine type once it has been created.

You can index your documents from one into the other, should you want to make the change.

Search: Public v. Private

The search API endpoint has two available querying methods:

1. Public method
2. Private method

Note: The documentation demonstrates public search queries.

Public Search Method

Public search uses the public Engine Key, a unique, read-only key associated with your Engine.

Public search requests require that the engine_key field contain the Engine Key.

All requests made with this key are read only.

It is used when:

• You are writing mobile applications.
• You are using client side JavaScript.
• Any case where you are comfortable with query information being exposed through a client.

curl -XGET 'https://search-api.swiftype.com/api/v1/public/engines/search.json' \
    -H 'Content-Type: application/json' \
    -d '{
          "engine_key": "YOUR_ENGINE_KEY",
          "q": "brothers",
          "document_types": ["magazines", "comics"]
        }'

Private Search Method

Private search uses the private API Key.

The API Key a unique, permissive key which can be used as a credential against all API endpoints.

Private search requests require that the auth_token parameter contain the API Key.

The Engine Key is passed in via the URL to identify a specific Engine.

The API Key will perform reads during search, but can be used to write to other endpoints.

It should be used with caution.

It is used when:

• You want to use a single key for all API operations.
• Proxying requests through your infrastructure to hide queries from the client. [1]

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": "brothers",
          "document_types": ["magazines", "comics"]
        }'

[1] If you have search data you need to keep hidden, we recommend routing all search requests through your own servers via the private method. Read more about protecting sensitive data.

Response Object

Search results will contain an object with the following key/value parameters.

In application, a response will appear as such:

{
"records": {
  "books": [
    {
      "title": "The Brothers Karamazov",
      "author": "Fyodor Dostoyevsky",
      "price": "14.95"
    },
    ...
  ]
},
"info": {
  "books": {
    "query": "brothers",
    "current_page": 1,
    "num_pages": 1,
    "per_page": 20,
    "total_result_count": 18,
    "facets": {}
  }
},
"errors": {}
}

Free-text Query Syntax

Text searches support a basic subset of the standard Lucene query syntax.

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

Visit the Lucene documentation for more information.

Parameter Encoding

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

This is the recommended method and is shown in the examples in this documentation.

However, you can also submit parameters using form encoding.

For example, the JSON parameter:

{
  "filters":
    {
      "videos":
      {
        "status": ["draft", "published"]
      }
    }
}

...is equivalent to:

/filters[videos][status][]=draft&filters[videos][status][]=published

Summary of API Endpoints

Site Search offers a variety of useful endpoints...

API Resources

There are 3 primary resources of the Site Search API:

1. Engine
2. DocumentType
3. Document

Engine

An Engine is the top-level object in your search index.

It has a freeform name field which is translated into a slug identifier and used as the ENGINE_ID.

You must reference the Engine in all API requests.

DocumentType

A DocumentType specify the structure of a set of documents in the Engine.

They act as entry points for searches.

They contain multiple fields types: string, text, enum, integer, float, date, and location.

The default DocumentType is called page. Read more.

Document

Documents represent all of the pieces of content in an Engine.

They are children of a DocumentType and conform to its field specification.

You do not need to specify the fields ahead of time, they will be inferred by a document contents.

All new fields will default to the text type.

When you perform a search on a DocumentType, you will receive document results.

The only required document field is external_id.

It can be any value, eg: the numeric ID you use to identify the object in your own data store.

Document Field Types

Documents in your Engine may contain as many fields as you like.

There are three tables to help you navigate Field Types:

• Field Types
• Use Cases
• Specifications

Field Types

To decide which field types to use, consider the tables below.

Another helpful resource is the Site Search schema design guide.

Field Type Use Cases

Field Type Specifications

Array values

When creating a document, pass the values as an array.

{"type": "enum", "name": "tags", "value": ["tag1", "tag2", "tag3"]}

Naming fields

Document field names must be limited to alphanumeric ASCII characters. Whitespace, special characters, and non-ASCII encoding are not allowed.

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