Hello, Hi, Hey from our brand new Synonyms API!

At Algolia we’re big on choice. We appreciate that different people search for the same things using different queries and keywords. Therefore incorporating synonyms has played a crucial part in making our search “intelligent”.

Over the last two years, we’ve refined and reworked our synonyms feature to make it one of the most comprehensive in the market. It now supports almost all types of expressions: multi-word expressions, abbreviations, expressions containing symbols and more. It even supports advanced features such as placeholders. Today, Algolia is excited to announce the release of a dedicated API for you to manage synonyms!

Why a new API?

We’ve made significant improvements to our synonyms feature since its inception, but we also know that the configuration methods for it need work. Up until today, you had to configure synonyms via an index setting. This approach worked perfectly well if you needed to add just a few synonyms but it became harder to manage with regard to speed if a lot of synonyms needed to be on the list. There were three main drawbacks:

• Adding more synonyms had become a challenge (you could not use the dashboard to configure a large set of synonyms but had to write a few lines of code to push all of them as a new index setting)

• Long lists of (thousands of) synonyms impacted the performance of the getSettings API call and the performance of search to a certain extent (settings are read when opening an index)

• Configuring the same synonyms on replica indices was a time-consuming process and left something to be desired for

What will I get with this API?

We’re primarily developers and fully comprehend the importance of backward compatibility. You can still use your previous methods of configuration via an index setting and decide when you want to use this new API.  In other words: there are no breaking changes! Your production code will continue to work as-is with support from the old API, which is still very much in existence and receives TLC on a regular basis.

We’ve merely introduced a small change in our new API clients: the getSettings method does not return synonyms and you need to use our new specialized search Synonyms method without any query, in order to retrieve all of them.

This new API is already supported by all of our API clients and you can start using it today. The documentation is available on this page. The major improvements you can benefit from are:

• Ease of use: one API endpoint for 99% of the use cases; you can just upload your synonyms in one big batch via the batch API call, using the parameter, replaceExistingSynonyms boolean, set to true.

• Scalability: this new endpoint supports millions of synonyms without impacting dashboard and search performance

• Enhanced Dashboard: we built a new interface in the dashboard to search and edit synonym sets

• Ease of Reproduction: you can use the forwardToReplicas boolean parameter to forward the synonyms to all replica indices (no more painful replication of synonyms!)

Available now!

This new feature has already been deployed and is available to all of our users. We hope you love this new API and have as much fun with it as we did while making it.  As always, we eagerly await your feedback, which we value deeply and and use to help improve the product!

Happy coding!