admapix-free

AdMapix 原始数据层基础客户端（免费版）。覆盖广告创意搜索、应用详情查询、商店榜单查询三大基础端点类别. 作为薄客户端透传 API 返回的原始结构化 JSON，不分析、不总结、不排序、不生成页面. 支持 X-API-Key 认证、page_size 上限 10 自动钳制、filter-options 元数据发现. 适用于广告创意搜索、应用信息查询、商店榜单查看等基础场景.

AdMapix LITE

AdMapix 原始 API 基础客户端（免费版）。获取原始结构化数据并返回 JSON，不分析、不总结、不排序、不生成页面.

运行环境

运行环境

• Agent 平台: 支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统: Windows / macOS / Linux
• 网络: 需可访问 https://api.admapix.com

依赖项

依赖项	类型	是否必需	获取方式
AdMapix API	远程 HTTP API	必需	https://www.admapix.com 注册获取
ADMAPIX_API_KEY	环境变量	必需	控制台 API Keys 创建；仅作 X-API-Key 请求头
curl 或等价 HTTP 客户端	命令行工具	必需	系统自带或包管理器安装

可用性分类

• 分类: MD+EXEC（Markdown 指令驱动，需 exec 执行 curl 命令）
• 说明: 基于自然语言指令驱动 Agent 调用 AdMapix API，透传原始结构化 JSON

能力梳理

参数映射

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

• 创意类型（010=视频等）、行业（trade_level1：602=游戏，607=金融...）、国家/地区分组、相对日期范围
• 未列出的代码调 GET /api/data/filter-options 获取

对于创意 search 端点，page_size 上限为 **

输出规则

返回 API 响应的原始结构化 JSON — 保留 API 字段名；不重命名、不丢弃、不总结、不排序。调用方 Agent 负责分析.

• 创意搜索返回 pageIndex / pageSize / totalSize / list。totalSize 在过滤查询时可能为 null — 此时以 list 长度为准.
• 空 list 是合法结果（无匹配），非

认证

使用 ADMAPIX_API_KEY 作为 X-API-Key 请求头。永不打印或暴露 Key.

bash

curl -s "https://api.admapix.com/api/data/{endpoint}?{params}" -H "X-API-Key: ${ADMAPIX_API_KEY}"
curl -s -X POST "https://api.admapix.com/api/data/{endpoint}" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" -d '{...}'

端点目录（基础端点）

创意 / 广告

端点	方法	用途
/api/data/search	POST	搜索广告创意
/api/data/count	POST	按条件统计创意数量
/api/data/filter-options	GET	全量筛选元数据（国家码、行业码、创意类型码等）

应用 / 产品

端点(续)	方法	用途
/api/data/unified-product-search	POST	统一应用/产品搜索
/api/data/app-detail	GET	按 unifiedProductId 查应用详情

榜单

端点(续)(续)	方法	用途
/api/data/store-rank	POST	应用商店榜单（免费/付费/畅销）
/api/data/store-categories	GET	商店类目代码

升级提示：创意分布查询、创意详情、SDK 审计、开发者画像、下载/收入估算、应用分发、市场级搜索等高级端点仅在 admapix 付费版 中提供.

参数映射(补充)

对于创意 search 端点，page_size 上限为 10（更大的值自动钳制到 10；用 page 翻页）.

输出规则(补充)

• 空 list 是合法结果（无匹配），非错误.

使用方法

Step 1：检查 API Key（永不打印值）

bash

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

Step 2：缺失时引导配置

需要先配置 AdMapix API Key：

1. 访问 https://www.admapix.com 注册并登录
2. 在控制台 API Keys 创建 Key
3. 终端环境变量：export ADMAPIX_API_KEY="你的Key"
4. 配置完成后重新发起查询

安全红线：永不接受/回显/存储来自聊天输入的 Key；Key 仅作为 X-API-Key 请求头使用.

Step 3：首次调用前拉取元数据

bash

admapix.com/api/data/filter-options" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}"

Step 4：按需调用端点，透传原始 JSON

• 每次请求调用单个端点，返回原始结构化 JSON
• 空 list 是合法结果，非错误
• page_size 上限 10 自动钳制，翻页用 page 参数

案例展示

案例1：竞品创意搜索

场景：广告投放团队需要搜索美国地区游戏类视频广告创意

bash

# 搜索美国地区游戏类视频广告创意
admapix.com/api/data/search" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"keyword":"rpg","countries":["US"],"trade_level1":["602"],"adTypes":["010"],"page":1,"page_size":10}'

输出：

json

{
  "pageIndex": 1,
  "pageSize": 10,
  "totalSize": 234,
  "list": [
    {"id": "ad_001", "url": "https://...", "first_seen": "2026-07-15", "type": "video", "duration": 30},
    {"id": "ad_002", "url": "https://...", "first_seen": "2026-07-16", "type": "video", "duration": 15}
  ]
}

分析：共找到 234 条匹配创意，当前返回前 10 条。翻页请用 page 参数递增.

案例2：商店榜单查询

场景：出海团队需要查询日本免费榜前 20 名应用

bash

