한국어 한국어   Englilsh English

.

Skip to end of metadata
Go to start of metadata

함께본상품(ViewTogether) 추천 혹은 함께구매한상품(BuyTogether) 추천을 받을 수 있는 API 입니다.

GET 방식으로 요청하실 수 있고, 정상적으로 추천 계산이 완료된 경우에는 JSON 형태의 추천리스트가 반환됩니다.

요청에 실패할 경우 상황에 따라 4XX 혹은 5XX형태의 에러코드가 반환됩니다.

일반적으로 상품상세페이지 상단 영역(장바구니 버튼 바로 아래)에 함께본상품 추천을 노출하는 경우 제일 좋은 추천 성과가 나옵니다.

Resource URL

 https://api.recopick.com/v1/recommendations/item/:service_id/:uid/:item_ids?limit=:limit&field=:field&channel=:channel&type=:type&callback=:callback

(GET v1/recommendations/item/:service_id/:user_id/:item_ids)

 *Native(Hybrid) App에서는 uid 자리에 반드시 GAID 혹은 IDFA값을 넣어서 업로드 해야 합니다.

Parameters

service_id

(required)

RecoPick에서 발급된 service id를 의미합니다. service id를 모르실 경우 RecoPick으로 문의해주시기 바랍니다.

Example Values : 1

uid

(required)

추천리스트를 가져올 사용자 ID를 의미합니다. 로그 수집에 사용하고 있는 사용자 ID를 입력해주시기 바랍니다.

로그 전송 과정에서 별도로 uid를 설정하지 않은 분들은 fetchUID (UID 가져오기) 문서를 참고 하셔서, RecoPick에서 브라우저 쿠키로 자동 설정한 uid를 읽은 다음, 이 영역을 채워 주시기 바랍니다.

 

Example Values : test_user_1234

item_ids

(required)

상품 ID의 목록입니다. 상품 id를 URI encoding한 다음 입력해주시기 바랍니다. 여러 개의 상품에 대해 추천을 요청할 경우, comma로 구분해서 입력해주시면 됩니다.

Example Values : 123,12311

limit

(optional)

최대 몇 개의 추천을 가져올지를 의미합니다. item_ids 의 상품당 추천 개수이므로, 2개의 상품에 대해 limit=5로 요청할 경우 총 10개의 추천 결과가 반환됩니다.

limit값이 없으면 계산된 추천 리스트 전체를 가져오게 되어 있습니다. 추천 결과의 개수가 limit보다 적은 경우, 전체 추천 결과가 반환됩니다.

Example Values : limit=5

field

(optional)

field=meta를 입력하시면 상품의 최신정보(상품명, 썸네일등) 까지 같이 제공됩니다. 

* 품절이된 상품의 경우 추천리스트에서 제외

Example Values : field=meta

channel

(optional)

추천클릭률, 추천기여매출을 추적하기 위해 channel을 입력합니다. 추천 노출 영역이 다르거나, A/B test 시에 서로 다른 channel을 부여하시면, channel 별로 성과를 계산하여 보여드립니다.

채널이란 하나의 사이트에서 여러 개의 추천 알고리즘을 각각 다른 위치에 제공하는 경우,
각 페이지에 제공된 추천 알고리즘 별로 추천 성과(추천클릭률 및 추천기여매출)를 확인할 수 있도록 하기 위한 식별자입니다.
예를 들어, 실시간 개인화 추천 알고리즘을 메인페이지, 상품상세페이지, 마이페이지에서 사용하는 경우, 각 페이지 별로 추천 성과가 달라집니다.
이 때에 각 페이지 별로 채널명을 부여하여 페이지 별로 구분하여 추천 알고리즘 성과를 분석할 수 있습니다.
채널명은 아래 예와 같이 공백 없는 영문 명을 사용하시는 걸 권장 드립니다.
예> 메인페이지 : main, 상품상세페이지_상단 : detail_top, 장바구니 : basket

Example Values : channel=detail_top

type

(optional)

추천의 종류를 설정합니다. 현재는 아래 두 가지 추천 리스트 중 하나를 선택할 수 있습니다.

  • viewtogether : 함께 본 상품 (대체재)
  • buytogether : 함께 구매한 상품 (보완재)

따로 값을 설정하지 않으시면, 기본값인 viewtogether 가 적용되며, 주로 대체재가 추천됩니다.

Example Values : type=viewtogether

category

(optional) 

카테고리 입니다. 최상위 카테고리만 지원 됩니다. 가구 , 여성의류 , 가전제품 ...

Example Values : category=아우터

brand

(optional)

브랜드입니다. brand라는 항목으로 수집된 brand명에 한하여 동일 텍스트에 한해 지원됩니다.  

Example Values : brand=STONE ISLAND

callback

(optional)

callback을 입력하시면 JSONP 형태의 응답을 제공합니다.

Example Values : callback=parseResponse 

Example Request : https://api.recopick.com/v1/recommendations/item/1/test_user/123/?callback=parseResponse


Example Request 


GET     https://api.recopick.com/v1/recommendations/item/1/test_user_1234/123,12311?limit=2  
 

Output

 반환되는 JSON 필드 설명은 아래를 참고해주세요.

