Tech Topics

Elastic App Search: Query Suggestion API Now Available

The Query Suggestion API is now available within Elastic App Search.

"Did you mean autocomplete?"

Ah, yes, thanks — we can call it that, or typeahead, or autosuggest. While the name of the technique might differ, the constant is that query suggestions can greatly improve a search experience. Read along to learn more, or visit the documentation to get building.



As a user types a query, the Query Suggestion API looks for strong queries to suggest. Herein lies the key: the endpoint does not suggest results. 

A quality search experience, by its nature, will provide the most relevant results. But sometimes users have trouble finding the right words to use when searching, and this endpoint can help them.

Imagine we have a search engine full of outdoor parks; we indexed all of our park objects into an Elastic App Search Engine, and they are ready to be searched upon.  

A document might look like this:

     "nps_link": "",
     "title": "Zion",
     "date_established": "1919-11-19T06:00:00+00:00",
     "world_heritage_site": "false",
     "states": [ "Utah"],
     "description":  "Located at the junction of the Colorado Plateau, Great Basin, and Mojave Desert, this park contains sandstone features such as mesas, rock towers, and canyons, including the Virgin River Narrows. The various sandstone formations and the forks of the Virgin River create a wilderness divided into four ecosystems: desert, riparian, woodland, and coniferous forest.",
     "visitors": 4295127,
     "id": "park_zion",
     "location": "37.3,-113.05",
     "square_km": 595.8,
     "acres": 147237.02

When a user conducts a search within our application, we have decided to match results based on the state and title fields of the park documents. That way, someone can type the name of the park they want to visit or the state that it is located, and receive relevant results.

Now let us put ourselves in the shoes of a searcher...

A friend told them about a beautiful park, but they cannot quite remember its name. It's Zion National Park, but they don't know that yet.

They want to search for it and book a ticket to visit it.

“It started with a Z… Zeyeon, maybe?… Hmm…”

And so they attempt a search for “zeyeon”, first without query suggestions:

    "meta": {
      "warnings": [],
      "page": {
        "current": 1,
        "total_pages": 0,
        "total_results": 0,
        "size": 10
      "request_id": "85b78b8f32ac81253cc1654e540e0625"
    "results": []

No surprise, the query returns zero results.

Even with accurate relevance, that query is not even close to the matching "Zion" document. 

We don't want the user to get discouraged and end their search. 

When using query suggestions, their search experience might go like this:

”Hmmm… There was a z”…

  curl -X POST '' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer search-7eud55t7ecdmqzcanjsc9cqu' \
  -d '{
    "query": "z",
    "types": {
      "documents": {
        "fields": [
    "size": 4

”That’s right! Zion National Park! Time to book a ticket!”

    "results": {
      "documents": [
          "suggestion": "zion"
    "meta": {
      "request_id": "8d37831753eb9d5636a761f5fb3d6767"

The right title value, “zion”, returned as a suggestion. The suggestion can then be used to fuel their actual search. 

By guiding the searcher through the querying process, we help them assemble the most effective searches.

May We Also Suggest...

The Query Suggestion API is but one tool in a robust, relevance improving search toolbox.

Other valuable tools include Synonyms, which build groupings of similar search terms.

A search for any synonym will return results relevant to the entire set.

The prototypical example of a synonym set is for car: car, automobile, vehicle.  

Or, in the park, consider mountains: mountain, cliff, peak, summit:


Another tool is Relevance Tuning, which can boost the relevance of documents given certain field values, and tune the baseline scoring weight attributed to each field.

You can boost results given their proximity to a location coordinate provided by the user: “Find the park nearest to me!” 

Or tune your title field so its matches reward greater than those of other fields:


Finally, there are curations: curate the results of certain queries.

Perhaps you sell “tea” and you want a certain seasonal tea ranked first  for “green tea” queries. Or if something is out of stock or season, and you want to hide it from your result sets.

With outdoor parks, we want to promote Rocky Mountain Park for those who query “mountains”:


All of these tools have refined APIs and matching dashboard UIs, and are informed through fully API-digestible analytics, which can be organized with tags to automate deep relevance tuning of your search experience.


The Query Suggestion API will help your users find the right words. When paired with the rest of the relevance refining features in Elastic App Search, we think you’ll enjoy seeing people find just the think they are seeking. The API is also available within the App Search JavaScript client and the Reference UI.

You can get started today with a  free 14 day trial of our hosted version or  download the beta of the self-managed version. Each new trial comes preloaded with the National Parks data set, so you can experiment before bringing your own data.