When navigating an eCommerce store’s catalogue and looking for a specific product, there may well be products that should appear in the results list as they have similar characteristic values to those of the query intent, but that don’t appear. This is often due to their pre-defined values not matching with the query value.

For these instances, Empathy.co has the Play API that allows users to create synonyms in a way that’s easy and intuitive, solving, in most cases, these types of issues.

One of the many definitions for synonyms is: “a word or phrase that means exactly or nearly the same as another word or phrase in the same language, for example shut is a synonym of close.”

However, we often find that the concept of synonyms can be confused when using this functionality as we try to match similar products that we want to be displayed within a search results list through cataloguing the values ​​of their characteristics but, in many cases, without these actually being a true synonym.

Let’s imagine that we have a fashion site and we do a search for ‘grey shirts.’ We note that one shirt that should appear, doesn’t, and it’s one we want to sell and believe to have great potential. However, at the same time we don’t want to boost it or give it an exaggerated importance.

The wonderful shirt in question is of the Latin artist “Bad Bunny” and in its characteristics it indicates that its colour is ‘ash’. So, one option could be to create a synonym between the terms ‘grey’ and ‘bad bunny’ to solve this issue and ensure that the shirt appears when this type of search is carried out. ERROR!

This doesn’t work as the synonym isn’t, by definition, a synonym and may therefore create other issues: In fact, it’s more similar to a product boost. This functionality was explained in a blog post by my colleague Roberto, take a look!

Another way to solve this specific use case is through understanding query context and intent and using this to position the query correctly in the results list. You can see more information about our context feature here.

In our case, and without breaking the definition of the synonym, we could create a synonym between the terms ‘grey’ and ‘ash’ that would help our beloved shirt appear in our original search.

Creating synonyms

Now that we’ve seen the pitfalls to avoid when creating synonyms, we’ll take a look at how to create these using two different methods.

  1. Create synonyms through the dashboard: With this intuitive interface we can create in seconds a synonym between terms of interest and similarity. You can find a complete guide of synonym creation in this post from my colleague Manuel.
  2. Create synonyms through the API: The Empathy Play API also enables synonyms to be created so that we can tailor the language used for products to define and improve the results lists. In the following example, we can see a small program created in the Golang language for the creation of a synonym:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
    "bytes"
    "encoding/json"
    )

const (
    //Header
    contentType       = "Content-Type"
    authorization     = "Authorization"
    bearer            = "Bearer"
    applicationJson   = "application/json"

    //URLs
    loginUrl          = "https://api.empathybroker.com/user/v1/user/login"
    synonymUrl        = "https://api.empathybroker.com/play/v1/{your_site}/synonyms"
)

type Synonym struct {
    Type             string               `json:"type"`
    Lang             string               `json:"lang"`
    Enabled          bool                 `json:"enabled"`
    Synonyms         []string             `json:"synonyms"`
    Alternatives     []string             `json:"alternatives"`
    Extra            map[string]string    `json:"extra"`
}

type LoginResult struct {
    ExpirationDate   string   `json:"expiration_date"`
    UserToken        string   `json:"user_token"`
}

type LoginUser struct {
    Email            string   `json:"email"`
    Password         string   `json:"password"`
}

var httpClient = &http.Client{}

//Handle errors in http request and print status and headers
func handleHttpResponse(resp *http.Response, err error) {
    //Handle error
    if err != nil {
        panic(err)
    }

    //Print details
    fmt.Println("Http Response Status: ", resp.Status)
    fmt.Println("Http Response Headers: ", resp.Header)
}

//Method to do httpRequest to login with user and password and obtain a valid token
func login() string {
    //Define request data
    fmt.Println("URL: > ", loginUrl)

    var loginUser = LoginUser { "your_email@company.co", "your_password" }
    jsonBody, _ := json.Marshal(loginUser)

    //Do http request
    req, _ := http.NewRequest(http.MethodPost, loginUrl, bytes.NewBuffer(jsonBody))
    req.Header.Set(contentType, applicationJson)
     
    resp, err := httpClient.Do(req)
    handleHttpResponse(resp, err)

    //Get login token (if login ok)
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println("Http Response Body:", string(body))

    var response LoginResult
    json.Unmarshal(body, &response)

    return string(response.UserToken)
}

//Method to do httpRequest to create a new dummy synonym
func createSynonym(token string) {
    //Define request data
    var synonymData = Synonym { "color", "en", true, []string{"grey", "ash"}, []string{}, map[string]string{"user": "username"} }
    jsonData, _ := json.Marshal(synonymData)

     //Do http request
    req, _ := http.NewRequest(http.MethodPost, synonymUrl, bytes.NewBuffer(jsonData))
    req.Header.Set(contentType, applicationJson)
    req.Header.Set(authorization, fmt.Sprintf("%s %s", bearer, token))
     
    resp, err := httpClient.Do(req)
    handleHttpResponse(resp, err)
}

func main() {
    token := login()
    createSynonym(token)
}

So, don’t wait any longer and start using good synonyms now! Let’s improve the experience and findability of your site…

oh! and make sure you check out and Bad Bunny too!