バリューコマースAPI プログラミング解説

バリューコマースから提供されているAPIについて解説します。

導入

APIの利用には、

  1. [Webサービス対応プログラム]を提供している広告主との提携 … 対応する広告主は、メニューの【広告プログラム検索 → Webサービス対応プログラム】から検索できます。Webサービス対応プログラムについて | 管理画面ヘルプ | バリューコマース アフィリエイト
  2. トークンの取得 … 1と同様、メニューの【広告プログラム検索 → Webサービス対応プログラム】のページで確認できます。Webサービスについて | 管理画面ヘルプ | バリューコマース アフィリエイト

が必要となります。

API対応の広告主の検索方法

カテゴリやキーワードで検索する

メニューの【広告プログラム検索 → Webサービス対応プログラム】から、条件を指定して検索します。

この管理ページのカテゴリは、APIの商品カテゴリとは一致していません。

報酬その他を条件として、検索結果を並べ替える

メニューの【広告プログラム検索 → プログラム検索】で、広告種類を[ウェブサービス]とするかキーワードに「PDB」を指定して検索します。

商品API

商品の情報を取得できます。

http://webservice.valuecommerce.ne.jp/productdb/search

検索条件として、以下のいずれかのパラメータが必須となります。

必須パラメータ
検索条件 パラメータ
キーワード keyword
商品カテゴリ ※1 category
位置情報 lat_min、lat_max、lng_min、lng_max
ECサイトのサブストアID
(Yahoo!ショッピングのストアをフィルタリングするためのパラメータ)
sub_store
商品識別コード product_id

※1 商品カテゴリを限定するcategoryには、商品カテゴリの一覧にある値を指定できます。このとき「和書 > 旅行ガイド」のようにカテゴリレベルの深くまで指定するには、"books-jp,travel"のようにレベル順にカンマで区切ります。また空白が含まれるときには「\」をその前に記述します。これらのことは、カテゴリAPIで確認できます。

各種パラメータの動作は、http://webservice.valuecommerce.ne.jp/productdb/で確認できます。

パラメータ名 意味 データタイプ データの制限範囲 必須 デフォルト値 マッチタイプ 無効の場合
token VCによって発行されたパートナーのアクセスキー 文字列 0-256 bytes --- マッチされない リクエストが無効
keyword 検索キーワード 文字列 0-256文字 × ※2 --- トークン (分割) 無視
category (※7) 検索する商品カテゴリー 文字列 0-255文字 × ※2 --- 前方一致 無視
ec_code (※1)(※3) 検索対象のECサイトID 半角英数 “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 ×   範囲 無視
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”   無視
rank (※5) 商品を売上ランク順にソート 文字列 “daily”, “weekly”, “monthly” × --- 完全 無視
rank_from (※6) 売上ランクの開始順位 数字 1-50 × 1 完全 デフォルトを使用
rank_to (※6) 売上ランクの終了順位 数字 1-50 × 50 完全 デフォルトを使用
lat_min 最小緯度 度 (浮動小数), 世界測地系 (WGS84) +/- 90度 × ※2 --- 範囲 無視
lat_max 最大緯度 度(浮動小数), 世界測地系 (WGS84) +/- 90度 × ※2 --- 範囲 無視
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 以外の場合は無視     無視
商品検索 - 商品API リファレンスガイド | アフィリエイトのバリューコマース | Developer Center
  • ※1 複数のECサイトIDを検索する場合は、カンマ区切りで指定
  • ※2 いずれかひとつが必要
  • ※3 merchantとec_codeの両方が指定された場合は、OR検索
  • ※4 vcptnはポイントサイトのみが利用
  • ※5 rankが指定された場合、sort_byとsort_orderは無視される
  • ※6 rank_fromとrank_toの値が逆ならば、'INVALID_SEARCH_PARAMETERS'が返される
  • ※7 カテゴリはカンマ区切り。スペースは「\」でエスケープ

レスポンス

