AdMapix广告情报数据层

技能文档

---
name: admapix
title: AdMapix 广告情报数据层
category: 办公效率
description: "AdMapix 广告与应用情报数据层，将自然语言请求转为 API 调用，返回原始结构化 JSON 数据。覆盖广告素材搜索、应用/产品信息、排行榜、下载量/收入估算、投放分布、市场分析（按国家/媒体/广告主/流量主维度的展示量与份额统计）、市场元数据等。当用户需要搜广告、找广告素材、竞品广告分析、查排行榜、查下载量、查收入、市场分析、广告市场规模、哪个国家广告最多、头部广告主、媒体份额、流量主排名、App 数据查询时触发。"
---

# AdMapix 广告情报数据层

AdMapix 只读 API 的轻量数据客户端。它获取**原始结构化数据**并以 JSON 格式返回。它**不**负责分析、汇总、排序、生成页面或执行自主研究——这些工作由调用方 Agent 决定调用哪些端点、按需串联工作流，并自行完成分析。

**不在本技能职责范围内**（本技能绝不执行）：HTML/H5 页面生成、托管式"深度研究"、自主多步研究、摘要/洞察/建议生成、仪表盘生成、消息发送。

## 技能工作流

### 步骤1：检查 API Key

在发起任何 API 调用之前，先验证密钥是否已配置（不要打印密钥值）：

```bash
[ -n "${ADMAPIX_API_KEY:-}" ] && echo ok || echo missing
```

### 步骤2：密钥缺失时展示配置指引

如果密钥缺失（且无 MCP 工具可用），**不要**调用 API。向用户展示如何获取和配置密钥，然后请用户配置后重试。

> 🔑 需要先配置 AdMapix API Key 才能使用：
> 1. 打开 https://www.admapix.com 注册账号
> 2. 登录后在控制台找到 **API Keys**，创建一个 Key
> 3. 配置环境变量：`export ADMAPIX_API_KEY="你的_API_KEY"`
> 4. 配置完成后重新发起查询 ✅

如果宿主平台提供安全密钥存储命令，优先引导用户使用该方式。绝不接受、回显或存储用户聊天中的密钥——密钥不得出现在回复、日志和链接中。对于程序化调用方，同时返回 `missing_api_key` 错误（参见错误处理）。

### 步骤3：调用认证

使用 `ADMAPIX_API_KEY` 作为 `X-API-Key` 请求头。绝不打印或泄露密钥。

```bash
admapix_auth_header="X-API-Key: ${ADMAPIX_API_KEY}"
# GET 请求
curl -s "https://api.admapix.com/api/data/{endpoint}?{params}" -H "$admapix_auth_header"
# POST 请求
curl -s -X POST "https://api.admapix.com/api/data/{endpoint}" \
  -H "$admapix_auth_header" -H "Content-Type: application/json" -d '{...}'
```

素材搜索优先使用 MCP 工具（如可用）；否则直接调用 `POST /api/data/search`。

### 步骤4：查阅端点文档并发起调用

每个端点都是原始数据源。**首次调用某个端点前，务必阅读对应的参考文档**——其中包含精确的参数和响应字段说明。根据需要组合多次调用；本技能每次请求只调用单个端点并返回原始 JSON。

## 端点目录

### 素材/广告 — `references/api-creative.md`

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/data/search` | POST | 搜索广告素材 |
| `/api/data/count` | POST | 统计查询匹配的素材数量 |
| `/api/data/count-all` | POST | 按维度细分的统计计数 |
| `/api/data/distribute` | POST | 素材分布细分 |
| `/api/data/distribute-dims` | GET | 可用的分布维度 |
| `/api/data/content-detail` | GET | 单条素材详情（`related=imagevideo|trend`） |
| `/api/data/item-apps` | POST | 素材关联的应用 |
| `/api/data/screen-types` | GET | 屏幕/元素类型代码 |
| `/api/data/page-config` | GET | 搜索页面配置 |

### 元数据/筛选 — `references/api-creative.md` + `references/param-mappings.md`

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/data/filter-options` | GET | **全部筛选元数据**：`countries`、`mediaChannels`、`adTypes`、`device`、`tradeLevel(Tree)`、`productModel` 等。调用此端点可发现任意筛选维度的有效代码。 |

### 应用/产品/公司 — `references/api-product.md`

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/data/unified-product-search` | POST | 统一应用/产品搜索 |
| `/api/data/product-search` | POST | 产品搜索 |
| `/api/data/company-search` | POST | 开发者/公司搜索 |
| `/api/data/app-detail` | GET | 应用详情（按 `unifiedProductId`） |
| `/api/data/developer-detail` | GET | 开发者详情 |
| `/api/data/app-profile` | GET | 应用画像 |
| `/api/data/similar-apps` | POST | 相似应用 |
| `/api/data/sdk-detail` | GET | 应用使用的 SDK |
| `/api/data/product-content-search` | POST | 某产品的素材 |
| `/api/data/product-content-counts` | POST | 某产品的素材数量 |
| `/api/data/product-list`、`/for-product-list`、`/product-agg-list` | POST | 产品列表/聚合 |

### 排行榜 — `references/api-ranking.md`

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/data/store-rank` | POST | 应用商店排行榜（免费/付费/畅销） |
| `/api/data/generic-rank` | POST | 通用排行列表 |
| `/api/data/store-categories` | GET | 商店分类代码 |
| `/api/data/store-countries` | GET | 商店国家代码 |

