Обзор API
Как получить ключ, авторизоваться и начать работу с API Market Ninja — модель поиск → получение, лимиты, формат ошибок.
API Market Ninja даёт программный доступ на чтение к тому же краудсорсинговому датасету, который вы видите в интерфейсе расширения: товары, цены (текущие и исторические), продавцы и категории с Wildberries, Ozon, Яндекс Маркета и Lamoda.
Получение ключа
Ключ выпускается в настройках расширения — раздел API-ключи, доступен на тарифе
Premium. Полное значение ключа (mn_live_...) показывается только один раз, в
момент создания — сохраните его сразу, восстановить позже нельзя (только отозвать и
выпустить новый).
Авторизация
Каждый запрос должен содержать заголовок:
Authorization: Bearer mn_live_ваш_ключcurl -H "Authorization: Bearer mn_live_..." \
"https://data.marketninja.ru/v1/products?page_size=3"Главная модель использования: «найти → получить»
Никто извне не знает внутренний id товара в нашей базе — он никому не известен
заранее. Вместо этого вы всегда начинаете с того, что у вас уже есть:
Найдите товар через GET /products, передав то, что у вас есть: ссылку на товар
(url), артикул маркетплейса (external_id + marketplace) или ваш собственный
внутренний артикул (seller_code).
Получите id из поля data[].id в ответе — это наш внутренний идентификатор.
При необходимости обратитесь к товару напрямую по id (GET /products/{id}) или к
истории его цен (GET /products/{id}/price-history) — но учтите, что текущая цена уже
есть в ответе на шаге 1, отдельный запрос нужен только для анализа динамики.
Подробные сценарии с примерами — в разделах Поиск товаров, История цен, Продавцы, Категории, Бренды, Массовая выгрузка, Сессии парсинга (получение того, что вы только что спарсили через расширение) и Вебхуки (уведомление о завершении сессии вместо опроса). Полное описание параметров и ответов каждого эндпоинта — в разделе Справочник.
Формат ошибок
Любая ошибка возвращается в едином виде:
{ "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 | Исчерпана дневная квота на объём данных — сбрасывается в 00:00 UTC. |
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 записей в сутки | Записи в ответах | В 00:00 UTC (03:00 МСК) | quota_exceeded |
Лимит запросов
Лимит запросов — это максимальное число запросов, которое ключ может отправить за одну минуту:
120. При превышении API отвечает 429 с кодом rate_limited. Считается каждый запрос,
независимо от того, сколько записей он вернул, включая запросы к /categories и /brands и
запросы, отклонённые из-за исчерпанной квоты.
Счётчик привязан к календарной минуте: он обнуляется в :00 секунд каждой минуты, а не через 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} | Квоту не расходуют |
Квота проверяется перед запросом: если она ещё не исчерпана, запрос выполняется полностью, поэтому последний запрос дня может немного превысить её.
Квота ограничивает объём за сутки, а не весь датасет: после сброса в 00:00 UTC (03: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.
-
Проверьте, через какой сетевой интерфейс идёт трафик. Узнайте IP-адрес сервера командой
nslookup data.marketninja.ru(нужен адрес в конце вывода, а не адрес DNS-сервера в первых строках), затем выполните:- macOS:
route -n get <IP>— если в строкеinterface:указанutun…, запросы идут через VPN; - Linux:
ip route get <IP>— если послеdevуказанtun…илиwg…, запросы идут через VPN; - Windows (PowerShell):
Find-NetRoute -RemoteIPAddress <IP>— в поле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после первого поиска и в следующий раз обращайтесь сразу по нему, не повторяяGET /products— это экономит и запросы, и квоту. unverified/flaggedданные не скрываются по умолчанию. Полеtrust_statusвсегда присутствует в ответе — решение, доверять ли ещё не подтверждённой записи, остаётся за вами.- Постраничная разбивка не требует явного знания общего числа страниц — у большинства
списочных эндпоинтов есть точный
meta.total; ориентируйтесь на него и продолжайте, пока не соберёте нужное количество записей. Исключение —GET /products: он возвращаетmeta.has_moreвместо этого (см. Массовую выгрузку).
Обновлено