@qzsy/mm-ozon-sdk

v0.1.7

Published

8 days ago

mm Ozon 数据平台 SDK

0High
0Medium
0Low

huanghuabin06

liuhuapiaoyuan1

curleaf

mm Ozon SDK

技术栈

Runtime: Bun
Language: TypeScript

安装

npm install @qzsyzn/mm-ozon-sdk
# 或
bun add @qzsyzn/mm-ozon-sdk

快速开始

import { MmSdk } from "@qzsyzn/mm-ozon-sdk";

const sdk = new MmSdk({
  token: "your-bearer-token",
  cookies: "your-browser-session-cookie",
  controlT: "1782823758078_d1a15691d4.6a9",
});

// 或从 .env 加载
const sdk = MmSdk.fromEnv();

// 大盘概览
const overview = await sdk.bigDisc.generalView();

// 热门关键词
const keywords = await sdk.keyword.hot({ dateType: "MONTH" });

// 搜索飙升词 + 关键词联想
const soaringKeywords = await sdk.keyword.soar({ dateType: "MONTH" });
const keyword = await sdk.keyword.searchKeyword({ link: "工具" });

// 中国馆热销新品
const products = await sdk.itemRanking.cnZone({
  hotSale: 1,
  bestAndNew: 1,
  minRatingStar: 4,
  minCreateDt: "2026-04-01",
  maxCreateDt: "2026-06-30",
});

// 行业热门类目
const hotCategories = await sdk.industry.hot({
  catId: 17027494,
  catLevel: 1,
  currentCatId: "17027494",
  dateType: "SEVEN_DAY",
});

// 类目树（自动解压）
const catTree = await sdk.cat.tree();
console.log(catTree[0].nameCn, catTree[0].children?.length);

API 模块

| 模块 | 说明 | 端点数 | |------|------|--------| | bigDisc | 大盘数据（概览、趋势、市场分布、行业视图） | 5 | | industry | 行业分析（热销 / 蓝海 / 潜力 Top） | 3 | | itemRanking | 产品排名（中国馆热销新品、销量/销售额/价格/品牌/类目分析） | 10 | | keyword | 关键词分析（热门 / 蓝海 / 高转化 / 飙升 / 搜索） | 5 | | cat | 类目树数据 | 2 | | filtrate | 筛选模型 | 1 |

API 接口一览

共 26 个端点，通过 sdk.<模块>.<方法>() 调用。

`sdk.bigDisc` — 大盘数据

| 方法 | 说明 | HTTP | 路径 | |------|------|------|------| | generalView() | 大盘概览 | POST | /api/ozon-report-service/v1/bigDisc/generalView | | chartTrend(rangeType?) | 大盘趋势图表 | POST | /api/ozon-report-service/v1/bigDisc/chartTrend | | market(params?) | 大盘市场分布 | POST | /api/ozon-report-service/v1/bigDisc/market | | industryViewV2(params) | 行业概览 V2 | POST | /api/ozon-report-service/v1/bigDisc/industryViewV2 | | industryTrendRange(params) | 行业数据趋势分析 | POST | /api/ozon-report-service/v1/bigDisc/industryTrendRange |

参数说明

chartTrend(rangeType?) — rangeType: "DAY" | "WEEK" | "MONTH"，默认 "DAY"
market(params?) — catId, dataType（默认 0）, timest
industryViewV2(params) — catId, currentCatId, catLevel（默认 1）, typeId（默认 0）
industryTrendRange(params) — 继承类目参数，另支持 IndustryTrendRangeQuery：

| 参数 | 类型 | 说明 | |------|------|------| | rangeType | "DAY" | "MONTH" | "QUARTERLY_FOR_YEAR" | "YEAR" | null | 趋势粒度 | | dayRange | { startTimest, endTimest } | rangeType: "DAY" 时使用，日期格式 YYYY-MM-DD | | monthRange | { startYearMonth, endYearMonth } | rangeType: "MONTH" 时使用，格式 YYYY-MM | | quarterlyRange | { startYearQuarterly, endYearQuarterly } | rangeType: "QUARTERLY_FOR_YEAR" 时使用，格式 YYYY-Qn | | yearRange | { startYear, endYear } | rangeType: "YEAR" 时使用，格式 YYYY |

// 按日趋势（近 30 天）
await sdk.bigDisc.industryTrendRange({
  catId: 17027491,
  rangeType: "DAY",
  dayRange: { startTimest: "2026-05-31", endTimest: "2026-06-29" },
});

// 按月趋势
await sdk.bigDisc.industryTrendRange({
  catId: 17027491,
  rangeType: "MONTH",
  monthRange: { startYearMonth: "2025-06", endYearMonth: "2026-05" },
});

返回类型: GeneralView, TrendDataPoint[], MarketItem[], IndustryViewV2, TrendDataPoint[]

`sdk.industry` — 行业 Top 分析

三个 Top 接口请求参数与高级筛选完全一致，仅路径不同：

| 方法 | 页面 | 说明 | HTTP | 路径 | |------|------|------|------|------| | hot(params) | 热销 Top | /workbench/industry/hot-selling | POST | /api/ozon-report-service/v1/industry/hot | | chance(params) | 蓝海 Top | /workbench/industry/opportunity | POST | /api/ozon-report-service/v1/industry/chance | | high(params) | 潜力 Top | /workbench/industry/high-priced | POST | /api/ozon-report-service/v1/industry/high |

基础参数（IndustryTopQuery，hot / high 使用；chance 使用 IndustryChanceQuery，额外含 topType）

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | catId | number | — | 当前类目 ID（必填） | | catLevel | number | 1 | 类目层级 | | currentCatId | string \| number | — | 类目路径，如 "17027491,17028705" | | typeId | number | 0 | 类型 ID | | dateType | DateType | "SEVEN_DAY" | 日期范围 | | timest | string | — | 统计时间点，格式随 dateType 变化 | | topType | number | 0 | 仅 chance（蓝海 Top）使用 |

timest 格式对照

| dateType | timest 示例 | |------------|---------------| | SEVEN_DAY / TWENTY_EIGHT_DAY | "2026-06-29" | | MONTH | "2026-05" | | QUARTERLY_FOR_YEAR | "2026-Q2" | | YEAR | "2026" |

高级筛选（IndustryTopFilter，三个 Top 均可选）

| 参数 | 说明 | |------|------| | sales / cbSales | 销量筛选（cbSales 可传 "" 表示不筛选） | | minGmv / maxGmv | 月销售额区间 | | minPrice / maxPrice | 价格区间 | | minSaleRatio / maxSaleRatio | 动销率区间（%） | | minSaleSkuNum / maxSaleSkuNum | 动销 SKU 数区间 | | minAvgSales / maxAvgSales | 平均销量区间 | | minBrandGmvRating / maxBrandGmvRating | 品牌 GMV 占比区间（%） | | minRfbsGmvRatio / maxRfbsGmvRatio | RFBS GMV 占比区间（%） | | minAvgCancelRate / maxAvgCancelRate | 平均取消率区间（%） | | minAvgWeight / maxAvgWeight | 平均重量区间 | | minAvgVolume / maxAvgVolume | 平均体积区间 |

const base = {
  catId: 17027494,
  catLevel: 1,
  dateType: "SEVEN_DAY" as const,
};

// 热销 Top
await sdk.industry.hot(base);

// 蓝海 Top + 重量筛选
await sdk.industry.chance({
  ...base,
  minAvgWeight: 2,
  maxAvgWeight: 10000,
  minGmv: 1,
  maxGmv: 10000,
});

// 潜力 Top + 价格 / 品牌占比筛选
await sdk.industry.high({
  ...base,
  minPrice: 1,
  maxPrice: 10000,
  minBrandGmvRating: 1,
  maxBrandGmvRating: 98,
});

返回类型: PaginatedData<IndustryCategoryItem>

IndustryCategoryItem 主要字段：catNameCn、monthSales、monthGmvRmb、monthSalesRating、topGmvRmb、topAvgPriceRmb、brandGmvRating、saleRatio、rfbsGmvRatio、topAvgGmvRmb、topAvgSales 等。

`sdk.itemRanking` — 产品排名（中国馆热销新品）

