Skip to content

How to integrate recommender API

Before integrating the recommender solution go through the following example which may help you to follow the fundamental steps to integrate your product into recommender solutions. Throughout this tutorial, we’ll walk you through the integration of an E-commerce shop API into the recommender system.

Item mapping key

Recommender engine has some default keys which are required to run the solution. As the first step you have to map the data source keys with recommender keys for integrating your product.

In this tutorial, we'll use Shop API as data source. Shop API searches multiple E-commerce inventory and finds the most suitable items.

Request endpoint to fetch data from Shop API:

  POST https://api.doozie.ai/v1/api/items/search

The response should be looked like below:

{
  "success": true,
  "result": [
    {
      "item_id": "rsswebshop:10034175",
      "title": "バートン スノーボードウェア レディース W22JP-212841 Women's Burton [ak] GORE-TEX 2L Kimmy Bib Pant ウィメンズ ゴアテックス 2レイヤー キミー ビブパンツ スノーボードパンツ ハイトップパンツ スノーパンツ 2021-2022 正規品",
      "description": "21-22モデルUS size商品■WOMEN'S BURTON [AK] GORE-TEX 2L KIMMY BIB PANT (ウーメンズ バートン [AK] ゴアテックス 2レイヤー キミー ビブパンツ) 【カラー】 ・True Black(ブラック  ・Victor Camo(カーキ系/カモ柄/迷彩柄) ・Ballet Slipper(ピンク) 【サイズ】cm ・XS = ウエスト周り:83.8/ヒップ周り:102.8/股上:22.9/股下:83.8/膝周り:46.4/裾周り:53.4 ・S = ウエスト周り:89/ヒップ周り:108/股上:24.1/股下:83.8/膝周り:48.2/裾周り:54.6 ・M = ウエスト周り:94/ヒップ周り:113/股上:25.4/股下:83.8/膝周り:50.2/裾周り:55.8 ※製品によって多少の誤差がある場合があります。 【サイズ目安】cm ・XXS = ウエスト:56-61 / ヒップ:81-86 / 股下:76 ・XS = ウエスト:61-66 / ヒップ:86-91 / 股下:76 ・S = ウエスト:66-71 / ヒップ:91-97 / 股下:76 ・M. = ウエスト:71-76 / ヒップ:97-102 / 股下:76 ・L = ウエスト:76-84/ ヒップ:102-108 / 股下:76 ・XL = ウエスト:76-84 / ヒップ:102-108 / 股下:76 ※ウエスト:自然な状態でウエスト周り:。 ※ヒップ:ヒップの最も大きい位置:。 ※股下:内腿の上からかかとの下まで。 【モデル情報】 [True Black] 身長175cm / 体重53kg / 着用サイズS [Ballet Slipper][Victor Camo] 身長173cm / 体重59kg / 着用サイズS スノーボーダーのリスペクトを集めるバックカントリーライダーたちのアイデアを詰め込みました。Burtonライダーやバックカントリーで活躍するキミー・ファサニと共同開発した、厳しい天候でも快適に過ごせるバックカントリー仕様のディテールを備えたビブパンツです。 プロライダー、キミー・ファサニとのコラボレーションによってデザインされたウィメンズ Burton [ak] GORE-TEX キミー 2L ビブパンツ。アクセシビリティを損なうことなく雪をシャットアウトします。洗面所のないバックカントリーでも用を足せるジップアウトシートをはじめ、キミー・ファサニの要望に合わせた機能を装備。バックカントリー対応の機能により、ライディング中もトレイル中も快適で、視認性が高く、ドライな着心地が持続します。 ●タイトでもなくバギーでもなく、ちょうど良いシルエットで、膝、肘、肩などの動作性を高めるレギュラー立体裁断フィット ●防風性や防水性、透湿性、耐久性に優れ、幅広いアウトドアアクティビティにおいて温かくドライな環境をキープするGORE-TEX 2レイヤー素材 ●GUARANTEED TO KEEP YOU DRYのGORE-TEXファブリクス ●縫い目を完全に密閉し、完璧な防水性をもたらすGORE-TEXシームテープ ●ドロップシート構造を採用した調節可能なサスペンダーシステム ●リフレクターのディテール ●簡単にアクセスできるビーコンクリップとメディアポケット付き胸ポケット / ジップハンドウォーマーポケット / ジップカーゴポケット ●ライフタイムワランティ対象 Burtonが販売したすべての衣類、アウターウェア、バッグ&ラゲッジにおいて、その製品の実質的な寿命までの期間、素材および製造上の欠陥がないことを保証します。誤用、乱用、事故、不注意、経年利用によるものと考えられる摩耗による破損は制限付きライフタイムワランティの対象外となりますが、修理可能な場合には妥当な代金にて修理を承ります。 ■注意点 ◆画面上と実物では多少色具合が変わって見える場合もあります。ご了承ください。 ◆柄の出方は生地の裁断により一点一点異なります。柄の繋ぎ目は全ては合っておりません。ご指定は出来ませんのでご了承の上お買い求め下さい。 ◆この商品は当店実店舗でも販売しております。 在庫数の更新は随時行っておりますが、お買い上げいただいた商品が、品切れになってしまうこともございます。 その場合、お客様には必ず連絡をいたしますが、万が一入荷予定がない場合は、 キャンセルさせていただく場合もございます。 あらかじめご了承ください。 スノボ スノーボード ハイトップパンツ サロペット オーバーオール スノーボードパンツ スノーウェア スノーパンツ ワンポイント ロゴメーカー希望小売価格はメーカーカタログに基づいて掲載しています。",
      "headline": "21-22 BURTON バートン [ak] レディース スノーボードパンツ ",
      "availability": true,
      "affiliate_rate": 4,
      "price": 52800,
      "shop_id": "rsswebshop",
      "shop_name": "masa surf and snow",
      "review_count": 2,
      "review_average": 4.5,
      "genre_id": "501842",
      "shop_url": "https://hb.afl.rakuten.co.jp/hgc/g00ray55.h3cpt966.g00ray55.h3cpud0b/?pc=https%3A%2F%2Fwww.rakuten.co.jp%2Frsswebshop%2F&m=http%3A%2F%2Fm.rakuten.co.jp%2Frsswebshop%2F",
      "item_url": "https://hb.afl.rakuten.co.jp/hgc/g00ray55.h3cpt966.g00ray55.h3cpud0b/?pc=https%3A%2F%2Fitem.rakuten.co.jp%2Frsswebshop%2Fw21jp-212841%2F&m=http%3A%2F%2Fm.rakuten.co.jp%2Frsswebshop%2Fi%2F10034175%2F",
      "image_urls": [
        "https://thumbnail.image.rakuten.co.jp/@0_mall/rsswebshop/cabinet/22burton/womens-soft/w22jp-212841-01.jpg?_ex=128x128",
        "https://thumbnail.image.rakuten.co.jp/@0_mall/rsswebshop/cabinet/22burton/womens-soft/w22jp-212841-02.jpg?_ex=128x128",
        "https://thumbnail.image.rakuten.co.jp/@0_mall/rsswebshop/cabinet/22burton/womens-soft/w22jp-212841-03.jpg?_ex=128x128"
      ],
      "tags": [
        1000317,
        1000318,
        1000319,
        1000876,
        1000882,
        1000886,
        1002302,
        1004016,
        1036998,
        1037806,
        1040043
      ],
      "shipping_overseas": "",
      "condition": 0,
      "genre_name": null,
      "shop_review_count": null,
      "shop_review_average": null,
      "platform": "rakuten"
    }
  ]
}

