AdMapix

A thin client over the AdMapix read API. It fetches raw structured data and returns it as JSON. It does not analyze, summarize, rank, generate pages, or run autonomous research — the calling agent (e.g. Code, Codex) decides which endpoints to call, composes multi-call workflows from the metadata, and does any analysis itself.

Out of scope (never done inside this skill): HTML/H5 page generation, hosted "deep research", autonomous multi-step research, summaries, insights, recommendations, dashboards, message-send.

Auth

Use ADMAPIX_API_KEY as the X-API-Key header. Never print or expose the key.

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

For creative search, prefer the admapix.search_creatives 协议 tool when available; otherwise call POST /api/data/search directly.

Step 1 — Check the key

Before any API call, verify the key is configured (without printing its value):

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

Step 2 — If missing, show the setup guide

If the key is missing (and no 协议 tool is available), do not call the API. Show the user how to get and configure a key — in their language — then ask them to retry. Detect language from the user's message.

中文用户：

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

1. 打开 https://www.admapix.com 注册账号
2. 登录后在控制台找到 API Keys，创建一个 Key
3. 选择一种方式配置：
   • Skill平台 / SkillHub：在终端运行 skill-platform 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:
   • Skill平台 / SkillHub: run skill-platform config set skills.entries.admapix.apiKey "YOUR_API_KEY" in your terminal
   • Generic env var: run export ADMAPIX_API_KEY="${API_KEY:?请设置环境变量}" in your terminal
4. Re-run your query after setup ✅

If the host provides a secure secret/config command, point the user to that instead. Never accept, echo, or store the key from chat — keep it out of responses, logs, and links. For programmatic callers, also return the missing_api_key error (see Error Handling).

Endpoint Catalog

Each endpoint is a raw data source. Read the listed reference file before using an endpoint you have not called yet — it carries the exact params and response fields. Compose multiple calls as needed; the skill itself stays single-call-per-request and returns raw JSON.

Creatives / ads — references/api-creative.md

Metadata / filters — references/api-creative.md + references/param-mappings.md

Apps / products / companies — references/api-product.md

Rankings — references/api-ranking.md

Downloads & revenue (third-party estimates) — references/api-download-revenue.md

⚠️ Download/revenue figures are third-party estimates, not official data. Return the raw numbers as-is; the calling agent must note they are estimates when presenting.

Distribution — references/api-distribution.md

Market — references/api-market.md

Parameter Mapping

Read references/param-mappings.md to translate natural language into codes:

• creative type (010=video, etc.), industry (trade_level1: 602=Game, 607=Finance…), country / region groups, relative date ranges, sorting, page size.
• For codes not in param-mappings (sub-industries, media channels, devices, store categories…), pull GET /api/data/filter-options or the endpoint-specific dimension call (e.g. store-categories).

For the creative search endpoint, page_size is capped at 10 (clamp any larger request down to 10; use page for more). Other list endpoints use their own documented ranges.

Output Rules

Return the API response as raw structured JSON — keep the API field names; do not rename, drop, summarize, rank, or editorialize. The calling agent composes and analyzes.

• Response shapes vary by endpoint. Creative search via direct API returns pageIndex / pageSize / totalSize / list; the 协议 tool additionally wraps it with request / page / page_size. totalSize may be null on filtered queries — use the length of list.
• An empty list is a valid result (no matches), not an error.
• Pass through extra fields (e.g. gptCorrect spelling suggestions) unchanged; do not silently swap a keyword.

Do not: generate H5 / landing / card / dashboard pages, hide records behind links, run hosted "deep research" or autonomous multi-step research, or produce analysis / recommendations unless the user explicitly asks after receiving the data.

Error Handling

Agent-level (no request was made — no 协议 tool and ADMAPIX_API_KEY is missing):

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

API-level (the call returned a non-2xx status). The API responds with { "detail": "...", "code": "..." }; surface it plus the HTTP status, and never print the key. HTTP 401 with INVALID_API_KEY / NOT_AUTHENTICATED means the key is missing, malformed, or disabled — do not retry:

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

