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

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

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.

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.

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:

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

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

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

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

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

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


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

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

Another helpful resource is the Site Search schema design guide.

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.


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