Recommendation API

API Endpoint

The default API Endpoint is as follows, and the current latest version is 2023-02.

https://api.kr.omnicommerce.ai/2022-08/
https://api.kr.omnicommerce.ai/2023-02/

Filter Query

When recommending similar products, it is possible to filter the recommendation results based on metadata. For detailed rules for filtering conditions, refer to the documents below.

Metadata Filter

Recommendation API

The Recommendation API recommends and delivers visually 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.

Provide visually similar recommendations to the requested product Id through the path parameter.

Request Header

Name	Required	Type	Description
x-api-key	Required	String	API Key (refer to API Authentication Guide)

Request Parameter

Name	Required	Type	Description
limit	Optional	String	Maximum number of items to recommend (default: 10, max: 500)
showInfo	Optional	List[String]	Select additional information to be displayed along with a recommendation result (multiple selections possible) `[METADATA, IMAGE_INFO, CONTEXT_INFO]`
metadataFilter	Optional	String	Metadata Filter Query (see: Metadata Filter)

Request Example

/similar-items/recommend/A1101?limit=500&showInfo=IMAGE_INFO&showInfo=METADATA&showInfo=CONTEXT_INFO&metadataFilter.name.eq=skirt

Response

Name	Type	Description
id	String	Unique ID of the query product to be recommended
limit	integer	Maximum number of items to recommend
showInfo	List[String]	Selected additional information to be displayed along with a recommendation result
metadataFilter	Object	Metadata Filter Query (See: Metadata Filter)
recommendation	List[Recommendation]	Recommendation results (see below)

Name	Type	Description
order	Integer	An integer number as sorted in order by similarity (zero-based)
id	String	Unique ID of the query product to be recommended
similarityScore	float	Between 0 and 1, the higher the value, the higher the similarity. [This is available in 2023-02 version only.]
metadata	Object	Various product information managed by the customer, such as product name, brand, price, season, and discount rate. (see Product metadata) Null if no value (default)
imageInfo	Object	Image information of the recommended product. If there is `IMAGE_INFO` as the input value of `showInfo` field in the request, the value will be displayed. Null if no value (default)
├ imageInfo.detection	String	The detection field which is provided by the client when the product information was put into the workspace. (see Detection Field)
└ imageInfo.url	String	The URL of the representative image of the product.
contextInfo	Object	Context information of the recommended product. If there is `CONTEXT_INFO` as the input value of `showInfo` field, the value will be displayed. Null if no value (default)
├ contextInfo.salesUrl	String	URL of the page where the product is being sold
└ contextInfo.mobileSalesUrl	String	Mobile version URL of the page where the product is being sold

Example Responses

400 Bad Request

Invalid input format

{
    "errors": "json format error."
}

HTTP Status Code : 200

The following situations can lead to this response:

No products were recommended.
The product does not exist.
When requesting recommendations for similar products to an item currently being processed.

{
  "id": "AT000123FB",
  "limit": 10,
  "showInfo": ["METADATA","IMAGE_INFO"],
  "metadataFilter": {
    "productName": {
      "eq": "skirt"
    }
  },
  "recommendation": []
}

HTTP Status Code : 201

When recommendations exists

{
  "id": "AT000123FB",
  "limit": 10,
  "showInfo": [],
  "metadataFilter": {
    "productName": {
      "eq": "skirt"
    }
  },
  "recommendation": [
    {
      "order": 0,
      "id": "AT000123FB",
      "similarityScore": 0.99,
      "metadata": null,
      "imageInfo": null,
      "contextInfo": null
    },
    {
      "order": 1,
      "id": "AT00158AE",
      "similarityScore": 0.98,
      "metadata": null,
      "imageInfo": null,
      "contextInfo": null
    },
    {
      "order": 2,
      "id": "F800158GA",
      "similarityScore": 0.97,
      "metadata": null,
      "imageInfo": null,
      "contextInfo": null
    },
    {
      "order": 3,
      "id": "AF10881GK",
      "similarityScore": 0.96,
      "metadata": null,
      "imageInfo": null,
      "contextInfo": null
    },    
  ]
}

Recommendations with Metadata, ImageInfo, and contextInfo

