API 概覽
如何取得金鑰、進行身分驗證並開始使用 Market Ninja API——先查找後取得的模式、限制說明和錯誤格式。
Market Ninja API 提供對同一個群眾外包資料集的唯讀程式化存取,也就是您在擴充功能介面中看到的資料: 來自 Wildberries、Ozon、Yandex Market 和 Lamoda 的商品、價格(目前與歷史)、賣家和類目。
取得金鑰
金鑰於擴充功能設定的 API 金鑰 區塊簽發,僅 Premium 方案可用。完整的金鑰值
(mn_live_...)只會在建立時顯示一次——請立即儲存,之後無法復原(只能撤銷後重新產生)。
身分驗證
每個請求都必須包含以下標頭:
Authorization: Bearer mn_live_your_keycurl -H "Authorization: Bearer mn_live_..." \
"https://data.marketninja.ru/v1/products?page_size=3"核心使用模式:「先查找,後取得」
外部整合方無法預先得知商品在我們資料庫中的內部 id——沒有任何管道能事先取得它。因此您總是從已擁有的資訊開始:
查找商品:呼叫 GET /products,傳入您已擁有的資訊——商品連結(url)、
電商平台自身的 SKU(external_id + marketplace),或您自己的內部貨號(seller_code)。
讀取 id:從回應的 data[].id 欄位取得我們的內部識別碼。
如有需要,可透過 id 直接取得該商品(GET /products/{id})或其價格歷史
(GET /products/{id}/price-history)——但請注意,目前價格已包含在第一步的回應中,
獨立的請求僅用於分析價格走勢。
詳細情境與範例請參閱:尋找商品、 價格歷史、賣家、 類目、品牌、 批次匯出、 擷取工作階段(取得您剛透過擴充功能採集的資料),以及 Webhook(工作階段完成時主動通知,無需輪詢)。 每個端點的完整參數與回應說明:參考文件。
錯誤格式
所有錯誤都以統一的格式回傳:
{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key" } }| HTTP 狀態碼 | error.code | 意義 |
|---|---|---|
400 | validation_error | 查詢參數無效。 |
401 | invalid_api_key | 金鑰缺失、格式錯誤、未知、已撤銷或已過期。 |
403 | subscription_lapsed | 金鑰有效,但 Premium 訂閱目前未生效。 |
404 | not_found | 找不到該 id 對應的商品。 |
429 | rate_limited | 超出每分鐘請求頻率限制——請在 Retry-After 秒後重試。 |
429 | quota_exceeded | 每日資料配額已用盡——於 UTC 00:00 重置。 |
500 | internal_error | 伺服器內部錯誤,可稍後重試。 |
503 | query_timeout | 查詢耗時過長。請等待 Retry-After 秒後重試;如果仍然失敗,請縮小查詢範圍(例如使用更長的 name_contains 關鍵字或增加篩選條件)。 |
503 | service_unavailable | 服務暫時繁忙——請在 Retry-After 秒後重試。 |
403 和 401 是兩種不同的問題:「金鑰本身有誤」(需要核對金鑰值)與「需要續訂」(金鑰本身有效,但存取已被暫停)。請不要在程式碼中用同一套邏輯處理它們——顯示給使用者的提示訊息也應有所區分。限制與配額
API 的存取受兩項彼此獨立的限制約束:請求頻率與每日資料量。兩者皆按 API 金鑰分別計算。
超出任一項時,API 都會回傳 429,可透過 error.code 欄位區分是哪一項。
| 限制 | 數值 | 計算對象 | 重置時間 | 錯誤代碼 |
|---|---|---|---|---|
| 請求頻率限制 | 每分鐘 120 次請求 | 每個 HTTP 請求 | 每分鐘開始時 | rate_limited |
| 每日資料配額 | 每天 75,000 筆記錄 | 回應中的記錄 | UTC 00:00(台北時間 08:00) | quota_exceeded |
請求頻率限制
請求頻率限制是指一個金鑰在一分鐘內可發送的最大請求數:120 次。超出後,API 會回傳 429,
錯誤代碼為 rate_limited。每個請求都會計入,與回傳多少筆記錄無關,包括對 /categories 和
/brands 的請求,以及因配額用盡而被拒絕的請求。
計數器依時鐘的整分鐘計算:在每分鐘的第 0 秒歸零,而不是從第一次請求起滿 60 秒後歸零。
收到 429 rate_limited 時,請等待 Retry-After 給出的秒數,然後重試同一請求。
每日資料配額
每日資料配額是指一個金鑰每天可透過 API 取得的最大記錄數:75,000 筆。配額用盡後,API 會回傳
429,錯誤代碼為 quota_exceeded。計算的不是請求次數,而是回應中的記錄數:page_size=500
的請求最多消耗 500 筆,page_size=10 的請求最多消耗 10 筆。
| 端點 | 計為一筆記錄的內容 |
|---|---|
GET /products | 回應中的每個商品 |
GET /products/{id} | 該商品(1 筆) |
GET /products/{id}/price-history | 每個價格歷史資料點 |
GET /sellers | 回應中的每個賣家 |
GET /me/scrapes/{id}/products | 回應中的每個商品(pending 列不計入) |
GET /categories、GET /brands、GET /me/scrapes、GET /me/scrapes/{id} | 不消耗配額 |
配額在請求執行前檢查:只要配額尚未用盡,請求就會完整執行,因此當天的最後一個請求可能會略微超出配額。
配額限制的是每天的取得量,而不是整個資料集:於 UTC 00:00(台北時間 08:00)重置後,您可以從上次 停下的地方繼續。每個金鑰當天的使用情況可在帳戶的 API 金鑰頁面查看。
收到 429 quota_exceeded 時,請暫停匯出直到配額重置:在此之前 API 會持續回傳同樣的回應。
該回應不包含 Retry-After 標頭,需要等待多久請參閱 X-Quota-Reset。
回應標頭
除 401 和 403 外,每個回應(包括成功回應)都帶有反映兩項限制目前狀態的標頭。
您可以據此控制請求節奏,而不必等到收到 429。
| 標頭 | 含義 |
|---|---|
X-RateLimit-Limit | 每分鐘允許的請求數 |
X-RateLimit-Remaining | 目前這一分鐘內剩餘的請求數 |
X-RateLimit-Reset | 距下一分鐘開始還有多少秒 |
Retry-After | 出現在 429 rate_limited 和 503 回應中:需等待多少秒後重試 |
X-Quota-Limit | 該金鑰的每日配額 |
X-Quota-Used | 今天已取得的記錄數(含本次回應) |
X-Quota-Remaining | 當天剩餘的記錄數 |
X-Quota-Reset | 距配額重置還有多少秒 |
/categories 和 /brands 不消耗配額,因此只回傳 X-RateLimit-* 標頭。
連線問題
如果連線在伺服器回應之前就被中斷,您會看到以下錯誤之一:
- cURL:
curl: (35) ... SSL_ERROR_SYSCALL或Connection reset by peer; - JavaScript(Node.js,
fetch):TypeError: fetch failed,error.cause中為ECONNRESET或Client network socket disconnected before secure TLS connection was established; - Python(
requests):SSLError ... EOF occurred in violation of protocol。
這表示連線在通往伺服器的途中被中斷,請求並未到達 API。這與金鑰、訂閱和限制無關:如果它們有問題,伺服器一律會回傳 HTTP 狀態碼和 JSON 回應主體(參見錯誤格式)。如果您收到了 JSON,代表連線本身沒有問題。
最常中斷連線的是 VPN、代理伺服器、會檢查 HTTPS 的防毒軟體或企業網路過濾器。請檢查以下幾點:
-
完全結束 VPN 應用程式(是結束程式,而不只是中斷連線),然後重試請求。VPN 設定中依網域設定的例外規則可能對腳本和 curl 無效,此時它們的流量仍會經過 VPN。
-
檢查流量經過哪個網路介面。 先用
nslookup data.marketninja.ru查出伺服器的 IP 位址(取輸出末尾的位址,而不是開頭幾行中 DNS 伺服器的位址),然後執行:- macOS:
route -n get <IP>— 如果interface:一行顯示utun…,代表請求經過了 VPN; - Linux:
ip route get <IP>— 如果dev後面是tun…或wg…,代表請求經過了 VPN; - Windows(PowerShell):
Find-NetRoute -RemoteIPAddress <IP>— 如果請求經過 VPN,InterfaceAlias欄位會顯示 VPN 介面卡的名稱。
如果需要一直開著 VPN,請將該 IP 位址加入其例外規則。該位址可能會變動,因此如果問題再次出現,請重新檢查。
- macOS:
-
檢查終端機中的代理環境變數(macOS/Linux):
env | grep -i proxy。 -
在 Windows 上檢查憑證撤銷錯誤。 系統內建的
curl.exe會檢查憑證是否已被撤銷,如果檢查失敗就會拒絕連線(錯誤CRYPT_E_NO_REVOCATION_CHECK或CRYPT_E_REVOCATION_OFFLINE)。--ssl-no-revoke參數會關閉這項檢查,可用來確認問題是否出在這裡。請僅將其用於診斷。 -
確認您的用戶端支援 TLS 1.2 或更新版本。 API 不接受更舊的協定版本。
如果以上方法都無效,請透過 Telegram 聯絡我們:@getmarketninja,並提供完整的 curl -v 輸出(請遮蓋金鑰)、嘗試的大約時間,以及您連線所用的 IP 位址(如果開著 VPN,則為 VPN 伺服器的公用位址)。
值得留意的幾點
- 快取已解析出的
id。 它不會改變——如果您需要定期查詢同一項商品(例如某個品牌 每天核對自己的商品目錄),請在第一次查找後儲存該id,之後直接依id呼叫, 而不是重複呼叫GET /products——同時節省請求次數與配額。 unverified/flagged資料預設不會被隱藏。trust_status欄位一律存在於每筆 商品回應中——是否信任一筆尚未獲得佐證的記錄,由您自行判斷,而非由 API 替您決定。- 分頁不需要事先得知總頁數——大多數列表端點都會回傳精確的
meta.total,讀取它並持續 翻頁,直到取得所需數量為止。GET /products是唯一的例外:它回傳的是meta.has_more(參見批次匯出)。
最後更新於