Recommendation API 가이드

개요

Recommendation API는 고객이 요청한 상품 Code를 기준으로 유사한 상품을 추천하여 전달합니다. GET, POST 방식을 모두 지원하므로 원하는 방식을 선택하여 사용할 수 있습니다.

Endpoint

현재 지원되고 있는 Lens API Version은 두가지가 있습니다

Version 1.1:

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

Version 1.2: 신규로 Lens를 사용하시는 경우 해당 Version 사용하시는 것을 추천드립니다

1.1 이랑 비교해서 Recommendation API Request 에 Filter 기능이 추가되었습니다

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

방식 1. GET /

요청 형식

Header

Name	Description
x-api-key	{omnious 로 부터 발급 받은 API Key} [Required]

Query Parameter

Name	Type	Description
id	String	(필수) 추천을 원하는 기준 상품의 상품 code
limit	Int	추천할 항목의 최대 수량 기본값: 10 최대값: 500
weightColorFeature	String	추천에 색상을 얼마나 반영할지 여부 기본값: MEDIUM 다음 값 중에서 선택가능 LOW MEDIUM HIGH
showContext	Bool	Context 정보를 표시할지 여부 기본값: false
showImageInfo	Bool	Image 정보를 표시할지 여부 기본값: false

요청 Example

Example1. Context 정보 없이 요청

curl --location --request GET 'https://api.omnious.com/lens/v1.1/recommend?id=725447&limit=10&weightColorFeature=MEDIUM' \
--header 'x-api-key: <<API-KEY>>'

Example2. Context 정보와 함께 요청

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>>'

Example3. Context 정보, Image 정보와 함께 요청

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>>'

응답 형식

추천된 상품을 유사도 순으로 반환합니다.

HTTP Status Code

Code	Description
403	API KEY 인증과 관련된 오류
400	입력 값 Validation 진행중 발생한 오류
200	성공적으로 추천 결과를 리턴하였지만 추천된 상품 정보가 없는 경우
201	성공적으로 추천 결과를 리턴하였고 추천된 상품 정보가 있는 경우
500	서버 오류

Response Data

Name	Type	Description
id	String	기준이 되는 상품 code
limit	Int	추천할 항목의 최대 수량
weightColorFeature	String	추천에 색상을 얼마나 반영할지 여부 [LOW
showContext	Bool	Context 정보를 표시할지 여부
showImageInfo	Bool	Image 정보를 표시할지 여부
recommendation	Array of Recommendation	추천 항목 (아래 참조)

Recommendation

Name	Type	Description
id	String	추천할 상품 code
url	String	추천할 상품 정보 url
context	Object	Data Management API 에서 입력했던 context 정보
imageInfo	Object	Data Management API 에서 입력했던 image 정보 (Detection 정보, Image URL) showImageInfo 가 false 인 경우 null
imageInfo.detection	String	해당 상품의 Detection 정보 (Detection 정보 참조)
imageInfo.content	String	분석에 사용된 상품 Image의 url

응답 Example

Example1. 4개의 상품이 추천된 경우 (HTTP Status Code: 201)

Context 정보 미포함, imageInfo 미포함

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

Example2. 4개의 상품이 추천된 경우 (HTTP Status Code: 201)

Context 정보 포함, imageInfo 포함

{
  "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": "집업 후드",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }

        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 2,
        "id": "AT00158AE",
        "url": "http://asdfmall/product?id=AT00158AE",
        "context": {
          "name": "기모 후드",
          "gender": "WOMEN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 3,
        "id": "F800158GA",
        "url": "http://asdfmall/product?id=F800158GA",
        "context": {
          "name": "회색 기모 후드",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 4,
        "id": "AF10881GK",
        "url": "http://asdfmall/product?id=AF10881GK",
        "context": {
          "name": "기모 맨투맨",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      }
    ]
  }
}

방식 2. POST /

요청 형식

Header

Name	Description
Content-Type	application/json
x-api-key	{omnious 로 부터 발급 받은 API Key} [Required]

Body

Name	Type	Description
id	String	(필수) 추천을 원하는 기준 상품의 상품 code
limit	Int	추천할 항목의 최대 수량 기본값: 10 최대값: 500
weightColorFeature	String	추천에 색상을 얼마나 반영할지 여부 기본값: MEDIUM 다음 값 중에서 선택가능 LOW MEDIUM HIGH
showContext	Bool	Context 정보를 표시할지 여부 기본값: false
showImageInfo	Bool	Image 정보를 표시할지 여부 기본값: false
filter	Filter object	필터는 v1.2에서 사용하실 수 있습니다.

Filter

Name	Type	Description
url	문자열 filter	include, exclude, match
image	Object
image.content	문자열 filter	include, exclude, match
context	Object
context.name	문자열 filter	include, exclude, match
context.gender	문자열 filter	include, exclude, match
context.brand	문자열 filter	include, exclude, match
context.price	Object
context.price.currency	currency filter	match
context.price.value	숫자 filter	type(required) gte, lte, gt, lt, eq : 5개 중 하나 이상 사용
context.price.discounted	숫자 filter	type(required) gte, lte, gt, lt, eq : 5개 중 하나 이상 사용
context.mobilePrice	Object
context.mobilePrice.currency	currency filter	match
context.mobilePrice.value	숫자 filter	type(required) gte, lte, gt, lt, eq : 5개 중 하나 이상 사용
context.mobilePrice.discounted	숫자 filter	type(required) gte, lte, gt, lt, eq : 5개 중 하나 이상 사용

