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

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:

Engine Types: Crawler based v. API based

When you sign-up for Site Search, the default flow has you enter a URI to begin the initial crawl of your website, thus creating a Crawler based Engine. You have the option of creating an API based Engine instead, either via the account creation flow or from the Site Search Engines API endpoint.

The two types provide similar functionality, with one exception: how documents are indexed. API based Engine's are not permitted to use Crawler API Operations. As a Crawler based Engine relies on the crawler to index documents, this endpoint gives you control over that process. The API based Engine uses the API itself to index documents and thus can not access the crawler-only endpoints.

You are unable to change the Engine type once it has been created. You can always index your documents from one into the other, should you want to make the change.

Endpoint Supported Engines
Document Indexing API based Engine only.
Crawler Operations Crawler based Engine only.
Engines Account level.
Search Both.
Autocomplete Both.
Analytics Both.


Site Search API Resources

There are 3 primary resources of the Site Search API: Engine, DocumentType, and Document.

Engine

Engines are the top-level objects in your search index. They have a free-form name field that we translate into a slug identifier, which is used as the ENGINE_ID to reference the Engine in all Site Search API calls.

DocumentType

DocumentTypes specify the structure of a set of documents in the Engine and are the entry point for searches. There are multiple types of fields on a DocumentType — string, text, enum, integer, float, date, and location.

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 the contents of a document.

When you perform a search on a DocumentType, you will receive document results. external_id is the only required field for a Document. It can be any value, for example: the numeric ID you use to identify the object in your own data store.

Search: Public v. Private

The search API endpoint has two available querying methods: the private method and the public method. It is important to understand the differences before using one or the other to conduct your search queries.

Private Search

Private search uses the private API Key, a unique, permissive key which can be used as a credential against all endpoints belonging to an Engine. Private search requests require that the auth_token parameter contain the API Key. The API Key will perform reads during search, but can be used to write to other endpoints. As such, it should be used with caution.

The basic endpoint looks as such:

GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


It is used when:

  • There is no risk of exposing your API Key.

Public Search

Public search uses the public Engine Key, a unique, read only key which is 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.

Given that the Engine Key is used to uniquely represent an Engine, there is no need to specify an Engine within the URL. Specifying a DocumentType can be done via the request body.

The basic endpoint looks as such:

GET https://search-api.swiftype.com/api/v1/public/engines/search.json


It is used when:

  • You are writing mobile applications.
  • You are using client side JavaScript.
  • Any case wherein you do not want to risk exposing your API Key.

Authentication

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

Method Description
Authentication Token Add the auth_token parameter to each request. Your auth_token can be either your API Key or your Engine Key.
HTTP Basic Auth Use your auth_token as the username. Do not include a password.

In addition to your secret credential, an Engine Slug is needed to make API calls. When you name an Engine we will assign your Engine a slug based on the name you provided.

For example, 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.

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 in accordance with Ruby on Rails conventions.

For example, the JSON parameter:

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

...is equivalent to:

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

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

To decide which field types to use, consider the tables below and read the Site Search schema design tutorial:

Field Type Description
string Smaller pieces of text, such as a book title. These are used for autocomplete and full-text search. String fields can also be used for filtering, faceting, and sorting
text Large bodies of text, such as a book chapter. These are only used for full-text search.
enum String attributes of a document that should be used for exact comparisons, such as a URL or the genre of a book. Enum fields can be used for filtering, faceting, and sorting. Exact matches will be included in results of autocomplete and full-text search.
integer An integer value, such as the number of sales of a book (e.g. 1234).
float A floating point value, such as the price of a book (e.g. 3.99).
date ISO 8601 compatible time strings, such as the publication date of a book.
location A geographic location specified by latitude and longitude (e.g. lat: 53.2, lon: 27.6).

Field Type Use Cases

Field Type Search Optimized for Autocomplete Functional Boosts Filtering Sorting Facets
string Yes Yes No Yes Yes Yes
text Yes No No No No No
enum Yes No No Yes Yes Yes
integer No No Yes Yes Yes Yes
float No No Yes Yes Yes Yes
date No No No Yes Yes Yes
location No No No Yes No No

Field Type Specifications

Type Name Value JSON
string title "My Post Title" {"type":"string","name":"title","value":"My Post Title"}
text body "This is the long content of my post..." {"type":"text","name":"body","value":"This is the long content of my post..."}
enum public true {"type":"enum","name":"public","value":true}
integer views 387 {"type":"integer","name":"views","value":387}
float price 6.95 {"type":"float","name":"price","value":6.95}
date posted_at "2012-07-02T20:44:05-07:00" {"type":"date","name":"posted_at","value":"2012-07-02T20:44:05-07:00"}
location posted_from {"lat":56.2,"lon":44.7} {"type":"location","name":"posted_from","value":{"lat":56.2,"lon":44.7}}

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.

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 a subset of the IETF RFC 5646, which coincide with ISO 639-1 and ISO 3166-1.

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

LanguageLanguage Code, ISO 639-1 and ISO 3166-1.
"Brazilian Portuguese"pt-br
“Chinese"zh
“Dutch"nl
“English"en
"French"fr
“German"de
"Italian"it
"Japanese"ja
"Koreanko
“Portuguese"pt
“Russian"ru
“Spanish"es
“Thai"th
"Universal"null

Summary of API Endpoints

Site Search offers a variety of useful endpoints...

Endpoint Details Engine Support
Document Indexing Add, remove, delete, or update documents. There are methods for bulk indexing, asynchronous indexing, and timed document expiry. API based Engines only.
Crawler Operations Add domains to your Engine, recrawl a domain, recrawl a URL -- this endpoint puts you in control of the Site Search Crawler. Crawler based Engines only.
Engines Create an Engine, list Engines, and destroy Engines. Account level.
Search The endpoint of endpoints! Search allows you to specify a broad range of parameters to generate diverse search queries and relevant result sets. Both.
Autocomplete Performs prefix matching to generate suggestions as the user is typing queries. With this endpoint, you can guide your users to the most relevant search keywords. Both.
Analytics Search is powerful. But the insights that searches generate can help you get ahead of your users expectations. Provides useful insights into clicks and queries. Both.



Stuck? Looking for help? Contact Support!