추천API 사용 가이드

이 문서는 추천결과를 받아오는 Recobell Recommendation API의 사용법에 대해서 설명한다.

레코벨의 추천시스템 REST API를 이용하는 방법은 다음과 같다.

레코벨 추천시스템 REST API는 추천 타입에 따라서 요구하는 파라미터가 다르다. 추천 타입별 파라미터는 아래의 Parameter 표에서 확인 할 수 있다.

Recommendation Type

recType	targetType	resultType	Description
a001	상품	상품	상품 연관 추천
a002	상품	상품	상품 대체재 추천(같은 카테고리)
a003	상품	상품	상품 보완재 추천(다른 카테고리)
a004	상품	상품	상품 연관 추천 (같은 브랜드)
a101	상품	기획전	상품 연관 기획전 추천
c001	카테고리	상품	카테고리 베스트 추천(카테고리 이용)
c002	카테고리	상품	카테고리 외 베스트 추천
b001	브랜드	브랜드	브랜드 연관 추천 (브랜드추천)
~~b002~~	~~브랜드~~	~~브랜드(상품)~~	~~브랜드 연관 추천(같은 카테고리)~~
~~b003~~	~~브랜드~~	~~브랜드(상품)~~	~~브랜드 연관 추천 (다른 카테고리)~~
b004	브랜드	상품	브랜드 베스트 추천
m001		상품	사이트 베스트 추천
m002		상품	사이트 클릭 베스트 추천
m003		상품	사이트 구매 베스트 추천
m004		상품	사이트 검색 베스트 추천
~~m005~~		상품	~~사이트 신상품 베스트 추천~~
m006		검색어	사이트 검색어 베스트 추천
m007		검색어	사이트 외부유입 키워드 베스트 추천
m101		기획전	사이트 기획전 베스트 추천
t001	시간	상품	사이트 시간대별 베스트 추천
s001	검색어	상품	검색어 연관 상품 추천
s101	검색어	기획전	검색어 연관 기획전 추천
~~d001~~	~~인구특성~~	상품	~~인구분포추천~~
p001	pcid, (userId)	상품	최근클릭추천
p002	pcid	상품	최근구매추천
p003	pcid	상품	유저행동이력 기반 세그먼트 추천
p201	userId	상품	최근클릭추천
p202	userId	상품	최근구매추천
p101	userId, pcid	상품	오프라인데이터 추천
p102	userid	기획전	최근클릭기반 기획전추천
x			커스터마이징

RecType 은 계약에 따라서, 열려있지 않은 것들이 존재할 수 있다.

Parameter

O : 필수 , Δ : 옵션, X : 불필요

Parameter Name	Data Type	Description	Example	Default Value	recType	Note	a001 a002 a003	m001 m002 m003	c001	p001 p002 p003	s001
cuid	String	client의 cuid	rbTest				O	O	O	O	O
format	String	json, jsonp 반환 포맷 결정	jsonp				O	O	O	O	O
size	Integer (< 30)	추천 결과 개수	20				O	O	O	O	O
pcid	String	Cookie('RB_PCID')	1468904633966396362	null	p-series		X	X	X	O	X
userId	String			null	p101		X	X	X	X	X
iids	CSV String	추천 대상 상품 아이디	13225,1235,p123	null	a-series	최대 10개 상품까지 가능	O	X	X	X	X
bids	CSV String	추천 대상 브랜드 아이디	1102, 13231,a111	null	b-series		X	X	X	X	X
cids	CSV String	추천 대상 상품 카테고리(c001), 추천 결과 상품 카테고리(c001 제외)	01,c1	null			Δ	Δ	O	Δ	Δ
~~cpcids~~	~~CSV String~~	~~보완로직이 c001일 경우 기준 카테고리~~	~~1231~~	~~null~~			Δ	X	X	Δ	Δ
exiids	CSV String	추천 결과 제외 상품 아이디	1212,1233	null			Δ	Δ	Δ	Δ	Δ
excids	CSV String	추천 결과 제외 상품 카테고리	02,x1	null			Δ	Δ	Δ	Δ	Δ
inbids	CSV String	추천 결과 대상 상품 브랜드 아이디	1001	null			X	X	X	X	X
exbids	CSV String	추천 결과 제외 상품 브랜드 아이디	1004	null			Δ	Δ	Δ	Δ	Δ
date	datetime	시간	2015-06-25T05:43:18Z	CurrentTimestamp	t001		X	X	X	X	X
rg	Integer(<5)	시간 범위	2	0	t001		X	X	X	X	X
cps	Boolean	방어 로직 사용 유무	false	true			Δ	X	Δ	Δ	Δ
cpt	String	방어로직의 종류(m001~003, t001)	t001	m001			Δ	X	Δ	Δ	Δ
callback	String	jsonp의 callback parameter	call1123	null			Δ	Δ	Δ	Δ	Δ
st	String	검색어 (searchTerm)	원피스	null	s-series		X	X	X	X	O
gender	String	성별	M	null	d001		X	X	X	X	X
age	Int(20,30,40,50)	나이	20	null	d001		X	X	X	X	X
minp	int	보여주고자하는 최저 가격	1000	null			Δ	Δ	Δ	Δ	Δ
maxp	int	보여주고자하는 최고 가격	2000	null			Δ	Δ	Δ	Δ	Δ
rnd	Boolean	방어로직 Randomness	true	false			Δ	Δ	Δ	Δ	Δ
channel	String	피씨 / 모바일 특화 로직일 경우	pc, mo	null			Δ	Δ	Δ	Δ	Δ