| 方法 | 说明 | HTTP | 路径 | |------|------|------|------| | timestMaxMin(type?) | 获取可用时间范围 | GET | /api/ozon-report-service/v1/itemRanking/timestMaxMin | | cnZone(params?) | 中国馆热销新品产品列表 | POST | /api/ozon-report-service/v1/itemRanking/cnZone | | cnZoneDataView(params?) | 中国馆热销新品数据概览 | POST | /api/ozon-report-service/v1/itemRanking/cnZoneDataView | | cnZoneMonthSaleAnalyse(params?) | 月销量分析 | POST | /api/ozon-report-service/v1/itemRanking/cnZoneMonthSaleAnalyse | | cnZoneMonthGmvAnalyse(params?) | 月销售额分析 | POST | /api/ozon-report-service/v1/itemRanking/cnZoneMonthGmvAnalyse | | cnZonePriceAnalyse(params?) | 价格区间分析 | POST | /api/ozon-report-service/v1/itemRanking/cnZonePriceAnalyse | | cnZoneStarAnalyse(params?) | 评分分布分析 | POST | /api/ozon-report-service/v1/itemRanking/cnZoneStarAnalyse | | cnZoneRatingNumAnalyse(params?) | 评论数分布分析 | POST | /api/ozon-report-service/v1/itemRanking/cnZoneRatingNumAnalyse | | cnZoneBrandAnalyse(params?) | 品牌分析 | POST | /api/ozon-report-service/v1/itemRanking/cnZoneBrandAnalyse | | cnZoneCategoryAnalyse(params?) | 类目分析 | POST | /api/ozon-report-service/v1/itemRanking/cnZoneCategoryAnalyse |

参数说明

timestMaxMin(type?) — type 默认 14
cnZone(params?) — CnZoneQuery：继承 CnZoneFilter 与类目参数，另支持 hotSale（默认 1）、dateType（默认 "TWENTY_EIGHT_DAY"）、timest、pageNo、pageSize
各 cnZone*Analyse 及 cnZoneDataView — CnZoneAnalyseQuery：catId, catLevel（默认 1）, typeId，以及下表筛选字段

CnZoneFilter 通用筛选（列表与各分析接口均可选）

| 参数 | 类型 | 说明 | |------|------|------| | minSales | number | 最低销量 | | minAvgPrice | number | 最低均价 | | minRatingStar | number | 最低评分 | | bestAndNew | number | 热销新品标识（如 1） | | minCreateDt / maxCreateDt | string | 上架日期区间，YYYY-MM-DD | | brand | string | 品牌关键词 | | blockedBySeller | number \| null | 卖家封禁筛选 | | sources | number \| null | 货源筛选 | | preLaunchDay | number \| null | 预售天数 | | dtType | number \| null | 日期类型 | | isBrand | number \| null | 是否品牌 | | isSuper | number \| string \| null | 超级商品 | | bin | number \| string \| null | BIN 筛选 | | cbSales | number \| string \| null | 跨境销量 | | skuLocation | number \| string \| null | SKU 所在地 | | version | number | 版本号，默认 0 |

// 热销新品列表（带筛选）
await sdk.itemRanking.cnZone({
  catId: 90922564,
  catLevel: 3,
  typeId: 971067131,
  minSales: 300,
  minAvgPrice: 3000,
  minRatingStar: 4,
  bestAndNew: 1,
  minCreateDt: "2026-04-01",
  maxCreateDt: "2026-06-30",
  dateType: "TWENTY_EIGHT_DAY",
  timest: "2026-06-30",
});

// 数据概览 + 价格/评分分析
await sdk.itemRanking.cnZoneDataView({ minSales: 3, bestAndNew: 1 });
await sdk.itemRanking.cnZonePriceAnalyse({ catId: 17027494, catLevel: 1 });
await sdk.itemRanking.cnZoneStarAnalyse({ catId: 17027494, catLevel: 1 });

返回类型: string[], PaginatedData<CnZoneProduct>, CnZoneDataView, AnalyseItem[], CnZoneChartAnalyse

`sdk.keyword` — 关键词分析

| 方法 | 说明 | HTTP | 路径 | |------|------|------|------| | hot(params?) | 热门关键词 | POST | /api/ozon-report-service/v1/keyword/hot | | chance(params?) | 蓝海词 | POST | /api/ozon-report-service/v1/keyword/chance | | high(params?) | 高转化热词 | POST | /api/ozon-report-service/v1/keyword/high | | soar(params?) | 搜索飙升词 | POST | /api/ozon-report-service/v1/keyword/soar | | searchKeyword(params) | 关键词搜索 / 联想 | POST | /api/ozon-report-service/v1/keyword/searchKeyword |