パラメータ名 意味 データタイプ データの制限範囲
title タイトル 文字列 ValueCommerce Service Database Search Results
link ホームリンク URL http://www.valuecommerce.com
description 内容の説明 文字列 処理時間等の時間が含まれます。
language 結果を表示する言語 文字列 “ja”
copyright 著作権情報 文字列 “Copyright 20**, ValueCommerce Co. Ltd.”
status 検索結果のステータス 文字列 下記参照
検索結果 - 商品API リファレンスガイド | アフィリエイトのバリューコマース | Developer Center
statusの値
コード 意味
OK 正常動作
INTERNAL_SERVER_ERROR サーバの内部エラー
INVALID_TOKEN token(アクセスキー) が無効
INVALID_CONFIGURATION 商品オファーが使用できるよう正しく設定されていない
INVALID_SEARCH_PARAMETERS 検索パラメータが無効
SERVICE_UNAVAILABLE 何らかの理由(メンテナンス等)によりサービスが停止している
INVALID_GADGET_ID ガジェットIDが無効
INVALID_SEARCH_VALUE 検索の値が無効
結果のヘッダ情報
パラメータ名 意味 データタイプ データの制限範囲
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:resultPerPage 1ページに表示される結果数 正の整数 1-100
vc:sortBy ソートに使用する属性 文字列 “price”,“fee”, “score”
vc:sortOrder ソート順(昇順または降順) 文字列 “asc”,“desc”
vc:rank 指定された売上ランク(降順) 文字列 “daily”, “weekly”, “monthly”
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
個々の商品の情報
パラメータ名 意味 データタイプ データの制限範囲
title 商品のタイトル 文字列 0-256文字
link ECサイトの商品へのクリックスルーリンク URL 0-2048文字
description 商品の説明 文字列 0-4096文字
guid 商品ページのURL URL 0-2048文字
vc:pvImg PV用のimgタグ (Webビーコン) 文字列 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 度

取得例

http://webservice.valuecommerce.ne.jp/productdb/search?token=***&keyword=cat
<?xml version="1.0" encoding="utf-8"?><rss version="2.0" xmlns:vc="http://valuecommerce.com/pdb/rss/">
    <channel>
        <title>ValueCommerce Product Database Search Results</title>
        <link>http://www.valuecommerce.com</link>
        <description>Processing time: 3405 ms</description>
        <language>ja</language>
        <copyright>Copyright 2014, ValueCommerce Co. Ltd.</copyright>
        <vc:keyword>cat</vc:keyword>
        <vc:adult>n</vc:adult>
        <vc:resultPerPage>20</vc:resultPerPage>
        <vc:sortBy>score</vc:sortBy>
        <vc:sortOrder>desc</vc:sortOrder>
        <vc:page>1</vc:page>
        <vc:resultcount>104173</vc:resultcount>
        <vc:pagecount>5209</vc:pagecount>
        <vc:mediaType>Web</vc:mediaType>
        <vc:status>OK</vc:status>
        <item>
            <title>CAT,CAT,CAT!オブジェソージュ…</title>
            <link>http://ck.jp.ap.valuecommerce.com/servlet/referral?…</link>
            <description>メーカー:マリーメゾンドミュー…</description>
            <guid>http://store.shopping.yahoo.co.jp/chanet/196282.html</guid>
            <vc:pvImg><![CDATA[<img src="http://ad.jp.ap.valuecommerce.com/servlet/gifbanner?vs=3058499&vp=883159238" height="1" width="1" border="0">]]></vc:pvImg>
            <vc:merchantName>Yahoo!ショッピング(ヤフー ショッピング)</vc:merchantName>
            <vc:ecCode>0hzmc</vc:ecCode>
            <vc:janCode>2250001962823</vc:janCode>
            <vc:markCode></vc:markCode>
            <vc:productCode></vc:productCode>
            <vc:modelCode></vc:modelCode>
            <vc:subStoreId>store-chanet</vc:subStoreId>
            <vc:subStoreName>Yahoo!ショッピング(ヤフー ショッピング)</vc:subStoreName>
            <vc:adult>n</vc:adult>
            <vc:startdate>20141210</vc:startdate>
            <vc:category>toysgameshobbies,toys,stuffed_animals</vc:category>
            <vc:image class="small" url="http://item.shopping.c.yimg.jp/i/c/chanet_196282" height="76" width="76" />
            <vc:image class="large" url="http://item.shopping.c.yimg.jp/i/g/chanet_196282" height="146" width="146" />
            <vc:image class="free" url="" height="" width="" />
            <vc:price>2805</vc:price>
            <vc:commissionValue>25</vc:commissionValue>
            <vc:commissionPercent>1.00</vc:commissionPercent>
            <vc:commissionFixed>0</vc:commissionFixed>
            <vc:latitude></vc:latitude>
            <vc:longitude></vc:longitude>
        </item>
        <item>
            ...
        </item>
    </channel>