# 查询日本免费游戏榜
admapix.com/api/data/store-rank" \
  -H "X-API-Key: ${ADMAPIX_API_KEY}" -H "Content-Type: application/json" \
  -d '{"countries":["JP"],"rankType":"free","category":"games","page":1,"page_size":20}'

输出：

json

{
  "list": [
    {"rank": 1, "appName": "示例应用A", "unifiedProductId": "app_001", "developer": "Dev A"},
    {"rank": 2, "appName": "示例应用B", "unifiedProductId": "app_002", "developer": "Dev B"}
  ]
}

异常修复

错误场景	错误信息	原因分析	处理方式
missing_api_key	{"error":{"code":"missing_api_key"}}	环境变量 ADMAPIX_API_KEY 未设置	不调 API，引导用户配置 Key；永不打印 Key
401 INVALID_API_KEY	{"code":"INVALID_API_KEY"}	Key 格式错误或已禁用	检查网络连接和配置后重试，引导用户检查 Key 格式
403 FORBIDDEN	{"code":"FORBIDDEN"}	套餐权限不足，端点不在套餐范围内	检查网络连接和配置后重试，提示用户升级 AdMapix 套餐
429 RATE_LIMITED	{"code":"RATE_LIMITED"}	API 调用频率超限	等待 1 秒后检查网络连接和配置后重试，最多 3 次
400 INVALID_PARAM	{"code":"INVALID_PARAM"}	国家/行业/创意类型码错误	检查网络连接和配置后重试，调 filter-options 核对参数代码
空 list 返回	{"list":[],"totalSize":null}	参数无匹配或代码错误	空列表是合法结果；调 filter-options 核对代码

常见疑问

Q1：page_size=50 为什么只返回了 10 条？

A：创意 search 端点 page_size 硬上限为 10，任何更大的值会被自动钳制到 10。翻页请用 page 参数递增（page=1, 2, 3...）.

Q2：totalSize 为什么是 null？

A：过滤查询时 totalSize 可能为 null。此时以 list 长度为准，或单独调 count 端点获取准确总数.

Q3：免费版和付费版有什么区别？

A：免费版（LITE）包含创意搜索、应用详情查询、商店榜单查询三大基础端点。付费版（AdMapix）额外提供：

• 创意分布查询（distribute / distribute-dims）与创意详情（content-detail）
• 开发者画像（company-search / developer-detail）与 SDK 审计（sdk-detail）
• 下载与收入估算（download-date / revenue-country 等 6 个端点）
• 应用分发（app-distribution / global-promote）与市场级搜索（market-search）
• 3 个完整案例（vs 免费版 2 个基础案例）
• 9 种错误处理（vs 免费版 6 种）

Q4：如何获取有效的国家码和行业码？

A：调 GET /api/data/filter-options 获取全量筛选元数据，包含 countries、mediaChannels、adTypes、tradeLevel(Tree) 等全部维度。商店类目调 store-categories.

能力边界

1. 基础端点：仅支持创意搜索、应用详情、商店榜单，不支持下载/收入估算、创意分布、SDK 审计、开发者画像（需升级付费版）
2. 薄客户端：仅透传原始结构化 JSON，不分析、不总结、不排序
3. 单次请求单端点：每次 API 调用仅请求一个端点
4. page_size 硬上限 10：创意搜索翻页 100 条需 10 次请求
5. 不做分析与推荐：仅透传结构化数据，不生成分析报告

技术创新

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
创意搜索	30分钟	1分钟	29分钟	5%
应用详情查询	15分钟	30秒	14分钟	10%
商店榜单查看	20分钟	2分钟	18分钟	8%
数据导出	2小时	15分钟	1小时45分钟	7%
数据分析	4小时	1小时	3小时	12%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
搜索速度	快速响应	逐个搜索	较快响应	极快响应
数据准确性	高	低	中	高
操作便捷性	高	低	中	高
成本	低	高	中	高
技术门槛	低	高	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
数据收集耗时	数据收集过程繁琐，耗时较长	广告分析、市场研究	利用AdMapix免费版实现自动化数据收集	时间节约20%
数据准确性低	数据来源单一，准确性不高	广告效果评估、市场分析	通过AdMapix免费版获取多源数据，提高准确性	准确率提升10%
数据处理效率低	数据处理过程复杂，效率低	广告分析、市场研究	利用AdMapix免费版实现自动化数据处理	效率提升30%

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	使用环境变量，禁止硬编码	定期检查代码库，确保无明文密钥
输入注入攻击	中	对输入参数进行转义和验证	定期运行注入测试用例，如SQL注入、XSS攻击等
输出内容不当	中	生成内容需人工审核	建立内容审核流程，定期抽样检查
依赖漏洞	中	定期更新依赖版本	运行安全扫描工具，如OWASP ZAP、Nessus等
并发冲突	低	使用锁机制保护共享资源	进行并发压力测试，确保系统稳定性
资源耗尽	低	设置超时和重试上限	监控资源使用情况，如CPU、内存、网络等

主要特性

• 自动化执行: AdMapix基础查询，创意搜索+应用详情+商店榜单。AdMapix 原始数据层基础客户端（免费版）。覆盖广告创意搜索、
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

疑问与回应

异常恢复流程

针对Admapix免费版使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

重要特性

• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据