概述
商品比價API，是指通過通過專門的商品價格API數據，使得網站開發人員和站長可以獲得諸如京東、亞馬遜中國、易迅、蘇寧易購等B2C商城中商品的價格信息，構建自己的APP、網站、Widgets或者其他數據服務。這種商品比價API是完全免費開放給開發人員和站長的。
目前網際網路上提供商品比價API的只有時時價比價網，現在開放的是Verion 1版，在下一版本會添加的的國美電器、淘寶商城、新蛋、噹噹等網上商城的價格信息及商品信息。
快速入門
商品比價API採用RESTFul風格，數據格式統一為JSON。
下面通過一個簡單的示例來演示商品比價API的使用。
"api開放網址//v1/product/183.js?apikey=yourapikey"
商品比價API將返回一個JSON文檔
{"id":"183","title":"蘋果iphone 4手機(3G手機，16GB,黑色，支持wifi)","brand":"蘋果(apple)","type":"iphone4","department":{"id":"21","departmentKey":"mobilephone","title":"手機"},...以下省略。
API Key申請
防止API被惡意使用，商品比價API開放網站要求所有API請求附加API KEY，請在註冊並登入後，訪問開發者頁面。
API 參考手冊
通用說明API總是形如：
"api開放網址/<version>/products.<format>/?page=<page>&rows=<rows>&apikey=<apikey>"
以下說明在每個 API請求中都需要包含的參數
| 參數 | 是否必須 | 意義 | 說明 |
|---|---|---|---|
| version | 是 | API版本，目前版本只有v1 | ​ |
| apikey | 是 | APIKey | 為防止API被惡意使用，時時價要求API請求附加API KEY, APIKey的申請請參考本頁相關章節 |
| format | 否 | 返回值格式，默認為js | 目前只支持json格式 |
| page | 否 | 返回多個元素時，頁數 | 頁數隻支持數字，如果留空則返回第一頁 |
| rows | 否 | 返回多個元素時，每頁顯示的數量 | 最大值為30 |
商品比價API通過HTTP Status Code來說明API請求是否成功，Status Code與W3C HTTP1.1規範保持一致。下面列舉了可能的返回狀態及其意義：
| 狀態碼 | 意義 |
|---|---|
| 200 OK | 請求成功 |
| 201 CREATED | 創建成功 |
| 202 ACCEPTED | 更新成功 |
| 204 NO CONTENT | 請求成功但是沒有找到對應的數據 |
| 400 BAD REQUEST | 請求中包含錯誤的參數 |
| 401 UNAUTHORIZED | 未授權 |
| 403 Forbidden | 被禁止訪問 |
| 404 NOT FOUND | 請求的資源不存在 |
| 500 INTERNAL SERVER ERROR | 內部錯誤 |
商品比價API V1目前支持如下商城：
| 商城名稱 | storeKey | URL |
|---|---|---|
| 京東商城 | jingdong | 請查看參考資料 |
| 卓越亞馬遜 | amazon | 請查看參考資料 |
| 易迅 | icson | 請查看參考資料 |
storeKey會用於API的URL搜尋查詢目錄
獲得目錄列表
"GET api開放網址/v1/departments"
返回結果是一個數據集合，以數組形式出現，包括所有的產品目錄：
[{"id":"11","departmentKey":"mobile","title":"手機通訊","parentId":null},{"id":"29","departmentKey":"e-book","title":"電子書","parentId":"12"},]
返回值說明：
| 名稱 | 意義 | 備註 |
|---|---|---|
| id | 目錄的ID | ​ |
| departmentKey | 目錄的Key值 | ​ |
| title | 目錄的名稱 | ​ |
| parentId | 目錄的上級目錄ID | 如有沒有上級目錄則為null |
獲得單個目錄信息
"GET api開放網址/v1/department/<departmentKey> "
返回結果是一個對象出現，包括產品目錄信息：
{"id":"45","departmentKey":"tablets","title":"平板電腦","parentId":"14"}
返回值說明
| 名稱 | 意義 | 備註 |
|---|---|---|
| id | 目錄的ID | ​ |
| departmentKey | 目錄的Key值 | ​ |
| title | 目錄的名稱 | ​ |
| parentId | 目錄的上級目錄ID | 如有沒有上級目錄則為null |
搜尋
"GET api開放網址/v1/search/{keyword}/{storeKey}/{departmentKey}/{order}"
返回結果是一個數據集合，分為兩部分，pager部分為搜尋的總數及分頁信息， products部分為符合搜尋條件的產品信息集合。
允許的排序
| order | 意義 |
|---|---|
| relevance | 按相關性從高到低 |
| popular | 按熱門程度從高到低（時時價降價通知的訂閱情況） |
| discount | 按折扣從高到低 |
| pricedesc | 按價格從高到低 |
| priceasc | 按價格從低到高 |
獲得產品信息
"GET api開放網址/v1/product/<productId>"
返回結果是一個數據對象，包含了產品的所有信息。
返回值說明
| 名稱 | 意義 | 備註 |
|---|---|---|
| id | 產品的ID | ​ |
| title | 產品名稱 | ​ |
| url | 產品URL | ​ |
| brand | 品牌 | ​ |
| type | 型號 | ​ |
| department | 所屬目錄 | ​ |
| buylink | 最低價商城的購買連結 | ​ |
| stock | 產品有貨/無貨的標記 | 只有當所有的比價商城都無貨時這裡才會標記為無貨 |
| cover | 商品圖片 | ​ |
| lowPrice | 商品當前最低價 | ​ |
| highPrice | 商品當前最高價 | ​ |
| averagePrice | 商品歷史平均價格 | ​ |
| lowestPrice | 商品歷史最低價格 | ​ |
| lowestPriceDate | 商品歷史最低價格發生時間 | ​ |
| highestPrice | 商品歷史最高價格 | ​ |
| highestPriceDate | 商品歷史最高價格發生時間 | ​ |
| marketPrice | 商品市場價 | ​ |
| logDays | 價格已追蹤天數 | ​ |
| lowPriceStore | 最低價商城信息 | ​ |
| stores | 所有商城信息 | ​ |
| images | 商品圖片集合 | 當一個商品有複數張圖片時，這裡會以數組形式出現 |
| lastLogTime | 價格最後更新時間 | ​ |
優惠信息
產品可能會存在優惠信息，產品的優惠信息簡單歸納為下列項目
| 中文名稱 | Key | 備註 |
|---|---|---|
| 換購 | redemption | ​ |
| 贈品 | gifts | ​ |
| 返券 | coupons | ​ |
| 限時折扣 | flashsale | ​ |
| 以舊換新 | newforold | ​ |
售後服務售後服務概要信息
| 中文名稱 | Key | 備註 |
|---|---|---|
| 免運費 | freedelivery | ​ |
| 無條件退貨 | refund | ​ |
| 增值稅發票 | vatinvoice | ​ |
| 分期付款 | installment | ​ |
| 延長質保 | extendwarranties | ​ |
| 價格保護 | protectiveprice | ​ |
獲得單個產品在某個時間段內的價格
"GET api開放網址/v1/price/<productId>?start={startTime}&end={endTime} "
請求參數說明
| 參數 | 是否必須 | 意義 | 說明 |
|---|---|---|---|
| productId | 是 | 產品ID | ​ |
| startTime | 否 | 查詢開始時間 | 如果沒有指定，則默認為與終止時間間隔31天的時間點 |
| endTime | 否 | 查詢終止時間 | 如果沒有指定，則默認為當前時刻 |
返回結果是一個數組對象，包含了產品在指定時間段內的價格記錄。
