Swiftype Search & Autocomplete

This add-on is operated by Swiftype

Fast, modern search with autocomplete, query result management, and analytics.

Swiftype Search & Autocomplete

Last Updated: 07 May 2015

Table of Contents

Swiftype is an add-on for providing real-time, full-text search to your Heroku application.

Swiftype is accessible via an API and has supported client libraries for Ruby, Python, and PHP.

Provisioning the add-on

Swiftype can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:create swiftype
-----> Adding swiftype to sharp-mountain-4005... done, v18 (free)

This will create a Swiftype search engine named “engine” associated with your Heroku application.

Once Swiftype has been added the SWIFTYPE_URL environment variable will be available in your app’s configuration. This will contain the base URL for the Swiftype API along with your credentials.

This can be confirmed using the heroku config command.

$ heroku config | grep SWIFTYPE
SWIFTYPE_URL    => https://your-secret-key:@api.swiftype.com/api/v1

After installing Swiftype the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export SWIFTYPE_URL=value.

Use Foreman to reliably configure and run the process formation specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the SWIFTYPE_URL value retrieved from heroku config to your .env file.

$ heroku config -s | grep SWIFTYPE_URL >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

To avoid conflicts, each development environment (and developer) should have its own Swiftype search engine.

Using the REST API

Swiftype provides client libraries for a number of languages, but if yours is not among them, you can use the REST API directly. Here’s an example using Clojure.

(require '[clj-http.client :as client])
(require '[cheshire.core :as json])

(def swiftype-endpoint (System/getenv "SWIFTYPE_URL"))

(client/post (str swiftype-endpoint "/engines/engine/document_types.json")
             {:body (json/encode {:document_type {:name "books"}})
             :content-type :json})

(client/post (str swiftype-endpoint "/engines/engine/document_types/books/documents.json")
             {:body (json/encode
                                 {:document {:external_id 123 :fields [{:name "title" :value "Alice's Adventures in Wonderland" :type "string"}
                                                                      {:name "author" :value "Lewis Carroll" :type "string"}
                                                                      {:name "published_in" :value 1865 :type "integer"}]}})
             :content-type :json})

(client/get (str swiftype-endpoint "/engines/engine/search.json")
            {:query-params {:q "alice"}
            :content-type :json})

Using with Ruby

First, install the Swiftype gem:

$ gem install swiftype

Now, use the library to interact with the API:

require 'swiftype'

Swiftype.authenticated_url = ENV['SWIFTYPE_URL']
client = Swiftype::Client.new

# The automatically created engine has a slug of 'engine'
engine_slug = 'engine'

# create a DocumentType within the automatically created engine called 'books'
document_type = client.create_document_type(engine_slug, 'books')
document_type_slug = document_type['slug']

# create Documents within the DocumentType
client.create_or_update_documents(engine_slug, document_type_slug, [
  {:external_id => '4', :fields => [
    {:name => 'title', :value => "Old Possum's Book of Practical Cats", :type => 'string'},
    {:name => 'author', :value => 'T. S. Elliot', :type => 'string'},
    {:name => 'published_in', :value => '1939', :type => 'integer'},
  {:external_id => '2', :fields => [
    {:name => 'title', :value => 'The Cat in the Hat', :type => 'string'},
    {:name => 'author', :value => 'Dr. Seuss', :type => 'string'},
    {:name => 'published_in', :value => '1957', :type => 'integer'},

# search the all the DocumentTypes (useful if you have more than one)
results = client.search(engine_slug, 'cat')

# search the 'books' DocumentType
results = client.search_document_type(engine_slug, document_type_slug, 'cat')

Using with Rails 3

The easiest way to get started using Swiftype with Rails is to read our Rails integration tutorial.

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Swiftype client library.

gem 'swiftype', '~> 1.0.0'

Update application dependencies with bundler.

$ bundle install

Create a configuration file at config/initializers/swiftype.rb, and add configuration information:

Swiftype.authenticated_url = ENV['SWIFTYPE_URL']

In your models, add callbacks to interact with the Swiftype API. See the Rails integration tutorial for details.

Using with Python

Add the Swiftype Python client library to your project.

Use the client:

import swiftype
import os
import urlparse from urlparse

swiftype_url = urlparse(os.environ['SWIFTYPE_URL'])
client = swiftype.Client(api_key=swiftype_url.username, host=swiftype_url.hostname)
engine_slug = 'engine'

client.create_document_type(engine_slug, 'books')

document = {
    'external_id': 123, # ID in your database
    'fields': [{ 'name': 'title',
                 'value': 'The Master and Margarita',
                 'type': 'string' },
                { 'name': 'author',
                  'value': 'Mikhail Bulgakov',
                  'type': 'string' },
                { 'name': 'published_in',
                  'value': '1967',
                  'type': 'integer' }]

client.create_document(engine_slug, 'books', document)

client.search(engine_slug, 'master')

Performing searches from the web front-end

The JSONP API will send all request parameters from the client. If you are using filters to hide data from users, you should not use JSONP API. Read more.

Swiftype has a read-only public API for search and suggest queries that is accessible using JSONP. This can be used from front-end code without passing through your servers.

To use the public API, install the Swiftype jQuery search library for search and Swiftype jQuery autocomplete library for type ahead autocomplete.


For more information on the features available within the Swiftype dashboard please see the features.

The Swiftype dashboard allows you to customize search results and browse your search analytics.

Swiftype Dashboard

Swiftype Dashboard

The dashboard can be accessed via the CLI:

$ heroku addons:open swiftype
Opening swiftype for sharp-mountain-4005…

Removing the add-on

Swiftype can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy swiftype
-----> Removing swiftype from sharp-mountain-4005... done, v20 (free)


All Swiftype support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@swiftype.com.

Additional resources

Additional resources are available at: