Расширенная аналитика Ozon API

12 POST-методов для исследования товаров и поискового спроса. Создайте ключ именно для аналитики Ozon. У направления отдельные тарифы и квота; ключ обычного Ozon не подходит.

Базовый URL: https://bhapi.ru/analytics/ozon/api/v1. Все методы принимают JSON object, Content-Type: application/json и X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN. Токен в query запрещён. Каждый успешный проверенный ответ, включая пустую выборку, расходует одну единицу квоты BHAPI.

Примеры ниже синтетические и показывают формат, а не фактические товары, цены или подтверждённые результаты. Замените SKU, бренд, категорию и ключ своими значениями. Пропущенные необязательные поля используют штатные значения по умолчанию, неизвестные значения ответа могут быть null.

Поиск товаров

Находит товары по фразе или списку SKU и возвращает их базовые сведения.

Когда применять: Используйте для первичного отбора товаров и получения SKU, которые затем можно изучить через карточку или дневную динамику.

• Выбор товаров: Укажите ровно одно поле: keyword или product_ids. Список содержит 1–100 уникальных SKU.
• Результат: Возвращаются базовые сведения о товаре, без цен и продаж.
• Пагинация: Параметры page и page_size не принимаются; переход к следующей странице не предусмотрен контрактом.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "keyword": "термокружка"
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/products/search" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"термокружка"}'

Ответ

Envelope: OzonAnalyticsSearchResponse. Поля data и все вложенные типы: OzonAnalyticsSearchResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "product_id": "123456789",
        "title": "Пример товара"
      }
    ],
    "pagination": {
      "page": null,
      "page_size": null,
      "returned_count": 1,
      "total_count": 1,
      "source_total": 1,
      "source_total_semantics": "matched_count",
      "has_next": null
    }
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Базовая карточка товара

Возвращает карточку одного товара и доступные показатели за выбранный период.

Когда применять: Подходит для изучения товара после поиска: проверьте сведения о бренде, продавце и доступные показатели перед сравнением с другими SKU.

• Выбор товара: Укажите ровно одно поле: product_id или product_url.
• Период: Необязательные start_date и end_date задают запрошенные границы. include_fbs при отсутствии не превращается в false.
• Цена: Цена базовой карточки требует независимой сверки даже при currency=RUB и не гарантирует текущую цену сайта.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "product_id": "123456789"
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/products/detail" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"123456789"}'

Ответ

Envelope: OzonAnalyticsDetailResponse. Поля data и все вложенные типы: OzonAnalyticsProductDetailResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "product": {
      "product_id": "123456789",
      "title": "Пример товара",
      "price": "1299.00",
      "currency": "RUB",
      "sales_units": 12,
      "sales_revenue": "15588.00"
    }
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified",
      "current_price_accuracy_unverified"
    ]
  }
}

Расширенная карточка товара

Объединяет расширенную карточку товара, агрегаты выбранного окна и доступные исторические ряды.

Когда применять: Используйте для углублённого анализа выбранного SKU: изучите показатели одного окна, дневную динамику и историю позиций в категориях, если эти данные доступны.

• Выбор товара: Укажите ровно одно поле: product_id или product_url.
• Окно анализа: period_days принимает 7, 30, 60, 90, 180 или 365; по умолчанию 30. Окно past_N_days отличается от календарного месяца.
• Состав результата: summary содержит агрегаты окна. sales_trend и category_ranks могут быть null.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "product_id": "123456789",
  "period_days": 30
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/products/expanded-detail" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"123456789","period_days":30}'

Ответ

Envelope: OzonAnalyticsExpandedDetailResponse. Поля data и все вложенные типы: OzonAnalyticsExpandedProductResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "product": {
      "product_id": "123456789",
      "title": "Пример товара",
      "price": "1299.00",
      "currency": "RUB",
      "sales_units": 12,
      "sales_revenue": "15588.00"
    },
    "summary": {
      "sales_units": 12,
      "sales_revenue": "15588.00",
      "sales_per_day": null,
      "stock_units": null
    },
    "sales_trend": null,
    "category_ranks": null
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": {
      "start": null,
      "end": null,
      "label": "past_30_days"
    },
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Отчёт по товарам

Формирует выборку товаров по сочетанию характеристик и аналитических фильтров.

Когда применять: Подходит для отбора конкурентов или товаров по вашим критериям: задайте диапазоны показателей, бренд, продавца и другие условия, затем сравните результаты в одном периоде.

• Отбор товаров: Все фильтры необязательны; product_ids содержит 1–10 SKU. fulfillment — массив до пяти значений; listing_months принимает 1/3/6/12/24.
• Бренд и метки: brand.mode=include или exclude требует непустые names; unbranded — пустой массив. labels: 0 — новый, 1 — оригинальный, 2 — bestseller. Эти метки не подтверждают права на товар.
• Диапазоны: review_rating ограничен 0–5. Единицы и ограничения остальных показателей смотрите в таблице параметров.
• Период: search_date выбирает предыдущий полный месяц: 2026-04-01 → март. Без даты используется rolling30.
• Сортировка: orders.field: sales_units, sales_revenue, price, rating, review_count, sales_growth_percent.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "product_ids": [
    "123456789"
  ],
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/products/report" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_ids":["123456789"],"page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsReportResponse. Поля data и все вложенные типы: OzonAnalyticsProductListResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "product_id": "123456789",
        "title": "Пример товара",
        "price": "1299.00",
        "currency": "RUB",
        "sales_units": 12,
        "sales_revenue": "15588.00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "matched_count",
      "has_next": null
    }
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Дневная динамика товара

Возвращает дневные точки продаж, цен и доступных остатков одного SKU.

Когда применять: Используйте, чтобы изучить изменение показателей по дням и отделить дни с данными от пропусков. Это полезно при анализе колебаний продаж или изменения цены.

• Выбор товара: Укажите ровно одно поле: product_id или product_url. include_fbs и include_search_stats необязательны.
• Дневной ряд: Точки отсортированы по дате; пропуски не интерполируются. has_data=false означает отсутствие данных, а не нулевые продажи.
• Остатки: stock_units описывает FBO и не гарантирует полный складской остаток.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "product_id": "123456789",
  "start_date": "2026-09-01",
  "end_date": "2026-09-03"
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/products/trend" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"123456789","start_date":"2026-09-01","end_date":"2026-09-03"}'

Ответ

Envelope: OzonAnalyticsTrendResponse. Поля data и все вложенные типы: OzonAnalyticsProductTrendResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "product_id": "123456789",
    "points": [
      {
        "date": "2026-09-01",
        "has_data": false,
        "sales_units": null,
        "stock_units": null
      }
    ]
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": {
      "start": "2026-09-01",
      "end": "2026-09-03",
      "label": null
    },
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Товары бренда

Собирает товары выбранного бренда с доступными аналитическими показателями.

Когда применять: Подходит для исследования ассортимента бренда: отсортируйте товары по нужной метрике и отберите позиции для дальнейшего сравнения.

• Бренд: brand_name — название бренда, а не ID.
• Настройки выборки: Действуют общие правила drill-down: page до 100000, page_size до 100, парная сортировка, валюта и AND-фильтры.
• Охват: Полнота рынка не гарантируется.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "brand_name": "Пример",
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/brands/products" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"brand_name":"Пример","page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsBrandProductsResponse. Поля data и все вложенные типы: OzonAnalyticsProductListResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "product_id": "123456789",
        "title": "Пример товара",
        "price": "1299.00",
        "currency": "RUB",
        "sales_units": 12,
        "sales_revenue": "15588.00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "unknown",
      "has_next": null
    }
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified",
      "total_semantics_unknown"
    ]
  }
}

Товары по пути категории

Возвращает подборку товаров из выбранной ветки каталога, заданной полным путём категории.

Когда применять: Используйте для исследования конкурентов внутри конкретной категории, когда вам известен её русский путь в каталоге.

• Категория: category_path — полный русский путь с разделителями /. Это отдельный селектор; category_id и niche_id здесь не используются.
• Настройки выборки: Действуют общие правила drill-down: пагинация, парная сортировка, валюта и AND-фильтры.
• Количество результатов: total источника может иметь неизвестную семантику; не трактуйте его как полный размер категории.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "category_path": "Дом / Кухня",
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/categories/products" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category_path":"Дом / Кухня","page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsCategoryProductsResponse. Поля data и все вложенные типы: OzonAnalyticsProductListResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "product_id": "123456789",
        "title": "Пример товара",
        "price": "1299.00",
        "currency": "RUB",
        "sales_units": 12,
        "sales_revenue": "15588.00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "unknown",
      "has_next": null
    }
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified",
      "total_semantics_unknown"
    ]
  }
}

Аналитический поиск категории

Возвращает товары и сводные показатели категории, выбранной по её ID.

Когда применять: Подходит для изучения категории за выбранный месяц: анализируйте её агрегаты отдельно от товаров текущей страницы.

• Категория и период: category_id — иерархический ID с подчёркиваниями. month — действительный месяц YYYY-MM.
• Схема доставки: fulfillment — одна строка OZON/FBO/FBS/RFBS/FBP, не массив.
• Сортировка: orders.field: sales_units, price, sales_revenue, rating.
• Агрегаты и страницы: category_summary описывает всю категорию, а не текущую страницу. source_total_semantics=page_count означает число страниц, не товаров.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "category_id": "100_200",
  "month": "2026-09",
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/categories/search" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"100_200","month":"2026-09","page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsCategorySearchResponse. Поля data и все вложенные типы: OzonAnalyticsCategorySearchResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "product_id": "123456789",
        "title": "Пример товара",
        "price": "1299.00",
        "currency": "RUB",
        "sales_units": 12,
        "sales_revenue": "15588.00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "page_count",
      "has_next": null
    },
    "category_info": null,
    "category_summary": {}
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": {
      "start": null,
      "end": null,
      "label": "2026-09"
    },
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Товары продавца

Возвращает ассортимент конкретного продавца с доступными показателями товаров.

Когда применять: Используйте для исследования магазина или продавца-конкурента: найдите его SKU и отберите позиции по аналитическим фильтрам.

• Продавец: seller_id — отдельная строгая строка; отрицательные значения допустимы. Этот параметр отличается от seller_names в отчёте по товарам.
• Настройки выборки: Действуют общие правила drill-down. Рейтинг и позиция зависят от измерения и периода.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "seller_id": "-12345",
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/sellers/products" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"seller_id":"-12345","page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsSellerProductsResponse. Поля data и все вложенные типы: OzonAnalyticsProductListResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "product_id": "123456789",
        "title": "Пример товара",
        "price": "1299.00",
        "currency": "RUB",
        "sales_units": 12,
        "sales_revenue": "15588.00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "unknown",
      "has_next": null
    }
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified",
      "total_semantics_unknown"
    ]
  }
}

Обратный поиск фраз по SKU

Находит поисковые фразы, связанные с указанными SKU, и доступные показатели этих фраз.

Когда применять: Подходит для исследования того, как товар представлен в поиске, и для подготовки исходного списка фраз к дальнейшему анализу спроса.

• Товары: product_ids содержит 1–20 уникальных SKU. Связанные products в ответе не обязаны входить в исходный список.
• Варианты и каналы: exclude_variants — обязательный boolean без значения по умолчанию. channels принимает organic/ad, один или два элемента.
• Период: month — действительный месяц YYYY-MM.
• Показатели: exposure/conversion в dimension — отношения 0–1. При нескольких SKU связь dimension с конкретным входным товаром может быть неизвестна.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "product_ids": [
    "123456789"
  ],
  "exclude_variants": true,
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/keywords/back-search" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_ids":["123456789"],"exclude_variants":true,"page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsKeywordBackSearchResponse. Поля data и все вложенные типы: OzonAnalyticsKeywordListResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "platform": 0,
        "keyword": "термокружка",
        "average_price": null,
        "dimension": null
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "matched_count",
      "has_next": null
    },
    "excluded_platform_count": 0
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Подбор поисковых фраз

Расширяет исходную поисковую фразу и возвращает связанные фразы с доступными показателями.

Когда применять: Используйте для расширения семантики: соберите кандидатов для исследования спроса или подготовки описания товара и отберите их по доступным метрикам.

• Исходная фраза: keyword — обязательная непустая фраза.
• Отбор и сортировка: Действуют общие правила keyword-фильтров и сортировки. Дополнительно доступны price и relevancy.
• Релевантность: Шкала relevancy не установлена и не пересчитывается.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "keyword": "термокружка",
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/keywords/mining" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"термокружка","page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsKeywordMiningResponse. Поля data и все вложенные типы: OzonAnalyticsKeywordListResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "platform": 0,
        "keyword": "термокружка",
        "average_price": null,
        "dimension": null
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "matched_count",
      "has_next": null
    },
    "excluded_platform_count": 0
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Исследование поискового рынка

Возвращает рыночные показатели поисковых фраз с возможностью фильтрации по фразам и категориям.

Когда применять: Подходит для сравнения поискового спроса и конкуренции по выбранным фразам, чтобы определить приоритеты дальнейшего исследования.

• Отбор: keywords, category_ids и search_date необязательны. Действуют общие правила сортировки поисковых фраз.
• Период: search_date выбирает предыдущий полный месяц; без даты используется rolling30.
• Единицы: У weight и volume неизвестные единицы. Они не наследуют граммы и литры одноимённых фильтров отчёта по товарам.

Формат и ключ: JSON; Content-Type: application/json и X-API-Token.

Учёт запросов: один проверенный успешный ответ — одна единица квоты. Ошибки успешную квоту не расходуют; подробнее в разделе ошибок.

Параметры запроса

{
  "keywords": [
    "термокружка"
  ],
  "page": 1,
  "page_size": 1
}

curl -X POST "https://bhapi.ru/analytics/ozon/api/v1/keywords/market-search" \
  -H "X-API-Token: YOUR_OZON_ANALYTICS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["термокружка"],"page":1,"page_size":1}'

Ответ

Envelope: OzonAnalyticsKeywordMarketSearchResponse. Поля data и все вложенные типы: OzonAnalyticsKeywordListResult. Период, свежесть и предупреждения: meta. Необязательные значения не восстанавливаются из нулей или соседних методов.

{
  "status": "success",
  "data": {
    "items": [
      {
        "platform": 0,
        "keyword": "термокружка",
        "average_price": null,
        "dimension": null
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 1,
      "returned_count": 1,
      "total_count": null,
      "source_total": null,
      "source_total_semantics": "matched_count",
      "has_next": null
    },
    "excluded_platform_count": 0
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001",
    "retrieved_at": "2026-10-10T12:00:01Z",
    "observed_at": "2026-10-10T12:00:00Z",
    "requested_period": null,
    "resolved_period": null,
    "snapshot_month": null,
    "freshness": "historical_or_periodic",
    "warnings": [
      "periodic_data_not_realtime",
      "coverage_and_estimation_method_unverified"
    ]
  }
}

Общие правила запросов

Формат и типы

• Неизвестные поля запрещены на всех уровнях.
• Integer и boolean строгие: строки и bool вместо числа не принимаются.
• Текст — непустая строка 1–1000 символов, состоящая не только из пробелов.
• JSON ограничен 1 MiB; дублирующиеся ключи, NaN/Infinity и некорректные типы отвергаются.

Идентификаторы товаров

• SKU — строка из 1–19 ASCII цифр, значение от 1 до 9223372036854775807.
• Ведущие нули учитываются при поиске дублей: "01" и "1" — один товар.
• Seller ID может быть отрицательным.
• Category ID — цифры и иерархические разделители _, до 1000 символов.

Ссылка на товар

• Identity selector: ровно один непустой product_id или product_url.
• URL до 4096 символов: HTTPS, ozon.ru или www.ozon.ru, без порта, userinfo, пробелов, управляющих символов и обратной косой черты.
• Путь /product/<sku>/ либо /product/<slug>-<sku>/; конечный slash необязателен.
• Query/fragment не участвуют в извлечении SKU.
• BHAPI не загружает URL товара.

Даты и период

• Даты — действительные YYYY-MM-DD, месяцы — YYYY-MM.
• Если обе границы заданы, start_date ≤ end_date; одна граница допустима.
• Параметры не меняются из-за T-1 ограничения свежести источника.

Числовые диапазоны и фильтры

• NumericRange: хотя бы одна непустая min/max, min ≤ max.
• NumericFilter.value/value2 и границы принимают только конечные JSON numbers, без строк и bool; не более 64 символов десятичного представления, абсолютный adjusted exponent ≤63.
• BETWEEN требует value2 ≥ value; прочие операторы запрещают value2.
• Все условия filters объединены AND, до 20 элементов.

Сортировка и валюта выборки

• Drill-down (бренд/путь категории/продавец): sort_field и sort_direction задаются вместе.
• Поля сортировки совпадают с NumericFilter.field.
• Валюта RUB/USD/EUR/CNY; currency_rate — целое 1–1000000 только для не-RUB валюты.
• BHAPI не вычисляет курс.

Пагинация и порядок выдачи

• Аналитическая пагинация report/category-search/keywords: page 1–100000 (default 1), page_size 1–20 (default 20).
• Drill-down page_size 1–100 (default 100).
• До 5 orders, direction asc/desc (default desc).
• Keyword orders.field: search_volume, search_growth_percent, word_count, average_price, product_count, sellers_count, market_space, relevance, title_density, add_to_cart_count.
• Разрешённые поля Report и Category Search указаны у методов.

Поисковые фразы

• Keyword match_type: exact/fuzzy/null.
• include_keywords/exclude_keywords — до 1000 непустых строк.
• Фильтры не назначают неизвестным шкалам искусственных границ или единиц; значения конкретного метода описаны в таблице.

OzonAnalyticsNumericRange

OzonAnalyticsNumericFilter

OzonAnalyticsBrandFilter

OzonAnalyticsOrder

Полная структура ответов

status="success", data и meta присутствуют явно. Поля ниже образуют полный справочник вложенных типов. В таблицах «необязательно; null допустим» означает неизвестное или отсутствующее значение; это не ноль. Все денежные Decimal поля передаются строками с сохранением точности.

OzonAnalyticsCategoryInfo

OzonAnalyticsCategoryNode

OzonAnalyticsCategoryRank

OzonAnalyticsCategorySearchResult

OzonAnalyticsCategorySummary

OzonAnalyticsExpandedProductResult

OzonAnalyticsKeywordCategoryInfo

OzonAnalyticsKeywordDimension

OzonAnalyticsKeywordListResult

OzonAnalyticsKeywordProduct

OzonAnalyticsKeywordRow

OzonAnalyticsPublicMetadata

OzonAnalyticsPagination

OzonAnalyticsPeriod

OzonAnalyticsProductCard

OzonAnalyticsProductDetailResult

OzonAnalyticsProductListResult

OzonAnalyticsProductTrendResult

OzonAnalyticsSearchProduct

OzonAnalyticsSearchResult

OzonAnalyticsSummary

OzonAnalyticsTrendPoint

OzonAnalyticsSearchResponse

OzonAnalyticsDetailResponse

OzonAnalyticsExpandedDetailResponse

OzonAnalyticsReportResponse

OzonAnalyticsTrendResponse

OzonAnalyticsBrandProductsResponse

OzonAnalyticsCategoryProductsResponse

OzonAnalyticsCategorySearchResponse

OzonAnalyticsSellerProductsResponse

OzonAnalyticsKeywordBackSearchResponse

OzonAnalyticsKeywordMiningResponse

OzonAnalyticsKeywordMarketSearchResponse

Периоды, свежесть и смысл показателей

Продажи и денежные показатели

• sales_units — продажи по методике источника, без подтверждения выкупов.
• sales_revenue — выручка; lost_revenue — оценка упущенной выручки, не прибыли.
• null и отсутствие значения не равны нулю. Цена базовой карточки не гарантирует текущую цену сайта даже при currency=RUB.

Окна анализа и свежесть

• Расширенная карточка использует past_N_days. Отчёт и исследование поискового рынка без search_date используют rolling30.
• Указанная дата выбирает предыдущий полный календарный месяц: 2026-04-01 → март. Месячные метки category_ranks сохраняются месяцами.
• T-1 ограничивает свежесть источника; BHAPI самостоятельно не обрезает запрос. Сравнивайте показатели в одинаковых окнах.
• meta.retrieved_at — время получения BHAPI, observed_at — время обработки источником. Это не время обновления базы.
• snapshot_month не является точной датой свежести. resolved_period содержит только подтверждённые границы и не достраивается из запроса.

Пагинация и количество результатов

• pagination.returned_count — длина текущего items; total_count — подтверждённые совпадения либо null.
• source_total_semantics: matched_count — число совпадений, page_count — число страниц, unknown — неизвестная семантика.
• Общее количество нельзя вычислять из размера страницы; has_next не вычисляется из её заполненности. Поиск товаров не принимает page.
• При исключении строк другой площадки excluded_platform_count > 0, total_count=null и предупреждение обязательно.

Единицы и ограничения интерпретации

• category_summary — агрегаты категории. stock_units дневного ряда — остаток FBO; has_data=false означает отсутствие данных дня.
• DRR, gross_margin, conversion, ca, concentration, relevancy и рейтинги имеют разные определения.
• dimension.exposure_ratio и dimension.conversion_ratio — отношения 0–1; ca и concentration — проценты.
• weight/volume отчёта — граммы/литры. У одноимённых фильтров исследования поискового рынка единицы неизвестны.
• При нескольких SKU связь dimension с конкретным SKU не доказана. Полнота рынка и обновление в реальном времени не гарантируются.

Ошибки, частота и квоты

Таблицы и примеры этого раздела описывают ошибки legacy (формат по умолчанию). Чтобы получать единый контракт ошибок, передайте заголовок X-BHAPI-Error-Format: problem-v1. Статусы некоторых ошибок в этом режиме отличаются; успешные ответы не меняются. Общий справочник кодов, форматов и действий клиента →

Ошибка BHAPI имеет форму {"detail":{"code":HTTP_NUMBER,"reason":"...","message":"..."}}. detail.code — целый HTTP-код, detail.reason — машинная причина, detail.message — безопасное русское сообщение. Ошибка доступа/тарифа использует общий контракт BHAPI; сервисная авторизация не превращается в отказ пользовательского ключа.

Для всех методов действует общий ограничитель: не чаще одного запроса в секунду; не более двух активных/ожидающих вызовов, ожидание допуска — до 5 секунд. Отправляйте запросы последовательно. BHAPI не повторяет вызовы автоматически и не выполняет скрытую пагинацию. Каждый повтор — новый вызов.

Локальный отказ и ошибка результата не расходуют успешную квоту BHAPI. Проверенный пустой успех расходует одну единицу. Отмена до решения об успехе не расходует успешную квоту; после проверки результата и фиксации успешного исхода потеря соединения не отменяет списание. При сбое БД восстановление слота требует подтверждённого завершения обработки; не считайте доставку ответа единственной границей учёта.

Клиентский timeout рекомендуем 120 секунд. После timeout внешний исход может быть неизвестен; не запускайте автоматический повтор без проверки. Тарифы направления задаются отдельно; бесплатный доступ и лимиты доступны только при соответствующем активном тарифе.

Python и сценарии исследования

import requests

response = requests.post(
    "https://bhapi.ru/analytics/ozon/api/v1/products/expanded-detail",
    headers={"X-API-Token": "YOUR_OZON_ANALYTICS_API_TOKEN"},
    json={"product_id": "123456789", "period_days": 30},
    timeout=120,
)
response.raise_for_status()
result = response.json()
print(result["data"]["summary"])
print(result["meta"]["resolved_period"])
# Денежные строки преобразуйте в Decimal, если нужен точный расчёт.
# Новые запросы выполняйте последовательно, с интервалом не менее секунды.

• Search → Detail → Trend: найдите SKU, получите карточку и сравните дневные точки одного периода; Search не содержит продаж.
• Brand / Category Products / Seller: выберите измерение, пару полей сортировки и AND-фильтры. Получайте страницы отдельными запросами, сохраняя семантику total.
• Back Search → Mining → Market Search: исследуйте фразы товара, расширьте список и сравните спрос. Не переносите неизвестные шкалы и связь dimension между методами.

Возможности аналитики Ozon · Общая справка BHAPI