# Recommendation API

## Overview

The Recommendation API recommends and delivers similar products based on the product code requested by the customer. Both GET and POST methods are supported. Please select and use the method you want.

## Endpoint

We currently support two LENS API versions

**Version 1.1:**

{% embed url="<https://api.omnious.com/lens/v1.1/recommend>" %}

**Version 1.2: Recommended for new LENS users**

Filter option added on request compared to version 1.1

{% embed url="<https://api.omnious.com/lens/v1.2/recommend>" %}

## **Method 1) GET /**

### **Request**

#### **Header**

| **Name**  | **Description**                                     |
| --------- | --------------------------------------------------- |
| x-api-key | API Key for authentication from Omnious \[Required] |

#### **Query Parameter**

| **Name**           | **Type** | **Description**                                                                                                                                                                                 |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                 | String   | (required) Product code of the query product you want to recommend                                                                                                                              |
| limit              | Int      | <p>Maximum number of items to recommend</p><ul><li>default: 10</li><li>max: 500</li></ul>                                                                                                       |
| weightColorFeature | String   | <p>Weight of color to be reflected in recommendations</p><ul><li>default: MEDIUM</li><li><p>Selectable from the following values</p><ul><li>LOW</li><li>MEDIUM</li><li>HIGH</li></ul></li></ul> |
| showContext        | Bool     | <p>Whether to display context information</p><ul><li>default: false</li></ul>                                                                                                                   |
| showImageInfo      | Bool     | <p>Whether to display image information</p><ul><li>default: false</li></ul>                                                                                                                     |

### **Request Examples**

**Example. request for recommendation (without Context information)**

```javascript
curl --location --request GET 'https://api.omnious.com/lens/v1.1/recommend?id=725447&limit=10&weightColorFeature=MEDIUM' \
--header 'x-api-key: <<API-KEY>>'
```

**Example. request for recommendation (with Context information)**

```javascript
curl --location --request GET 'https://api.omnious.com/lens/v1.1/recommend?id=725447&limit=10&weightColorFeature=MEDIUM&showContext=true' \
--header 'x-api-key: <<API-KEY>>'
```

**Example. request for recommendation (with Context and image information)**

```javascript
curl --location --request GET 'https://api.omnious.com/lens/v1.1/recommend?id=725447&limit=10&weightColorFeature=MEDIUM&showContext=true&showImageInfo=true' \
--header 'x-api-key:  <<API-KEY>>'
```

### **Response**

Return recommended products in order of similarity.

#### **HTTP Status Codes**

| **Code** | **Description**                                          |
| -------- | -------------------------------------------------------- |
| 403      | API KEY authentication related error                     |
| 400      | Input Data Validation related error                      |
| 200      | Success response with zero recommendation results        |
| 201      | Success response with one or more recommendation results |
| 500      | Server error                                             |

#### **Response Data**

| **Name**           | **Type**                 | **Description**                                                                                            |
| ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| id                 | String                   | Product code of the query product you want to recommend                                                    |
| limit              | Int                      | Maximum number of items to recommend                                                                       |
| weightColorFeature | String                   | <p>Weight of color to be reflected in recommendations</p><ul><li>LOW</li><li>MEDIUM</li><li>HIGH</li></ul> |
| showContext        | Bool                     | Whether to display context information                                                                     |
| showImageInfo      | Bool                     | Whether to display image information                                                                       |
| recommendation     | Array of Recommendations | List of recommendations (refer to the below)                                                               |

#### **Recommendations**

| **Name**            | **Type** | **Description**                                                                                                                       |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| id                  | String   | Product code to recommend                                                                                                             |
| url                 | String   | Recommended product information url                                                                                                   |
| context             | Object   | Context information inserted in Data Management API                                                                                   |
| imageInfo           | Object   | <p>Image information entered in Data Management API</p><p>(Detection information, Image URL)</p><p>null if showImageInfo is false</p> |
| imageInfo.detection | String   | Detection information of the product                                                                                                  |
| imageInfo.content   | String   | The url of the product image used in the analysis                                                                                     |

### **Response Example**

**Example. When 4 products are recommended**

> Context information and imageinfo are not included

**HTTP Status Code: 201**

```javascript
{
  "status": "ok",
  "error": null,
  "data": {
    "id": "AT000123FB",
    "limit": 10,
    "weightColorFeature": "HIGH",
    "showContext": false,
    "showImageInfo": false,
    "recommendation": [
      {
        "order": 1,
        "id": "AT000123FB",
        "url": "http://asdfmall/product?id=AT00123FB",
        "context": null,
        "imageInfo": null
      },
      {
        "order": 2,
        "id": "AT00158AE",
        "url": "http://asdfmall/product?id=AT00158AE",
        "context": null,
        "imageInfo": null
      },
      {
        "order": 3,
        "id": "F800158GA",
        "url": "http://asdfmall/product?id=F800158GA",
        "context": null,
        "imageInfo": null
      },
      {
        "order": 4,
        "id": "AF10881GK",
        "url": "http://asdfmall/product?id=AF10881GK",
        "context": null,
        "imageInfo": null
      },

    ]
  }
}
```