### 下载量与收入（第三方估算） — `references/api-download-revenue.md`

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/data/download-date`、`download-detail`、`download-country` | GET/POST | 按日期/明细/国家的下载量估算 |
| `/api/data/revenue-date`、`revenue-detail`、`revenue-country` | GET/POST | 按日期/明细/国家的收入估算 |

> ⚠️ 下载量/收入数据为第三方**估算**值，非官方数据。原样返回原始数字；展示时调用方 Agent 必须注明为估算数据。

### 投放分布 — `references/api-distribution.md`

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/data/app-distribution` | POST | 应用级分布数据 |
| `/api/data/global-promote` | POST | 全球推广数据 |

### 市场分析 — `references/api-market.md`

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/data/market-search` | POST | 从 5 个维度分析广告市场：国家规模、媒体份额、子媒体细分、头部广告主、头部流量主。支持游戏/应用两类数据，返回展示量与占比排名。 |

**注意：** `market-search` 的响应结构与其他端点不同——使用 `data_list`（非 `list`），字段名为嵌套点号格式（如 `market_query.list.impression`）。日期格式为斜杠 `YYYY/MM/DD`。首次使用前务必阅读 `references/api-market.md`。

**5 个分析维度（`class_type`）：**

| class_type | 维度 | 典型问题 |
|---|---|---|
| 1 | 国家 | "哪些国家的游戏广告最多？" |
| 2 | 媒体 | "哪些广告平台使用量最大？" |
| 3 | 子媒体 | "Facebook 哪些广告版位热门？" |
| 4 | 广告主 | "最大的游戏广告主有哪些？" |
| 5 | 流量主 | "哪些流量主承载的广告最多？" |

## 参数映射

阅读 `references/param-mappings.md` 将自然语言翻译为代码：

- 素材类型（`010`=视频 等）、行业（`trade_level1`：`602`=游戏、`607`=金融…）、国家/地区分组、相对日期范围、排序、每页数量。
- 对于 param-mappings 中未列出的代码（子行业、媒体渠道、设备、商店分类…），调用 `GET /api/data/filter-options` 或对应端点的维度查询（如 `store-categories`）。

素材 `search` 端点的 `page_size` 上限为 **10**（超过 10 时自动截断；使用 `page` 翻页）。其他列表端点使用各自文档中定义的范围。

## 输出规则

将 API 响应以**原始结构化 JSON** 返回——保留 API 字段名；不重命名、不删除、不汇总、不排序、不添加编辑评论。调用方 Agent 负责组合与分析。

- 不同端点的响应结构各异。素材搜索通过直接 API 返回 `pageIndex` / `pageSize` / `totalSize` / `list`；市场分析返回 `data_list` 与点号字段名；MCP 工具会额外包装 `request` / `page` / `page_size`。`totalSize` 在筛选查询中可能为 `null`——以 `list` 长度为准。
- 空 `list` 是有效结果（无匹配），不是错误。
- 透传额外字段（如 `gptCorrect` 拼写建议）；不要静默替换关键词。

禁止：生成 H5/落地页/卡片/仪表盘页面、将记录隐藏在链接后面、执行托管式"深度研究"或自主多步研究，或在用户收到数据后未明确要求时产出分析/建议。

## 错误处理

**Agent 级**（未发起请求——无 MCP 工具且 `ADMAPIX_API_KEY` 缺失）：

```json
{ "error": { "code": "missing_api_key", "message": "缺少 ADMAPIX_API_KEY 环境变量", "retry": false } }
```

**API 级**（调用返回非 2xx 状态码）。API 响应格式为 `{ "detail": "...", "code": "..." }`；原样展示并附带 HTTP 状态码，绝不打印密钥。HTTP 401 配合 `INVALID_API_KEY` / `NOT_AUTHENTICATED` 表示密钥缺失、格式错误或已禁用——不要重试：

```json
{ "error": { "code": "invalid_api_key", "http_status": 401, "message": "API 密钥格式无效", "retry": false } }
```

使用说明

# AdMapix 广告情报数据层

将自然语言请求转为 AdMapix API 调用，返回原始结构化 JSON——广告素材、应用信息、排行榜、下载量/收入估算、投放分布、市场元数据，一站式获取。

## 前置条件

1. 前往 [www.admapix.com](https://www.admapix.com) 注册并创建 API Key
2. 配置环境变量：

```bash
export ADMAPIX_API_KEY="你的_API_KEY"
```

## 使用

向 Agent 发出自然语言指令即可，技能自动选择端点并返回原始数据：

```text
搜一下 puzzle game 的视频广告
美国 App Store 免费榜 Top10
Temu 最近 30 天的下载量估算
东南亚游戏广告市场数据
```

## 支持的数据类型

| 数据 | 示例指令 |
|------|----------|
| 素材搜索 | 「找东南亚投放的休闲游戏素材」 |
| 应用/产品 | 「拉 Temu 的应用详情」 |
| 排行榜 | 「日本畅销游戏榜」 |
| 下载量/收入 | 「SHEIN 各国收入估算」 |
| 投放分布 | 「Temu 主要在哪些国家投广告？」 |
| 市场分析 | 「金融行业最大的广告主」 |

## 工作原理

技能每次请求调用一个 API 端点，原样返回 JSON 数据。多步分析由 Agent 按需串联多个调用完成。支持中文与英文输入。

> ⚠️ 下载量和收入为第三方估算数据，非官方应用商店数字。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。