Upload
others
View
0
Download
0
Embed Size (px)
Citation preview
バリューコマ ース・ウェブサービス
API マニュアル
2016 年 6 月 21 日 第 4 版
第 1 章 API を導入してみよう
1.1 はじめに
本書では、商品 API を簡単に利用するための準備やステップ、その他基本的な説明をします。
バリューコマースの API を利用して、次のことができます。
• 広告主が持つ商品情報の簡単検索
• 異なる広告主が持つ同一商品の価格比較• お目当て商品の売り上げ順ランキング など
図 1.1: バリューコマース・ウェブサービスの仕組み
自由なアイデアとバリューコマースの持つコンテンツを組み合わせて、あなたのウェブサイトに新しいサービスを生み出してください。
※ウェブサービスの利用にはプログラミングのスキルが必要です。バリューコマースではプログラミングに関するサポートは行っていません。
1.2 商品 API を利用するための準備
商品 API を利用し、広告主が持つ商品情報を取得するには、下記 4 つの準備が必要です。
• バリューコマースのアフィリエイトサイトとして登録し、審査を通過する• 商品情報を持つ広告主と提携する• トークンを取得する
• 使用するプログラム言語(PHP)の動作確認
1.2.1 バリューコマースのアフィリエイトサイトとして登録し、審査を通過する
ウェブサービスを利用するために、まずはバリューコマースにアフィリエイトサイトとして登録しましょう。下記のページから申し込みます。
バリューコマース:https://www.valuecommerce.ne.jp/
申し込み手続きが終わると、登録 E メールアドレス宛に仮パスワードが送信され、本パスワードを作成し管理画面に接続することができます。
しかし、この時点ではまだウェブサービスを使うことはできません。
バリューコマースではあなたのサイトが適切かどうかの審査を行っており、審査に通過するとウェブサービスが利用できるようになります。
審査終了のお知らせは、登録 E メールアドレス宛に届きます。
※審査終了まで数日かかります。
1.2.2 商品情報を持つ広告主と提携する
メニューの「広告ブログラム検索」→「Web サービス対応プログラム」からウェブサービスを提供している広告主を探すことができます。このなかから利用したいウェブサービスを提供している広告主を探して提携し、広告スペースを作成してください。自動承認の場合は、広告スペースも自動で作成されます。
1.2.3 トークンを取得する
トークンはウェブサービスを使用する上で必ず必要になる情報です。「広告ブログラム検索」→「Web サービス対応プログラム」から確認できます。
既に提携し、広告スペースが作成されている場合は、広告スペース詳細画面でも確認できます。
1.2.4 使用するプログラミング言語(PHP)の動作確認
ウェブサービスを利用するためには、プログラミング言語を用いて検索ページを制作する必要があります。使用するプログラミング言語は好きなものを使ってください。
1. PHP を使用することができるサーバを用意する
これからレンタルホスティングサービスなど契約しサーバを用意する場合は、PHPが使用できるサーバを用意するようにします。
既にレンタルホスティングサービスと契約、もしくはサーバを用意をしている場合は、そのサーバで PHP が使えるかどうかサーバ管理者等に確認してください。
2. PHP が正しく動作するか、簡単なスクリプトを使って動作テストをする
あなたが用意したサーバに「phpinfo.php」をアップロードし、正常に動作するかどうかをアクセスして確認します。
• ファイル名:phpinfo.php
• PHP ファイルが置かれているディレクトリのパーミッション:drwxr-xr-x(755)• PHP ファイルのパーミッション:-rw-r--r--(644)
ここまでで、バリューコマースが提供しているウェブサービスが動作する環境の準備が完了となります。
続いて、バリューコマース API の基本的ルールを検索例やフォーマットの特長を確認しながら理解していきましょう。
第 2 章 商品 API の基本的ルール
ウェブサービスでは、検索パラメータとその値をブラウザのアドレスバーに入力することによって、検索結果を受け取ります。
下記、バリューコマースで作成した検索ページを例に下記項目について確認し理解していきましょう。
• 基本ルール• 検索例• フォーマットの特徴と指定方法
• 検索結果 (format=rss)• エラーの場合
• 検索結果を PHP で表示できるように解析する
2.1 実際に API のパラメータを使って検索してみる
図 2.1: 商品 API での検索
検索ページ:http://webservice.valuecommerce.ne.jp/productdb/
検索項目に必要な値(トークンや検索キーワード)を入力し「検索する」をクリックしてください。検索結果が表示されブラウザのアドレスバーには検索パラメータと入力した値がはいっていることが分かります。これが商品 API の検索の仕組みです。
パラメータとその値を手動で入力して検索結果を表示させることもできます。
バリューコマースウェブサービス商品 API リファレンスガイドの検索パラメータを参照し、検索パラメータとそれぞれの値についてのルールを確認し、基本ルールに沿ってブラウザのアドレスバーに入力してみてください。
※パラメータの値に全角文字を使用する場合、その文字をエンコードする必要があります。詳しくは検索例を参照してください。
2.1.1 基本ルール
http://webservice.valuecommerce.ne.jp/productdb/search?token=123456789&keyword=japan
※「123456789」の部分にあなたのトークンが入ります。
URL の後ろに「?」を付け、“token”パラメータからスタートします。“token”パラメータとその値がない場合や値が間違っている場合には、検索結果は表示されません。
「=」でパラメータの値を入力し、「&」でパラメータをつなげます。
2.1.2 検索例
【例 1】検索キーワードを「bicycle」として検索リクエストを送信した場合
http://webservice.valuecommerce.ne.jp/productdb/search?token=123456789&serv_type=1&keyword=bicycle
キーワード検索をするパラメータとして“keyword”を入力します。「=」でパラメータの値である“bicycle”を入力します。
【例 2】検索キーワードを全角(自転車)で検索リクエストを送信した場合
http://webservice.valuecommerce.ne.jp/productdb/search?token=123456789&serv_type=1&keyword=%E8%87%AA%E8%BB%A2%E8%BB%8A
全角文字は UTF-8 にエンコードする必要があります。
【例 3】検索キーワード「自転車(全角)」で指定し、月の売上順で商品を並べるよう検索リクエストを送信した場合
http://webservice.valuecommerce.ne.jp/productdb/search?token=123456789&keyword=%E8%87%AA%E8%BB%A2%E8%BB%8A&rank=monthly&rank_from=1&rank_to=5
“rank”パラメータで月、週、日いづれのランキングにするか指定します。“rank_from”および“rank_to”で、開始順位と終了順位を指定します。
2.1.3 フォーマットの特徴と指定方法
商品 API を使いリクエストして取得した検索結果は、RSS、JSON、JSONP のいずれかのフォーマットで返されます。
検索リクエストを送信する際、レスポンスのフォーマットを“format”パラメータを使って指定します。(指定しなかった場合は、デフォルト値として設定されているRSS フォーマットで返されます)
RSS(xml)フォーマット
RSS リーダーで読む事が可能で、ライブラリの拡張が容易なのが特徴です。レスポンスを RSS バナーとして配信することも可能です。
http://webservice.valuecommerce.ne.jp/productdb/search?token=123456789&serv_type=1&keyword=japan&format=rss
JSON フォーマット
JavaScript に組み込んで直接扱えるので、JavaScript を利用している方はもちろん、その記述方式からその他の言語(Perl, PHP 等)を使用する方にも扱いやすいフォーマットです。データサイズが軽量なのも特徴です。
http://webservice.valuecommerce.ne.jp/productdb/search?token=123456789&serv_type=1&keyword=japan&format=json
JSONP フォーマット
JSON と同様の特徴に加えて、コールバック関数を指定することができます。
http://webservice.valuecommerce.ne.jp/productdb/search?token=123456789&serv_type=1&keyword=japan&format=jsonp&callback=sdb_results
2.1.4 検索結果(format=rss)
ブラウザのアドレスバーを使って RSS フォーマットを指定し検索リクエストを送信した場合、下図のように XML RSS2.0 形式で検索結果が返ります。
図 2.2: 検索結果(RSS)
※画面デザインはブラウザ及びそのバージョンによって異なります。左図は Internet Explorer8 を使っています。
このページのソースを見ると下記のように表示されます。
ここに表示されているパラメータについては、バリューコマースウェブサービスAPI リファレンスの検索結果を参照してください。
1 2 3 4 ValueCommerce Product Database Search Results5 http://www.valuecommerce.com6 Processing time: 45 ms7 ja8 Copyright 2010, ValueCommerce Co. Ltd.9 japan
10 n11 2012 score13 desc14 115 4214416 210817 Web18 OK19 20 【Japan】 USB-IRL0821 http://ck.jp.ap.valuecommerce.com/servlet/referral?vs=1234567&vp=123456789&vc_url=http%3A%2F%2Fwww.sample.com22 USB ケーブル〔0.8m〕(ホワイト)23 http://www.sample.com24 ]]>25 ABC 電機26 *****27 *************28 29 30 ***-****31 abc123456732 ABC 電機オンラインショップ33 n34 2010052435 electronics,audio,audio36 37 38 39 147040 1441 1.0042 043 44 45 46 47 (省略)48 49 50
2.2 エラーの場合
何らかの原因でエラーになり検索結果が返ってこなかった場合には、下図のように表示されます。
図 2.3: エラー
【例】“keyword”パラメータを、誤って「keyward」と入力した場合
※画面デザインはブラウザ及びそのバージョンによって異なります。左図は Internet Explorer8 を使っています。
このページのソースを見ると、“vc:status”パラメータに「INVALID_SEARCH_PARAMETERS」と表示されます。
1 2 3 4 ValueCommerce Product Database Search Results5 http://www.valuecommerce.com6 Processing time: 1 ms7 ja8 Copyright 2010, ValueCommerce Co. Ltd.9 INVALID_SEARCH_PARAMETERS
10 11
※エラーの内容によって表示されるステータスは異なります。詳しくはバリューコマースウェブサービス商品 API リファレンスガイドの検索結果を参照してください。
ステータスは OK ですが、結果が表示されない場合は、次の原因である可能性があります:
• EC と提携しましたが、「広告作成」ボタンを押していない
• 商品 API の EC と提携がありますが、検索している EC(ecCode)と提携がない• 検索条件数を減らしてみてください
2.2.1 検索結果を PHP で表示できるように解析する
ブラウザのアドレスバーを使って RSS フォーマットを指定し検索リクエストを送信した場合、XML RSS2.0 形式で検索結果が返ります。
このページのソースを見ると下記のように表示されます。
ここに表示されているパラメータについては、バリューコマースウェブサービス商品 API リファレンスの検索結果パラメータを参照してください。
phpinfo に下図の記述があったら、SimpleXML モジュールは有効になっています。
図 2.4: SimpleXML
PHP5 を使わない場合や SimpleXML モジュールが使えない場合は、lastRSS ファイルなどお好きなライブラリを使ってください。
※ PHP5 の SimpleXML の詳細については PHP Manual を参照してください。
第 3 章 商品 API リファレンスガイド
3.1 商品検索
検索は指定の URL にアクセスすることによって実行します。入力データは UTF-8でエンコードする必要があります。検索 URL パラメータは下記の通りです。
3.1.1 検索パラメータ
表 3.1: 検索パラメータ
パラメータ名 意味データタイプ データの制限範囲 必須
デフォルト値
マッチタイプ
無効の場合
token VC によって発行されたパートナーのアクセスキー
文字列 0-256 bytes はい - マッチされない
リクエストが無効
keyword 検索キーワード
文字列 0-256 文字 いいえ(*2)
- トークン(分割)
無視
category(*5) 検索する商品カテゴリー
文字列 0-255 文字 いいえ(*2)
- 前方一致
無視
ecCode(*1)(*3) 検索対象の EC
サイトコード半角英数“0-9”,“A-Z”,“a-z”
1-50 文字 いいえ - 完全(大文字と小文字を区
存在しない ECサイトID が指定された場
別する)
合、空の検索結果が返る。
merchant(*3) 検索対象の ECサイトを指定
文字列 0-255 文字 いいえ - 完全(大文字と小文字を区別する)
存在しない ECサイト名が指定された場合、空の検索結果が返る。
sub_store EC サイトのサブストア ID
文字列 0-256 文字 いいえ(*2)
完全 無視
adult アダルト商品を検索結果に含めるかどうかの指定
文字列 “y”,“n” いいえ “n” 完全 デフォルト値を使用
price_max 最大価格 0 以上の浮動小数
0-999999999 いいえ - 範囲 無視
price_min 最小価格 0 以上の浮動小数
0-999999999 いいえ - 範囲 無視
rate_max 最大報酬率 0 以上の浮動小数
0-100 いいえ 範囲 無視
rate_min 最小報酬率 0 以上の浮動小数
0-100 いいえ 範囲 無視
fixed_max 最大定額報酬料
0 以上の浮動小数
0-999999999 いいえ 範囲 無視
fixed_min 最小定額報酬料
0 以上の浮動小数
0-999999999 いいえ 範囲 無視
fee_max 最大報酬額 0 以上の浮動小数
0-999999999 いいえ 範囲 無視
fee_min 最小報酬額 0 以上の浮動小数
0-999999999 いいえ 範囲 無視
size 検索対象のサ 文字列 0-255 byte いいえ トー 無視
イズを指定 クン(分割)
color 検索対象の色を指定
文字列 0-255 byte いいえ トークン(分割)
無視
stock 検索対象の在庫状況
"0"(なし),"1"(在庫有り),"2"(お取り寄せ),"3"(予約受付)
1byte いいえ 完全 無視
gender 検索対象の性別
"0"(メンズ),"1"(レディース),"2"(ユニセックス)
1byte いいえ 完全 無視
vcptn(*4) 注文の際に入力するポイントシステムパラメータ
ASCII “,(コンマ)”, “=”, “&”, “[”, “]”, “”は除く
0-255 文字 いいえ - - 無視
page 表示する検索結果のページ番号
正の整数 1-1000 いいえ 1 無視
results_per_page 1 ページ毎の結果件数
正の整数 1-50 いいえ 20 無視
sort_by ソートの属性 文字列 “price”,“fee”, “score”
いいえ “score” 無視
sort_order ソート順(昇順または降順)
文字列 “asc(昇順)”,“desc(降順)”
いいえ “desc” 無視
lat_min 最小緯度 度 (浮動小数), 世界測地系(WGS84)
+/- 90 度 いいえ(*2)
- 範囲 無視
lat_max 最大緯度 度(浮動小数), 世界測地系
+/- 90 度 いいえ(*2)
- 範囲 無視
(WGS84)lng_min 最小経度 度(浮動小
数), 世界測地系(WGS84)
+/- 180 度 いいえ(*2)
- 範囲 無視
lng_max 最大経度 度(浮動小数, 世界測地系(WGS84)
+/- 180 度 いいえ(*2)
- 範囲 無視
product_id 商品識別コード
文字列 300 文字 いいえ(*2)
完全 無視
format 検索結果のフォーマット
文字列 “rss”,“json”,“jsonp” いいえ “rss” デフォルト値を使用
callback “jsonp”が指定された時のコールバックファンクション名
文字列 0-256 bytes.
(A-Z,a-z),(0-9),“.(ドッ)”, “_(アンダーバー)”,“[”,“]”([ ]はエンコードする)
format=jsonp 以外の場合は無視
無視
(*1)複数の EC サイト ID(ecCode)を検索する場合は、カンマ区切り( , )で指定してください(例:123,456,789)。また、ecCode は大文字・小文字を区別するのでご注意ください。→ecCode の一覧
(*2)下記いずれか最低 1 つは有効な値が存在する必要があります。そうでない場合、リクエストは無効となります。
keyword, category, 位置情報 (lat_min, lat_max, lng_min, lng_max), sub_store, product_id
(*3)merchant 及び ecCode の両方が指定された場合は、OR 検索になります。
(*4)vcptn はポイントサイトのみが利用します。一般のパートナーサイトで利用することはありません。
(*5)第一カテゴリー、第二カテゴリー、第三カテゴリーは、カンマ区切り( , )で指定してください。スペースを含んだカテゴリー名を指定する場合はスペースの前に「\」を加えてください。(例:recreationoutdoor,golf,golf\ boston\ bags)
すべてのフィルタ結果はその値を含みます。したがって、price_min=100 の検索結果には、価格が100 の商品も含まれます。
パートナーのアクセスキーに無効なデータが含まれている場合、全体の要求が無効とみなされます。その他のパラメータが無効である場合は無視されます。要求が無効とみなされるか、あるいはパラメータが無視されるかは上記の表にも示しています。指定されたすべての検索パラメータに一致する検索結果のみが返されます。つまり、パラメータは、OR クエリではなく AND クエリとして処理されます。
sub_store は、Yahoo!Shopping 内のストアを絞り込むためのパラメータです。予め sub_storeID をご確認の上ご利用ください。
■sub_storeID の確認方法
絞り込みたいストアの URL が http://store.shopping.yahoo.co.jp/○○○○/ の場合、sub_storeID は「store-○○○○」となります。
以下に検索 URL の例を示します。
http://webservice.valuecommerce.ne.jp/productdb/search?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&keyword=Gucci&category=fashion&fee_min=1000&vcptn=YASubAff11&page=1&sort_by=fee&sort_order=desc
また以下の URL にて各種パラメータの動作テストを行うことができます。
http://webservice.valuecommerce.ne.jp/productdb/
3.1.2 検索結果
検索結果は、UTF-8 でエンコーディングされた XML RSS 2.0 ファイル、またはJSON/JSONP フォーマットで提供されます。ヘッダー情報には次のパラメータが含まれます。
表 3.2: 検索結果
パラメータ名 意味データタイプ データの制限範囲
title タイトル 文字列 ValueCommerce Service Database Search Results
link ホームリンク URL http://www.valuecommerce.com
description 内容の説明 文字列 処理時間等の時間が含まれます。
language 結果を表示する言語
文字列 “ja”
copyright 著作権情報 文字列 “Copyright 20**, ValueCommerce Co. Ltd.”
status 検索結果のステータス
文字列 下記参照
status パラメータの表示例
INVALID_TOKEN
下記のいずれかが status の値で返ります。
表 3.3: ステータス
コード 意味
OK 正常動作
INTERNAL_SERVER_ERROR サーバの内部エラー
INVALID_TOKEN token(アクセスキー) が無効
INVALID_CONFIGURATION 商品オファーが使用できるよう正しく設定されていない
INVALID_SEARCH_PARAMETERS 検索パラメータが無効
SERVICE_UNAVAILABLE 何らかの理由(メンテナンス等)によりサービスが停止している
INVALID_GADGET_ID ガジェット ID が無効
INVALID_SEARCH_VALUE 検索の値が無効
結果のヘッダ情報には次のパラメータが含まれます。
表 3.4: 結果のヘッダ情報
パラメータ名 意味 データタイプ データの制限範囲
vc:keyword 検索されたキーワード文字列
文字列 0-256 文字
vc:subStoreId フィルタに使用する EC サイトのサブストア ID
文字列 0-256 文字
vc:category 検索された商品カテゴリー 文字列 0-255 文字
vc:merchantName クエリで指定された EC サイト名
文字列 0-256 文字
vc:ecCode 検索された EC サイトコード
整数[0-9], テキスト[A-Z] [a-z]
1-50 文字
vc:adult アダルト商品を表示するかどうかを指定するフラグ
文字列 “y” または “n”
vc:priceMax フィルタに使用する最大商品価格
負でない浮動小数点 0-999999999
vc:priceMin フィルタに使用する最小商品価格
負でない浮動小数点 0-999999999
vc:rateMax フィルタに使用する最大報酬率
負でない浮動小数点 0-100
vc:rateMin フィルタに使用する最小報酬率
負でない浮動小数点 0-100
vc:fixedMax フィルタに使用する最大定額料
負でない浮動小数点 0-999999999
vc:fixedMin フィルタに使用する最小定額料
負でない浮動小数点 0-999999999
vc:commissionValueMax フィルタに使用する最大報酬額
負でない浮動小数点 0-999999999
vc:commissionValueMin フィルタに使用する最小報酬額
負でない浮動小数点 0-999999999
vc:latMin フィルタに使用する最小緯度
度(浮動小数), 世界測地系(WGS84)
+/- 90 度
vc:latMax フィルタに使用する最大緯度
度(浮動小数),世界測地系(WGS84)
+/- 90 度
vc:lngMin フィルタに使用する最小経度
度(浮動小数),世界測地系(WGS84)
+/- 180 度
vc:lngMax フィルタに使用する最大経度
度(浮動小数), 世界測地系(WGS84)
+/- 180 度
vc:size フィルタに使用するサイズ 文字列 0-255 文字
vc:color フィルタに使用する色 文字列 0-255 文字
vc:stock フィルタに使用する在庫 "0","1","2""3" 1byte
vc:gender フィルタに使用する性別 "0""1","2" 1byte
vc:resultPerPage 1 ページに表示される結果数
正の整数 1-100
vc:sortBy ソートに使用する属性 文字列 “price”,“fee”, “score”
vc:sortOrder ソート順(昇順または降順) 文字列 “asc”,“desc”
vc:page 現在表示されている検索結果のページ番号
正の整数 1-1000
vc:resultcount 商品の検索結果の合計件数 負でない整数 0-1000
vc:pagecount 合計ページ数 正の整数 1-100
vc:mediaType パートナーのメディアタイプ
文字列 “Web”,“i-mode ”,“EZweb”, “Yahoo!keitai”
vc:status 応答の状態 文字列 0-256 bytes
商品ごとに以下の値が戻ります。
表 3.5: 戻り値
パラメータ名 意味 データタイプ データの制限範囲
title 商品のタイトル 文字列 0-256 文字
link EC サイトの商品へのクリックスルーリンク
URL 0-2048 文字
description 商品の説明 文字列 0-4096 文字
guid 商品ページの URL URL 0-2048 文字
vc:pvImg PV 用の img タグ 文字列 0-2048 文字
vc:merchantName EC サイト名 文字列 0-256 文字
vc:ecCode 検索された EC サイトコード 半角英数
“0-9”, “A-Z”, “a-z” 1-50 文字
vc:janCode 商品の JAN コード 文字列 300 文字
vc:markCode 商品の業界コード 文字列 300 文字
vc:productCode 商品の EC 商品コード 文字列 300 文字
vc:modelCode 商品の製品型番 文字列 300 文字
vc:subStoreId EC サイトのサブストア ID 文字列 0-256 文字
vc:subStoreName EC サイトのサブストア名 文字列 0-256 文字
vc:adult アダルトフラグ 1 文字 “y”,“n”
vc:startDate 商品の提供開始日(日本時間) 日付文字列 YYYYMMDD
vc:category 商品カテゴリー 文字列 0-255 文字
vc:image class="small" 小さい商品イメージ、可能であれば 150×150 ピクセルより小さいイメージ
URL とサイズ URL:0-2048 文字
サイズ:正の整数
vc:image class="large" 大きい商品イメージ URL とサイズ URL:0-2048 文字
サイズ:正の整数
vc:image class="free" フリーサイズの商品イメージ URL とサイズ URL:0-2048 文字
サイズ:正の整数
vc:price 商品の価格 負でない浮動小数点
0-999999999
vc:commissionValue パートナーがその商品から得られる報酬額
負でない浮動小数点
0-999999999
vc:commissionPercent 報酬率、または定額の場合は 0 負でない浮動小数点
0-100
vc:commissionFixed 定額報酬料、または定率報酬の場合は 0
負でない浮動小数点
0-999999999
vc:latitude 地理位置情報(緯度) 度(浮動小数), 世界測地系(WGS84)
+/- 90 度
vc:longitude 地理位置情報(経度) 度(浮動小数), 世界測地系(WGS84)
+/- 180 度
vc:product_category 商品区分 文字列 "新品", "中古", "訳あり"
vc:brand_name ブランド名 文字列 0-255 文字
vc:brand_url ブランド URL URL 0-2048 文字
vc:stock 在庫 文字列 "なし", "在庫有り", "お取り寄せ", "予約受付"
vc:postage 送料 文字列 "なし", "あり"
vc:point ポイント 負でない浮動小数点
0-999999999
vc:size サイズ 文字列 0-255 文字
vc:color 色 文字列 0-255 文字
vc:gender 性別 文字列 "メンズ", "レディース", "ユニセックス"
vc:shipping_arrangement 発送手配 文字列 "当日", "明日", "5営業日以内"
vc:sale_price セール価格 負でない浮動小数点
0-999999999
vc:sale_start_date セール開始日時 日付 YYYYMMDDTTTT
vc:sale_end_date セール終了日時 日付 YYYYMMDDTTTT
vc:product_update_day 商品更新日 日付 YYYYMMDD
※検索結果として取得可能な商品件数は最大 100,000 件です。例えば 1 ページ 100 件表示の場合は 1000 ページまでとなり、1001 ページ以降に表示されるデータは、1 ページのものと同一データになりますのでご注意ください。
※パラメータ名は RSS 2.0 フォーマットで記載されています。ユーザが JSON/JSONP フォーマットを選択した場合、vc namespace( “vc:” )のプリフィックスは省きます。
検索結果例 for xml
1 2 3 4 ValueCommerce Product Database Search Results5 http://www.valuecommerce.com6 Processing time: 32 ms7 ja8 Copyright 2012, ValueCommerce Co. Ltd.9 book10 n11 2012 score13 desc14 115 116 8757017 Web18 OK19 20 香港21 http://ck.jp.ap.valuecommerce.com/servlet/referral?vs=1234567&vp=123456789&vc_url=http%3A%2F%2FdpDasn22 香港旅行記23 http://webservice.valuecommerce.ne.jp/db/hongkong/index.api24 ]]>25 通販サイト26 AB00127 123456728 29 30 31 032 abcbook33 n34 2009040935 books36 37 38 39 157040 5541 342 0
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
検索結果例 for json
1 {2 "encoding":“UTF-8”,3 "title":“ValueCommerce Product Database Search Results”,4 "link":“http://www.valuecommerce.com”,5 "description":“Processing time: 31 ms”,6 "language":“ja”,7 "copyright":“Copyright 2012, ValueCommerce Co. Ltd.”,8 "category":“book”,9 "adult":“n”,10 "resultPerPage":20,11 "sortBy":“score”,12 "sortOrder":“desc”,13 "page":1,14 "resultCount":17,15 "pageCount":1,16 "mediaType":“Web”,17 "status":“OK”,18 "items":19 [20 {21 "title":“香港”,22 "link":“http://ck.jp.ap.valuecommerce.com/servlet/referral?vs=1234567&vp=123456789&vc_url=http%3A%2F%2FdpDasn”,23 "description":“香港旅行記”,24 "guid": “http://webservice.valuecommerce.ne.jp/db/hongkong/index.api”,25 "pvImg": “
56789” height=“1” width=“1” Border=“0”>”,26 "merchantName":“abcbook 通販サイト”,27 "ecCode":“AB001”,28 "janCode":“1234567”,29 "markCode":“”,30 "productCode":“”,31 "modelCode":“”,32 "subStoreId":“0”,33 "subStoreName":“abcbook”,34 "adult": “n”,35 "startDate":“20080409”,36 "category":“books-jp,travel”,37 "imageSmall":{38 “url”:“http://webservice.valuecommerce.ne.jp/images/s46x75.jpg”,39 "height":75,40 "width":4641 },42 "imageLarge":{43 "url":“http://webservice.valuecommerce.ne.jp/images/l97x160.jpg”,44 "height":160,45 "width":19746 },47 "imageFree":{48 "url":“http://webservice.valuecommerce.ne.jp/images/g302x500.jpg”,49 "height":500,50 "width":30251 },52 "price":1570,53 "commissionValue":47,54 "commissionPercent":3,55 "commissionFixed":0,56 "latitude":"",57 "product_category": "",58 "brand_name": "",59 "brand_url": "",60 "stock": "",61 "postage": "",62 "point": "",63 "size": "",64 "color": "",65 "gender": "",66 "shipping_arrangement": "",67 "sale_price": "",68 "sale_start_date": "",69 "sale_end_date": "",70 "product_update_day": ""71 }72 ]73 }
検索結果例 for json&callback=sdb_results
1 pdb_results(2 {3 "encoding":“utf-8”,4 "page":1,
(以下「商品検索検索結果例 for output=json」と同様の為省略)
カテゴリー検索
検索は指定の URL にアクセスすることによって実行します。入力データは、UTF-8 でエンコードする必要があります。検索 URL パラメータは以下の通りです。
検索パラメータ
表 3.6: 検索パラメータ
パラメータ名 意味
データタイプ
データの制限範囲
必須?
デフォルト値
マッチタイプ
無効の場合
token VC によって発行されたパートナーのアクセスキー
文字列
0-256 bytes
はい マッチされない
リクエストが無効
category_name(*1) 商品カテゴリー 文字列
0-256 文字
いいえ(*2)
前方一致
無視
category_level カテゴリーレベル数 数字 1-3 いいえ(*2)
完全 無視(*3)
format レスポンスフォーマット
文字列
“rss” , “json”, “jsonp”
いいえ
“rss” 完全 デフォルト値を使用
callback “jsonp” が指定された時のコールバックファンクション名
文字列
0-256 bytes
(A-Z,a-z),(0-9), “.(ドット)”, “_(アンダーバー)”, “[”, “]” ([ ]はエンコードする)
format=jsonp 以外の場合は無視
- 無視
childless(*4) 指定されたカテゴリーレベルのみのデータを返す
- - いいえ
無効なリクエスト
(*1)カテゴリー項目のフォーマットは“親カテゴリー , 子カテゴリー ,... ”の順でカンマ区切りで指定できます。ただし、子カテゴリーを指定した場合、category_level は子カテゴリーを含んだ階層よりも大きい数字を指定するか、ブランクにする必要があります。(例; books-jp, art とした場合、category_level は 2 か 3、及びブランクとする)
(*2)最低 1 つのパラメータが必要です。
(*3)全カテゴリーレベルから検索します。
(*4)このパラメータを利用する場合は、必ず“category_level”も利用してください。“childless”のみで利用した場合“INVALID_SEARCH_PARAMETERS”が返ります。下記のように検索 URL の末尾で利用します。
childless を利用した場合の例http://webservice.valuecommerce.ne.jp/productdb/category?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&category_level=1&childless
以下に検索 URL の例を示します。http://webservice.valuecommerce.ne.jp/productdb/category?token=xxxxxxxxx...
また以下の URL にて各種パラメータの動作テストを行うことができます。http://webservice.valuecommerce.ne.jp/productdb/category.html
検索結果
検索結果は UTF-8 でエンコーディングされた XML RSS 2.0 ファイル、またはJSON/JSONP フォーマットで提供されます。ヘッダ情報には次のパラメータが含まれます。
表 3.7: 検索結果
パラメータ名 意味 データタイプ データの制限範囲
title タイトル テキスト ValueCommerce Product Database Search Results
link ホームリンク URL http://www.valuecommerce.com
description 内容の説明 テキスト 処理時間等の時間が含まれます。
language 結果を表示する言語 文字列 “ja”
copyright 著作権情報 文字列 “Copyright 2***, ValueCommerce Co. Ltd.”
status 検索結果のステータス 文字列 下記参照
status パラメータの表示例
INVALID_TOKEN
下記のいずれかが status の値で返ります。
表 3.8: ステータス
コード 意味
OK 正常動作
INTERNAL_SERVER_ERROR サーバーの内部エラー
INVALID_TOKEN token(アクセスキー)が無効
INVALID_CONFIGURATION パートナーがカテゴリー検索を使用できるよう正しく設定されていない
INVALID_SEARCH_PARAMETERS 検索パラメータが無効
SERVICE_UNAVAILABLE 何らかの理由(メンテナンス等)によりサービスが停止している
結果のヘッダ情報には次のパラメータが含まれます。
表 3.9: ヘッダ情報
パラメータ名 意味 データタイプ データの制限範囲
vc:categoryName 検索した商品カテゴリー 文字列 0-256 bytes
vc:categoryLevel 検索したカテゴリーレベル 負でない整数 1-3
vc:resultcount カテゴリアイテムの検索結果の合計数 負でない整数 0-999999999
vc:status 応答の状況 文字列 0-256 bytes
カテゴリーごとに以下の値が戻ります。
表 3.10: 戻り値
パラメータ名 意味データタイプ データの制限範囲
title カテゴリー名 文字列 0-256 文字
link カテゴリーに入ってる商品を検索する為のURL
URL 0-2048 文字
description カテゴリー名(日本語) 文字列 0-4096 文字
guid カテゴリー検索 API でそのカテゴリーを検索する為の URL
URL 0-2048 文字
vc:childCategoryCount 子カテゴリー数 数字 子カテゴリー数の正の整数
vc:parentCategory 親カテゴリーの情報が含まれる - -
vc:childCategory 子カテゴリーの情報が含まれる - -
vc:categoryLevel カテゴリーレベル 数字 1-3
パラメータ名は RSS 2.0 フォーマットで記載されています。ユーザが JSON/JSONPフォーマットを選択した場合、vc namespace(“vc:”)のプリフィックスは省きます
バリューコマース・ウェブサービス API マニュアル
2016 年 6 月 21 日 発行
著 者 バリューコマース株式会社
Copyright (c), ValueCommerce co., ltd.