{
  "123": [ 
    {
      "id": "137",
      "intersection": 68,
      "score": 0.33252823,
      "method": "4",
      "clicklog_link": "https://lc.recopick.com/3/log/click/1?source=123&reco_list=%5B%22137%22%2C%22179%22%5D&pick=137&method=4&channel=ch01&reco_type=item-item",
      "clicklog_redirect_link": "https://lc.recopick.com/1/banner/1/pick?source=123&reco_list=%5B%22137%22%2C%22179%22%5D&pick=137&method=4&channel=ch01&reco_type=item-item"
    },
    {
      "id": "179",
      "intersection": 51,
      "score": 0.31178883,
      "method": "4",
      "clicklog_link": "https://lc.recopick.com/3/log/click/1?source=123&reco_list=%5B%22137%22%2C%22179%22%5D&pick=179&method=4&channel=ch01&reco_type=item-item",
      "clicklog_redirect_link": "https://lc.recopick.com/1/banner/1/pick?source=123&reco_list=%5B%22137%22%2C%22179%22%5D&pick=179&method=4&channel=ch01&reco_type=item-item"
    }
  ],
"12311": [
    {
      "id": "1567",
      "intersection": 68,
      "score": 0.33252823,
      "method": "4",
      "clicklog_link": "https://lc.recopick.com/3/log/click/1?source=12311&reco_list=%5B%22137%22%2C%22179%22%5D&pick=1567&method=4&channel=ch01&reco_type=item-item",
      "clicklog_redirect_link": "https://lc.recopick.com/1/banner/1/pick?source=12311&reco_list=%5B%22137%22%2C%22179%22%5D&pick=1567&method=4&channel=ch01&reco_type=item-item"
    },
    {
      "id": "245",
      "intersection": 51,
      "score": 0.31178883,
      "method": "4",
      "clicklog_link": "https://lc.recopick.com/3/log/click/1?source=12311&reco_list=%5B%22137%22%2C%22179%22%5D&pick=245&method=4&channel=ch01&reco_type=item-item",
      "clicklog_redirect_link": "https://lc.recopick.com/1/banner/1/pick?source=12311&reco_list=%5B%22137%22%2C%22179%22%5D&pick=245&method=4&channel=ch01&reco_type=item-item"
    }
  ]
}


"상품 기준 추천"을 이용하시지 않는 경우 HTTP 405로 아래와 같이 응답됩니다. (자세한 내용은 0.3 과금 정책 을 참고하세요.)

{
	"errors": [
		{
			"message": "API call limit exceeded. Request item product to uses this API."
		}
	]
}


요청에 대해 JSON Object가 반환됩니다. 해당 Object에는 요청시 주어졌던 상품 ID와, 해당 상품 ID에 해당하는 추천 결과가 각각 Key/Value 값으로 들어있게 됩니다. 추천 결과는 개별 상품의 Array 형태로 주어지며 개별 상품 정보의 자세한 사항은 아래와 같습니다.

field의 미비 고
id추천된 상품의 id
intersection같이 본 사용자의 수원 상품과, 추천된 상품을 같이 본 사용자의 수 입니다.
score추천의 품질 지표score가 높은 순으로 추천 리스트를 노출하시면 됩니다. 일반적으로는 score가 높은 순으로 리스트를 드립니다.
method추천 계산 알고리즘 id
clicklog_link클릭로그 저장용 링크 주소해당 링크를 방문하거나 Ajax GET, JSONP 등의 방법으로 호출하면 추천 클릭 로그가 전송됩니다.
clicklog_redirect_link클릭로그 저장 및 페이지 이동 링크 주소해당 링크를 방문하면, 추천 클릭 로그가 RecoPick 서버에 저장되고, 상품 상세 페이지로 이동됩니다. 이때 이동되는 상품 상세 페이지를 변경하고자 하시면, ?url=:encodedURL 을 붙여주시면, 클릭 로그를 남긴 다음, 해당 페이지로 이동 시켜 드립니다.


(warning) 주의하세요! 사용자들이 추천 리스트를 클릭하는 경우, clicklog_link 혹은 clicklog_redirect_link를 통해 추천 클릭로그를 남겨주셔야 합니다. 추천 클릭 로그를 제대로 남기지 않을 경우, 추천에 대한 성과를 계산할 수 없으며, 향후 추천 품질이 저하되는 문제가 생깁니다. 브라우저의 경우, 간단하게 clicklog_redirect_link 를 통해 추천 클릭로그를 남기면서, 페이지를 이동하게 하는 것을 추천 드리며, 불가피하게 clicklog_redirect_link를 사용할 수 없을 경우, 서버 혹은 ajax 등 다른 방법으로 clicklog_link를 호출하셔서 추천 클릭 로그를 남겨주시면 됩니다.

※ 참고 : 추천 상품 클릭 시에 추천 API 결과에 있는 clicklog_link 혹은 clicklog_redirect_link를 반드시 레코픽으로 전달해주셔야 합니다. 그래야 레코픽 추천 성과가 잡힙니다.

  • 상품상세페이지의 URL 패턴이 정형화 되어 있지 않다면 clicklog_redirect_link는 사용하지 못하고, clicklog_link를 사용해주셔야 합니다.
  • clicklog_redirect_link : 추천된 상품에 대한 클릭 정보를 레코픽으로 전송한 뒤에 클릭된 상품의 상세페이지로 redirect시켜 드립니다.
  • clicklog_link : 추천된 상품에 대한 클릭 정보를 레코픽으로 전송합니다. 이 경우에는 추천된 상품의 상세페이지로 직접 이동해주셔야 합니다.

 또한, API 응답 내에 있는 위의 method 값을 아래 형식으로 상세페이지의 URL 파라미터에 추가적으로 넣어주셔야 하고, 추천 서비스를 사용하는 경우 'product_type=R' 파라미터도 추가적으로 넣어주셔야 합니다.

• 형식 : recopick=method 값

• 예1 : http://aaa.test.co.kr/product/detail.html?product_no=1338&recopick=4&product_type=R

• 예2 : http://test.xxx.co.kr/product/product_detail/3395854?recopick=25&product_type=R



  • No labels