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.

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"]
}'

{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

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"]
}'

{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

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"]
}'

{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

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"]
}'

{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

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"]
}'

{
  "id": "syn-33dh34689rre8994g5h94i0nf4",
  "synonyms": [
    "summit",
    "peak",
    "cliff",
    "mountain"
  ]
}

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"]
}'

{
  "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.

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.

• Analytics
• Clickthrough
• Curations

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