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

Synonyms Guide

Synonyms relate queries together that contextually have the same meaning in your dataset.

Sometimes users will use different terminology than your context might expect.

This can lead them to poor search relevance: you are selling movies, but they want films!

The Synonym feature builds synonym sets. A synonym set contains two or more queries that have similar meaning.

The queries can be synonyms, but they do not need to be.

Each item within a synonym set is a query. A query can be a string made up of one or more words.

Once a synonym set has been created, it will be applied to all future queries.

You can create them via the API or the Dashboard.

  • A synonym set can contain up to 32 words.
  • Synonym sets do not necessarily return the same results, because they are not equivalent from a relevance standpoint. You will likely get different results for the various terms in a synonym set.
  • Curations applied on a term don't apply for its synonyms unless explicitly configured.

API

You may construct, list, or delete synonym sets using the /synonyms API endpoint.

Example
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["summit", "peak", "cliff", "mountain"]
}'
Example Response
{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

Example
No Java example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["summit", "peak", "cliff", "mountain"]
}'
Example Response
No Java example available, showing cURL
{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

Example
No Node example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["summit", "peak", "cliff", "mountain"]
}'
Example Response
No Node example available, showing cURL
{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

Example
No Ruby example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["summit", "peak", "cliff", "mountain"]
}'
Example Response
No Ruby example available, showing cURL
{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

Example
No Python example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["summit", "peak", "cliff", "mountain"]
}'
Example Response
No Python example available, showing cURL
{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

Example
No Javascript example available, showing cURL
curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/synonyms' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "synonyms": ["summit", "peak", "cliff", "mountain"]
}'
Example Response
No Javascript example available, showing cURL
{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

Each synonym has a unique id which you can use to display or delete the synonym set after it has been created.

See the Synonyms API Reference for further information.

Dashboard

Within the dashboard, click into an Engine.

The Engine navigation menu has Search Settings section.

Under it you will find Synonyms alongside Curations and Relevance Tuning. Click into Synonyms.

Next, select Create a Synonym Set and then enter an assortment of queries.

Synonyms - A synonym set within the dashboard.
A synonym set through the eyes of the dashboard.

Once you click Save, the synonym set will be applied.

To remove the synonym set, click Manage, then Delete.

The moment it is deleted, the set will no longer influence your search results.

What's Next?

Configuring Synonyms is a useful way to guide your users to the most relevant content. It is most useful when you know the precise terms that they are searching for. For that, you should explore the Analytics and Clickthrough end-points, so that you are aware of your insightful capabilities. If you are looking to provide even more precise and curated results, venture to the Curations end-point.


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