문자열 filter

• include: 해당 단어가 포함된 문자열 필터

  • e.g) "include": "shirts" 일 경우 T-shirts(o), pants(x)

• exclude: 해당 단어가 제외된 문자열 필터

  • e.g) "exclude": "shirts" 일 경우 T-shirts(x), pants(o)

• match: 해당 단어와 동일한 문자열 필터

  • e.g) "match": "shirts" 일 경우 T-shirts(x), shirts(o)

숫자 filter

• type: rate or abs (rate: 비율, abs: 절대값)

• gte: great than or equal to (>=입력값)

• lte: less than or equal to (<=입력값)

• gt: great than (>입력값)

• eq: equals (=입력값)

Currency filter

• match: 해당 단어와 동일한 문자열 필터

위 필터 단어들은 대소문자를 구별하지 않습니다.

요청 Example

Example1. Context 정보 없이 요청

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

Example2. Context 정보와 함께 요청

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

Example3. Context 정보, Image 정보와 함께 요청

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

Example4. 가격이 40,000 ~70,000원 사이의 값을 필터링 하고 싶은 경우

{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "price": {
      "value": {
        "type": "abs",
        "gte": 40000,
        "lte": 70000
      }
    }
  }
}

Example5. 요청한 상품 가격이 50,000원이고 비율(rate)이 0.7 ~ 1.2 사이의 값을 필터링 하고 싶은 경우

{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "price": {
      "value": {
        "type": "rate",
        "gte": 0.7,
        "lte": 1.2
      }
    }
  }
}

Example6. brand가 "nike"인 상품만 필터링 하고 싶은 경우

{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "context": {
      "brand": {
        "match": "nike"
      }
    }
  }
}

Example7. 상품명에 셔츠가 들어간 상품만 필터링 하고 싶은 경우

{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "context": {
      "name": {
        "include": "셔츠"
      }
    }
  }
}

Example8. 상품명에 셔츠가 들어간 상품을 제외 하고 싶은 경우

{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "filter": {
    "context": {
      "name": {
        "exclude": "셔츠"
      }
    }
  }
}

응답 형식

추천된 상품을 유사도 순으로 반환합니다.

HTTP Status Code

Code	Description
403	API KEY 인증과 관련된 오류
400	입력 값 Validation 진행중 발생한 오류
200	성공적으로 추천 결과를 리턴하였지만 추천된 상품 정보가 없는 경우
201	성공적으로 추천 결과를 리턴하였고 추천된 상품 정보가 있는 경우
500	서버 오류

Response Data

Name	Type	Description
id	String	기준이 되는 상품 code
limit	Int	추천할 항목의 최대 수량
weightColorFeature	String	추천에 색상을 얼마나 반영할지 여부 [LOW
showContext	Bool	Context 정보를 표시할지 여부
showImageInfo	Bool	Image 정보를 표시할지 여부
recommendation	Array of Recommendation	추천 항목 (아래 참조)

Recommendation

Name	Type	Description
id	String	추천할 상품 code
url	String	추천할 상품 정보 url
context	Object	Data Management API 에서 입력했던 context 정보
imageInfo	Object	Data Management API 에서 입력했던 image 정보 (Detection 정보, Image URL) showImageInfo 가 false 인 경우 null
imageInfo.detection	String	해당 상품의 Detection 정보 (Detection 정보 참조)
imageInfo.content	String	분석에 사용된 상품 Image의 url

응답 Example

Example1. 4개의 상품이 추천된 경우 (HTTP Status Code: 201)

Context 정보 미포함, imageInfo 미포함

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

Example2. 4개의 상품이 추천된 경우 (HTTP Status Code: 201)

Context 정보 포함, imageInfo 포함

{
  "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": "집업 후드",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 2,
        "id": "AT00158AE",
        "url": "http://asdfmall/product?id=AT00158AE",
        "context": {
          "name": "기모 후드",
          "gender": "WOMEN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 3,
        "id": "F800158GA",
        "url": "http://asdfmall/product?id=F800158GA",
        "context": {
          "name": "회색 기모 후드",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      },
      {
        "order": 4,
        "id": "AF10881GK",
        "url": "http://asdfmall/product?id=AF10881GK",
        "context": {
          "name": "기모 맨투맨",
          "gender": "MAN",
          "brand": "GAP",
          "price": {
            "currency": "KRW",
            "value": 12000,
            "discounted": 9900
          },
          "mobilePrice": {
            "currency": "KRW",
            "value": 11000,
            "discounted": 9900
          }
        },
        "imageInfo": {
          "detection": "TOP",
          "content": "http://imageserverurl/some.image.jpg"
        },
      }
    ]
  }
}