</rss>

カテゴリAPI

指定カテゴリを検索するための、商品APIのURLを取得できます。

http://webservice.valuecommerce.ne.jp/productdb/category

このAPIの動作は、http://webservice.valuecommerce.ne.jp/productdb/category.htmlで確認できます。

Category Level 1のカテゴリ
categoryパラメータの値 カテゴリ名
adult アダルト
babykidsmaternity ベビー・キッズ・マタニティ
bicycle_car_motorcycle 自転車・車・バイク
book_magazine_comics 本・雑誌・コミック
cd_dvd CD・DVD
cosmetics_beauty_perfume コスメ・美容・香水
dailynecessities_stationery 日用品・文具
fashion ファッション
flowergarden フラワー・ガーデン
fooddrink フード・ドリンク
furniture_interior 家具・インテリア
health_medicalcare_care 健康・医療・介護
hobby_musicalinstrument 趣味・楽器
house_diy 住宅・DIY
householdappliance_avapparatus_camera 家電・AV機器・カメラ
outdoorleisure アウトドア・レジャー
pcmobile パソコン・モバイル
petarticle ペット用品
sports スポーツ
tableware_kitchenarticle 食器・キッチン用品
toy_game おもちゃ・ゲーム
trip 旅行

レスポンス

取得例

automotive (車) カテゴリを検索する場合を考えます。

http://webservice.valuecommerce.ne.jp/productdb/category?token=***&category_name=automotive
<?xml version="1.0" encoding="utf-8"?><rss version="2.0" xmlns:vc="http://valuecommerce.com/pdb/rss/">
    <channel>
        <title>ValueCommerce Product Database Category Search Results</title>
        <link>http://www.valuecommerce.com</link>
        <description>Processing time: 68 ms</description>
        <language>ja</language>
        <copyright>Copyright 2013, ValueCommerce Co. Ltd.</copyright>
        <vc:categoryName>automotive</vc:categoryName>
        <vc:resultcount>19</vc:resultcount>
        <vc:status>OK</vc:status>
        <item>
            <title>automotive,carsupplies,audio</title>
            <link>http://webservice.valuecommerce.ne.jp/productdb/search?category=automotive%2Ccarsupplies%2Caudio&amp;token=***</link>
            <description>車、バイク,カー用品,カーオーディオ</description>
            <guid>http://webservice.valuecommerce.ne.jp/productdb/category?category_level=3&amp;category_name=automotive%2Ccarsupplies%2Caudio&amp;token=***</guid>
            <vc:categoryLevel>3</vc:categoryLevel>
            <vc:childCategoryCount>                0</vc:childCategoryCount>
            <vc:parentCategory>
                <title>automotive,carsupplies</title>
                <link>http://webservice.valuecommerce.ne.jp/productdb/search?category=automotive%2Ccarsupplies&amp;token=***</link>
                <description>車、バイク,カー用品</description>
                <guid>http://webservice.valuecommerce.ne.jp/productdb/category?category_level=2&amp;category_name=automotive%2Ccarsupplies&amp;token=***</guid>
                <vc:categoryLevel>2</vc:categoryLevel>
            </vc:parentCategory>
        </item>
        <item>
            ...
        </item>
    </channel>
</rss>

結果はこのように返され、ここから次のように商品APIのURLを取得できます。

<title>automotive,carsupplies,audio</title>
<link>http://webservice.valuecommerce.ne.jp/productdb/search?category=automotive%2Ccarsupplies%2Caudio&amp;token=***</link>

トラベルAPI

条件を満たすホテルなどの情報を取得できます。

http://ws.valuecommerce.ne.jp/travel/search

検索対象として、

  • ホテル … じゃらん
  • エアチケット … AB-ROAD
  • ツアー … AB-ROAD

の3つを指定できます。

このAPIの動作は、http://ws.valuecommerce.ne.jp/travel/で確認できます。