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 不接受更旧的协议版本。
如果以上方法都无效,请通过微信联系我们(微信号:getmarketninja),并提供完整的 curl -v 输出(请隐去密钥)、尝试的大致时间,以及您发起连接所用的 IP 地址(如果开着 VPN,则为 VPN 服务器的公网地址)。
值得注意的几点
- 缓存已解析出的
id。 它不会改变——如果您需要定期查询同一个商品(例如某个品牌 每天核对自己的商品目录),请在首次查找后保存该id,之后直接按id调用, 而不是重复调用GET /products——既能节省请求次数,也能节省配额。 unverified/flagged数据默认不会被隐藏。trust_status字段始终存在于每条 商品响应中——是否信任一条尚未得到印证的记录,由您自行判断,而非由 API 替您决定。- 分页无需提前知道总页数——大多数列表端点都会返回精确的
meta.total,读取它并持续 翻页,直到获取到所需数量为止。GET /products是唯一的例外:它返回的是meta.has_more(参见批量导出)。
最后更新于