Recommendation API

API Endpoint

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

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

Filter Query

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

유사 상품 추천 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)
attributeFilter	선택	string	Attribute Filter Query (참조: Attribute Filter)

Request Example

/similar-items/recommend/A1101?limit=500&showInfo=IMAGE_INFO&showInfo=METADATA&showInfo=CONTEXT_INFO&metadataFilter.name.eq=skirt&attributeFilter.item=T0015&attributeFilter.textures=T1127&attributeFilter.prints=T1114

Response

Name	Type	Description
id	String	추천의 기준이 되는 상품의 아이디
limit	integer	추천 결과로 보여줄 상품의 최대 수량
showInfo	List[String]	추천 결과로 보여줄 부가 정보
metadataFilter	Object	Metadata Filter Query (참조: Metadata Filter)
attributeFilter	Object	Attribute Filter Query (참조: Attribute 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."
}

Index가 준비되지 않아 상품 추천을 할 수 없는 경우.

주의

Index 계산은 하루에 한 번(0시) 이루어집니다. 만약 Workspace에 상품 정보를 새로 입력한 경우 하루가 지난 이후부터 추천이 정상적으로 이루어집니다.

{
    "errors": "No product id exists."
}

HTTP Status Code : 200

아래에 해당되는 경우

0 개의 상품이 추천 된경우
상품이 존재하지 않은 경우
당일 신규로 등록한 상품으로 유사상품 추천을 요청하는 경우

주의

Index 계산은 하루에 한 번(0시) 이루어집니다. 만약 Workspace에 상품 정보를 새로 입력한 경우 하루가 지난 이후부터 추천이 정상적으로 이루어집니다.

{
  "id": "AT000123FB",
  "limit": 10,
  "showInfo": ["METADATA","IMAGE_INFO"],
  "metadataFilter": {
    "productName": {
      "eq": "skirt"
    }
  },
  "attributeFilter": {
    "item": "T0015",
    "textures": "T1127",
    "prints": "T1114"
  }, 
  "recommendation": []
}

HTTP Status Code : 201

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

{
  "id": "AT000123FB",
  "limit": 10,
  "showInfo": [],
  "metadataFilter": {
    "productName": {
      "eq": "skirt"
    }
  },
  "attributeFilter": {
    "item": "T0015",
    "textures": "T1127",
    "prints": "T1114"
  },
  "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"
    }
  },
  "attributeFilter": {
    "item": "T0015",
    "textures": "T1127",
    "prints": "T1114"
  },
  "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)
attributeFilter	선택	Object	Attribute Filter Query (참조: Attribute Filter)

Request Example

{
    "limit": 500,
    "showInfo": ["METADATA", "IMAGE_INFO", "CONTEXT_INFO"],
    "metadataFilter" : {"productName": {"eq": "skirt"}},
    "attributeFilter": {
        "item" : "T0015",
        "textures": "T1127",
        "prints": "T1114"
    }
}

Response

Name	Type	Description
id	String	추천의 기준이 되는 상품의 아이디
limit	integer	추천 결과로 보여줄 상품의 최대 수량
showInfo	List[String]	추천 결과로 보여줄 부가 정보
metadataFilter	Object	Metadata Filter Query (참조: Metadata Filter)
attributeFilter	Object	Attribute Filter Query (참조: Attribute 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

GET /similar-items/recommend/<product id>/attribute-tags: 추천 결과에 대한 Attribute Tag 보기

Request Header

Name	Required	Type	Description
X-Api-Key	필수	String	API Key (참조: API 인증 가이드)
Content-Type	필수	String	요청 Type. Application/json 만 지원합니다.
Accept-Language	필수	String	태그 정보를 받을 언어를 선택합니다. `KO`(한국어) \| `EN`(영어) \| `ZH`(중국어) \| `JA`(일본어) 4개 중 하나 선택, (default: `EN`)

Request Example

/similar-items/recommend/A1101/attribute-tags

Response

Name	Type	Description
id	String	추천의 기준이 되는 상품의 아이디
attributes	List[Attributes]	추천 결과로부터 집계된 Attribute Tag 목록

Attributes

Name	Type	Description
order	Integer	표시 순서 (추천 결과에 많이 포함된 순서로 정렬, 0부터 시작)
field	String	Field
name	String	Attribute 이름. Accept-Language Header로 요청된 언어로 표시됩니다
code	String	Attribute Code

Example Responses

HTTP Status Code : 200

0개의 Attribute 값이 반환 된 경우

{
  "id": "AT000123FB",
  "attributes": []
}

HTTP Status Code : 201

1개 이상의 Attribute 값이 반환 된 경우

Accept-language : en

{
  "id": "AT000123FB",
  "attributes": [
    {
      "order": 0,
      "field": "item",
      "name": "cardigun",
      "code": "T0015"
    },
    {
      "order": 1,
      "field": "textures",
      "name": "angora",
      "code": "T1127"
    },
    {
      "order": 2,
      "field": "textures",
      "name": "canvas",
      "code": "T1128"
    },
    {
      "order": 3,
      "field": "textures",
      "name": "chiffon",
      "code": "T1129"
    }
  ]
}

1개 이상의 Attribute 값이 반환 된 경우

Accept-language : ko

{
  "id": "AT000123FB",
  "attributes": [
    {
      "order": 0,
      "field": "item",
      "name": "가디건",
      "code": "T0015"
    },
    {
      "order": 1,
      "field": "textures",
      "name": "앙고라",
      "code": "T1127"
    },
    {
      "order": 2,
      "field": "textures",
      "name": "캔버스",
      "code": "T1128"
    },
    {
      "order": 3,
      "field": "textures",
      "name": "시폰",
      "code": "T1129"
    }
  ]
}

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​

GET /similar-items/recommend/<product id>/attribute-tags: 추천 결과에 대한 Attribute Tag 보기​

Request Header​

Request Example​

Response​

Attributes​

Example Responses​

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

GET /similar-items/recommend/<product id>/attribute-tags: 추천 결과에 대한 Attribute Tag 보기

Request Header

Request Example

Response

Attributes

Example Responses