AdMapix—广告创意市场数据 API 客户端

AdMapixAdMapix与 AI 图像、广告素材生成和创意工作流相关的项目/工具。查看相关文章查看项目档案 读取 API 的轻量级客户端。它获取原始结构化数据并以 JSON 格式返回。它不做分析、摘要、排名、生成页面或运行自主研究——调用方（如 Claude Code、Codex）决定调用哪些端点、从元数据组合多调用工作流，并自行完成分析。

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

认证

使用 ADMAPIX_API_KEY 作为 X-API-Key 请求头。切勿打印或暴露密钥。

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 '{...}'

对于创意搜索，当 admapix.search_creatives MCP 工具可用时优先使用；否则直接调用 POST /api/data/search。

步骤 1 — 检查密钥

在任何 API 调用之前，验证密钥已配置（但不打印其值）：

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

步骤 2 — 如果缺失，显示设置指南

如果密钥缺失（且没有可用的 MCP 工具），不要调用 API。用用户的语言向他们展示如何获取和配置密钥，然后请他们重试。从用户的消息中检测语言。

中文用户：

🔑 需要先配置 AdMapix API Key 才能使用：

1. 打开 https://www.admapix.com 注册账号
2. 登录后在控制台找到 API Keys，创建一个 Key
3. 选择一种方式配置：
   • OpenClaw / ClawHub：在终端运行 openclaw config set skills.entries.admapix.apiKey "你的_API_KEY"
   • 通用环境变量：在终端运行 export ADMAPIX_API_KEY="你的_API_KEY"
4. 配置完成后重新发起查询 ✅

English users:

🔑 You need an AdMapix API Key to get started:

1. Sign up at https://www.admapix.com
2. After signing in, open API Keys in your dashboard and create one
3. Configure it one of these ways:
   • OpenClaw / ClawHub: run openclaw config set skills.entries.admapix.apiKey "YOUR_API_KEY" in your terminal
   • Generic env var: run export ADMAPIX_API_KEY="YOUR_API_KEY" in your terminal
4. Re-run your query after setup ✅

如果主机提供了安全的 secret/config 命令，请引导用户使用该命令。切勿从聊天中接受、回显或存储密钥——保持其远离响应、日志和链接。对于程序化调用方，还应返回 missing_api_key 错误（参见错误处理）。

端点目录

每个端点都是一个原始数据源。在使用尚未调用过的端点之前，请先阅读列出的参考文件——其中包含精确的参数和响应字段。根据需要组合多个调用；此技能本身保持单次请求单次调用并返回原始 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
/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	按日期/明细/国家估算收入

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

分发 — references/api-distribution.md

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

市场 — references/api-market.md

端点	方法	用途
/api/data/market-search	POST	市场级搜索/聚合

参数映射

阅读 references/param-mappings.md 将自然语言转换为代码：

• 创意类型（010=视频等）、行业（trade_level1：602=游戏、607=金融……）、国家/地区组、相对日期范围、排序、页面大小。
• 对于 param-mappings 中没有的代码（子行业、媒体渠道、设备、商店分类……），请调用 GET /api/data/filter-options 或特定端点的维度调用（如 store-categories）。

对于创意 search 端点，page_size 上限为10（将任何大于 10 的请求压缩到 10；使用 page 获取更多）。其他列表端点使用各自文档中规定的范围。

输出规则

将 API 响应作为原始结构化 JSON返回——保留 API 字段名；不要重命名、删除、摘要、排名或编辑。调用方进行组合和分析。

• 响应结构因端点而异。通过直接 API 进行创意搜索返回 pageIndex/pageSize/totalSize/list；MCP 工具额外包装了 request/page/page_size。在过滤查询中 totalSize 可能为 null——请使用 list 的长度。
• 空的 list 是有效结果（无匹配），不是错误。
• 原样透传额外字段（如 gptCorrect 拼写建议）；不要静默替换关键词。

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

错误处理

代理级（未发出请求——没有 MCP 工具且 ADMAPIX_API_KEY 缺失）：

{ "error": { "code": "missing_api_key", "message": "Missing ADMAPIX_API_KEY environment variable", "retry": false } }

API 级（调用返回了非 2xx 状态）。API 以 { "detail": "...", "code": "..." } 形式响应；将其与 HTTP 状态一起展示，切勿打印密钥。HTTP 401 伴随 INVALID_API_KEY/NOT_AUTHENTICATED 表示密钥缺失、格式错误或已禁用——不要重试：

{ "error": { "code": "invalid_api_key", "http_status": 401, "message": "Invalid API key format", "retry": false } }