**Example. When 4 products are recommended (HTTP Status Code: 201)**

> Context information and imageinfo are included

```javascript
{
  "status": "ok",
  "error": null,
  "data": {
    "id": "AT000123FB",
    "limit": 10,
    "weightColorFeature": "HIGH",
    "showContext": true,
    "showImageInfo": true,
    "recommend": [
      {
        "order": 1,
        "id": "AT000123FB",
        "url": "http://asdfmall/product?id=AT00123FB",
        "context": {
          "name": "zip-up hoodie",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 11,
            "discounted": 9.99
          }

        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 2,
        "id": "AT00158AE",
        "url": "http://asdfmall/product?id=AT00158AE",
        "context": {
          "name": "fleece hoodie",
          "gender": "WOMEN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 11,
            "discounted": 9.99
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 3,
        "id": "F800158GA",
        "url": "http://asdfmall/product?id=F800158GA",
        "context": {
          "name": "gray fleece hoddie",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 4,
        "id": "AF10881GK",
        "url": "http://asdfmall/product?id=AF10881GK",
        "context": {
          "name": "fleece t-shirts",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 11,
            "discounted": 9.99
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      }
    ]
  }
}
```

## **Method 2) POST /**

### **Request**

#### **Header**

| **Name**     | **Description**                                     |
| ------------ | --------------------------------------------------- |
| Content-Type | application/json                                    |
| x-api-key    | API Key for authentication from Omnious \[Required] |

#### **Body**

| **Name**           | **Type**      | **Description**                                                                                                                                                                                 |
| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                 | String        | (Required) Product code of the query product you want to recommend                                                                                                                              |
| limit              | Int           | <p>Maximum number of items to recommend</p><ul><li>default: 10</li><li>max: 500</li></ul>                                                                                                       |
| weightColorFeature | String        | <p>Weight of color to be reflected in recommendations</p><ul><li>default: MEDIUM</li><li><p>Selectable from the following values</p><ul><li>LOW</li><li>MEDIUM</li><li>HIGH</li></ul></li></ul> |
| showContext        | Bool          | <p>Whether to display context information</p><ul><li>default: false</li></ul>                                                                                                                   |
| showImageInfo      | Bool          | <p>Whether to display image information</p><ul><li>default: false</li></ul>                                                                                                                     |
| filter             | Filter object | Filters are available from version 1.2                                                                                                                                                          |

#### Filter

| Name                           | Type            | Description                                                             |
| ------------------------------ | --------------- | ----------------------------------------------------------------------- |
| url                            | String filter   | include, exclude, match                                                 |
| image                          | Object          |                                                                         |
| image.content                  | String filter   | include, exclude, match                                                 |
| context                        | Object          |                                                                         |
| context.name                   | String filter   | include, exclude, match                                                 |
| context.gender                 | String filter   | include, exclude, match                                                 |
| context.brand                  | String filter   | include, exclude, match                                                 |
| context.price                  | Object          |                                                                         |
| context.price.currency         | currency filter | match                                                                   |
| context.price.value            | Integer filter  | <p>type(required)</p><p>gte, lte, gt, lt, eq : Use one out of the 5</p> |
| context.price.discounted       | Integer filter  | <p>type(required)</p><p>gte, lte, gt, lt, eq : Use one out of the 5</p> |
| context.mobilePrice            | Object          |                                                                         |
| context.mobilePrice.currency   | currency filter | match                                                                   |
| context.mobilePrice.value      | Integer filter  | <p>type(required)</p><p>gte, lte, gt, lt, eq : Use one out of the 5</p> |
| context.mobilePrice.discounted | Integer filter  | <p>type(required)</p><p>gte, lte, gt, lt, eq : Use one out of the 5</p> |

{% hint style="info" %}

#### String filters

* include: If the string is included
  * e.g) **If** "include": "shirts" **then** T-shirts(o), pants(x)
* exclude: If the string is not included
  * e.g) **If** "exclude": "shirts" **then** T-shirts(x), pants(o)
* match: If there is an exact string match
  * e.g) **If** "match": "shirts" **then** T-shirts(x), shirts(o)

#### Integer filter

* type: rate or abs (rate: ratio, abs: absolute value)
* gte: great than or equal to (>=value)
* lte: less than or equal to (<=value)
* gt: great than (>value)
* eq: equals (=value)

#### currency filter

* match: If there is an exact string match

#### Both lowercase and uppercase are accepted.

{% endhint %}

###

### **Request Examples**

**Example 1. Request for recommendation (without context information)**

```javascript
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM"
}
```

**Example 2. Request for recommendation (with context information)**

```javascript
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true
}
```

**Example 3. Request for recommendation (with context and image information)**

```javascript
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true
}
```