{
  "id": "AT000123FB",
  "limit": 10,
  "showInfo": ["METADATA","IMAGE_INFO", "CONTEXT_INFO"],
  "metadataFilter": {
    "productName": {
      "eq": "skirt"
    }
  },
  "recommendation": [
    {
      "order": 0,
      "id": "AT000123FB",
      "similarityScore": 0.99,
      "metadata": {
        "productName": "a",
        "originPrice": 100
      },
      "imageInfo": {
        "detection": "TOP",
        "url": "http://imageserverurl/some.image.jpg"
      }"contextInfo": {
        "salesUrl": "http://imageserverurl/some.image.jpg",
        "mobileSalesUrl": "http://imageserverurl/some.image.jpg"
      }
    },
    {
      "order": 1,
      "id": "AT00158AE",
      "similarityScore": 0.98,
      "metadata": {
        "productName": "b",
        "originPrice": 200
      },
      "imageInfo": {
        "detection": "TOP",
        "url": "http://imageserverurl/some.image.jpg"
      },
      "contextInfo": {
        "salesUrl": "http://imageserverurl/some.image.jpg",
        "mobileSalesUrl": "http://imageserverurl/some.image.jpg"
      }
    },
    {
      "order": 2,
      "id": "F800158GA",
      "similarityScore": 0.97,
      "metadata": {
        "productName": "c",
        "originPrice": 300
      },
      "imageInfo": {
        "detection": "TOP",
        "url": "http://imageserverurl/some.image.jpg"
      },
      "contextInfo": {
        "salesUrl": "http://imageserverurl/some.image.jpg",
        "mobileSalesUrl": null
      }
    },
    {
      "order": 3,
      "id": "AF10881GK",
      "similarityScore": 0.96,
      "metadata": {
        "productName": "d",
        "originPrice": 400
      },
      "imageInfo": {
        "detection": "TOP",
        "url": "http://imageserverurl/some.image.jpg"
      },
      "contextInfo": {
        "salesUrl": null,
        "mobileSalesUrl": "http://imageserverurl/some.image.jpg"
      }
    },
    
  ]
}

Provide visually similar recommendations to the requested product Id through the path parameter.

Request Header

Name	Required	Type	Description
x-api-key	Required	String	API Key (refer to API Authentication Guide)
Content-Type	Required	String	Content Type. Only `Application/json` is supported.

Request Body

Name	Required	Type	Description
limit	Optional	String	Maximum number of items to recommend (default: 10, max: 500)
showInfo	Optional	List[String]	Select additional information to be displayed along with a recommendation result (multiple selections possible) `[METADATA, IMAGE_INFO, CONTEXT_INFO]`
metadataFilter	Optional	Object	Metadata Filter Query (see: Metadata Filter)

Request Example

{
    "limit": 500,
    "showInfo": ["METADATA", "IMAGE_INFO", "CONTEXT_INFO"],
    "metadataFilter" : {"productName": {"eq": "skirt"}}
}

Response

Name	Type	Description
id	String	Unique ID of the query product to be recommended
limit	integer	Maximum number of items to recommend
showInfo	List[String]	Selected additional information to be displayed along with a recommendation result
metadataFilter	Object	Metadata Filter Query (See: Metadata Filter)

| recommendation | List[Recommendation] | Recommendation results (see below) |

Name	Type	Description
order	Integer	An integer number as sorted in order by similarity (zero-based)
id	String	Unique ID of the query product to be recommended
similarityScore	float	Between 0 and 1, the higher the value, the higher the similarity. [This is available in 2023-02 version only.]
metadata	Object	Various product information managed by the customer, such as product name, brand, price, season, and discount rate. (see Product metadata) Null if no value (default)
imageInfo	Object	Image information of the recommended product. If there is `IMAGE_INFO` as the input value of `showInfo` field in the request, the value will be displayed. Null if no value (default)
├ imageInfo.detection	String	The detection field which is provided by the client when the product information was put into the workspace. (see Detection Field)
└ imageInfo.url	String	The URL of the representative image of the product.
contextInfo	Object	Context information of the recommended product. If there is `CONTEXT_INFO` as the input value of `showInfo` field, the value will be displayed. Null if no value (default)
├ contextInfo.salesUrl	String	URL of the page where the product is being sold
└ contextInfo.mobileSalesUrl	String	Mobile version URL of the page where the product is being sold

Recommendation API

API Endpoint​

Filter Query​

Recommendation API​

GET /similar-items/recommend/<product id>: Get visually similar recommendations​

Request Header​

Request Parameter​

Request Example​

Response​

Recommendation​

Example Responses​

POST /similar-items/recommend/<product id>: Get visually similar recommendations​

Request Header​

Request Body​

Request Example​

Response​

Recommendation​

API Endpoint

Filter Query

Recommendation API

GET /similar-items/recommend/<product id>: Get visually similar recommendations

Request Header

Request Parameter

Request Example

Response

Recommendation

Example Responses

POST /similar-items/recommend/<product id>: Get visually similar recommendations

Request Header

Request Body

Request Example

Response

Recommendation