运行环境

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent( Code / Cursor / Codex / Gemini CLI等)
• 操作系统: Windows / macOS / Linux

依赖说明

API Key 配置

• 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)

可用性分类

• 分类: MD+execute(纯Markdown指令,部分功能需要exec命令行执行能力)
• 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务

能力清单

• AdMapix raw data layer for ad creatives, apps, rankings, downloads/revenue
• 触发关键词: apps, admapix, data, creatives, layer

适用范围

不适用于：需要人工判断的复杂决策场景

操作流程

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

示例展示

示例1：基础用法

# 请参考上方使用说明进行配置和调用
result = "ready"

错误处理机制

常见疑问

Q1: 如何开始使用AdMapix？

A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。

Q2: 遇到错误怎么办？

A: 请参考错误处理章节，按照表格中的处理方式操作。

Q3: AdMapix有什么限制？

A: 请参考已知限制章节了解具体限制。

功能边界

• 需要API Key，无Key环境无法使用

创新特色

效率提升量化分析

差异化对比

核心痛点解决

常见问题FAQ

Q1: AdMapix广告投放工具支持哪些广告平台？

A: AdMapix广告投放工具支持多个广告平台，包括但不限于Google AdWords、Facebook Ads、Bing Ads等。具体支持的平台和功能请参考官方文档。

Q2: 如何获取AdMapix广告投放工具的API Key？

A: 您需要先在AdMapix官方网站注册账号并登录，然后在控制台找到API Keys部分创建一个新的Key。创建后，您可以根据官方文档指导配置API Key。

Q3: AdMapix广告投放工具的数据更新频率是多少？

A: AdMapix广告投放工具的数据更新频率取决于具体的数据源和平台，一般而言，数据更新频率较高，可以满足实时监控和决策需求。

Q4: AdMapix广告投放工具是否支持多语言？

A: AdMapix广告投放工具支持多种语言，包括但不限于英语、中文、西班牙语等，具体支持的语言请参考官方文档。

Q5: AdMapix广告投放工具如何处理数据隐私问题？

A: AdMapix广告投放工具严格遵守相关数据保护法规，对用户数据进行严格加密和脱敏处理，确保用户数据的安全和隐私。

诊断与修复

安全提示

1. 确保API Key不被泄露，避免被未授权用户使用。
2. 定期检查API Key的使用记录，防止异常访问。
3. 限制API Key的权限，仅授权必要的操作。
4. 使用HTTPS协议进行API调用，确保数据传输安全。
5. 定期更新AdMapix广告投放工具，修复已知安全漏洞。

安全风险防范

常见问题解答 (FAQ)

Q: 为什么需要使用环境变量来存储API密钥？

A: 使用环境变量存储API密钥可以防止密钥在代码库中被意外泄露。如果密钥被硬编码在代码中，一旦代码库被公开或被攻击者访问，密钥就会暴露。环境变量可以在部署时设置，且不会被包含在版本控制系统中。

Q: 如何防止输入注入攻击？

A: 为了防止输入注入攻击，应该对所有用户输入进行验证和转义。这包括使用参数化查询来防止SQL注入，以及使用HTML实体编码来防止XSS攻击。此外，可以使用专门的库或框架来帮助处理这些安全问题。

Q: 为什么输出内容需要人工审核？

A: 人工审核输出内容可以确保内容不包含敏感信息或误导性信息，这对于维护品牌声誉和用户信任至关重要。审核过程应该记录下来，以便于追踪和审计。

Q: 如何处理依赖漏洞？

A: 定期更新依赖版本是处理依赖漏洞的关键。可以使用自动化工具如Snyk或OWASP Dependency-Check来扫描项目中的依赖项，并自动更新有漏洞的依赖项。

Q: 如何监控并发冲突和资源耗尽？

A: 通过实施资源监控和警报系统，如Prometheus和Grafana，可以监控应用程序的性能和资源使用情况。进行并发压力测试可以帮助识别并发问题，并确保应用程序能够处理高负载。

核心特性

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

功能概览

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

初始配置

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