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

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

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

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

1.2 와 비교해서 Recommendation API Request 에 Metadata Filter 기능이 추가되었습니다

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

방식 1. GET /

요청 형식

Header

Name

Description

x-api-key

{omnious 로 부터 발급 받은 API Key} [Required]

Query Parameter

Name

Type

Description

String

(필수) 추천을 원하는 기준 상품의 상품 code

limit

Int

추천할 항목의 최대 수량

기본값: 10
최대값: 500

weightColorFeature

String

추천에 색상을 얼마나 반영할지 여부

기본값: MEDIUM
다음 값 중에서 선택가능
- LOW
- MEDIUM
- HIGH

showContext

Bool

Context 정보를 표시할지 여부

기본값: false

showImageInfo

Bool

Image 정보를 표시할지 여부

기본값: false

mfilter

String

메타데이터 필터는 v1.3에서 사용하실 수 있습니다.

metadata filter

문자열에 작은 따옴표(')나 큰따옴표(“)로 감싸야 합니

연산자

정의

문자열

숫자

날짜

예제

and

query 연결

price gt 1000 and price lt 10000

brand eq 'nike'

brand ne 'nike'

price ge 1000

datetime gt 2021-01-01

datetime le 2021-01-01T00:00:00

price lt 10000

in (포함관계)

brand in ('nike', 'adidas')

유사관계

productName like 'skirt'

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

Example4. (metadata filter) price가 1000보다 크고 10000보다 낮으며, datetime이 2021-01-01보다 크고, color이 white와 black 중 하나인 경우

curl --location --request GET 'https://api.omnious.com/lens/v1.3/recommend?id=725447&limit=10&weightColorFeature=MEDIUM&showContext=true&showImageInfo=true&mfilter=price gt 1000 and price le 10000 and datetime gt 2021-01-01 and color in ('white', 'black') \
--header 'x-api-key:  <<API-KEY>>'

응답 형식

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

HTTP Status Code

Code

Description

403

API KEY 인증과 관련된 오류

400

입력 값 Validation 진행중 발생한 오류

200

성공적으로 추천 결과를 리턴하였지만 추천된 상품 정보가 없는 경우

201

성공적으로 추천 결과를 리턴하였고 추천된 상품 정보가 있는 경우

500

서버 오류

Response Data

Name

Type

Description

String

기준이 되는 상품 code

limit

Int

추천할 항목의 최대 수량

weightColorFeature

String

추천에 색상을 얼마나 반영할지 여부

[LOW | MEDIUM | HIGH]

showContext

Bool

Context 정보를 표시할지 여부

showImageInfo

Bool

Image 정보를 표시할지 여부

recommendation

Array of Recommendation

Recommendation

Name

Type

Description

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

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에서 사용하실 수 있습니다.

mfilter

String

메타데이터 필터는 v1.3에서 사용하실 수 있습니다.

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": "셔츠"
      }
    }
  }
}

Example9. (metadata filter) price가 1000보다 크고 10000보다 낮으며, datetime이 2021-01-01보다 크고, color가 white와 black 중 하나인 경우

{
  "id": "725447",
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true,
  "mfilter": "price gt 1000 and price le 10000 and datetime gt 2021-01-01 and color in ('white', 'black')"
}

응답 형식

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

HTTP Status Code

Code

Description

403

API KEY 인증과 관련된 오류

400

입력 값 Validation 진행중 발생한 오류

200

성공적으로 추천 결과를 리턴하였지만 추천된 상품 정보가 없는 경우

201

성공적으로 추천 결과를 리턴하였고 추천된 상품 정보가 있는 경우

500

서버 오류

Response Data

Name

Type

Description

String

기준이 되는 상품 code

limit

Int

추천할 항목의 최대 수량

weightColorFeature

String

추천에 색상을 얼마나 반영할지 여부

[LOW | MEDIUM | HIGH]

showContext

Bool

Context 정보를 표시할지 여부

showImageInfo

Bool

Image 정보를 표시할지 여부

recommendation

Array of Recommendation

Recommendation

Name

Type

Description

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

PreviousData Management API 가이드 NextCamera Search API 가이드

Last updated 3 years ago

hashtag개요

hashtagEndpoint

hashtag방식 1. GET /

hashtag요청 형식

hashtagHeader

hashtag

hashtagQuery Parameter

hashtag요청 Example

hashtagExample1. Context 정보 없이 요청

hashtagExample2. Context 정보와 함께 요청

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

hashtag응답 형식

hashtagHTTP Status Code

hashtagResponse Data

hashtagRecommendation

hashtag응답 Example

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

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

hashtag방식 2. POST /

hashtag요청 형식

hashtagHeader

hashtag

hashtagBody

hashtagFilter

hashtag문자열 filter

hashtag숫자 filter

hashtagCurrency filter

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

hashtag요청 Example

hashtagExample1. Context 정보 없이 요청

hashtagExample2. Context 정보와 함께 요청

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

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

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

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

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

hashtag응답 형식

hashtagHTTP Status Code

hashtagResponse Data

hashtag

hashtagRecommendation

hashtag응답 Example

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

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

개요

Endpoint

방식 1. GET /

요청 형식

Header

Query Parameter

요청 Example

Example1. Context 정보 없이 요청

Example2. Context 정보와 함께 요청

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

응답 형식

HTTP Status Code

Response Data

Recommendation

응답 Example

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

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

방식 2. POST /

요청 형식

Header

Body

Filter

문자열 filter

숫자 filter

Currency filter

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

요청 Example

Example1. Context 정보 없이 요청

Example2. Context 정보와 함께 요청

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

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

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

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

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

응답 형식

HTTP Status Code

Response Data

Recommendation

응답 Example

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

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