** s001 (검색추천) 의 경우에는 cps 의 기본값이 false 로 설정되어있음.

*** p101 (오프라인 데이터 추천) 의 경우에는 오프라인 데이터 연결을 위한 별도의 작업필요

PCID

레코벨이 유저를 구분하는 방법은 Cookie 에 임의의 String 을 발급하는 형식이며, 이 쿠키의 이름은 아래와 같다.

RB_PCID

REST API Url Pattern

REST API Url Pattern

http://rb-rec-api-apne1.recobell.io/rec/{recType}?cuid=...&format=...&size=...&iids=...&cids=...&exiids=...&excids=...&cps=...&callback=...&fields=...

Response Data Model

recType : a001, a002, a003

Field Name	Data Type	Description	Example
recType	String	추천타입	a001
iids	CSV String	추천 대상 상품 아이디(최대 10개)	123,12
cids	CSV String	추천 대상 상품 카테고리	01,03
exiids	CSV String	추천 결과 제외 상품 아이디	11,123
excids	CSV String	추천 결과 제외 상품 카테고리	01,c1
products	List<Product>	추천 대상 상품 정보	{"itemId":"","itemName":"","itemImage":"","originalPrice":"","salePrice":"","category1":"","category2":"","category3":"","regDate":"","updateDate":"","expireDate":"","stock":"","state":"","description":"","extraImage":"","locale":""}
results	List<RankedProduct>	추천 결과 상품 정보	{"itemId":"","categoryId":"","rank":"","score":"","isCompensation":"","product":{"itemId":"","itemName":"","itemImage":"","originalPrice":"","salePrice":"","category1":"","category2":"","category3":"","regDate":"","updateDate":"","expireDate":"","stock":"","state":"","description":"","extraImage":"","locale":""}}

recType : c001

Field Name	Data Type	Description	Example
recType	String	추천타입	c001
cids	CSV String	추천 대상 상품 카테고리	01,03
exiids	CSV String	추천 결과 제외 상품 아이디	11,123
excids	CSV String	추천 결과 제외 상품 카테고리	01,c1
results	List<RankedProduct>	추천 결과 상품 정보	{"itemId":"","categoryId":"","rank":"","score":"","isCompensation":"","product":{"itemId":"","itemName":"","itemImage":"","originalPrice":"","salePrice":"","category1":"","category2":"","category3":"","regDate":"","updateDate":"","expireDate":"","stock":"","state":"","description":"","extraImage":"","locale":""}}

recType : m001, m002, m003

Field Name	Data Type	Description	Example
recType	String	추천타입	r001
exiids	CSV String	추천 결과 제외 상품 아이디	11,123
excids	CSV String	추천 결과 제외 상품 카테고리	01,c1
results	List<RankedProduct>	추천 결과 상품 정보	{"itemId":"","categoryId":"","rank":"","score":"","isCompensation":"","product":{"itemId":"","itemName":"","itemImage":"","originalPrice":"","salePrice":"","category1":"","category2":"","category3":"","regDate":"","updateDate":"","expireDate":"","stock":"","state":"","description":"","extraImage":"","locale":""}}

RankedProduct