Now we'll build the mapper with POST /v1/mapper endpoint of Recommender API. In this endpoint, we have to pass the keys of our data source. Before mapping the keys we need to comprehend the parameters. All the parameters have depicted below.

name key type value type description
item_id str str item_id is the unit of recommended items.
title str str Represents product or item title.
second_title Optional[str] str If the item has a headline field it can be assigned here.
third_title Optional[str] str If item has any other field similar to the title level could be assigned here.
fourth_title Optional[str] str If item has any other field similar to the title level could be assigned here.
availability str bool Represents whether the item is available or not. Data type for this key must be boolean.
description Optional[str] str Represents product details information.
image_url Optional[str] str Represents image url of the data source.
image_url_type Optional[Enum] Selected enum value Based on this recommender process image url data. Available values are STR, LIST_STR, LIST_DICT, DICT.
item_url str str Represents the product or item details page url.
price str int Represents the price of product or item.
categories List[Dict[str,str]] str Represents your category list. Multiple values can be added here. Each category contains name and separator.
flag List[str] bool Represents list of flags available in your dataset. Flag value data type must be boolean.

Let’s have a look at the example of a mapper that we built for our Shop API:

{
  "key_map": {
    "item_id": "item_id",
    "title": "title",
    "second_title": "headline",
    "third_title": "shop_name",
    "fourth_title": "genre_name",
    "availability": "availability",
    "description": "description",
    "image_url": "image_urls",
    "image_url_type": "LIST_STR",
    "item_url": "item_url",
    "price": "price",
    "category": [
      {
        "name": "genre_id",
        "separator": ""
      },
    ],
    "flag": [
      "condition"
    ]
  }
}

