Recommendation API

API Endpoint

기본 API Endpoint는 아래와 같으며, 현재 최신 버전은 2023-02 입니다.

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

Filter Query

유사 상품 추천시 Metadata 기준으로 추천 결과 값을 Filtering 할 수 있습니다. 세부적인 Filtering 조건 입력 방법은 아래의 하위 문서를 참조하세요.

Metadata Filter

유사 상품 추천 API

Request Header

Name	Required	Type	Description
x-api-key	필수	String	API Key (참조: API 인증 가이드)

Request Parameter

Name	Required	Type	Description
limit	선택	String	추천 결과로 보여줄 상품의 최대 수량 (기본값: 10, 최대값: 500)
showInfo	선택	List[String]	추천 결과로 보여줄 부가 정보 선택 (복수 선택 가능) `[METADATA, IMAGE_INFO, CONTEXT_INFO]`
metadataFilter	선택	String	Metadata Filter Query (참조: 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	추천의 기준이 되는 상품의 아이디
limit	integer	추천 결과로 보여줄 상품의 최대 수량
showInfo	List[String]	추천 결과로 보여줄 부가 정보
metadataFilter	Object	Metadata Filter Query (참조: Metadata Filter)
recommendation	List[Recommendation]	추천 결과 항목 (아래 표 참조)

Name	Type	Description
order	Integer	유사도 순으로 정렬된 순서 (0부터 시작)
id	String	추천된 상품 아이디
similarityScore	float	0~1 사이 ,값을 기준으로 높을수록 유사도가 높은 형태 [해당 항목은 2023-02 version 에서만 제공됩니다.]
metadata	Object	추천된 상품의 Meta 정보. showInfo 의 입력값으로 METADATA 가 있는 경우 상품 Metadata 형식의 데이터를 표시. 값이 없는 경우 Null (기본값)
imageInfo	Object	추천된 상품의 이미지 정보. showInfo 의 입력값으로 IMAGE_INFO가 있는 경우 값을 표시. 값이 없는 경우 Null (기본값)
├ imageInfo.detection	String	추천된 상품의 Detection 정보
└ imageInfo.url	String	추천된 상품의 대표이미지 URL
contextInfo	Object	추천된 상품의 Context 정보. showInfo 의 입력값으로 `CONTEXT_INFO`가 있는 경우 값을 표시. 값이 없는 경우 Null (기본값)
├ contextInfo.salesUrl	String	추천된 상품의 판매 페이지 URL
└ contextInfo.mobileSalesUrl	String	추천된 상품의 모바일 버전 판매 페이지 URL

Example Responses

400 Bad Request

잘못된 입력 format

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

HTTP Status Code : 200

아래에 해당되는 경우

0 개의 상품이 추천 된경우
상품이 존재하지 않은 경우
처리 중인 상품으로 유사상품 추천을 요청하는 경우

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

HTTP Status Code : 201

한 개 이상의 상품이 추천 된경우

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

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

Request Header

Name	Required	Type	Description
x-api-key	필수	String	API Key (참조: API 인증 가이드)
Content-Type	필수	String	요청 Type. Application/json 만 지원합니다.

Request Body

Name	Required	Type	Description
limit	선택	String	추천 결과로 보여줄 상품의 최대 수량 (기본값: 10, 최대값: 500)
showInfo	선택	List[String]	추천 결과로 보여줄 부가 정보 선택 (복수 선택 가능) [METADATA, IMAGE_INFO, CONTEXT_INFO]
metadataFilter	선택	Object	Metadata Filter Query (참조: Metadata Filter)

Request Example

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

Response

Name	Type	Description
id	String	추천의 기준이 되는 상품의 아이디
limit	integer	추천 결과로 보여줄 상품의 최대 수량
showInfo	List[String]	추천 결과로 보여줄 부가 정보
metadataFilter	Object	Metadata Filter Query (참조: Metadata Filter)
recommendation	List[Recommendation]	추천 결과 항목 (아래 표 참조)

Name	Type	Description
order	Integer	유사도 순으로 정렬된 순서 (0부터 시작)
id	String	추천된 상품 아이디
similarityScore	float	0~1 사이 ,값을 기준으로 높을수록 유사도가 높은 형태 [해당 항목은 2023-02 version 에서만 제공됩니다.]
metadata	Object	추천된 상품의 Meta 정보. showInfo 의 입력값으로 METADATA 가 있는 경우 상품 Metadata 형식의 데이터를 표시. 값이 없는 경우 Null (기본값)
imageInfo	Object	추천된 상품의 이미지 정보. showInfo 의 입력값으로 IMAGE_INFO가 있는 경우 값을 표시. 값이 없는 경우 Null (기본값)
├ imageInfo.detection	String	추천된 상품의 [Detection 정보]
└ imageInfo.url	String	추천된 상품의 대표이미지 URL
contextInfo	Object	추천된 상품의 Context 정보. showInfo 의 입력값으로 `CONTEXT_INFO`가 있는 경우 값을 표시. 값이 없는 경우 Null (기본값)
├ contextInfo.salesUrl	String	추천된 상품의 판매 페이지 URL
└ contextInfo.mobileSalesUrl	String	추천된 상품의 모바일 버전 판매 페이지 URL

Recommendation API

API Endpoint​

Filter Query​

유사 상품 추천 API​

GET /similar-items/recommend/<product id>: 상품 아이디와 유사한 상품 추천​

Request Header​

Request Parameter​

Request Example​

Response​

Recommendation​

Example Responses​

POST /similar-items/recommend/<product id>: 상품 아이디와 유사한 상품 추천​

Request Header​

Request Body​

Request Example​

Response​

Recommendation​

API Endpoint

Filter Query

유사 상품 추천 API

GET /similar-items/recommend/<product id>: 상품 아이디와 유사한 상품 추천

Request Header

Request Parameter

Request Example

Response

Recommendation

Example Responses

POST /similar-items/recommend/<product id>: 상품 아이디와 유사한 상품 추천

Request Header

Request Body

Request Example

Response

Recommendation