Field Name	Data Type	Description	Example
index	Integer	추천 결과 리스트 내 순위	1
logicType	String	적용 된 추천타입	a001, m001, a001-cps-b001, a002-rff-m001
itemId	String	상품코드	11
categoryId	String	상품 카테고리	123
rank	Integer	추천 결과 내 순위	1
score	Double	추천 결과 점수	123.45
isCompensation	Boolean	방어 로직으로 나온 결과값인지 여부	false
product	Product	추천 결과 상품 정보	{"itemId":"","itemName":"","itemImage":"","originalPrice":"","salePrice":"","category1":"","category2":"","category3":"","regDate":"","updateDate":"","expireDate":"","stock":"","state":"","description":"","extraImage":"","locale":""}

Response Example

ex) recType=a001,format=json

{
	"recType": "a001",
	"iids": "123",
	"cids": "01",
	"exiids": "1234",
	"excids": "02",
	"products": [{
		"itemId": "123",
		"itemName": "testItem",
		"itemImage": "http://test.com",
		"originalPrice": 3500,
		"salePrice": 3500,
		"category1": "01",
		"category2": "101002",
		"category3": "101002100204",
		"regDate": null,
		"updateDate": null,
		"expireDate": null,
		"stock": 0,
		"state": null,
		"description": null,
		"extraImage": null,
		"locale": null
	}],
	"results": [{
		"itemId": "123456",
		"categoryId": "010101",
		"rank": 1,
		"score": 0.5,
		"isCompensation": false,
		"product": {
			"itemId": "123456",
			"itemName": "resultItem1",
			"itemImage": "http://itemImage1.com",
			"originalPrice": 12000,
			"salePrice": 12000,
			"category1": "01",
			"category2": "010101",
			"category3": "010101010101",
			"regDate": null,
			"updateDate": null,
			"expireDate": null,
			"stock": 0,
			"state": null,
			"description": null,
			"extraImage": null,
			"locale": null
		}
	}, {
		"itemId": "12345678",
		"categoryId": "010101010101",
		"rank": 2,
		"score": 0.3,
		"isCompensation": false,
		"product": {
			"itemId": "12345678",
			"itemName": "resultItem2",
			"itemImage": "http://itemImage2.com",
			"originalPrice": 1234,
			"salePrice": 120,
			"category1": "01",
			"category2": "010101",
			"category3": "010101010101",
			"regDate": null,
			"updateDate": null,
			"expireDate": null,
			"stock": 0,
			"state": null,
			"description": null,
			"extraImage": null,
			"locale": null
		}
	}]
}

ex) recType=m001,format=jsonp

callbackexample(
{
	"recType": "m001",
	"iids": null,
	"exiids": "1234",
	"excids": "02",
	"results": [
		{
			"itemId": "123456",
			"categoryId": "010101",
			"rank": 1,
			"score": 0.5,
			"isCompensation": false,
			"product": {
				"itemId": "123456",
				"itemName": "resultItem1",
				"itemImage": "http://itemImage1.com",
				"originalPrice": 12000,
				"salePrice": 12000,
				"category1": "01",
				"category2": "010101",
				"category3": "010101010101",
				"regDate": null,
				"updateDate": null,
				"expireDate": null,
				"stock": 0,
				"state": null,
				"description": null,
				"extraImage": null,
				"locale": null,
			}
		},
		{
			"itemId": "12345678",
			"categoryId": "010101",
			"rank": 2,
			"score": 0.3,
			"isCompensation": false,
			"product": {
				"itemId": "12345678",
				"itemName": "resultItem2",
				"itemImage": "http://itemImage2.com",
				"originalPrice": 1234,
				"salePrice": 120,
				"category1": "01",
				"category2": "010101",
				"category3": "010101010101",
				"regDate": null,
				"updateDate": null,
				"expireDate": null,
				"stock": 0,
				"state": null,
				"description": null,
				"extraImage": null,
				"locale": null,
			}
		}
	]
}
)

레코벨 Logger 에 정보를 전달하는 방법

추천영역이 삽입되고, 그 추천영역에서의 기여도를 레코벨 Logger 에서 보고싶다면 아래와 같은 parameter 를 상품상세로 가는 href 에 추가하면 된다.

parameter value 는 자유롭게 가능하다. 예를 들면 아래와 같은 값들을 가진다.

rccode=recobell_pc_detail

rccode=pc_main_rec1

레코벨 API 서버의 도메인 및 대역폭

위에 있는 것처럼 레코벨 API 서버는

rb-rec-apne1.recobell.io

도메인을 가지고 있다.

이에 할당된 IP 는 Amazon Elastic LoadBalancer 의 특성상 유동적이며 변화할 수 있다.

따라서 outbound Firewall 을 이용할 시에는 도메인을 이용하여야한다.