#### Example 4. **Filtering items in the price range** of 400 \~ 700

```json
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "price": {
      "value": {
        "type": "abs",
        "gte": 400,
        "lte": 700
      }
    }
  }
}
```

**Example 5. Filtering items between 0.7 \~ 1.2 ratio (70% \~ 120%) of the price of the input item**

```json
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "price": {
      "value": {
        "type": "rate",
        "gte": 0.7,
        "lte": 1.2
      }
    }
  }
}
```

#### Example 6. Filtering "Nike" brand products

```json
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "context": {
      "brand": {
        "match": "Nike"
      }
    }
  }
}
```

#### Example 7. Filtering products that include "shirts" in the product name

```json
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "context": {
      "name": {
        "include": "shirts"
      }
    }
  }
}
```

**Example 8. Filtering products don't include "shirts" in the product name**

```json
{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "context": {
      "name": {
        "exclude": "shirts"
      }
    }
  }
}
```

###

### **Response**

Return recommended products in order of similarity.

**HTTP Status Code**

| **Code** | **Description**                                          |
| -------- | -------------------------------------------------------- |
| 403      | API KEY authentication related error                     |
| 400      | Input Data Validation related error                      |
| 200      | Success response with zero recommendation results        |
| 201      | Success response with one or more recommendation results |
| 500      | Server error                                             |

#### **Response Data**

| **Name**           | **Type**                | **Description**                                                       |
| ------------------ | ----------------------- | --------------------------------------------------------------------- |
| id                 | String                  | Product code to base the search on                                    |
| limit              | Int                     | Maximum number of items to recommend                                  |
| weightColorFeature | String                  | <p>Weight of color to be reflected in recommendations</p><p>\[LOW</p> |
| showContext        | Bool                    | Whether to display context information                                |
| showImageInfo      | Bool                    | Whether to display image information                                  |
| recommendations    | List of Recommendations | List of recommendations (refer to the below)                          |

#### **Recommendations**

| **Name**            | **Type** | **Description**                                                                                                                       |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| id                  | String   | Product code to recommend                                                                                                             |
| url                 | String   | Recommended product information url                                                                                                   |
| context             | Object   | Context information inserted in Data Management API                                                                                   |
| imageInfo           | Object   | <p>Image information entered in Data Management API</p><p>(Detection information, Image URL)</p><p>null if showImageInfo is false</p> |
| imageInfo.detection | String   | Detection information of the product                                                                                                  |
| imageInfo.content   | String   | The url of the product image used in the analysis                                                                                     |

**Example. When 4 products are recommended (HTTP Status Code: 201)**

> Context information and imageinfo are not included

```javascript
{
  "status": "ok",
  "error": null,
  "data": {
    "id": "AT000123FB",
    "limit": 10,
    "weightColorFeature": "HIGH",
    "showContext": false,
    "showImageInfo": false,
    "recommendation": [
      {
        "order": 1,
        "id": "AT000123FB",
        "url": "http://asdfmall/product?id=AT00123FB",
        "context": null,
        "imageInfo": null
      },
      {
        "order": 2,
        "id": "AT00158AE",
        "url": "http://asdfmall/product?id=AT00158AE",
        "context": null,
        "imageInfo": null
      },
      {
        "order": 3,
        "id": "F800158GA",
        "url": "http://asdfmall/product?id=F800158GA",
        "context": null,
        "imageInfo": null
      },
      {
        "order": 4,
        "id": "AF10881GK",
        "url": "http://asdfmall/product?id=AF10881GK",
        "context": null,
        "imageInfo": null
      },

    ]
  }
}
```

**Example. When 4 products are recommended (HTTP Status Code: 201)**

> Context information and imageinfo are included

```javascript
{
  "status": "ok",
  "error": null,
  "data": {
    "id": "AT000123FB",
    "limit": 10,
    "weightColorFeature": "HIGH",
    "showContext": true,
    "showImageInfo": true,
    "recommend": [
      {
        "order": 1,
        "id": "AT000123FB",
        "url": "http://asdfmall/product?id=AT00123FB",
        "context": {
          "name": "Zip-Up hoodie",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 11,
            "discounted": 8.99
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 2,
        "id": "AT00158AE",
        "url": "http://asdfmall/product?id=AT00158AE",
        "context": {
          "name": "Fleece hoodie",
          "gender": "WOMEN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 11,
            "discounted": 8
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 3,
        "id": "F800158GA",
        "url": "http://asdfmall/product?id=F800158GA",
        "context": {
          "name": "Gray fleece hoodie",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 11,
            "discounted": 8.99
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 4,
        "id": "AF10881GK",
        "url": "http://asdfmall/product?id=AF10881GK",
        "context": {
          "name": "Fleece t-shirts",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "USD",
            "value": 12,
            "discounted": 9.99
          },
          "mobilePrice": {
            "currency": "USD",
            "value": 11,
            "discounted": 8
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      }
    ]
  }
}
```