参数说明（KeywordListQuery，hot / chance / high / soar 共用）

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | catId | string \| number | "" | 类目 ID | | dataType | number | 1 | 数据类型 | | keyword | string | "" | 关键词筛选 | | fuzzySearch | boolean | true | 模糊搜索 | | dateType | DateType | "MONTH" | 日期范围 | | timest | string | — | 统计时间点，格式随 dateType 变化 | | typeId | number | — | 类型 ID | | catLevel | number | — | 类目层级 | | minHotCheck | number | — | 最小搜索热度 | | minCheckRatio | number | — | 最小搜索增长比例 | | minAvgPrice / maxAvgPrice | number | — | 平均价格区间 |

searchKeyword(params) 参数为 KeywordSearchQuery：link（搜索词，必填）、type（默认 "word"）。

// 蓝海词
await sdk.keyword.chance({ dateType: "MONTH" });

// 搜索飙升词 + 系统筛选模型字段
await sdk.keyword.soar({
  catId: 17028940,
  catLevel: 2,
  typeId: 0,
  dateType: "YEAR",
  timest: "2026",
  minHotCheck: 1000,
  minCheckRatio: 10,
});

// 高单价热词
await sdk.keyword.high({ minHotCheck: 1000, minAvgPrice: 3000 });

// 关键词搜索 / 联想
await sdk.keyword.searchKeyword({ link: "工具" });

返回类型: HotKeyword[], KeywordSearchResult

`sdk.cat` — 类目树

| 方法 | 说明 | HTTP | 路径 | |------|------|------|------| | backgroundZip() | 获取类目树数据（gzip+base64） | GET | /api/ozon-report-service/v1/cat/backgroundZip | | tree() | 获取解压后的类目树 | GET | 同上（自动解压解析） |

backgroundZip() 返回 H4sI 开头的 gzip+base64 编码字符串。tree() 会自动解压并返回 CategoryTreeNode[] 树形结构。也可使用 decodeBackgroundZip() 手动解压缓存数据。

返回类型: string, CategoryTreeNode[]

`sdk.filtrate` — 筛选模型

| 方法 | 说明 | HTTP | 路径 | |------|------|------|------| | checkModelList(type?) | 获取筛选模型列表 | GET | /api/ozon-report-service/v1/filtrate/checkModelList |

type 默认 "item"，关键词筛选模型传 "word"

返回类型: FilterModel[]

公共类型

RangeType: "DAY" | "WEEK" | "MONTH"

PaginatedData<T>: { pageNo, pageSize, total, pages, list, updateTime? }

CategoryTreeNode: { catId, children?, id, level, name, nameCn, nameEn, onlyLocal, parentCatId, typeId }

关键词类型: KeywordListQuery, KeywordListFilter, KeywordSearchQuery, KeywordSearchResult, KeywordCheckPoint

认证

API 需要浏览器登录会话。从 Chrome DevTools → Network 中复制：

authorization → MM_TOKEN（Bearer Token，必填）
cookie → MM_COOKIES（必填）
control-t → MM_CONTROL_T（推荐，与 Cookie 中 Control-T 一致）

SDK 会自动补全 Origin、Referer、x-risk-dida 等请求头。

配置

API 基础地址默认为 https://mm.ozon.com，支持以下方式覆盖：

// 构造参数
const sdk = new MmSdk({ baseUrl: "https://mm.ozon.com", token: "...", cookies: "..." });

# 环境变量（fromEnv 或任意 new MmSdk() 均生效）
MM_BASE_URL=https://mm.ozon.com

HAR 分析

bun run analyze-har                    # 分析默认 HAR 文件
bun run analyze-har path/to/file.har   # 分析指定 HAR 文件

运行示例

cp .env.template .env   # 填入 token / cookies / control-t
bun run examples/basic.ts

项目结构

src/
├── index.ts          # SDK 入口
├── client.ts         # HTTP 客户端
├── types.ts          # TypeScript 类型定义
├── utils/
│   └── cat-tree.ts   # 类目树 gzip+base64 解压
└── apis/             # API 模块
    ├── big-disc.ts
    ├── industry.ts
    ├── item-ranking.ts
    ├── keyword.ts
    ├── cat.ts
    └── filtrate.ts
scripts/
└── analyze-har.ts    # HAR 分析工具
examples/
└── basic.ts          # 使用示例

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme