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:

https://api.omnious.com/lens/v1.1/recommendapi.omnious.com

Version 1.2: Recommended for new LENS users

Filter option added on request compared to version 1.1

https://api.omnious.com/lens/v1.2/recommendapi.omnious.com

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	Maximum number of items to recommend default: 10 max: 500
weightColorFeature	String	Weight of color to be reflected in recommendations default: MEDIUM Selectable from the following values LOW MEDIUM HIGH
showContext	Bool	Whether to display context information default: false
showImageInfo	Bool	Whether to display image information default: false

Request Examples

Example. request for recommendation (without Context information)

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)

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)

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	Weight of color to be reflected in recommendations LOW MEDIUM HIGH
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	Image information entered in Data Management API (Detection information, Image URL) null if showImageInfo is false
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

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

{
  "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	Maximum number of items to recommend default: 10 max: 500
weightColorFeature	String	Weight of color to be reflected in recommendations default: MEDIUM Selectable from the following values LOW MEDIUM HIGH
showContext	Bool	Whether to display context information default: false
showImageInfo	Bool	Whether to display image information default: false
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	type(required) gte, lte, gt, lt, eq : Use one out of the 5
context.price.discounted	Integer filter	type(required) gte, lte, gt, lt, eq : Use one out of the 5
context.mobilePrice	Object
context.mobilePrice.currency	currency filter	match
context.mobilePrice.value	Integer filter	type(required) gte, lte, gt, lt, eq : Use one out of the 5
context.mobilePrice.discounted	Integer filter	type(required) gte, lte, gt, lt, eq : Use one out of the 5

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.

Request Examples

Example 1. Request for recommendation (without context information)

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

Example 2. Request for recommendation (with context information)

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

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

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

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

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

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

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

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

{
  "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	Weight of color to be reflected in recommendations [LOW
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	Image information entered in Data Management API (Detection information, Image URL) null if showImageInfo is false
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

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

{
  "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"
        },
      }
    ]
  }
}