@lableb/javascript-sdk/documentation/recommend.md

Lableb cloud search client for javascript

# Lableb's Client | Recommend API

After creating a new instance of Lableb's Client,

```js
const lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
});
```

You can use the recommend function as 

```js
const { code, response, time } = await lablebClient.recommend(options);

const recommendResults = response.results;
```

----------------------

## Options

All options has types validation built in for you, in case you mis-typed something, And if you're using [typescript](https://github.com/microsoft/TypeScript) the code editor will tell you for any mis-typed argument instantly.

Options are of three categories:
- recommend specific
- globally shared, which can be used to override any global option for this recommend function call
- user related

----------------------

### recommend specific options


| field   | type   | description |
| ------- | ------ | ----------- |                                                     
| id*     | string | document(data) id that you want similar document of |                
| title   | string | document(data) title that you want similar document of |
| url     | string | document(data) url that you want similar document of |
| sort    | string | sort your results by specific field and specific order |
| limit   | number | limit your recommend results to some number |




  - Sort syntax

    You type the field name followed by the `asc` or `desc` to sort data by that field in an ascending or   descending order respectively.
    
    Example:
    
    ```js
    await lablebClient.search({
        sort: "date desc"
    });
    ```


----------------------



### Globally shared options

Passing these options to the recommend function will override any globally passed options to the main `LablebClient` of the same name.

| field         | type   | description |
| ------------- | ------ | ----------- |
| platformName  | string | your platform name in small-letters |
| indexName     | string | the used index name for the recommend function |
| recommendHandler | string | the used recommend handler for the recommend function |
| APIKey        | string | your recommend API Key copied from [Lableb Dashboard](https://dashboard.lableb.com) |



----------------------


### User related options

Useful to track your users behavior later on, because knowing your users can help you better develop your platform/product.

| field         | type   | description |
| ------------- | ------ | ----------- |
| userId        | string | end user id |
| userIp        | string | end user IP address |
| userCountry   | string | end user country code(ISO-3166) |
| sessionId     | string | uniques session Id for your end user |
| sessionIdGenerator  | function | pass callback that generate unique session id string |

-----------------------


#### Alternative syntax for async code

```js
let lablebClient = LablebClient({
    APIKey: process.env.API_KEY,
    platformName: process.env.PLATFORM_NAME,
})

  lablebClient.recommend(options)
  .then(recommendResponse => {

      const { code, response, time } = recommendResponse;

      const recommendResults = response.results;
  })
  .catch(console.error);;

```


-------------------------



### Recommend Response


```js
const recommendResponse = await lablebClient.recommend(options);
```


| field                              | type   | description |
| ---------------------------------- | ------ | ----------- |
| time                               | number | time spent for the request in milliseconds |
| code                               | number | http response code                         |
| [response](#recommend-results)  | object | [recommend results](#recommend-results) |




### recommend Results

| field                         | type   | description |
| ----------------------------- | ------ | ----------- |
| found_documents               | number | documents count found for the given recommend request |
| [results](#results-example)   | array  | array of documents each has at least an `id` and a `feedback` object |
| [facets](#facets-example)     | object | contains filters keywords that can be used to further filters the returned documents |



---------------------



#### recommend Response Examples



##### Results Example

```json
[
    { 
        id: "8112-cmb", 
        feedback: {            
            sourceId: 141,
            sourceTitle: "Searching for water",
            sourceUrl: "https://example.com/articles/searching-for-water",

            targetId: 984,
            targetTitle: "How to preserve water consumption by 20%",
            targetUrl: "https://example.com/articles/preserve-water-consumption",

            itemOrder: 2,
            sessionId: "a9VAm22",

            userCountry: "AE",
            userId: "um29ava-mv92na-kieyqn-annv1",
            userIp: "172.165.32.1" 
        }, 
        ...fields 
    },
    ...
]
```


Now you can use the `feedback` object returned for the future [recommend Feedback](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/recommend-feedback.md) request


```js
const { code, response, time } = await lablebClient.recommend(options);

const recommendResults = response.results;

// later on, the end user clicks on the first result
const userInteraction = recommendResults[0];

await lablebClient.feedback.recommend.single({
  documentFeedback: userInteraction.feedback
});
```



##### Facets Example

For details on each property check [Facets Anatomy](https://gitlab.com/lableb-cse-sdks/javascript-sdk/-/blob/master/documentation/facets.md)

```json
{
    "count": 3,
    "language": {
        "buckets": [
            {
                "value": "ar",
                "count": 199
            },
            {
                "value": "en",
                "count": 199
            }
        ]
    },
    "categories": {
        "buckets": [
            {
                "value": "Accessories",
                "count": 37
            },
            {
                "value": "Hats ",
                "count": 252
            },
            ...
        ]
    },
    "status": {
        "buckets": [
            {
                "value": "Out Of Stock",
                "count": 194
            },
            {
                "value": "In Stock",
                "count": 5
            }
        ]
    }
}
```