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 条记录无法满足您的需求,请通过微信联系我们(微信号: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 不接受更旧的协议版本。

如果以上方法都无效,请通过微信联系我们(微信号:getmarketninja),并提供完整的 curl -v 输出(请隐去密钥)、尝试的大致时间,以及您发起连接所用的 IP 地址(如果开着 VPN,则为 VPN 服务器的公网地址)。

值得注意的几点

  • 缓存已解析出的 id。 它不会改变——如果您需要定期查询同一个商品(例如某个品牌 每天核对自己的商品目录),请在首次查找后保存该 id,之后直接按 id 调用, 而不是重复调用 GET /products——既能节省请求次数,也能节省配额。
  • unverified/flagged 数据默认不会被隐藏。 trust_status 字段始终存在于每条 商品响应中——是否信任一条尚未得到印证的记录,由您自行判断,而非由 API 替您决定。
  • 分页无需提前知道总页数——大多数列表端点都会返回精确的 meta.total,读取它并持续 翻页,直到获取到所需数量为止。GET /products 是唯一的例外:它返回的是 meta.has_more (参见批量导出)。

最后更新于

本页目录