Code Example

import http.client

conn = http.client.HTTPSConnection("api.recommender.gigalogy.com")

payload = "{\"key_map\":{\"item_id\":\"item_id\",\"title\":\"title\",\"second_title\":\"string\",\"third_title\":\"string\",\"fourth_title\":\"string\",\"availability\":\"availability\",\"description\":\"string\",\"image_url\":\"string\",\"image_url_type\":\"STR\",\"item_url\":\"string\",\"price\":\"price\",\"categories\":[{\"name\":\"category_1\",\"separator\":\"_\"},{\"name\":\"category_2\",\"separator\":\"\"}],\"flag\":[\"condition\"]}}"

headers = {
    'content-type': "application/json",
    'project-key': "SOME_STRING_VALUE",
    'api-key': "SOME_STRING_VALUE"
    }

conn.request("POST", "/v1/mapper", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
const settings = {
"async": true,
"crossDomain": true,
"url": "https://api.recommender.gigalogy.com/v1/mapper",
"method": "POST",
"headers": {
  "content-type": "application/json",
  "project-key": "SOME_STRING_VALUE",
  "api-key": "SOME_STRING_VALUE"
},
"processData": false,
"data": "{\"key_map\":{\"item_id\":\"item_id\",\"title\":\"title\",\"second_title\":\"string\",\"third_title\":\"string\",\"fourth_title\":\"string\",\"availability\":\"availability\",\"description\":\"string\",\"image_url\":\"string\",\"image_url_type\":\"STR\",\"item_url\":\"string\",\"price\":\"price\",\"categories\":[{\"name\":\"category_1\",\"separator\":\"_\"},{\"name\":\"category_2\",\"separator\":\"\"}],\"flag\":[\"condition\"]}}"
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.recommender.gigalogy.com/v1/mapper")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["project-key"] = 'SOME_STRING_VALUE'
request["api-key"] = 'SOME_STRING_VALUE'
request.body = "{\"key_map\":{\"item_id\":\"item_id\",\"title\":\"title\",\"second_title\":\"string\",\"third_title\":\"string\",\"fourth_title\":\"string\",\"availability\":\"availability\",\"description\":\"string\",\"image_url\":\"string\",\"image_url_type\":\"STR\",\"item_url\":\"string\",\"price\":\"price\",\"categories\":[{\"name\":\"category_1\",\"separator\":\"_\"},{\"name\":\"category_2\",\"separator\":\"\"}],\"flag\":[\"condition\"]}}"

response = http.request(request)
puts response.read_body

You can update any of mapped keys with PUT /v1/mapper endpoint and get the mapper you build from GET /v1/mapper endpoint.

Behavior mapping key

Similar to the item mapping key, there are some default keys for user behavior data. This step is required If you want to save user behavior data through CSV files.

Quick Reference

HTTP Method Path Description
POST /v1/browse/mapper Map data source key with recommender browse key
PUT /v1/browse/mapper Update browse mapped keys
GET /v1/browse/mapper Get browse mapped keys
POST /v1/purchase/mapper Map data source key with recommender purchase key
PUT /v1/purchase/mapper Update purchase mapped keys
GET /v1/purchase/mapper Get purchase mapped keys
POST /v1/rating/mapper Map data source key with recommender rating key
PUT /v1/rating/mapper Update rating mapped keys
GET /v1/rating/mapper Get rating mapped keys
POST /v1/user/mapper Map data source key with recommender rating key
PUT /v1/user/mapper Update purchase rating keys
GET /v1/user/mapper Get purchase rating keys