AdMapix广告投放工具

问题：如何从广告平台获取可编程的原始数据？

当需要从 AdMapix 这类广告平台获取原始数据用于定制分析时，直接对接其 API 往往面临几个挑战：需要管理 API_KEY 认证、需要根据文档手动组装参数、以及需要处理不同端点的差异化响应格式。对于工程师或数据管道而言，核心需求不是又一个分析工具，而是一个能稳定返回 原始结构化 JSON 的可靠数据层，以便将数据无缝集成到自定义的分析流水线、报表生成器或数据库中。

工作方式：一个纯粹的 API 数据访问层

本技能被设计为一个 薄客户端，其唯一职责是封装与 AdMapix Read API 的通信。它解决了数据获取阶段的痛点，但绝不越界替代调用方（你或你的 Agent）进行分析、总结或报告生成。

核心工作流与能力：

1. 认证与配置：技能首先验证环境变量 ADMAPIX_API_KEY 是否已设置。如果缺失，它会提供清晰的配置指南（中英文），并停止执行。它绝不存储、记录或回显密钥，确保安全。

1. 端点路由与调用：它暴露了丰富的 API 端点目录，主要覆盖四大领域：

广告创意：通过 POST /api/data/search 搜索，通过 GET /api/data/content-detail 获取详情。注意，创意搜索的 page_size 被限制为 10。
应用与公司：使用 POST /api/data/unified-product-search 进行统一搜索，或调用 GET /api/data/app-detail 获取特定应用信息。
排名与市场：通过 POST /api/data/store-rank 获取商店排名，或使用 POST /api/data/market-search 进行市场数据聚合。
估算数据：通过 /api/data/download-date 等端点获取第三方估算的下载量和收入数据。

1. 参数映射：技能内嵌了对 references/param-mappings.md 的理解，能将自然语言（如“视频广告”、“游戏行业”）映射为 API 所需的代码（如 creative_type=010, trade_level1=602）。对于更细粒度的维度（如设备、子行业），则动态调用 GET /api/data/filter-options 来发现有效值。

1. 原始输出：这是最关键的一点。技能必须将 API 的响应原封不动地以 JSON 返回。这意味着：保留所有原始字段名（如 pageIndex, list），不重命名、不筛选、不总结、不添加任何分析性文字。一个空列表（[]）是有效的“无结果”响应。

适用边界与关键注意点

这是一个 数据获取工具，而非分析或决策工具。理解其边界至关重要：

• 不做的事（明确排除）：技能绝不生成 HTML/H5 页面、仪表盘、报告、摘要或推荐。它不会发起自主的多步“深度研究”。如果用户要求分析，必须在数据已经返回给调用方之后再提出。
• 错误处理：如果 API 返回非 2xx 状态，技能会透传错误详情。特别是 401 INVALID_API_KEY，这明确指示密钥问题，应引导用户检查配置而非重试。
• 数据性质：下载量和收入数据是第三方估算值。在展示时，调用方有责任注明这一点。
• 调用粒度：技能设计为每次请求只进行一次 API 调用并返回该调用的结果。复杂的分析工作流（如搜索后获取详情再聚合）需要由调用方（如 Agent）编排多个连续的技能调用来完成。

总之，它让工程师能够以编程方式、高效且安全地收集广告平台的原始数据，将数据处理的智慧留给更上层的应用逻辑。