Market NinjaMarket Ninja

API 概覽

如何取得金鑰、進行身分驗證並開始使用 Market Ninja API——先查找後取得的模式、限制說明和錯誤格式。

Market Ninja API 提供對同一個群眾外包資料集的唯讀程式化存取,也就是您在擴充功能介面中看到的資料: 來自 Wildberries、Ozon、Yandex Market 和 Lamoda 的商品、價格(目前與歷史)、賣家和類目。

API 不會自行採集資料,也無法依需求觸發擷取——它只提供對資料集中既有資料的唯讀存取。新商品只能透過 Market Ninja 瀏覽器擴充功能加入資料集:如果資料集中還沒有您需要的商品,請先用擴充功能採集它,之後才能透過 API 取得。
API 僅供伺服器端整合使用(server-to-server)。金鑰是長期有效的憑證,絕不能出現在瀏覽器中執行的程式碼裡(與 Stripe 金鑰的要求相同)。

取得金鑰

金鑰於擴充功能設定的 API 金鑰 區塊簽發,僅 Premium 方案可用。完整的金鑰值 (mn_live_...)只會在建立時顯示一次——請立即儲存,之後無法復原(只能撤銷後重新產生)。

身分驗證

每個請求都必須包含以下標頭:

Authorization: Bearer mn_live_your_key
curl -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意義
400validation_error查詢參數無效。
401invalid_api_key金鑰缺失、格式錯誤、未知、已撤銷或已過期。
403subscription_lapsed金鑰有效,但 Premium 訂閱目前未生效。
404not_found找不到該 id 對應的商品。
429rate_limited超出每分鐘請求頻率限制——請在 Retry-After 秒後重試。
429quota_exceeded每日資料配額已用盡——於 UTC 00:00 重置。
500internal_error伺服器內部錯誤,可稍後重試。
503query_timeout查詢耗時過長。請等待 Retry-After 秒後重試;如果仍然失敗,請縮小查詢範圍(例如使用更長的 name_contains 關鍵字或增加篩選條件)。
503service_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。

如果每天 75,000 筆記錄無法滿足您的需求,請透過 Telegram 聯絡我們:@getmarketninja,我們可以為您的金鑰商議限額。

回應標頭

除 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 的防毒軟體或企業網路過濾器。請檢查以下幾點:

  1. 完全結束 VPN 應用程式(是結束程式,而不只是中斷連線),然後重試請求。VPN 設定中依網域設定的例外規則可能對腳本和 curl 無效,此時它們的流量仍會經過 VPN。

  2. 檢查流量經過哪個網路介面。 先用 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 位址加入其例外規則。該位址可能會變動,因此如果問題再次出現,請重新檢查。

  3. 檢查終端機中的代理環境變數(macOS/Linux):env | grep -i proxy。

  4. 在 Windows 上檢查憑證撤銷錯誤。 系統內建的 curl.exe 會檢查憑證是否已被撤銷,如果檢查失敗就會拒絕連線(錯誤 CRYPT_E_NO_REVOCATION_CHECK 或 CRYPT_E_REVOCATION_OFFLINE)。--ssl-no-revoke 參數會關閉這項檢查,可用來確認問題是否出在這裡。請僅將其用於診斷。

  5. 確認您的用戶端支援 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 (參見批次匯出)。

最後更新於

本頁目錄