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:

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 cannot 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

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.


Search: Public v. Private

The search API endpoint has two available querying methods: the public method and private method. The documentation demonstrates public search queries. In some cases, you may want to construct queries using private method.

It is important to note that all search requests executed with the public API from your user's web browser are visible to the user. You can use filters to restrict the data returned, but your users will be able to examine those filters and change them.

Therefore, if you have search data you need to keep separate from different users, we recommend routing all search requests through your own servers via the private method.

Read more about protecting sensitive data.

Public Search Method

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.

It is used when:

  • You are writing mobile applications.
  • You are using client side JavaScript.
  • Any case wherein you are comfortable with your Engine information being exposed through a client.
GET https://search-api.swiftype.com/api/v1/public/engines/search.json
POST https://search-api.swiftype.com/api/v1/public/engines/search.json


Example - Using the public search method to search within the bookstore Engine for the query "brothers" across two DocumentTypes.
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, 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 Engine Key is passed in via the URL to identify your specific Engine.

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.

It is used when:

  • You want to use a single key for all API operations.
  • You are interested in proxying your requests through your infrastructure to hide your Engine from the client.
GET https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json
POST https://search-api.swiftype.com/api/v1/engines/{engine_id}/search.json


Example - Using the private search method to search within the bookstore Engine for the query "brothers" across two DocumentTypes.
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"]
        }'

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.

Basic Search Concepts

Search Results

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

Key Value Description
records Hash of DocumentType slug to Array of result objects Contains the search results for each DocumentType.
info Hash of DocumentType slug to a result info object Contains query metadata like number of results and facet counts.
errors Hash of option name to Hash or Array of errors Contains details about query options that were used incorrectly. See Error messages for more details.

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": {}
}

Default Search Behavior

search_fields
optional
A hash containing arrays of the fields you want to match your query against for each object of each DocumentType. Defaults to all text fields. Supports autocomplete.
fetch_fields
optional
A hash containing arrays of the fields you want to have returned for each object of each DocumentType. Supports autocomplete.

When you search an Engine, it will search each DocumentType by default and return a set of matches for each DocumentType in the response. You can search just a single DocumentType by using the search endpoint for that DocumentType or by specifying the document_types parameter within the request body.

By default, when you search a DocumentType, the search is performed over every text field and string field in your schema. That means that if any of your documents contain matching terms in any of those fields then those documents will be returned. If you would rather search specific fields within a DocumentType, you may pass an array of those fields in the search_fields parameter.

Similarly, any text or string field that matches your query will be returned as part of the result set. If you would rather we only return specific fields, you may pass an array of those fields in the fetch_fields parameter.

Snippets and Highlighting

highlight_fields
optional
A hash containing the fields you want to have highlighted for each object of each DocumentType. For each field, specify size as the maximum number of characters to include in the snippet. Set fallback to true to force inclusion of a non-highlighted snippet if a highlight is not available for that field. Supports autocomplete.

Any fields that are queried during a search will return a concise match within the highlight property of the results. All snippets in this form have HTML entities from the original text encoded. Actual highlighting is specified using unencoded <em> tags.

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.

Authentication

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

Method Description
Authentication Token Add the auth_token or engine_key parameter to each request. They take your API Key and your Engine Key, respectively.
HTTP Basic Auth Use your auth_token or engine_key as the username. Do not include a password.

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. 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.

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!