Overview Crawler Developer API Platform API Tutorials Client Libraries

Read-only Public API

In addition to the private API which is secured with your API key, Swiftype supports a read-only public API that uses your Search Engine's Engine Key. The public API is read-only, so it is appropriate for using from client-side JavaScript or a mobile app where you do not want to expose your read-write API key.

To use the public API, find the Engine Key for your search engine. The Engine Keys for each of your search engines are located on your Swiftype dashboard.

Public Search API

To perform a full-text with, use the search endpoint. The parameters are the same as the private search scoped by Engine.

Search an Engine with the Public API

GET /api/v1/public/engines/search?q={query}&engine_key={your engine key}
POST /api/v1/public/engines/search?q={query}&engine_key={your engine key}

Public Search Options

Option Default Description
engine_key none The Engine Key used to look up the search engine to search. (required)
callback none The name of a callback function in your client-side JavaScript. If provided, the results will be sent in JSONP format.

For the remaining options, see the search options.

Public autocomplete API

To perform a prefix search, use the suggest endpoint. The parameters are the same as the private autocomplete endpoint scoped by Engine.

Autocomplete within an Engine with the Public API

GET /api/v1/public/engines/suggest?q={query}&engine_key={your engine key}
POST /api/v1/public/engines/suggest?q={query}&engine_key={your engine key}

Public Search Options

Option Default Description
q none The query used for a prefix match. Queries shorter than a few characters may not return results. (required)
engine_key none The Engine Key used to look up the search engine to search. (required)
callback none The name of a callback function in your client-side JavaScript. If provided, the results will be sent in JSONP format.

For the remaining options, see the search options.

Cross-domain requests with JSONP

The public API supports JSONP, making it easy to execute searches and autocompletions directly from client-side JavaScript. To use JSONP, set the format to JSON by specifying the .json extension and add a callback parameter specifying the name of the function in your code to call with the results.

Example - JSONP search request
curl -X GET "http://api.swiftype.com/api/v1/public/engines/search.json?q=brothers&callback=yourCallbackFunction&engine_key=YOUR_ENGINE_KEY"
  

Example Response

yourCallbackFunction({
  "records": {
    "page": [
      {
        "body": "Band of Brothers DVD",
        "external_id": "9508ace2e1ba669854eb49fbe9429952ff1a6d4c",
        "sections": "",
        "title": "Band of Brothers",
        "updated_at": "2013-02-04T19:09:40Z",
        "image": "",
        "type": "post",
        "url": "http://yoursite.com/band-of-brothers",
        "popularity": 1,
        "published_at": "2012-01-01T08:00:00Z",
        "info": "",
        "id": "5025a3036052f6b650000006",
        "_score": 3.1224604,
        "highlight": {
          "title": "Band of _Brothers_",
          "body": "Band of _Brothers_ DVD"
        },
      }
    ]
  },
  "info": {
    "page": {
      "query": "brothers",
      "current_page": 1,
      "num_pages": 1,
      "per_page": 20,
      "total_result_count": 1,
      "facets": {}
    }
  }
})

To see more examples of cross-domain requests, see our jQuery customization tutorial or review our jQuery search or autocomplete plugins.

Security

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.

Read more about protecting sensitive data.