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"
        },
      }
    ]
  }
}
PreviousData Management APINextCamera Search API

Last updated

Was this helpful?