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 wield programmatic control over the content that you have ingested and indexed within your Engines. In conjunction with the usability of the dashboard, you can craft a deep experience useful for both developers and non-developers. The stipulation is that effective usage requires expertise within at least one programming language and a solid understanding of core web development fundamentals.

Before digging deeper into the Site Search API, we would encourage you to check-out App Search. It is a great choice for web, application and mobile developers.


You can consider the Site Search API as being composed of two parts. One part is Private. The other is Public. Each one uses a separate key, the intention being to limit the scope of operations within each half. Each one accesses the same engine, but they do so in a different way. The result is a more secure and intentional development expression across the various Site Search API endpoints.

The Private indexing functionality of the API requires a different type of Engine: an API-based Engine. This Engine type can not use the crawler. You can index your Engines on your own terms, with your schema of choice. In addition, there are endpoints for powerful features like Autocomplete and access to your Analytics. To explore the two types of Engines: API-based and Crawler-based, read here.

Private functions are done with your API Key, which is to be kept secret. With Private functions you can control various endpoints and manipulate Engine resources in an administrative way.

Public functions are accessed using your Engine Key. This key can be included within client libraries. It only allows operations that return results from your engine. You are unable to change - to control - result values or engine resources, only Search them - read them.

This overview covers:

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.

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.

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. To decide which field types to use, consider the tables below and read the Site Search schema design tutorial

Field Types

Option 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

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 Specification Examples

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.

Engine Slugs

When you name an Engine we will assign your engine a slug based on the engine name. 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.

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 ingested. API-based Engine's are not permitted to use Crawler API Operations. As a Crawler-based Engine relies on the crawler to ingest documents, this endpoint gives you control over that process. The API-based Engine uses the API itself to ingest 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 ingest 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 Both.
Search, Private Both.
Search, Public. Both.
Autocomplete Both.
Analytics Both.



Stuck? Looking for help? Contact Support!