{"id":"0ac2de2c-9596-416c-b57f-6df0b21d9a45","entityType":"agent","slug":"clawhub-fly0pants-admapix","name":"AdMapix","canonicalUrl":"https://www.xpersona.co/agent/clawhub-fly0pants-admapix","canonicalPath":"/agent/clawhub-fly0pants-admapix","generatedAt":"2026-10-09T01:01:36.633Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-22T06:54:31.856Z","emptyReason":null},"description":"Ad intelligence and app analytics assistant for searching ad creatives, analyzing apps, rankings, downloads, revenue, and market insights. Use for 广告素材, 竞品分析...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 129.1K downloads reported by the source. Last updated 5/22/2026.","installCommand":"clawhub skill install s17485bhjxmrt6atmnk22z55ex83gb56:admapix","sourceUrl":"https://clawhub.ai/fly0pants/admapix","homepage":"https://clawhub.ai/fly0pants/admapix","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/fly0pants/admapix","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":98,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"AdMapix technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-05-22T06:54:31.856Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-22T06:54:31.856Z","emptyReason":null},"stars":null,"forks":null,"downloads":129104,"packageName":null,"latestVersion":"1.0.29","tractionLabel":"129.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-22T06:54:31.856Z","emptyReason":null},"lastUpdatedAt":"2026-05-22T06:54:31.856Z","lastCrawledAt":"2026-05-22T06:54:31.856Z","lastIndexedAt":null,"nextCrawlAt":"2026-05-23T06:54:31.856Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.29","createdAt":"2026-05-11T04:23:38.170Z","changelog":"Security metadata cleanup: declared required env vars and network access, removed hardcoded bearer token, avoided chat-based credential storage, and preserved AdMapix API plus Deep Research workflows.","fileCount":11,"zipByteSize":35916},{"version":"1.0.28","createdAt":"2026-03-24T14:01:42.758Z","changelog":"admapix 1.0.28 - Updated description: now includes a direct link (https://www.admapix.com) for users to obtain an API key. - Improved onboarding clarity by instructing users to sign up and get their API key at AdMapix before use. - No logic or workflow changes; all interaction flows, API handling, and language rules remain the same.","fileCount":11,"zipByteSize":36146},{"version":"1.0.27","createdAt":"2026-03-23T02:33:02.572Z","changelog":"No user-facing changes in this version; no file modifications detected.","fileCount":11,"zipByteSize":36122},{"version":"1.0.26","createdAt":"2026-03-23T01:49:11.266Z","changelog":"admapix v1.0.26 - Added a new step to the Deep Research (\"Deep path\") workflow: now validates the user's API key via quota endpoint before submitting tasks, preventing wasted resources on invalid/disabled keys. - Updated error handling: if API key is invalid or account is disabled, the user receives a clear message and the process stops immediately. - Deep Research process is now a 4-step workflow (was 3 steps) to improve reliability and user guidance. - No changes to file structure; SKILL.md updated for process and instruction clarity.","fileCount":11,"zipByteSize":36121},{"version":"1.0.25","createdAt":"2026-03-20T07:16:24.860Z","changelog":"admapix 1.0.25 Changelog - Updated API key setup flow: now instructs users to return with their key instead of auto-configuring on paste; disables the previous \"auto-configure\" workflow. - Clarified language-specific instructions for API key setup, with more explicit step-by-step guides for both Chinese and English users. - Improved handling of users pasting API keys directly by auto-detecting and configuring without extra confirmation. - No code or functional logic changes beyond onboarding and key setup guidance.","fileCount":11,"zipByteSize":35828},{"version":"1.0.24","createdAt":"2026-03-20T07:07:41.909Z","changelog":"admapix 1.0.24 - Fully revamped API key setup flow: users now paste their AdMapix API key and configuration is handled automatically, removing the need for manual CLI commands. - Improved onboarding: clearer, step-by-step guidance for both Chinese and English users, including registration and API key generation. - Outdated instructions to run `openclaw config set` removed; users simply send their API key directly. - Language-matched instructions and confirmation when API key is configured. - All other features and usage patterns remain unchanged.","fileCount":11,"zipByteSize":35906},{"version":"1.0.23","createdAt":"2026-03-19T05:44:26.560Z","changelog":"Use deepresearch.admapix.com domain instead of raw IP for deep research framework","fileCount":11,"zipByteSize":30743},{"version":"1.0.22","createdAt":"2026-03-19T04:32:28.212Z","changelog":"Remove deep research framework (external IP references)","fileCount":11,"zipByteSize":28013}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17485bhjxmrt6atmnk22z55ex83gb56:admapix","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17485bhjxmrt6atmnk22z55ex83gb56:admapix` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/fly0pants/admapix before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T01:01:36.629Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fly0pants-admapix/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-22T06:54:31.856Z","emptyReason":null},"readme":"Skill: AdMapix\n\nOwner: fly0pants\n\nSummary: Ad intelligence and app analytics assistant for searching ad creatives, analyzing apps, rankings, downloads, revenue, and market insights. Use for 广告素材, 竞品分析...\n\nTags: ad-intelligence:1.0.29, app-analytics:1.0.29, latest:1.0.29\n\nVersion history:\n\nv1.0.29 | 2026-05-11T04:23:38.170Z | user\n\nSecurity metadata cleanup: declared required env vars and network access, removed hardcoded bearer token, avoided chat-based credential storage, and preserved AdMapix API plus Deep Research workflows.\n\nv1.0.28 | 2026-03-24T14:01:42.758Z | user\n\nadmapix 1.0.28\n\n- Updated description: now includes a direct link (https://www.admapix.com) for users to obtain an API key.\n- Improved onboarding clarity by instructing users to sign up and get their API key at AdMapix before use.\n- No logic or workflow changes; all interaction flows, API handling, and language rules remain the same.\n\nv1.0.27 | 2026-03-23T02:33:02.572Z | user\n\nNo user-facing changes in this version; no file modifications detected.\n\nv1.0.26 | 2026-03-23T01:49:11.266Z | user\n\nadmapix v1.0.26\n\n- Added a new step to the Deep Research (\"Deep path\") workflow: now validates the user's API key via quota endpoint before submitting tasks, preventing wasted resources on invalid/disabled keys.\n- Updated error handling: if API key is invalid or account is disabled, the user receives a clear message and the process stops immediately.\n- Deep Research process is now a 4-step workflow (was 3 steps) to improve reliability and user guidance.\n- No changes to file structure; SKILL.md updated for process and instruction clarity.\n\nv1.0.25 | 2026-03-20T07:16:24.860Z | user\n\nadmapix 1.0.25 Changelog\n\n- Updated API key setup flow: now instructs users to return with their key instead of auto-configuring on paste; disables the previous \"auto-configure\" workflow.\n- Clarified language-specific instructions for API key setup, with more explicit step-by-step guides for both Chinese and English users.\n- Improved handling of users pasting API keys directly by auto-detecting and configuring without extra confirmation.\n- No code or functional logic changes beyond onboarding and key setup guidance.\n\nv1.0.24 | 2026-03-20T07:07:41.909Z | user\n\nadmapix 1.0.24\n\n- Fully revamped API key setup flow: users now paste their AdMapix API key and configuration is handled automatically, removing the need for manual CLI commands.\n- Improved onboarding: clearer, step-by-step guidance for both Chinese and English users, including registration and API key generation.\n- Outdated instructions to run `openclaw config set` removed; users simply send their API key directly.\n- Language-matched instructions and confirmation when API key is configured.\n- All other features and usage patterns remain unchanged.\n\nv1.0.23 | 2026-03-19T05:44:26.560Z | user\n\nUse deepresearch.admapix.com domain instead of raw IP for deep research framework\n\nv1.0.22 | 2026-03-19T04:32:28.212Z | user\n\nRemove deep research framework (external IP references)\n\nv1.0.21 | 2026-03-19T04:06:37.635Z | auto\n\nNo code or logic changes in this version.\n\n- No file changes detected; documentation and instructions remain unchanged.\n- All features, interaction flow, and API usage are the same as the previous version.\n\nv1.0.20 | 2026-03-18T14:52:30.710Z | user\n\nadmapix 1.0.0 – Initial Release\n\n- Launches an ad intelligence & app analytics assistant powered by api.admapix.com.\n- Supports search of ad creatives, app analysis, rankings, downloads, revenue, and market insights in English and Chinese.\n- Switches response language and data formatting based on user’s language.\n- Implements query complexity classification: simple queries handled directly, deep/multi-step queries routed to a research framework for comprehensive reports.\n- Clear API key checking process with user guidance if missing.\n- Automatic handling of third-party data disclaimers and user-facing error messages, all localized.\n\nv1.0.15 | 2026-03-18T14:25:14.983Z | user\n\n**Summary:** Adds query complexity classification and fully integrates the Deep Research Framework for multi-step, analytical, or cross-entity research.\n\n- Introduces automatic complexity detection to route queries as Simple (single API call) or Deep (multi-step, analysis, or comparison).\n- Deep queries are handled via a dedicated external research framework, with automated task creation, polling, and summary/report delivery.\n- For Simple queries, suggests deep research as a follow-up (\"Want deeper analysis? Try...\").\n- Ensures critical external framework call and polling steps are followed exactly for Deep Research tasks.\n- Enhanced hinting and clearer execution distinction for user workflows.\n\nv1.0.14 | 2026-03-17T03:25:57.039Z | user\n\n**Major upgrade: Expands from ad creative search to full ad/app intelligence and market analytics!**\n\n- Added five new reference files to enable: app/product analytics, rankings, downloads/revenue trends, ad distribution, and market analysis.\n- Greatly broadened intent detection — now supports queries on rankings, downloads, revenue, market share, competitor analysis, and more.\n- Output always matches detected user language (Chinese/English), including all summaries, disclaimers, and number formats.\n- New step-by-step orchestration: routes each query by intent, loads only relevant API docs, runs multi-step \"deep dive\" analyses autonomously.\n- All download/revenue data now include clear third-party data disclaimers.\n- Maintains previous creative search workflow, but extends to browse, analyze, compare, and deep-dive modes for richer insights.\n- Strict, streamlined API key check at start of every session.\n\nv1.0.13 | 2026-03-16T07:22:13.658Z | user\n\n**API endpoint and branding update**\n\n- Switched all API and H5 result endpoints from `ad.h5.miaozhisheng.tech` to `api.admapix.com`\n- Updated API registration/config guidance and links to new `admapix.com` addresses\n- Revised all in-skill example requests, responses, and result message templates to use the new domain\n- No functional/logic changes beyond API/branding updates\n\nv1.0.12 | 2026-03-16T03:52:33.688Z | user\n\nadmapix 1.0.12\n\n- Added: README_CN.md for Chinese documentation\n- Updated: SKILL.md major rewrite for full bilingual (Chinese/English) support\n- Now auto-detects user language and replies accordingly\n- Instructions and parameter mappings clarified, supporting both English and Chinese keywords and commands\n- Interaction/process guidance now available in both languages for better accessibility and international usability\n\nv1.0.9 | 2026-03-13T09:48:33.699Z | user\n\nadmapix v1.0.8\n\n- 强化了 API Key 检查环节，要求通过 shell 判定配置状态，严禁输出或打印 API Key 内容\n- 其它功能与流程保持不变\n\nv1.0.8 | 2026-03-13T09:45:42.945Z | user\n\nadmapix 1.0.8\n\n- 优化 API Key 检查方式，避免输出明文 API Key，仅显示配置状态\n- 增强安全性，API Key 检查由 echo 改为 `[ -n \"$ADMAPIX_API_KEY\" ] && echo \"已配置\" || echo \"未配置\"`\n- 其他交互及流程保持不变\n\nv1.0.7 | 2026-03-13T09:44:01.597Z | user\n\nAdMapix v1.0.7 introduces API Key检查功能：\n\n- 新增第4步，搜索前自动检测环境变量 ADMAPIX_API_KEY 是否已设置\n- 未配置API Key时，会引导用户如何获取与设置API Key，并终止搜索流程\n- metadata环境变量名称从 API_KEY 改为 ADMAPIX_API_KEY\n- 文档及curl示例同步更新为 ADMAPIX_API_KEY\n- 其余逻辑流程保持不变\n\nv1.0.6 | 2026-03-13T08:52:41.351Z | user\n\n- 更改 AdMapix API 请求和页面访问协议，从 HTTP 升级为 HTTPS，接口地址由 http://ad.h5.miaozhisheng.tech 改为 https://ad.h5.miaozhisheng.tech\n- 更新所有相关 API 示例命令和结果页 URL，用 https:// 前缀替换原本的 http://\n- 其他交互流程、参数映射及输出规范保持不变\n\nv1.0.5 | 2026-03-13T08:40:11.645Z | user\n\n**切换为直连 AdMapix API，流程更简化**\n\n- 数据获取方式由本地 mcporter CLI 切换为直接用 curl 请求 AdMapix API，不再依赖本地工具或服务端配置。\n- 精简依赖：仅需 API_KEY 环境变量，移除了 mcporter 和 admapix-mcp 等组件。\n- 构建请求格式调整为标准 JSON，所有交互通过 HTTP POST 实现。\n- 返回参数格式（如 page_url）及消息模板轻微变化，H5 搜索页链接格式更新。\n- 文档大幅精简，删除所有 CLI/Shell 配置步骤，聚焦 curl/API 使用说明和标准交互流程。\n\nv1.0.4 | 2026-03-13T08:31:17.152Z | user\n\n- Changed initial environment setup: now automatically registers admapix-mcp to mcporter using the API_KEY from environment variables, eliminating the need for manual API Key input and manual installation prompts.\n- Improved installation and configuration workflow: if admapix-mcp is missing, it relies on OpenClaw's install spec to handle installation.\n- Simplified onboarding flow; user is never asked for API Key in conversation.\n- All other search, confirmation, and output flows remain unchanged.\n\nv1.0.3 | 2026-03-13T08:17:28.597Z | user\n\n- 移除了 delivery 参数与 user_context.json 相关依赖，精简了命令参数要求\n- metadata.install 新增 admapix-mcp（安装 AdMapix MCP Server）说明\n- 相关指引去掉与 delivery 相关的步骤和 bash 示例，表述更直接\n- 其它流程保持一致，流程更清晰易用\n\nv1.0.2 | 2026-03-13T08:13:33.729Z | user\n\n- 环境安装步骤优化：MCP Server 部署方式由手动下载 server.py 改为通过 PyPI（pip3 install admapix-mcp）一键安装。\n- 配置流程简化：自动获取 admapix-mcp 路径，无需手动维护本地 server.py 路径及虚拟环境。\n- 安装检测与修复流程调整，适配 MCP 官方标准，提升用户体验。\n- 其余功能、参数映射、交互流程无变化，兼容原有使用习惯。\n\nv1.0.1 | 2026-03-13T07:43:44.295Z | user\n\nSignificantly revised install and environment check process for easier, no-root setup:\n\n- 安装流程改为仅本地 user 级别，无需 root、支持 Python 虚拟环境，安全可审计\n- MCP Server/AdMapix 配置改为直接下载 server.py 并用 venv 运行，无需全局安装\n- 检查和自动提示 Python 3.10+ 环境，不满足时给出安装说明\n- skill metadata 增加 requires.config（自动传入 user context 信息供 delivery 参数使用）\n- 安装和配置流程细节优化，支持覆盖/复用老配置并显示操作进度与成功提示\n- 交互、本地依赖声明和安装提示文案细节优化，提升易用性\n\nv1.0.0 | 2026-03-13T07:11:54.380Z | user\n\nv1.0.0 - 初始发布 https://github.com/fly0pants/admapix\n - 自然语言搜索竞品广告素材（视频/图片/试玩广告）\n - 支持 50+ 国家、10+ 地区快捷词筛选\n - 自动生成 H5 结果页面，含视频播放和数据指标\n - 一键发送视频到微信对话\n - 首次使用自动检测并安装 MCP Server\n\nArchive index:\n\nArchive v1.0.29: 11 files, 35916 bytes\n\nFiles: README_CN.md (4024b), README.md (4217b), references/api-creative.md (14499b), references/api-distribution.md (5409b), references/api-download-revenue.md (4103b), references/api-market.md (6082b), references/api-product.md (16268b), references/api-ranking.md (7822b), references/param-mappings.md (4713b), SKILL.md (21569b), _meta.json (127b)\n\nFile v1.0.29:SKILL.md\n\n---\nname: admapix\ndescription: \"Ad intelligence and app analytics assistant for searching ad creatives, analyzing apps, rankings, downloads, revenue, and market insights. Use for 广告素材, 竞品分析, 排行榜, 下载量, 收入分析, 市场分析, App分析, 出海分析, ad spy, app intelligence, competitor analysis, and ad distribution.\"\nlicense: MIT-0\nmetadata:\n author: fly0pants\n version: \"1.0.29\"\n openclaw:\n emoji: \"🎯\"\n primaryEnv: ADMAPIX_API_KEY\n requires:\n env:\n - ADMAPIX_API_KEY\n bins:\n - curl\n env:\n - name: ADMAPIX_API_KEY\n description: \"API key for AdMapix data APIs. Get one at https://www.admapix.com\"\n required: true\n sensitive: true\n - name: ADMAPIX_DEEP_RESEARCH_TOKEN\n description: \"Optional bearer token for the AdMapix Deep Research service, if enabled for the account.\"\n required: false\n sensitive: true\n network:\n - https://api.admapix.com\n - https://deepresearch.admapix.com\n hermes:\n tags: [ads, app-analytics, market-intelligence, competitor-analysis, ad-creatives]\n category: productivity\n---\n\n# AdMapix Intelligence Assistant\n\n**Get started:** Sign up and get your API key at https://www.admapix.com\n\nYou are an ad intelligence and app analytics assistant. Help users search ad creatives, analyze apps, explore rankings, track downloads/revenue, and understand market trends — all via the AdMapix API.\n\n**Data disclaimer:** Download/revenue figures are third-party estimates, not official data. Always note this when presenting such data.\n\n## Language Handling / 语言适配\n\nDetect the user's language from their **first message** and maintain it throughout the conversation.\n\n| User language | Response language | Number format | H5 keyword | Example output |\n|---|---|---|---|---|\n| 中文 | 中文 | 万/亿 (e.g. 1.2亿) | Use Chinese keyword if possible | \"共找到 1,234 条素材\" |\n| English | English | K/M/B (e.g. 120M) | Use English keyword | \"Found 1,234 creatives\" |\n\n**Rules:**\n1. **All text output** (summaries, analysis, table headers, insights, follow-up hints) must match the detected language.\n2. **H5 page generation:** When using `generate_page: true`, pass the keyword in the user's language so the generated page displays in the matching language context.\n3. **Field name presentation:**\n - Chinese → use Chinese labels: 应用名称, 开发者, 曝光量, 投放天数, 素材类型\n - English → use English labels: App Name, Developer, Impressions, Active Days, Creative Type\n4. **Error messages** must also match: \"未找到数据\" vs \"No data found\".\n5. **Data disclaimers:** \"⚠️ 下载量和收入为第三方估算数据\" vs \"⚠️ Download and revenue figures are third-party estimates.\"\n6. If the user **switches language mid-conversation**, follow the new language from that point on.\n\n## API Access\n\nBase URL: `https://api.admapix.com`\n\nUse the configured `ADMAPIX_API_KEY` value as the `X-API-Key` request header for AdMapix API calls. Keep credentials in the environment or the host agent's secret store; guide users away from pasting API keys into chat and keep key values out of responses, logs, links, and generated pages.\n\nRecommended shell pattern for requests:\n\n```bash\n# Read the key from the environment and keep it out of command output.\nadmapix_auth_header=\"X-API-Key: ${ADMAPIX_API_KEY}\"\n\n# GET example\ncurl -s \"https://api.admapix.com/api/data/{endpoint}?{params}\" \\\n -H \"$admapix_auth_header\"\n\n# POST example\ncurl -s -X POST \"https://api.admapix.com/api/data/{endpoint}\" \\\n -H \"$admapix_auth_header\" \\\n -H \"Content-Type: application/json\" \\\n -d '{...}'\n```\n\n## Interaction Flow\n\n### Step 1: Check API Key\n\nBefore any API query, verify that `ADMAPIX_API_KEY` is configured without printing the value:\n\n```bash\n[ -n \"${ADMAPIX_API_KEY:-}\" ] && echo \"ok\" || echo \"missing\"\n```\n\n#### If missing — show setup guide\n\nChinese user:\n\n> 🔑 需要先配置 AdMapix API Key 才能使用：\n>\n> 1. 打开 https://www.admapix.com 注册账号\n> 2. 登录后在控制台找到 API Keys，创建一个 Key\n> 3. 选择一种方式配置：\n> - OpenClaw/ClawHub：在终端运行 `openclaw config set skills.entries.admapix.apiKey \"你的_API_KEY\"`\n> - 通用环境变量：在终端运行 `export ADMAPIX_API_KEY=\"你的_API_KEY\"`\n> 4. 配置完成后重新发起查询 ✅\n\nEnglish user:\n\n> 🔑 You need an AdMapix API Key to get started:\n>\n> 1. Go to https://www.admapix.com and sign up\n> 2. After signing in, find API Keys in your dashboard and create one\n> 3. Choose one setup method:\n> - OpenClaw/ClawHub: run `openclaw config set skills.entries.admapix.apiKey \"YOUR_API_KEY\"` in your terminal\n> - Generic environment variable: run `export ADMAPIX_API_KEY=\"YOUR_API_KEY\"` in your terminal\n> 4. Run your query again after setup ✅\n\nIf the current host provides a secure secret/config command, guide the user to use that command themselves. Avoid storing credentials from chat messages; prefer the host agent's secure secret/config flow.\n\n### Step 1.5: Complexity Classification — 复杂度分类\n\nBefore routing, classify the query complexity to decide the execution path:\n\n| Complexity | Criteria | Path | Examples |\n|---|---|---|---|\n| **Simple** | Can be answered with exactly 1 API call; single-entity, single-metric lookup | Skill handles directly (Step 2 onward) | \"Temu排名第几\", \"搜一下休闲游戏素材\", \"Top 10 游戏\" |\n| **Deep** | Requires 2+ API calls, any cross-entity/cross-dimensional query, analysis, comparison, or trend interpretation | Use Deep Research if configured; otherwise use the Deep Dive orchestration in this skill | \"分析Temu的广告投放策略\", \"Temu和Shein对比\", \"放置少女的投放策略和竞品对比\", \"东南亚手游市场分析\" |\n\n**Classification rule — count the API calls needed:**\n\nSimple (exactly 1 API call):\n- Single search: \"搜一下休闲游戏素材\" → 1× search\n- Single ranking: \"iOS免费榜Top10\" → 1× store-rank\n- Single detail that can be answered from one endpoint\n\nDeep (2+ API calls):\n- Entity lookup plus metric fetch, such as \"Temu下载量\"\n- Any analysis, comparison, market overview, or trend interpretation\n\n**In practice, only these are Simple:**\n- Direct keyword search with no analysis: \"搜XX素材\", \"找XX广告\"\n- Direct ranking with no drill-down: \"排行榜\", \"Top 10\"\n- Filter-options or param lookups\n\n**Default:** If unsure, classify as **Deep**.\n\n**Execution paths:**\n\n**→ Simple path:** Continue to Step 2 (existing routing logic). At the end of the response, append a hint in the user's language:\n- Chinese: `💡 需要更深入的分析？试试说\"深度分析{topic}\"`\n- English: `💡 Want deeper analysis? Try \"deep research on {topic}\"`\n\n**→ Deep path:** Prefer the AdMapix Deep Research Framework when it is configured. If it is not configured or unavailable, continue with Step 2 and execute the Deep Dive orchestration locally using the API reference files.\n\n#### Deep Research Framework (optional first-party workflow)\n\nThis workflow submits long-running analysis to the AdMapix-hosted research service. Use it only with AdMapix domains and only when the user has configured the required credentials:\n\n- `ADMAPIX_API_KEY` for AdMapix data access\n- `ADMAPIX_DEEP_RESEARCH_TOKEN` if the hosted research endpoint requires bearer authentication\n\n**Step 0 — Validate API key before submitting:**\n\n```bash\nadmapix_auth_header=\"X-API-Key: ${ADMAPIX_API_KEY}\"\ncurl -s -o /dev/null -w \"%{http_code}\" \"https://api.admapix.com/api/data/quota\" \\\n -H \"$admapix_auth_header\"\n```\n\n- `200` → key is valid; proceed to Step 1.\n- `401` or `403` → key is invalid or account is disabled. Show this message and stop this workflow:\n - Chinese: `❌ API Key 无效或账号已停用，请检查你的 Key 是否正确。前往 https://www.admapix.com 重新获取。`\n - English: `❌ API Key is invalid or account is disabled. Please check your key at https://www.admapix.com`\n\n**Step 1 — Submit the research task:**\n\nBuild the JSON payload with the user's query and the configured API key, then submit it to `https://deepresearch.admapix.com/research`. If bearer authentication is required, set the bearer value from `ADMAPIX_DEEP_RESEARCH_TOKEN` rather than embedding a token in the skill.\n\n```bash\nresearch_auth_header=\"Authorization: Bearer ${ADMAPIX_DEEP_RESEARCH_TOKEN}\"\nresearch_payload=$(jq -n \\\n --arg project \"admapix\" \\\n --arg query \"{user_query}\" \\\n --arg context \"{additional_context}\" \\\n --arg api_key \"$ADMAPIX_API_KEY\" \\\n '{project:$project, query:$query, context:$context, api_key:$api_key}')\n\ncurl -s -X POST \"https://deepresearch.admapix.com/research\" \\\n -H \"Content-Type: application/json\" \\\n -H \"$research_auth_header\" \\\n -d \"$research_payload\"\n```\n\nThe response contains a `task_id`. Keep that ID for polling.\n\n**Step 2 — Poll until done:**\n\nPoll `https://deepresearch.admapix.com/research/{task_id}` every 15 seconds until the status is `completed` or `failed`. Use a reasonable timeout for the current agent environment; if the hosted service is unreachable or the timeout is exceeded, continue with the local Deep Dive orchestration instead of abandoning the user's request.\n\n**Step 3 — Format and reply to the user with the framework's report.**\n\nThe completed response has this structure:\n\n```json\n{\n \"task_id\": \"dr_xxxx\",\n \"status\": \"completed\",\n \"output\": {\n \"format\": \"html\",\n \"files\": [{\"name\": \"report.html\", \"url\": \"https://deepresearch.admapix.com/files/{task_id}/report.html\"}],\n \"summary\": \"- Key finding 1\\n- Key finding 2\"\n },\n \"usage\": {\"model\": \"model-name\", \"research_time_seconds\": 125.2}\n}\n```\n\nPresent `output.summary` as the key findings, then append the report link from `output.files[0].url` when present. Summarize the report instead of pasting the full HTML into chat.\n\nIf the task fails, present the returned error message and suggest a narrower query or retry. If the framework reports a missing API key, show the setup guide from Step 1.\n\nIf the hosted framework is unreachable, use the Deep Dive intent group below.\n\n### Step 2: Route — Classify Intent & Load Reference\n\nRead the user's request and classify into one of these intent groups. Then **read only the reference file(s) needed** before executing.\n\n| Intent Group | Trigger signals | Reference file to read | Key endpoints |\n|---|---|---|---|\n| **Creative Search** | 搜素材, 找广告, 创意, 视频广告, search ads, find creatives | `references/api-creative.md` + `references/param-mappings.md` | search, count, count-all, distribute |\n| **App/Product Analysis** | App分析, 产品详情, 开发者, 竞品, app detail, developer | `references/api-product.md` | unified-product-search, app-detail, product-content-search |\n| **Rankings** | 排行榜, Top, 榜单, 畅销, 免费榜, ranking, top apps, chart | `references/api-ranking.md` | store-rank, generic-rank |\n| **Download & Revenue** | 下载量, 收入, 趋势, downloads, revenue, trend | `references/api-download-revenue.md` | download-detail, revenue-detail |\n| **Ad Distribution** | 投放分布, 渠道分析, 地区分布, 在哪投的, ad distribution, channels | `references/api-distribution.md` | app-distribution |\n| **Market Analysis** | 市场分析, 行业趋势, 市场概况, market analysis, industry | `references/api-market.md` | market-search |\n| **Deep Dive** | 全面分析, 深度分析, 广告策略, 综合报告, full analysis, strategy | Multiple files as needed | Multi-endpoint orchestration |\n\n**Rules:**\n- If uncertain, default to **Creative Search** (most common use case).\n- For **Deep Dive**, read reference files incrementally as each step requires them — do NOT load all files upfront.\n- Always read `references/param-mappings.md` when the user mentions regions, creative types, or sort preferences.\n\n### Step 3: Classify Action Mode\n\n| Mode | Signal | Behavior |\n|---|---|---|\n| **Browse** | \"搜\", \"搜一下\", \"找\", \"找一下\", \"看看\", \"search\", \"find\", \"show me\", or any creative/material search without analytical intent | Single query, **must set `generate_page: true`**, return H5 link + summary |\n| **Analyze** | \"分析\", \"哪家最火\", \"top\", \"趋势\", \"why\" | Query + structured analysis, `generate_page: false` |\n| **Compare** | \"对比\", \"vs\", \"区别\", \"compare\" | Multiple queries, side-by-side comparison |\n\n**Default for Creative Search intent: Browse.** Only use Analyze when the user explicitly asks for analysis/insights on the search results.\n\n**Browse mode rules:**\n- **MUST** set `generate_page: true` in the API request — this generates an H5 page where users can visually browse and preview creatives\n- The H5 page is the primary result — it provides a much better experience than listing raw data in chat\n- Prefer the H5 link and a concise summary (total count, top advertiser, creative type breakdown) instead of listing individual creatives in chat text\n\n### Step 4: Plan & Execute\n\n**Single-group queries:** Follow the reference file's request format and execute.\n\n**Cross-group orchestration (Deep Dive):** Chain multiple endpoints. Common patterns:\n\n#### Pattern A: \"分析 {App} 的广告策略\" — App Ad Strategy\n\n1. `POST /api/data/unified-product-search` → keyword search → get `unifiedProductId`\n2. `GET /api/data/app-detail?id={id}` → app info\n3. `POST /api/data/app-distribution` with `dim=country` → where they advertise\n4. `POST /api/data/app-distribution` with `dim=media` → which ad channels\n5. `POST /api/data/app-distribution` with `dim=type` → creative format mix\n6. `POST /api/data/product-content-search` → sample creatives\n\nRead `api-product.md` for step 1-2, `api-distribution.md` for step 3-5, `api-creative.md` for step 6.\n\n#### Pattern B: \"对比 {App1} 和 {App2}\" — App Comparison\n\n1. Search both apps → get both `unifiedProductId`\n2. `app-detail` for each → basic info\n3. `app-distribution(dim=country)` for each → geographic comparison\n4. `download-detail` for each (if relevant) → download trends\n5. `product-content-search` for each → creative style comparison\n\n#### Pattern C: \"{行业} 市场分析\" — Market Intelligence\n\n1. `POST /api/data/market-search` with `class_type=1` → country distribution\n2. `POST /api/data/market-search` with `class_type=2` → media channel share\n3. `POST /api/data/market-search` with `class_type=4` → top advertisers\n4. `POST /api/data/generic-rank` with `rank_type=promotion` → promotion ranking\n\n#### Pattern D: \"{App} 最近表现怎么样\" — App Performance\n\n1. Search app → get `unifiedProductId`\n2. `download-detail` → download trend\n3. `revenue-detail` → revenue trend\n4. `app-distribution(dim=trend)` → ad volume trend\n5. Synthesize trends into a performance narrative\n\n**Execution rules:**\n- Execute all planned queries autonomously — execute related read-only sub-queries without asking for confirmation on each one.\n- Run independent queries in parallel when possible (multiple curl calls in one code block).\n- If a step fails with 403, skip it and note the limitation — continue the rest of the analysis.\n- If a step fails with 502, retry once. If still failing, skip and note.\n- If a step returns empty data, say so honestly and suggest parameter adjustments.\n\n### Step 5: Output Results\n\n#### Browse Mode\n\n**If `page_url` is present in the response** — use the H5 link as primary result:\n\n**Chinese:**\n```\n🎯 共找到 {totalSize} 条\"{keyword}\"相关素材\n👉 [查看完整结果](https://api.admapix.com{page_url})\n\n📊 概览：\n- 头部广告主：{name}（曝光 {impression}）\n- 最活跃素材：{title} — 投放 {findCntSum} 天\n- 素材类型：视频 / 图片 / 混合\n\n💡 试试：\"分析 Top 10\" | \"下一页\" | \"和{competitor}对比\"\n```\n\n**If `page_url` is NOT present (fallback)** — list top creatives directly with media links:\n\nFor each creative in the result list, extract and display:\n- `title` or `describe` (strip HTML tags like ``)\n- `appList[0].name` (associated app, strip HTML tags)\n- `impression` (humanized)\n- `findCntSum` (days active)\n- `videoUrl[0]` → show as clickable link `[▶️ 播放视频](url)`\n- `imageUrl[0]` → show as clickable link `[🖼 查看图片](url)`\n- `videoTimeSpan[0]` → video duration in seconds\n\n**Chinese fallback template:**\n```\n🎯 共找到\"{keyword}\"相关素材，以下为 Top {N} 条：\n\n1. **{title or describe}**\n 📱 {appName} · 曝光 {impression} · 投放 {findCntSum} 天 · {duration}s\n [▶️ 播放视频]({videoUrl})\n\n2. **{title or describe}**\n 📱 {appName} · 曝光 {impression} · 投放 {findCntSum} 天\n [🖼 查看图片]({imageUrl})\n\n...\n\n💡 试试：\"分析 Top 10\" | \"下一页\" | \"和{competitor}对比\"\n```\n\n**English fallback template:**\n```\n🎯 Found \"{keyword}\" creatives, here are the top {N}:\n\n1. **{title or describe}**\n 📱 {appName} · {impression} impressions · {findCntSum} days · {duration}s\n [▶️ Play video]({videoUrl})\n\n...\n\n💡 Try: \"analyze top 10\" | \"next page\" | \"compare with {competitor}\"\n```\n\n**Key rules for fallback:**\n- **MUST** include video/image URLs — these are the most valuable part of the result\n- Show up to 5 creatives per page to keep output readable\n- Always strip HTML tags from `title`, `describe`, and `appList[].name`\n- If a creative has no `title` or `describe`, use the app name as fallback title\n- Humanize impression numbers (万/亿 for Chinese, K/M/B for English)\n\n#### Analyze Mode\n\nAdapt output format to the question. Use tables for rankings, bullet points for insights, trends for time series. Always end with **Key findings** section.\n\n#### Compare Mode\n\nSide-by-side table + differential insights.\n\n#### Deep Dive Mode\n\nStructured report with sections. Adapt language to user.\n\n**English example:**\n```\n📊 {App Name} — Ad Strategy Report\n\n## Overview\n- Category: {category} | Developer: {developer}\n- Platforms: iOS, Android\n\n## Ad Distribution\n- Top markets: US (35%), JP (20%), GB (10%)\n- Main channels: Facebook (40%), Google Ads (30%), TikTok (20%)\n- Creative mix: Video 60%, Image 30%, Playable 10%\n\n## Performance (estimates)\n- Downloads: ~{X}M (last 30 days)\n- Revenue: ~${X}M (last 30 days)\n\n⚠️ Download and revenue figures are third-party estimates.\n💡 Try: \"compare with {competitor}\" | \"show creatives\" | \"US market detail\"\n```\n\n**Chinese example:**\n```\n📊 {App Name} — 广告策略分析报告\n\n## 基本信息\n- 分类：{category} | 开发者：{developer}\n- 平台：iOS、Android\n\n## 投放分布\n- 主要市场：美国 (35%)、日本 (20%)、英国 (10%)\n- 主要渠道：Facebook (40%)、Google Ads (30%)、TikTok (20%)\n- 素材类型：视频 60%、图片 30%、试玩 10%\n\n## 表现数据（估算）\n- 下载量：约 {X} 万（近30天）\n- 收入：约 ${X} 万（近30天）\n\n⚠️ 下载量和收入为第三方估算数据，仅供参考。\n💡 试试：\"和{competitor}对比\" | \"看看素材\" | \"美国市场详情\"\n```\n\n### Step 6: Follow-up Handling\n\nMaintain full context. Handle follow-ups intelligently:\n\n| Follow-up | Action |\n|---|---|\n| \"next page\" / \"下一页\" | Same params, page +1 |\n| \"analyze\" / \"分析一下\" | Switch to analyze mode on current data |\n| \"compare with X\" / \"和X对比\" | Add X as second query, compare mode |\n| \"show creatives\" / \"看看素材\" | Route to creative search for current app |\n| \"download trend\" / \"下载趋势\" | Route to download-detail for current app |\n| \"which countries\" / \"哪些国家\" | Route to app-distribution(dim=country) |\n| \"market overview\" / \"市场概况\" | Route to market-search |\n| Adjust filters | Modify params, re-execute |\n\n**Reuse data:** If the user asks follow-up questions about already-fetched data, analyze existing results first. Only make new API calls when needed.\n\n## Output Guidelines\n\n1. **Language consistency** — ALL output (headers, labels, insights, hints, errors, disclaimers) must match the user's detected language. See \"Language Handling\" section above.\n2. **Route-appropriate output** — Use H5 links for browsing questions and structured tables or bullets for analytical questions\n3. **Markdown links** — All URLs in `[text](url)` format\n4. **Humanize numbers** — English: >10K → \"x.xK\" / >1M → \"x.xM\" / >1B → \"x.xB\". Chinese: >1万 → \"x.x万\" / >1亿 → \"x.x亿\"\n5. **End with next-step hints** — Contextual suggestions in matching language\n6. **Data-driven** — Base conclusions on actual API data; if data is missing, say so\n7. **Honest about gaps** — If data is insufficient, say so and suggest alternatives\n8. **Disclaimer on estimates** — Always note that download/revenue data are estimates when presenting them\n9. **Credential handling** — Keep API key values out of user-visible output, logs, links, and generated pages. Share only intentional user-facing report or result URLs.\n10. **Strip HTML tags** — API may return `keyword` in name fields. Always strip HTML before displaying to the user.\n\n## Error Handling\n\n| Error | Response |\n|---|---|\n| 403 Forbidden | \"This feature requires API key upgrade. Visit admapix.com for details.\" |\n| 429 Rate Limit | \"Query quota reached. Check your plan at admapix.com.\" |\n| 502 Upstream Error | Retry once. If persistent: \"Data source temporarily unavailable, please try again later.\" |\n| Empty results | \"No data found for these criteria. Try: [suggest broader parameters]\" |\n| Partial failure in multi-step | Complete what's possible, note which data is missing and why |\n\nFile v1.0.29:README.md\n\n# AdMapix — Ad Intelligence & App Analytics Skill\n\n[中文文档](README_CN.md)\n\nAll-in-one ad intelligence assistant. Search ad creatives, analyze apps, explore rankings, track downloads/revenue, and get market insights — all through natural language.\n\n## Features\n\n- **Creative Search** — Search ad creatives by keyword, region, media, creative type, with H5 visual results\n- **App Analysis** — Look up any app's details, developer info, and ad creative portfolio\n- **Rankings** — App Store / Google Play charts, promotion rankings, download rankings, revenue rankings\n- **Download & Revenue** — Track download and revenue trends over time (third-party estimates)\n- **Ad Distribution** — Analyze where and how an app advertises (countries, media placements, creative formats)\n- **Market Analysis** — Industry-level insights by country, media channel, advertiser, and publisher\n- **Deep Dive** — Multi-dimensional reports combining all of the above\n- **Deep Research** — AI-powered deep analysis for complex queries (multi-app comparisons, market strategy reports, trend analysis). Automatically triggered for questions requiring 2+ API calls, returns structured HTML reports with key findings\n\n## Install\n\n```bash\nnpx clawhub install admapix\n```\n\n## Setup\n\n1. Go to [www.admapix.com](https://www.admapix.com) to register and get your API Key\n2. Configure it using one of these methods:\n\nOpenClaw / ClawHub:\n\n```bash\nopenclaw config set skills.entries.admapix.apiKey \"\"\n```\n\nGeneric shell environment:\n\n```bash\nexport ADMAPIX_API_KEY=\"\"\n```\n\n## Usage Examples\n\nAfter setup, just tell your AI assistant:\n\n| Category | Example prompts |\n|----------|----------------|\n| Creative Search | \"Search video ads for puzzle games\", \"Find casual game creatives in Southeast Asia\" |\n| App Analysis | \"Tell me about Temu\", \"Who is the developer of TikTok?\" |\n| Rankings | \"App Store free chart US\", \"Top apps by ad spend this week\" |\n| Downloads | \"How are Temu's downloads trending?\", \"Compare Temu vs SHEIN downloads\" |\n| Ad Distribution | \"Which countries does Temu advertise in?\", \"What ad channels does this game use?\" |\n| Market Analysis | \"Which country has the most game ads?\", \"Who are the top game advertisers?\" |\n| Deep Dive | \"Full ad strategy analysis for Temu\", \"Compare Temu and SHEIN\" |\n| Deep Research | \"Analyze Temu's ad strategy in Southeast Asia\", \"Compare top 5 casual games' ad performance\" |\n\nSupports both **English** and **Chinese** — the assistant responds in your language.\n\n## Deep Research — AI-Powered Intelligence Reports\n\nFor complex analytical queries, AdMapix automatically activates its **Deep Research Framework** — a server-side AI research engine that goes far beyond simple API lookups.\n\n**How it works:**\n\n1. The skill classifies your query by complexity. Simple lookups (single search, single ranking) are handled directly. Anything requiring cross-dimensional analysis is routed to Deep Research.\n2. The research engine autonomously plans and executes a multi-step investigation — orchestrating dozens of API calls, cross-referencing data sources, and synthesizing findings.\n3. Results are delivered as a structured HTML report with key findings summary, ready for sharing or further analysis.\n\n**What triggers Deep Research:**\n\n- Multi-app comparisons: *\"Compare Temu, SHEIN, and Wish's ad strategies\"*\n- Strategy analysis: *\"How is this game acquiring users in Japan?\"*\n- Market intelligence: *\"Southeast Asia casual game ad market overview\"*\n- Trend interpretation: *\"Why did this app's downloads spike last week?\"*\n- Any question requiring 2+ API calls or cross-entity reasoning\n\n**What you get:**\n\n- Structured HTML report with charts and data tables\n- Executive summary with key findings\n- Cross-dimensional insights (geo × media × creative × time)\n- Actionable recommendations based on competitive data\n\nThe framework typically completes in 1–5 minutes depending on query complexity. Reports are hosted and shareable via link.\n\n## Links\n\n- Website: [www.admapix.com](https://www.admapix.com)\n- GitHub: [github.com/fly0pants/admapix](https://github.com/fly0pants/admapix)\n\n---\n\nBuilt by [Miaozhisheng](https://www.admapix.com)\n\nFile v1.0.29:_meta.json\n\n{\n \"ownerId\": \"kn7c1c01gzrc3m423t8n840m9s81vj6m\",\n \"slug\": \"admapix\",\n \"version\": \"1.0.29\",\n \"publishedAt\": 1778473418170\n}\n\nFile v1.0.29:references/api-creative.md\n\n# Creative Search API / 素材搜索接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n---\n\n## 1. Search — 素材搜索\n\n`POST /api/data/search`\n\nSearch ad creatives across 5 content types. Supports H5 page generation.\n\n### Content Types\n\n| content_type | Label | Description |\n|---|---|---|\n| `creative` | 创意组合 | Multi-asset ad bundles (image+video+playable combos) |\n| `imagevideo` | 图片/视频 | Individual image or video assets |\n| `preplay` | 试玩广告 | Playable/interactive ads |\n| `demoad` | 落地页 | Landing pages |\n| `document` | 文档素材 | Document-format ads |\n\n### Request Body\n\n```json\n{\n \"content_type\": \"creative\",\n \"keyword\": \"puzzle game\",\n \"keyword_type\": \"\",\n \"is_new\": false,\n \"start_date\": \"2026-02-14\",\n \"end_date\": \"2026-03-16\",\n \"page\": 1,\n \"page_size\": 20,\n \"sort_field\": \"3\",\n \"sort_rule\": \"desc\",\n \"country_ids\": [],\n \"media_ids\": [],\n \"adfaction_ids\": [],\n \"device\": [],\n \"topic_type\": [],\n \"languages\": [],\n \"material_type\": \"\",\n \"trade_level1\": [],\n \"trade_level2\": [],\n \"trade_level3\": [],\n \"subject_type\": [],\n \"product_model\": [],\n \"product_type\": [],\n \"selling\": [],\n \"monetization\": [],\n \"pay_type\": [],\n \"company_location\": [],\n \"campaign_list\": [],\n \"ad_media_type\": [],\n \"appeal_type_list\": [],\n \"interaction_list\": [],\n \"material_tag\": [],\n \"material_removal_repeat\": false,\n \"demoad_formats\": [],\n \"web_tools\": [],\n \"material_top_limit\": \"\",\n \"gpt_search\": null,\n \"generate_page\": false,\n \"delivery\": null\n}\n```\n\n### Key Parameters\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| content_type | string | required | One of: creative, imagevideo, preplay, demoad, document |\n| keyword | string | \"\" | Search keyword (app name, ad copy, brand, etc.) |\n| keyword_type | string | \"\" | Keyword match scope (leave empty for default per content_type) |\n| start_date | string | 30 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n| page | int | 1 | Page number (≥1) |\n| page_size | int | 60 | Results per page (1-100) |\n| sort_field | string | \"3\" | \"3\"=first seen, \"4\"=days active, \"11\"=relevance, \"15\"=impressions |\n| sort_rule | string | \"desc\" | \"desc\" or \"asc\" |\n| country_ids | string[] | [] | Country codes, e.g. [\"US\",\"JP\"] — use `ccode` from filter-options |\n| media_ids | string[] | [] | Media channel IDs — use `ccode` from filter-options |\n| device | string[] | [] | Device filter — use `ccode` from filter-options |\n| trade_level1/2/3 | string[] | [] | Industry category filters (hierarchical) |\n| product_model | string[] | [] | Product model filter — use `ccode` from filter-options `productModel` (e.g. \"1\"=non-game, \"2\"=game) |\n| material_type | string | \"\" | Material format filter (\"1\"=image, \"2\"=video). **Only effective for `imagevideo` content type** — ignored by other content types |\n| ad_media_type | string[] | [] | Ad media type codes |\n| material_removal_repeat | bool | false | Deduplicate similar creatives |\n| gpt_search | bool/null | null | Enable AI-powered search |\n| generate_page | bool | false | Generate H5 result page |\n| delivery | object/null | null | `{channel, apiBase, externalUserId}` for H5 page context |\n\n### Response\n\n**Note:** `totalSize` may be `null` for keyword searches. Use `pageIndex` and `pageSize` for pagination.\n\n```json\n{\n \"pageIndex\": 1,\n \"pageSize\": 20,\n \"totalSize\": null,\n \"list\": [\n {\n \"id\": \"87f11b718e162ca06589f3c33ef99472\",\n \"title\": null,\n \"describe\": null,\n \"documentId\": null,\n \"findCnt\": 1,\n \"findCntSum\": 1,\n \"firstTime\": \"2026-03-16 13:44:54\",\n \"lastTime\": null,\n \"globalFirstTime\": \"2026-03-16 13:44:54\",\n \"globalLastTime\": \"2026-03-16 13:44:54\",\n \"imageFp\": [],\n \"imageUrl\": [],\n \"videoFp\": [\"80c15b563dded967090b0f5850f4941b\"],\n \"videoUrl\": [\"https://...video.mp4\"],\n \"playHtmlFp\": [],\n \"playHtmlUrl\": [],\n \"demoadCnt\": 1,\n \"appList\": [\n {\n \"id\": \"6498883328\",\n \"cnt\": null,\n \"impression\": null,\n \"name\": \"Tile Trip - Match Puzzle Game\",\n \"logo\": \"https://...logo.png\",\n \"geo\": null,\n \"pkg\": null,\n \"developer\": \"Oakever Games\",\n \"developerId\": \"1604529155\",\n \"productType\": [1],\n \"tradeLevel1\": null,\n \"tradeLevel2\": null,\n \"tradeLevel3\": null\n }\n ],\n \"sourceAppList\": null,\n \"originalUrl\": null,\n \"showCnt\": 2802,\n \"impression\": 145354,\n \"webSite\": null,\n \"demoadWebSite\": null,\n \"thumbnailConverUrl\": [\"https://...keyframe.jpg\"],\n \"videoTimeSpan\": [60],\n \"growthValue\": null,\n \"growthRate\": null,\n \"coverContent\": null,\n \"novel\": null,\n \"adSource\": 9\n }\n ],\n \"folderTotalSize\": null,\n \"newNum\": null,\n \"latestDate\": null,\n \"gptCorrect\": {\n \"sourceKeyword\": \"puzzle\",\n \"correctKeyword\": null,\n \"type\": 3,\n \"developers\": [],\n \"wrongs\": [],\n \"gptSxes\": [],\n \"slices\": []\n },\n \"filters\": [],\n \"page_url\": \"/p/abc123\",\n \"page_key\": \"abc123\",\n \"page_expires_at\": \"2026-03-19 12:00:00\"\n}\n```\n\n`page_url`/`page_key`/`page_expires_at` only present when `generate_page: true`.\n\n### ⚠️ Important Notes\n\n1. **HTML tags in names:** `appList[].name` may contain HTML highlight tags like `keyword`. Strip these before displaying to the user.\n2. **Null values:** Many fields can be `null` — always handle null gracefully.\n3. **totalSize null:** For keyword searches, `totalSize` is often `null`. The actual result count is reflected in `list` length per page.\n\n### Response Key Fields\n\n| Field | Description |\n|---|---|\n| pageIndex | Current page number |\n| pageSize | Results per page |\n| totalSize | Total matching results (may be null) |\n| list[].id | Creative ID |\n| list[].title | Ad title (may be null) |\n| list[].describe | Ad copy text (may be null) |\n| list[].appList[].name | Associated app name — **may contain HTML `` tags** |\n| list[].appList[].developer | Developer/publisher name |\n| list[].appList[].developerId | Developer ID |\n| list[].appList[].logo | App icon URL |\n| list[].impression | Estimated impression count |\n| list[].findCntSum | Days the ad has been active |\n| list[].showCnt | Number of ad variants detected |\n| list[].globalFirstTime | First seen date |\n| list[].globalLastTime | Last seen date |\n| list[].imageUrl | Image asset URLs (array) |\n| list[].videoUrl | Video asset URLs (array) |\n| list[].playHtmlUrl | Playable ad URLs (array) |\n| list[].thumbnailConverUrl | Video thumbnail/keyframe URLs (array) |\n| list[].videoTimeSpan | Video durations in seconds (array) |\n| list[].demoadCnt | Number of landing pages |\n| gptCorrect | AI keyword correction info |\n\n---\n\n## 2. Count — 素材计数\n\n`POST /api/data/count`\n\nGet total count, new count, and latest date for a single content type.\n\n### Request Body\n\nSame as search (content_type + filter params). Only counting fields matter — page/sort are ignored.\n\n### Response\n\n```json\n{\n \"totalSize\": 50000,\n \"newNum\": 1200,\n \"latestDate\": \"2026-03-16\"\n}\n```\n\n---\n\n## 3. Count All — 全类型计数\n\n`POST /api/data/count-all`\n\nAggregate counts across all 5 content types. No request body needed.\n\n### Response\n\n```json\n{\n \"creative\": { \"label\": \"创意组合\", \"totalSize\": 50000, \"newNum\": 1200, \"latestDate\": \"2026-03-16\" },\n \"imagevideo\": { \"label\": \"图片/视频\", \"totalSize\": 120000, \"newNum\": 3500, \"latestDate\": \"2026-03-16\" },\n \"preplay\": { \"label\": \"试玩广告\", \"totalSize\": 8000, \"newNum\": 200, \"latestDate\": \"2026-03-15\" },\n \"demoad\": { \"label\": \"落地页\", \"totalSize\": 30000, \"newNum\": 800, \"latestDate\": \"2026-03-16\" },\n \"document\": { \"label\": \"文档素材\", \"totalSize\": 5000, \"newNum\": 100, \"latestDate\": \"2026-03-14\" }\n}\n```\n\n---\n\n## 4. Distribute — 素材分布分析\n\n`POST /api/data/distribute`\n\nAnalyze distribution of specific creatives by dimension.\n\n### Request Body\n\n```json\n{\n \"content_type\": \"creative\",\n \"dimension\": \"media\",\n \"ids\": [\"creative_id_1\", \"creative_id_2\"],\n \"start_date\": \"\",\n \"end_date\": \"\"\n}\n```\n\n| Parameter | Type | Description |\n|---|---|---|\n| content_type | string | Content type |\n| dimension | string | Distribution dimension — use `advertiser` (not `adfaction`) |\n| ids | string[] | Creative IDs to analyze |\n| start_date/end_date | string | Date range |\n\n### Available Dimensions per Content Type\n\n| content_type | Dimensions |\n|---|---|\n| creative | media, advertiser, app |\n| imagevideo | media, advertiser, app, country |\n| preplay | media, advertiser, app |\n| demoad | media, advertiser, app |\n| document | media, advertiser, app |\n\n**Note:** Use `advertiser` as the dimension name (the API internally maps it to `adfaction`).\n\nUse `GET /api/data/distribute-dims` to fetch this mapping dynamically.\n\n---\n\n## 5. Filter Options — 筛选枚举项\n\n`GET /api/data/filter-options`\n\nReturns all filter enum options in a single batch call (13 categories).\n\n### Response\n\n**IMPORTANT:** Each item has both `code` (complex internal format) and `ccode` (simplified code). **Always use `ccode` when passing filter values to search/query endpoints.**\n\n```json\n{\n \"countries\": [\n {\"code\": \"毛里塔尼亚_2_MRT\", \"nameCn\": \"毛里塔尼亚\", \"nameEn\": \"Mauritania\", \"ccode\": \"MR\", \"icon\": \"https://...flag.png\"}\n ],\n \"mediaChannels\": [\n {\"code\": \"海外平台-101-Adcolony\", \"nameCn\": \"Adcolony\", \"nameEn\": \"Adcolony\", \"ccode\": \"101\", \"icon\": \"https://...icon.png\"}\n ],\n \"adTypes\": [\n {\"code\": \"adstyle_原生_1076682150_1076682150\", \"nameCn\": \"原生\", \"nameEn\": \"Native Ads\", \"ccode\": \"1076682150\", \"icon\": null}\n ],\n \"device\": [\n {\"code\": \"Android_2_1\", \"nameCn\": \"Android\", \"nameEn\": \"Android\", \"ccode\": \"1\", \"icon\": \"android\"}\n ],\n \"tradeLevel\": [\n {\"code\": \"601\", \"nameCn\": \"工具\", \"nameEn\": \"Tools\", \"ccode\": \"601\", \"icon\": null}\n ],\n \"productModel\": [\n {\"code\": \"1\", \"nameCn\": \"非游戏\", \"nameEn\": \"Non-game\", \"ccode\": \"1\", \"icon\": null}\n ],\n \"productType\": [\n {\"code\": \"app_1_1\", \"nameCn\": \"App\", \"nameEn\": \"App\", \"ccode\": \"1\", \"icon\": null}\n ],\n \"selling\": [\n {\"code\": \"5005_w2a\", \"nameCn\": \"W2A\", \"nameEn\": \"W2A\", \"ccode\": \"w2a\", \"icon\": null}\n ],\n \"subjectType\": [\n {\"code\": \"gold_0_1\", \"nameCn\": \"金币\", \"nameEn\": \"Gold\", \"ccode\": \"1\", \"icon\": null}\n ],\n \"topicType\": [\n {\"code\": \"传奇_9_64\", \"nameCn\": \"传奇\", \"nameEn\": \"Legend\", \"ccode\": \"90064\", \"icon\": null}\n ],\n \"languages\": [\n {\"code\": \"南非荷兰语_af\", \"nameCn\": \"南非荷兰语\", \"nameEn\": \"Afrikaans\", \"ccode\": \"af\", \"icon\": null}\n ],\n \"materialTag\": [\n {\"code\": \"AI_0_1\", \"nameCn\": \"AI\", \"nameEn\": \"AI\", \"ccode\": \"001\", \"icon\": \"\"}\n ],\n \"tradeLevel2\": [\n {\"code\": \"60301\", \"nameCn\": \"电商\", \"nameEn\": \"E-commerce\", \"ccode\": \"60301\", \"icon\": null}\n ],\n \"materialFormat\": [\n {\"code\": \"5006_100\", \"nameCn\": \"单图\", \"nameEn\": \"Single Image\", \"ccode\": \"100\", \"icon\": null}\n ]\n}\n```\n\n### Filter Code Usage\n\n| Filter parameter | Use `ccode` from | Example |\n|---|---|---|\n| country_ids | countries | \"US\", \"JP\", \"MR\" |\n| media_ids | mediaChannels | \"101\" (Adcolony) |\n| device | device | \"1\" (Android) |\n| trade_level1/2/3 | tradeLevel / tradeLevel2 | \"601\" (Tools), \"60301\" (E-commerce) |\n| product_model | productModel | \"1\" (Non-game), \"2\" (Game) |\n| ad_media_type | adTypes | \"1076682150\" (Native Ads) |\n| languages | languages | \"af\" (Afrikaans) |\n| material_tag | materialTag | \"001\" (AI) |\n\n### Additional Response Field: tradeLevelTree\n\nThe response also includes `tradeLevelTree` — a hierarchical tree structure of all industry categories (level 1 → 2 → 3), useful for building category pickers or understanding the category hierarchy.\n\n---\n\n## 6. Content Detail — 素材详情\n\n`GET /api/data/content-detail`\n\nGet detailed information about a specific creative, or its related content (associated media, trends, profile, etc.).\n\n### Query Parameters\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| content_type | string | required | creative, imagevideo, preplay, demoad, document |\n| id | string | required | Content ID |\n| related | string | (none) | Related data type (see below). Omit for base info. |\n| material_type | string | \"\" | Only for `related=imagevideo`: \"1\"=image, \"2\"=video |\n| start_date | string | 365 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n\n### Related Types\n\n| related | Description |\n|---|---|\n| *(omitted)* | Base info — creative metadata and asset URLs |\n| `imagevideo` | Related image/video assets |\n| `document` | Related document assets |\n| `trend` | Impression/activity trend over time |\n| `profile` | Audience profile data |\n| `preplay` | Related playable ads |\n| `demoad` | Related landing pages |\n\n### Examples\n\n```\n# Get base info for a creative\nGET /api/data/content-detail?content_type=creative&id=abc123\n\n# Get related videos\nGET /api/data/content-detail?content_type=creative&id=abc123&related=imagevideo&material_type=2\n\n# Get trend data\nGET /api/data/content-detail?content_type=creative&id=abc123&related=trend&start_date=2026-01-01&end_date=2026-03-16\n```\n\n---\n\n## 7. Item Apps — 素材关联应用\n\n`POST /api/data/item-apps`\n\nBatch-fetch the associated apps for a list of creative IDs. Useful for enriching search results with app info.\n\n### Request Body\n\n```json\n{\n \"content_type\": \"creative\",\n \"ids\": [\"id1\", \"id2\", \"id3\"]\n}\n```\n\n| Parameter | Type | Description |\n|---|---|---|\n| content_type | string | Content type |\n| ids | string[] | Creative IDs (max 100) |\n\n### Response\n\nReturns a mapping of creative ID → app list:\n\n```json\n{\n \"id1\": [\n {\"id\": \"com.example.app\", \"name\": \"App Name\", \"logo\": \"https://...\"}\n ],\n \"id2\": [\n {\"id\": \"6498883328\", \"name\": \"Another App\", \"logo\": \"https://...\"}\n ]\n}\n```\n\n---\n\n## 8. Screen Types — 单类筛选项\n\n`GET /api/data/screen-types?element_type=1`\n\nFetch a single filter category by element type ID.\n\n| element_type | Category |\n|---|---|\n| 1004 | tradeLevel (industry) |\n| 2002 | countries |\n| 2004 | device |\n| 2005 | languages |\n| 2006 | mediaChannels |\n| 2008 | materialTag |\n| 3000 | subjectType |\n| 3006 | productType |\n| 5001 | adTypes |\n| 5005 | selling |\n| 5006 | materialFormat |\n\n---\n\n## 7. Page Config — 页面配置\n\n`GET /api/data/page-config?scope=search`\n\nReturns page layout configuration for the specified scope.\n\nFile v1.0.29:references/api-distribution.md\n\n# App Distribution API / 应用投放分布接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n> These endpoints require a `unified_product_id`. Get it from `unified-product-search` first.\n\n---\n\n## 1. App Distribution — 应用推广分布\n\n`POST /api/data/app-distribution`\n\nAnalyze an app's ad distribution across different dimensions.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"dim\": \"country\",\n \"start_time\": \"\",\n \"end_time\": \"\",\n \"countries\": [],\n \"media_ids\": [],\n \"material_type\": \"\",\n \"index_type\": 0\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| unified_product_id | string | required | Target app ID |\n| dim | string | required | Distribution dimension (see below) |\n| start_time | string | 30 days ago | YYYY-MM-DD |\n| end_time | string | today | YYYY-MM-DD |\n| countries | string[] | [] | Country filter |\n| media_ids | string[] | [] | Media channel filter |\n| material_type | string/int | \"\" | Material type filter |\n| index_type | int | 0 | Index type selector |\n\n### Dimensions\n\n| dim | Description | Returns |\n|---|---|---|\n| `trend` | 投放趋势 | Time series of ad volume over time |\n| `country` | 投放国家分布 | Per-country ad placement distribution |\n| `media` | 投放媒体位分布 | Distribution across publisher apps/placements where ads are displayed. **Note:** This returns the specific apps where ads appear (e.g. \"Block Blast\", \"Snake.io\", \"Solitaire\"), NOT ad network names like Facebook/Google. These are the traffic sources/publisher apps carrying the ads. Present them as \"投放媒体位\" or \"广告展示位\". |\n| `platform` | 平台分布 | iOS vs Android breakdown |\n| `type` | 素材类型分布 | Image vs video vs playable distribution |\n| `image` | 图片尺寸分布 | Image size/aspect ratio breakdown |\n| `video` | 视频时长分布 | Video duration breakdown |\n| `lang` | 语言分布 | Ad language distribution |\n\n### Response Examples\n\n**dim=country:**\n```json\n{\n \"list\": [\n {\"code\": \"US\", \"name\": \"United States\", \"cnt\": 500, \"ratio\": 0.35},\n {\"code\": \"JP\", \"name\": \"Japan\", \"cnt\": 300, \"ratio\": 0.21}\n ]\n}\n```\n\n**dim=trend:**\n```json\n{\n \"list\": [\n {\"date\": \"2026-03-01\", \"cnt\": 50},\n {\"date\": \"2026-03-02\", \"cnt\": 65}\n ]\n}\n```\n\n**dim=media (publisher apps / ad placements):**\n```json\n{\n \"list\": [\n {\"id\": \"101\", \"name\": \"Block Blast Adventure Master\", \"cnt\": 400, \"ratio\": 0.15},\n {\"id\": \"102\", \"name\": \"Snake.io\", \"cnt\": 250, \"ratio\": 0.09},\n {\"id\": \"103\", \"name\": \"Solitaire\", \"cnt\": 180, \"ratio\": 0.07}\n ]\n}\n```\nThese are the apps where the target app's ads are being shown (publisher side). When presenting this data, you can categorize them (e.g. casual games, tools, content apps) to provide more actionable insights.\n\n---\n\n## 2. Distribute Dims — 素材分布维度\n\n`GET /api/data/distribute-dims`\n\nReturns which distribute dimensions are available per content type. This is for the creative-level distribute endpoint (`/api/data/distribute`), not for app-distribution.\n\n### Response\n\n```json\n{\n \"creative\": [\"media\", \"advertiser\", \"app\"],\n \"imagevideo\": [\"media\", \"advertiser\", \"app\", \"country\"],\n \"preplay\": [\"media\", \"advertiser\", \"app\"],\n \"demoad\": [\"media\", \"advertiser\", \"app\"],\n \"document\": [\"media\", \"advertiser\", \"app\"]\n}\n```\n\n---\n\n## 3. Global Promote — 全局推广分布\n\n`POST /api/data/global-promote`\n\nAnalyze the global promotion distribution for one or more products across countries, media, or advertisers.\n\n### Request Body\n\n```json\n{\n \"ids\": [\"product_id_1\", \"product_id_2\"],\n \"dim\": \"country\",\n \"keyword\": \"\",\n \"sort_field\": \"15\",\n \"sort_rule\": \"desc\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| ids | string[] | required | Product IDs (non-empty array) |\n| dim | string | \"country\" | Dimension: `country`, `media`, or `adfaction` |\n| keyword | string | \"\" | Optional keyword filter |\n| sort_field | string | \"15\" | Sort field (\"15\"=impressions) |\n| sort_rule | string | \"desc\" | Sort direction |\n\n### Response\n\nReturns distribution data for the specified dimension. Structure varies by `dim`.\n\n### Difference from app-distribution\n\n- **app-distribution** — Analyzes a single app's ad placement distribution (where/how it advertises)\n- **global-promote** — Analyzes one or more products' promotion footprint across the global market (country/media/advertiser breakdown)\n\n---\n\n## Common Workflows / 常用工作流\n\n### \"Temu 主要在哪些国家投广告？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"country\")\n```\n\n### \"Temu 用了哪些广告渠道？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"media\")\n```\n\n### \"Temu 的投放趋势怎么样？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"trend\", start_time=\"2026-01-01\", end_time=\"2026-03-16\")\n```\n\n### \"Temu 在美国投了多少视频广告 vs 图片广告？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"type\", countries=[\"US\"])\n```\n\n### Full app advertising profile (multi-call)\n\n1. `dim=\"country\"` → where they advertise (target countries)\n2. `dim=\"media\"` → which publisher apps carry their ads (ad placements)\n3. `dim=\"type\"` → what creative formats they use\n4. `dim=\"trend\"` → how ad volume changes over time\n5. `dim=\"lang\"` → which languages they target\n\nCombine all 5 for a comprehensive advertising strategy overview.\n\nFile v1.0.29:references/api-download-revenue.md\n\n# Download & Revenue API / 下载量与收入接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n> These endpoints require a `unified_product_id`. Get it from `unified-product-search` first.\n\n---\n\n## 1. Download Date Range — 下载量可用日期\n\n`GET /api/data/download-date`\n\nReturns the available date range for download data queries.\n\n### Response\n\n```json\n{\n \"startDate\": \"2023-01-01\",\n \"endDate\": \"2026-03-15\"\n}\n```\n\n**Use this to validate date params before calling download-detail/download-country.**\n\n---\n\n## 2. Download Detail — 下载量趋势\n\n`POST /api/data/download-detail`\n\nFetch download trend data for a specific app over time.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"query_start_date\": \"2026-02-14\",\n \"query_end_date\": \"2026-03-16\",\n \"compare_start_date\": \"\",\n \"compare_end_date\": \"\",\n \"country_st\": [],\n \"day_type\": 1,\n \"flag\": true,\n \"is_all\": false\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| unified_product_id | string | required | Target app ID |\n| query_start_date | string | required | YYYY-MM-DD |\n| query_end_date | string | required | YYYY-MM-DD |\n| compare_start_date | string | \"\" | Compare period start (optional) |\n| compare_end_date | string | \"\" | Compare period end (optional) |\n| country_st | string[] | [] | Country filter (empty = global) |\n| day_type | int | 1 | Granularity: 1=daily, 2=weekly, 3=monthly |\n| flag | bool | true | Include trend data |\n| is_all | bool | false | All countries aggregated |\n\n### Response\n\nReturns time series data:\n```json\n{\n \"list\": [\n {\"date\": \"2026-03-01\", \"download\": 150000, \"compareDownload\": 120000},\n {\"date\": \"2026-03-02\", \"download\": 160000, \"compareDownload\": 125000}\n ]\n}\n```\n\n---\n\n## 3. Download Country — 按国家下载量\n\n`POST /api/data/download-country`\n\nFetch download data broken down by country.\n\n### Request Body\n\nSame as download-detail.\n\n### Response\n\nReturns per-country breakdown:\n```json\n{\n \"list\": [\n {\"country\": \"US\", \"countryName\": \"United States\", \"download\": 500000},\n {\"country\": \"JP\", \"countryName\": \"Japan\", \"download\": 300000}\n ]\n}\n```\n\n---\n\n## 4. Revenue Date Range — 收入可用日期\n\n`GET /api/data/revenue-date`\n\nReturns the available date range for revenue data queries.\n\n### Response\n\n```json\n{\n \"startDate\": \"2023-01-01\",\n \"endDate\": \"2026-03-15\"\n}\n```\n\n---\n\n## 5. Revenue Detail — 收入趋势\n\n`POST /api/data/revenue-detail`\n\nFetch revenue trend data for a specific app.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"query_start_date\": \"2026-02-14\",\n \"query_end_date\": \"2026-03-16\",\n \"compare_start_date\": \"\",\n \"compare_end_date\": \"\",\n \"country_st\": [],\n \"day_type\": 1,\n \"flag\": true,\n \"is_all\": false,\n \"revenue_type\": \"ALL\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| (same as download-detail, plus:) | | | |\n| revenue_type | string | \"ALL\" | Revenue type filter |\n\n---\n\n## 6. Revenue Country — 按国家收入\n\n`POST /api/data/revenue-country`\n\nFetch revenue data broken down by country.\n\n### Request Body\n\nSame as revenue-detail.\n\n---\n\n## Common Workflows / 常用工作流\n\n### \"Temu 最近下载量怎么样？\"\n\n1. `unified-product-search(keyword=\"temu\")` → get `unifiedProductId`\n2. `download-date` → confirm available range\n3. `download-detail(unified_product_id=id, query_start_date=\"2026-02-14\", query_end_date=\"2026-03-16\")` → trend\n4. Present trend data with insights\n\n### \"对比 Temu 在美国和日本的收入\"\n\n1. Get `unifiedProductId` (step 1 above)\n2. `revenue-country(unified_product_id=id, ...)` → per-country revenue\n3. Filter & compare US vs JP data\n\n### \"Temu vs SHEIN 下载量对比\"\n\n1. Search both apps → get both `unifiedProductId`\n2. `download-detail` for each → two trend datasets\n3. Present side-by-side comparison\n\n### Day Type Reference\n\n| day_type | Granularity | Best for |\n|---|---|---|\n| 1 | Daily | Short ranges (≤90 days) |\n| 2 | Weekly | Medium ranges (1-6 months) |\n| 3 | Monthly | Long ranges (6+ months) |\n\nFile v1.0.29:references/api-market.md\n\n# Market Analysis API / 市场分析接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n---\n\n## Market Search — 市场分析搜索\n\n`POST /api/data/market-search`\n\nAnalyze the advertising market from 5 different dimensions. Provides macro-level market intelligence.\n\n### Request Body\n\n```json\n{\n \"class_type\": 1,\n \"data_type\": \"1\",\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"trade_level3\": [],\n \"country_level2\": [],\n \"media_ids\": [],\n \"device\": [],\n \"ad_company_location\": [],\n \"traffic_company_location\": [],\n \"page\": 1,\n \"page_size\": 20\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| class_type | int | required | Analysis dimension (1-5, see below) |\n| data_type | string | \"1\" | \"1\"=game, \"2\"=app |\n| start_date | string | today | YYYY/MM/DD (note: slash format) |\n| end_date | string | today | YYYY/MM/DD (note: slash format) |\n| trade_level3 | string[] | [] | Sub-industry filter |\n| country_level2 | string[] | [] | Country filter |\n| media_ids | string[] | [] | Media channel filter |\n| device | string[] | [] | Device filter |\n| ad_company_location | string[] | [] | Advertiser company location filter |\n| traffic_company_location | string[] | [] | Publisher/traffic source location filter |\n| page | int | 1 | Page number |\n| page_size | int | 20 | Results per page (1-100) |\n\n### Dimensions (class_type)\n\n| class_type | Dimension | Description | Best for |\n|---|---|---|---|\n| 1 | 国家 Country | Market size by country | \"Which countries have the most game ads?\" |\n| 2 | 媒体 Media | Market share by ad network | \"Which ad platforms are most used?\" |\n| 3 | 子媒体 Sub-Media | Breakdown within media channels | \"What Facebook ad placements are popular?\" |\n| 4 | 广告主 Advertiser | Top advertisers in the market | \"Who are the biggest game advertisers?\" |\n| 5 | 流量主 Publisher | Top publishers / traffic sources | \"Which publishers carry the most ads?\" |\n\n### Data Type\n\n| data_type | Description |\n|---|---|\n| \"1\" | 游戏 Game — game industry data |\n| \"2\" | 应用 App — non-game app data |\n\n**Note:** Date format for this endpoint uses slashes (`YYYY/MM/DD`), not dashes.\n\n### Response\n\n**IMPORTANT:** This endpoint returns a different structure from other endpoints. The response uses `data_list` (not `list`) and nested dot-notation field names.\n\n**Pagination fields:** `page_total` (total pages), `page_num` (current page), `page_size`.\n\n#### class_type=1 (Country) response:\n```json\n{\n \"data_list\": [\n {\n \"market_query.list.id\": \"ID\",\n \"query.country_info.s_code\": \"ID\",\n \"query.country_info.c_code\": \"ID\",\n \"query.country_info.country_name\": \"印度尼西亚\",\n \"market_query.list.raw_impression\": 11578945855,\n \"market_query.list.impression\": \"116亿\",\n \"market_query.list.impressionRatio\": \"13.64%\",\n \"market_query.list.rank\": 1,\n \"query.country_info.image\": \"https://...flag.png\"\n }\n ],\n \"page_total\": 34,\n \"page_num\": 1,\n \"page_size\": 3\n}\n```\n\nKey fields to extract:\n- `query.country_info.country_name` — country name (Chinese)\n- `query.country_info.c_code` — country code\n- `market_query.list.impression` — impression count (pre-formatted string like \"116亿\")\n- `market_query.list.raw_impression` — raw numeric impression count\n- `market_query.list.impressionRatio` — percentage share\n- `market_query.list.rank` — rank position\n\n#### class_type=4 (Advertiser) response:\n```json\n{\n \"data_list\": [\n {\n \"market_query.list.market_query.list.advertiser\": \"275091615\",\n \"market_query.list.query.company_info.unified_company_name\": \"VGam.es\",\n \"market_query.list.query.company_info.unified_company_id\": \"275091615\",\n \"query.pkg_info.productName\": \"Math Crossword – Endless Fun\",\n \"query.pkg_info.productLogo\": \"https://...logo.png\",\n \"query.pkg_info.unifiedPkgId\": \"com.vgames.mathcrossword\",\n \"market_query.list.market_query.list.company_impression\": \"64亿\",\n \"market_query.list.market_query.list.raw_company_impression\": 6449946845,\n \"market_query.list.market_query.list.company_impressionRatio\": \"10.31%\",\n \"market_query.list.market_query.list.top1_app_impression\": \"64亿\",\n \"market_query.list.market_query.list.rank\": 1\n }\n ],\n \"page_total\": 500,\n \"page_num\": 1,\n \"page_size\": 2\n}\n```\n\nKey fields to extract:\n- `market_query.list.query.company_info.unified_company_name` — company name\n- `query.pkg_info.productName` — top product name\n- `market_query.list.market_query.list.company_impression` — total impression (formatted)\n- `market_query.list.market_query.list.company_impressionRatio` — market share %\n- `market_query.list.market_query.list.rank` — rank position\n\n---\n\n## Common Workflows / 常用工作流\n\n### \"全球游戏广告市场哪个国家最大？\"\n\n```json\n{\"class_type\": 1, \"data_type\": \"1\"}\n```\n\n### \"美国市场最大的游戏广告主是谁？\"\n\n```json\n{\"class_type\": 4, \"data_type\": \"1\", \"country_level2\": [\"US\"]}\n```\n\n### \"电商App广告市场对比：东南亚 vs 北美\"\n\nTwo queries:\n1. `{\"class_type\": 1, \"data_type\": \"2\", \"country_level2\": [\"TH\",\"VN\",\"ID\",\"MY\",\"PH\",\"SG\"]}`\n2. `{\"class_type\": 1, \"data_type\": \"2\", \"country_level2\": [\"US\",\"CA\"]}`\n\nCompare total counts, top advertisers, media distribution.\n\n### Market overview combo (multi-call)\n\nFor a comprehensive market report on a segment:\n1. `class_type=1` → geographic distribution\n2. `class_type=2` → media channel breakdown\n3. `class_type=4` → top advertisers\n4. `class_type=5` → top publishers\n\nCombine for a full market intelligence report.\n\n---\n\n## Filter Codes\n\nUse `GET /api/data/filter-options` to get valid codes for:\n- `trade_level3` — industry/sub-category codes\n- `country_level2` — country codes (use the `ccode` field, e.g. \"US\", \"JP\")\n- `media_ids` — media channel IDs (use the `ccode` field, e.g. \"101\" for Adcolony)\n- `device` — device type codes (use the `ccode` field, e.g. \"1\" for Android)\n\nSee `references/param-mappings.md` for common country/region mappings.\n\nFile v1.0.29:references/api-product.md\n\n# Product & Company API / 产品与公司接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n---\n\n## 1. Unified Product Search — 统一产品搜索\n\n`POST /api/data/unified-product-search`\n\nSearch for unified products (cross-platform aggregated apps). This is the primary entry point for finding apps/products.\n\n### Request Body\n\n```json\n{\n \"keyword\": \"temu\",\n \"type\": 1,\n \"page\": 1,\n \"page_size\": 20,\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"sort_field\": \"3\",\n \"sort_rule\": \"desc\",\n \"unified_product_id\": \"\",\n \"unified_developer_id\": \"\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| keyword | string | \"\" | Search keyword |\n| type | int | 1 | Search type |\n| page | int | 1 | Page number |\n| page_size | int | 20 | Results per page (1-100) |\n| start_date | string | 30 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n| sort_field | string | \"3\" | Sort field |\n| sort_rule | string | \"desc\" | Sort direction |\n| unified_product_id | string | \"\" | Filter by specific unified product |\n| unified_developer_id | string | \"\" | Filter by specific developer |\n| country_ids | string[] | [] | Country filter (mapped to countryLevel2) |\n| media_ids | string[] | [] | Media channel filter |\n| device | string[] | [] | Device filter |\n\n**Note:** `country_ids`, `media_ids`, and `device` also apply to `product-search` and `company-search`.\n\n### Response\n\n```json\n{\n \"pageIndex\": 1,\n \"pageSize\": 20,\n \"totalSize\": 96,\n \"list\": [\n {\n \"unifiedProductId\": \"1641486558\",\n \"unifiedProductName\": \"Temu: Shop Like a Billionaire\",\n \"unifiedCompanyId\": \"569338280\",\n \"unifiedCompanyName\": \"Temu\",\n \"productIds\": [\"com.einnovation.temu\", \"1641486558\", \"com.Temu_Team_Up.used_letgo_buy_app1\"],\n \"tradeLevel1\": [\"603\"],\n \"tradeLevel2\": [\"60301\", \"60303\"],\n \"tradeLevel3\": [\"6030102\", \"6030301\"],\n \"tradeLevel4\": [],\n \"showCost\": 23236263827,\n \"impression\": 2412399002696,\n \"materialUvCnt\": 7451078,\n \"productCnt\": 3,\n \"iconUrl\": \"https://...logo.png\",\n \"collectId\": null,\n \"formerNames\": null,\n \"adSource\": 9\n }\n ],\n \"folderTotalSize\": null,\n \"newNum\": 0,\n \"latestDate\": null,\n \"gptCorrect\": null,\n \"filters\": null\n}\n```\n\n### ⚠️ Important Notes\n\n1. **HTML tags in names:** `unifiedProductName` may contain HTML highlight tags `keyword`. Strip these before displaying.\n2. The `unifiedProductId` returned here is the key input for detail/distribution/download/revenue endpoints.\n3. `productIds` contains platform-specific IDs (Android package name, iOS app ID).\n\n### Key Fields\n\n| Field | Description |\n|---|---|\n| unifiedProductId | Unique cross-platform product ID — **use this for all detail/distribution queries** |\n| unifiedProductName | App name (may contain HTML `` tags for keyword highlighting) |\n| unifiedCompanyId | Developer/company ID |\n| unifiedCompanyName | Developer/company name |\n| productIds | Array of platform-specific product IDs |\n| iconUrl | App icon URL |\n| showCost | Total ad spend estimate (raw number) |\n| impression | Total impression count (raw number) |\n| materialUvCnt | Total unique creative count |\n| productCnt | Number of platform versions |\n| tradeLevel1/2/3/4 | Industry category codes |\n\n---\n\n## 2. Product Search — 产品搜索\n\n`POST /api/data/product-search`\n\nSearch for individual products (platform-specific). Same request body as unified product search.\n\n### Response\n\nReturns **normalized** product items (different structure from unified-product-search):\n\n```json\n{\n \"list\": [\n {\n \"id\": \"com.einnovation.temu\",\n \"unifiedProductId\": \"com.einnovation.temu\",\n \"name\": \"Temu: Shop Like a Billionaire\",\n \"logo\": \"https://...logo.png\",\n \"pkg\": \"com.einnovation.temu\",\n \"developer\": \"Whaleco Inc.\",\n \"developerId\": \"569338280\",\n \"os\": \"android\",\n \"tags\": [\"60301\", \"60303\"],\n \"impressionEstimate\": 2412399002696,\n \"materialCnt\": 7451078,\n \"firstTime\": \"2022-09-01\",\n \"lastTime\": \"2026-03-17\",\n \"adDays\": 1293,\n \"countries\": [\"US\", \"JP\"],\n \"mediaList\": [\"Facebook\", \"Google\"],\n \"selling\": \"w2a\",\n \"productType\": \"App\"\n }\n ],\n \"totalSize\": 96\n}\n```\n\n### Key Fields\n\n| Field | Description |\n|---|---|\n| id | Product ID (package name or app store ID) |\n| unifiedProductId | Same as id for individual products |\n| name | App name (HTML stripped) |\n| os | \"android\" or \"ios\" |\n| tags | Industry category codes (tradeLevel3 > tradeLevel2 > tradeLevel1) |\n| impressionEstimate | Estimated impressions (raw number) |\n| adDays | Calculated days between firstTime and lastTime |\n\n---\n\n## 3. Company Search — 公司/开发者搜索\n\n`POST /api/data/company-search`\n\nSearch for companies/developers. Same request body as unified product search.\n\n### Response\n\n```json\n{\n \"pageIndex\": 1,\n \"pageSize\": 1,\n \"totalSize\": 7,\n \"list\": [\n {\n \"unifiedCompanyId\": \"1773957248\",\n \"unifiedCompanyName\": \"Bytedance 字节跳动\",\n \"unifiedCompanyRegion\": \"CN\",\n \"uaList\": [1, 2, 3],\n \"showCost\": 10768429037,\n \"impression\": 2844436033460,\n \"collectId\": null,\n \"productIds\": [\"com.zhiliaoapp.musically\", \"com.ss.android.ugc.trill\", \"1235601864\", \"...\"],\n \"productCnt\": 53,\n \"downloadCnt\": null,\n \"hitDeveloper\": false,\n \"unifiedCompanyNameDefault\": null,\n \"developerList\": [\n {\"id\": \"640989321\", \"name\": \"Bytedance Pte. Ltd\", \"status\": 0, \"productCnt\": 9, \"collectId\": null}\n ],\n \"unifiedCompanyNameOrigin\": \"Bytedance 字节跳动\",\n \"adSource\": 9\n }\n ]\n}\n```\n\n### Key Fields\n\n| Field | Description |\n|---|---|\n| unifiedCompanyId | Unified company ID — **use for developer-detail queries** |\n| unifiedCompanyName | Company name (may contain HTML `` tags) |\n| unifiedCompanyNameOrigin | Original company name without highlighting |\n| unifiedCompanyRegion | Company region code (e.g. \"CN\") |\n| showCost | Total ad spend estimate |\n| impression | Total impressions |\n| productCnt | Total number of products |\n| productIds | All product IDs under this company |\n| developerList | List of developer accounts under the company |\n| developerList[].id | Developer ID |\n| developerList[].name | Developer name |\n| developerList[].productCnt | Products under this developer |\n\n---\n\n## 4. App Detail — 应用详情\n\n`GET /api/data/app-detail?id={unifiedProductId}`\n\nGet comprehensive detail for a specific app/product.\n\n| Parameter | Type | Description |\n|---|---|---|\n| id | string | unified product ID (from unified-product-search), or a package name (e.g. `com.einnovation.temu`) — the API will auto-resolve package names to unified IDs |\n\n### Response\n\n```json\n{\n \"unifiedProductId\": \"com.einnovation.temu\",\n \"unifiedProductName\": \"Temu: Shop Like a Billionaire\",\n \"unifiedCompanyId\": \"569338280\",\n \"unifiedCompanyName\": \"Temu\",\n \"productIds\": [\"com.einnovation.temu\", \"1641486558\", \"com.Temu_Team_Up.used_letgo_buy_app1\"],\n \"tradeLevel1\": [\"603\"],\n \"tradeLevel2\": [\"60301\", \"60303\"],\n \"tradeLevel3\": [\"6030102\", \"6030301\"],\n \"tradeLevel4\": null,\n \"showCost\": null,\n \"impression\": null,\n \"materialUvCnt\": null,\n \"productCnt\": 3,\n \"iconUrl\": \"https://...logo.png\",\n \"collectId\": null,\n \"formerNames\": null,\n \"adSource\": 9\n}\n```\n\n**Note:** `showCost`, `impression`, `materialUvCnt` are `null` in app-detail (these are only available in search results). Use unified-product-search to get these metrics.\n\n---\n\n## 5. Developer Detail — 开发者详情\n\n`GET /api/data/developer-detail?id={unifiedCompanyId}`\n\nGet developer/company detail.\n\n| Parameter | Type | Description |\n|---|---|---|\n| id | string | unified company ID (from unified-product-search or company-search) |\n\n### Response\n\n```json\n{\n \"unifiedCompanyId\": \"569338280\",\n \"unifiedCompanyName\": \"Temu\",\n \"unifiedCompanyRegion\": \"美国\",\n \"uaList\": [1, 2, 3],\n \"showCost\": null,\n \"impression\": null,\n \"collectId\": null,\n \"productIds\": [\"com.einnovation.temu\", \"1641486558\", \"com.Temu_Team_Up.used_letgo_buy_app1\"],\n \"productCnt\": 6,\n \"downloadCnt\": null,\n \"hitDeveloper\": null,\n \"unifiedCompanyNameDefault\": null,\n \"developerList\": [\n {\"id\": \"444696740\", \"name\": \"HY Dev LLC\", \"status\": 0, \"productCnt\": 7, \"collectId\": null},\n {\"id\": \"480100326\", \"name\": \"Temu\", \"status\": 0, \"productCnt\": 2, \"collectId\": null}\n ],\n \"unifiedCompanyNameOrigin\": null,\n \"adSource\": 9\n}\n```\n\n### Key Fields\n\n| Field | Description |\n|---|---|\n| unifiedCompanyName | Company name |\n| unifiedCompanyRegion | Company location (Chinese name, e.g. \"美国\") |\n| productIds | All product IDs |\n| productCnt | Total product count |\n| developerList | Sub-developer accounts |\n\n---\n\n## 6. For Product List — 公司子产品列表\n\n`POST /api/data/for-product-list`\n\nGet individual products under a company (used in company search popover).\n\n### Request Body\n\n```json\n{\n \"unified_id\": \"xxx\",\n \"page\": 1,\n \"page_size\": 10\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| unified_id | string | required | Unified company ID |\n| page | int | 1 | Page number |\n| page_size | int | 10 | Results per page (1-100) |\n| trade_level3 | string[] | [] | Industry category filter |\n| device | string[] | [] | Device filter |\n| country_level2 | string[] | [] | Country filter |\n\n---\n\n## 6b. Product List — 子产品列表\n\n`POST /api/data/product-list`\n\nGet individual products (per platform) under a unified product.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"page\": 1,\n \"page_size\": 20\n}\n```\n\n---\n\n## 7. Product Agg List — 开发者产品聚合列表\n\n`POST /api/data/product-agg-list`\n\nGet aggregated products under a specific developer.\n\n### Request Body\n\n```json\n{\n \"unified_developer_id\": \"xxx\",\n \"page\": 1,\n \"page_size\": 20\n}\n```\n\n---\n\n## 8. Product Content Search — 产品维度素材搜索\n\n`POST /api/data/product-content-search`\n\nSearch for ad creatives specifically associated with a product.\n\n### Request Body\n\nTwo ways to specify the target product — use **one** of these:\n\n```json\n// Option A: unified product ID (32-char hex hash, covers all platforms)\n{\n \"content_type\": \"creative\",\n \"unified_product_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"page\": 1, \"page_size\": 20,\n \"sort_field\": \"3\", \"sort_rule\": \"desc\"\n}\n\n// Option B: individual product IDs (appCode — package name or numeric store ID)\n{\n \"content_type\": \"creative\",\n \"product_ids\": [\"com.example.app\"],\n \"page\": 1, \"page_size\": 20,\n \"sort_field\": \"3\", \"sort_rule\": \"desc\"\n}\n```\n\n| Parameter | Type | Description |\n|---|---|---|\n| content_type | string | creative, imagevideo, preplay, demoad, document |\n| unified_product_id | string | Unified product ID (32-char hex). Use for product groups |\n| product_ids | string[] | Individual product IDs (appCode/pkg). Use for single products |\n| keyword | string | Optional further keyword filter |\n\n**How to choose:** If the ID is a 32-character hex string → use `unified_product_id`. Otherwise (package name like `com.xxx` or numeric ID like `583700738`) → use `product_ids`.\n\n### Response\n\nSame structure as `/api/data/search` response — `pageIndex`, `pageSize`, `totalSize` + `list[]` of creatives. See api-creative.md for full field documentation.\n\n---\n\n## 9. App Profile — 应用商店画像\n\n`GET /api/data/app-profile?id={productId}&type=1`\n\nGet app store profile and audience data.\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| id | string | required | Product ID |\n| type | int | 1 | Profile type |\n\n### Response\n\nReturns store information, audience demographics, category rankings, etc.\n\n---\n\n## 10. Similar Apps — 相似/竞品应用\n\n`POST /api/data/similar-apps`\n\nFind apps with similar audiences or competitive overlap based on a package name.\n\n### Request Body\n\n```json\n{\n \"pkg\": \"com.einnovation.temu\",\n \"sort_field\": \"7\",\n \"sort_rule\": \"desc\",\n \"trade_level3\": [],\n \"device\": [],\n \"country_level2\": []\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| pkg | string | required | App package name |\n| sort_field | string | \"7\" | Sort: \"7\"=ad days, \"1\"=similarity, \"15\"=impressions, \"5\"=creative count, \"3\"=first seen |\n| sort_rule | string | \"desc\" | Sort direction |\n| trade_level3 | string[] | [] | Industry category filter |\n| device | string[] | [] | Device filter |\n| country_level2 | string[] | [] | Country filter |\n\n### Response\n\nReturns normalized product list (same structure as `product-search` response), with an additional `similarity` field per item.\n\n---\n\n## 11. SDK Detail — SDK 集成详情\n\n`GET /api/data/sdk-detail?pkg={packageName}`\n\nQuery which SDKs an app has integrated.\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| pkg | string | required | App package name (e.g. `com.einnovation.temu`) |\n| sdk_type | string | \"\" | Optional SDK type filter |\n\n### Response\n\nReturns SDK integration details for the specified app. Returns `{}` if no data available.\n\n---\n\n## 12. Product Content Counts — 产品素材类型计数\n\n`POST /api/data/product-content-counts`\n\nGet the total creative count for a product across all 5 content types. Useful for showing a quick overview of a product's ad creative portfolio.\n\n### Request Body\n\nTwo ways to specify the target — use **one** of these:\n\n```json\n// Option A: unified product ID (32-char hex)\n{ \"unified_product_id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\", \"start_date\": \"\", \"end_date\": \"\" }\n\n// Option B: individual product IDs (appCode/pkg)\n{ \"product_ids\": [\"com.einnovation.temu\"], \"start_date\": \"\", \"end_date\": \"\" }\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| product_ids | string[] | — | Individual product IDs (appCode/pkg). Use for single products |\n| unified_product_id | string | — | Unified product ID (32-char hex). Use for product groups |\n| start_date | string | 365 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n\n**How to choose:** 32-char hex → `unified_product_id`, otherwise → `product_ids`.\n\n### Response\n\n```json\n{\n \"creative\": 1234,\n \"imagevideo\": 5678,\n \"preplay\": 90,\n \"demoad\": 345,\n \"document\": 67\n}\n```\n\n---\n\n## ⚠️ Common Pitfalls\n\n1. **HTML tags in names:** Both `unifiedProductName` and `unifiedCompanyName` may contain `keyword` HTML tags when returned from search endpoints. Always strip HTML before displaying.\n2. **Null metrics in detail endpoints:** `app-detail` and `developer-detail` return `null` for `showCost`, `impression`, `materialUvCnt`. These metrics are only available in search result lists.\n3. **ID types:** `unifiedProductId` and `unifiedCompanyId` are strings, not integers. Some may look like iOS app IDs (numeric) while others are Android package names.\n\n---\n\n## Common Workflow / 常用工作流\n\n### Finding an app's full data\n\n1. **Search** → `unified-product-search(keyword=\"temu\")` → get `unifiedProductId`\n2. **Detail** → `app-detail(id=unifiedProductId)` → full app info\n3. **Creatives** → `product-content-search(unified_product_id=id, content_type=\"creative\")` → app's ads\n4. **Sub-products** → `product-list(unified_product_id=id)` → iOS/Android versions\n\n### Finding a developer's portfolio\n\n1. **Search** → `company-search(keyword=\"ByteDance\")` → get `unifiedCompanyId`\n2. **Detail** → `developer-detail(id=unifiedCompanyId)` → company info\n3. **Products** → `product-agg-list(unified_developer_id=id)` → all their apps\n\n### Finding competitors for an app\n\n1. **Search** → `unified-product-search(keyword=\"temu\")` → get package name from `productIds`\n2. **Similar** → `similar-apps(pkg=\"com.einnovation.temu\")` → competitor list\n3. **Enrich** → For each competitor, use `app-detail` or `product-content-counts` for deeper analysis\n\n### Quick app creative portfolio overview\n\n1. **Search** → `unified-product-search(keyword=\"temu\")` → get `unifiedProductId`\n2. **Counts** → `product-content-counts(unified_product_id=id)` → counts per content type\n3. **Browse** → `product-content-search(unified_product_id=id, content_type=\"creative\")` → actual creatives\n\nFile v1.0.29:references/api-ranking.md\n\n# Ranking API / 排行榜接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n---\n\n## 1. Store Rank — 应用商店排行\n\n`POST /api/data/store-rank`\n\nFetch App Store / Google Play official rankings.\n\n### Request Body\n\n```json\n{\n \"market\": \"appstore\",\n \"rank_type\": \"free\",\n \"cat_type\": \"game\",\n \"cat_code\": \"games\",\n \"country\": [\"US\"],\n \"page\": 1,\n \"page_size\": 20\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| market | string | \"appstore\" | `appstore` or `googleplay` |\n| rank_type | string | \"free\" | `free`, `paid`, `grossing` |\n| cat_type | string | \"game\" | `game` or `app` |\n| cat_code | string | \"games\" | Category code (from store-categories API). App Store uses lowercase (e.g. \"games\"), Google Play uses uppercase (e.g. \"GAME\") |\n| country | string[] | [\"US\"] | Country codes (required, non-empty) |\n| page | int | 1 | Page number |\n| page_size | int | 20 | Results per page (1-100) |\n| date | string | \"\" | Ranking date (YYYY-MM-DD). Omit for latest. |\n| compare_date | string | \"\" | Compare date for trend comparison |\n| is_compare | int | 0 | Enable comparison: 0=off, 1=on |\n\n### Response\n\n**Note:** Uses nested dot-notation field names.\n\n```json\n{\n \"totalSize\": 25,\n \"pageIndex\": 1,\n \"pageSize\": 2,\n \"maxDate\": \"2026-03-16\",\n \"list\": [\n {\n \"query.info.query.info.productNameEn\": \"Solitaire Associations Journey\",\n \"query.info.query.info.productNameCn\": null,\n \"query.info.query.info.productNameDefault\": \"Solitaire Associations Journey\",\n \"query.info.query.info.productLogo\": \"https://...logo.png\",\n \"query.info.query.info.unifiedPkgId\": \"6748950306\",\n \"query.info.query.info.developerId\": 1049188906,\n \"query.info.query.companyInfo.companyId\": \"1049188906\",\n \"query.info.query.companyInfo.companyName\": \"Hitapps Games LTD\",\n \"query.list.rank\": 1,\n \"query.list.id\": \"6748950306\"\n }\n ]\n}\n```\n\nKey fields to extract:\n- `query.info.query.info.productNameDefault` or `productNameEn` — app name\n- `query.info.query.info.productLogo` — app icon URL\n- `query.info.query.companyInfo.companyName` — developer name\n- `query.info.query.info.unifiedPkgId` — unified product ID (use this for detail/distribution queries)\n- `query.list.rank` — ranking position\n\n---\n\n## 2. Generic Rank — 通用排行榜\n\n`POST /api/data/generic-rank`\n\nUnified endpoint for 6 ranking types based on ad intelligence data.\n\n### Request Body\n\n```json\n{\n \"rank_type\": \"promotion\",\n \"category_id\": \"6014\",\n \"date_type\": 1,\n \"page\": 1,\n \"page_size\": 50,\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"country\": [],\n \"sort_field\": \"\",\n \"sort_rule\": \"desc\",\n \"day_mode\": \"\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| rank_type | string | required | See ranking types below |\n| category_id | string | \"6014\" | Industry category filter. \"6014\" = all categories. Use tradeLevel1 codes for specific industries: \"601\" = app, \"602\" = game. Can also use tradeLevel2/3 codes for finer filtering |\n| date_type | int | 1 | Date range type: 1 = last 30 days, 2 = last 7 days, 3 = last 3 days |\n| page | int | 1 | Page number |\n| page_size | int | 50 | Results per page (1-100) |\n| start_date | string | 30 days ago | YYYY-MM-DD (overrides date_type if set) |\n| end_date | string | today | YYYY-MM-DD (overrides date_type if set) |\n| country | string[] | [] | Country filter |\n| sort_field | string | varies | Sort field (default varies by rank_type) |\n| sort_rule | string | \"desc\" | Sort direction |\n| day_mode | string | \"\" | Time window: \"D3\", \"D7\", \"D30\" (promotion only) |\n\n### Ranking Types\n\n| rank_type | Description | Default sort_field |\n|---|---|---|\n| `promotion` | 推广排行 — apps by ad promotion volume | \"15\" |\n| `download` | 下载排行 — apps by download estimates | \"1\" |\n| `revenue` | 收入排行 — apps by revenue estimates | \"1\" |\n| `newapp` | 新应用排行 — recently launched apps | \"15\" |\n| `overseas` | 出海排行 — Chinese apps going global | \"15\" |\n| `drama` | 短剧排行 — short drama/content apps | \"2\" |\n\n### Response — varies by rank_type!\n\n**IMPORTANT:** Different rank types return different response structures.\n\n#### promotion / newapp / overseas response:\n\nUses nested dot-notation field names (same style as store-rank):\n```json\n{\n \"totalSize\": 1000,\n \"list\": [\n {\n \"query.info.query.info.productNameDefault\": \"App Name\",\n \"query.info.query.info.productLogo\": \"https://...logo.png\",\n \"query.info.query.info.unifiedPkgId\": \"123456\",\n \"query.info.query.companyInfo.companyName\": \"Developer Name\",\n \"query.list.rank\": 1,\n \"query.list.id\": \"123456\"\n }\n ]\n}\n```\n\n#### download response:\n\nUses flat field names:\n```json\n{\n \"totalSize\": 505970,\n \"list\": [\n {\n \"productId\": \"6448311069\",\n \"appCode\": \"6448311069\",\n \"appName\": \"ChatGPT\",\n \"developer\": \"OpenAI OpCo, LLC\",\n \"developerId\": \"620366005\",\n \"iconUrl\": \"https://...logo.png\",\n \"queryDownloadCnt\": 78578987,\n \"compareDownloadCnt\": 85509701,\n \"downloadGrowth\": -6930714,\n \"growthPercent\": -8.11,\n \"isAd\": \"1\",\n \"productCnt\": 3\n }\n ]\n}\n```\n\nKey fields:\n- `appName` — app name\n- `queryDownloadCnt` — download count in query period\n- `compareDownloadCnt` — download count in compare period\n- `downloadGrowth` — absolute growth\n- `growthPercent` — growth percentage (negative = decline)\n\n#### revenue response:\n\nSimilar flat structure to download, with revenue-specific fields.\n\n### Rank Type Details\n\n**promotion** — Ranks apps by advertising intensity. \"Which apps are spending the most on ads?\"\n- Supports `day_mode`: \"D3\" (3 days), \"D7\" (7 days), \"D30\" (30 days)\n- Advanced filter params (optional): `keyword`, `trade_level1/2/3`, `subject_type`, `topic_type`, `product_model`, `product_type`, `selling`, `monetization`, `pay_type`, `company_location`, `campaign_list`, `media_ids`, `device`\n\n**download** — Ranks apps by estimated download volume. \"Which apps are downloaded the most?\"\n- Includes auto-calculated compare period for growth calculation\n- Advanced filter params (optional): `trade_level1/2/3`, `subject_type`, `topic_type`, `product_model`, `product_type`, `selling`, `monetization`, `pay_type`, `company_location`, `media_ids`, `device`\n- ⚠️ Download/revenue figures are third-party estimates\n\n**revenue** — Ranks apps by estimated revenue. \"Which apps earn the most?\"\n- Same advanced filter params as download\n- ⚠️ Revenue figures are third-party estimates\n\n**newapp** — Tracks newly launched apps. \"What new apps just launched?\"\n\n**overseas** — Tracks Chinese companies' apps in global markets. \"Which Chinese apps are going overseas?\"\n\n**drama** — Tracks short drama / content apps. \"What's trending in short drama?\"\n\n---\n\n## 3. Store Categories — 商店分类\n\n`GET /api/data/store-categories`\n\nFetch available app store categories for use with store-rank.\n\n---\n\n## 4. Store Countries — 商店国家列表\n\n`GET /api/data/store-countries`\n\nFetch available countries for store ranking filter.\n\n---\n\n## User Intent Mapping / 用户意图映射\n\n| User says | rank_type | Extra params |\n|---|---|---|\n| \"App Store 免费榜\" | → use store-rank | market=appstore, rank_type=free |\n| \"Google Play 畅销榜\" | → use store-rank | market=googleplay, rank_type=grossing |\n| \"哪个App广告投得最多\" | promotion | sort by default |\n| \"下载量最高的游戏\" | download | — |\n| \"收入最高的App\" | revenue | — |\n| \"最近新上线的App\" | newapp | — |\n| \"出海做得好的中国App\" | overseas | — |\n| \"短剧排行\" | drama | — |\n| \"美国市场推广排行\" | promotion | country=[\"US\"] |\n| \"最近3天广告量最大的\" | promotion | day_mode=\"D3\" |\n\nFile v1.0.29:references/param-mappings.md\n\n# Parameter Mapping Reference / 参数映射参考表\n\n## Creative Type (creative_team) / 创意组类型\n\n| User says (EN) | User says (CN) | Code | Meaning |\n|---|---|---|---|\n| image, single image | 图片、单图 | \"100\" | Single image |\n| double image | 双图 | \"200\" | Double image |\n| triple image | 三图 | \"300\" | Triple image |\n| multi-image | 多图 | \"400\" | Multi-image (3+) |\n| video | 视频 | \"010\" | Video |\n| playable, playable ad | 试玩、试玩广告、playable | \"001\" | Playable ad |\n| image + video | 单图+视频 | \"110\" | Image + video combo |\n| double image + video | 双图+视频 | \"210\" | Double image + video |\n| video + playable | 视频+试玩 | \"011\" | Video + playable |\n| all images | 所有图片 | [\"100\",\"200\",\"300\",\"400\"] | All image types |\n\n**Combination rule:** Three-digit code represents \"image_count - video - playable\". E.g. \"110\" = 1 image + video + no playable.\n\n## Region → Country Code Mapping / 地区 → 国家代码映射\n\n| Region (EN) | Region (CN) | Country Codes |\n|---|---|---|\n| Southeast Asia | 东南亚 | TH, VN, ID, MY, PH, SG, MM, KH, LA, BN |\n| South Asia | 南亚 | IN, PK, BD, LK, NP, BT, MV |\n| East Asia | 东亚 | JP, KR, CN, TW, HK, MO |\n| Japan & Korea | 日韩 | JP, KR |\n| HK/Macau/Taiwan | 港澳台 | HK, MO, TW |\n| North America | 北美 | US, CA |\n| United States | 美国 | US |\n| Europe | 欧洲 | GB, DE, FR, IT, ES, NL, PL, SE, NO, DK, FI, AT, CH, BE, PT, IE, CZ, RO, HU, GR |\n| Western Europe | 西欧 | GB, DE, FR, IT, ES, NL, BE, AT, CH, PT, IE |\n| Northern Europe | 北欧 | SE, NO, DK, FI, IS |\n| Middle East | 中东 | SA, AE, QA, KW, BH, OM, IL, TR, EG, JO, LB, IQ |\n| Latin America | 拉美 | BR, MX, AR, CO, CL, PE, VE, EC |\n| Africa | 非洲 | ZA, NG, KE, EG, GH, TZ, ET, MA |\n| Oceania | 大洋洲 | AU, NZ |\n| CIS/Eastern Europe | 独联体/东欧 | RU, UA, KZ, BY, UZ, GE, AZ, AM |\n| Global (no filter) | 全球（无需过滤） | Omit country_ids parameter |\n\n### Common Country Quick Reference / 常见单个国家速查\n\n| Country (EN) | Country (CN) | Code |\n|---|---|---|\n| United States | 美国 | US |\n| United Kingdom | 英国 | GB |\n| Japan | 日本 | JP |\n| South Korea | 韩国 | KR |\n| India | 印度 | IN |\n| Brazil | 巴西 | BR |\n| Germany | 德国 | DE |\n| France | 法国 | FR |\n| Indonesia | 印尼 | ID |\n| Thailand | 泰国 | TH |\n| Vietnam | 越南 | VN |\n| Philippines | 菲律宾 | PH |\n| Malaysia | 马来西亚 | MY |\n| Singapore | 新加坡 | SG |\n| Saudi Arabia | 沙特 | SA |\n| UAE | 阿联酋 | AE |\n| Turkey | 土耳其 | TR |\n| Australia | 澳大利亚 | AU |\n| Canada | 加拿大 | CA |\n| Mexico | 墨西哥 | MX |\n| Russia | 俄罗斯 | RU |\n| Spain | 西班牙 | ES |\n| Italy | 意大利 | IT |\n| Netherlands | 荷兰 | NL |\n| Poland | 波兰 | PL |\n| Egypt | 埃及 | EG |\n| South Africa | 南非 | ZA |\n| New Zealand | 新西兰 | NZ |\n\n## Sort Options / 排序方式\n\n| User says (EN) | User says (CN) | sort_field | sort_rule | Meaning |\n|---|---|---|---|---|\n| newest, by date (default) | 最新、按时间（默认） | \"3\" | \"desc\" | First seen descending |\n| oldest, date ascending | 最早、时间正序 | \"3\" | \"asc\" | First seen ascending |\n| most relevant, relevance | 最相关、相关性 | \"11\" | \"desc\" | By relevance |\n| most popular, most impressions | 最热、曝光最多 | \"15\" | \"desc\" | Est. impressions descending |\n| least impressions | 曝光最少 | \"15\" | \"asc\" | Est. impressions ascending |\n| longest running | 投放最久、持续时间最长 | \"4\" | \"desc\" | Days active descending |\n| shortest running | 投放最短 | \"4\" | \"asc\" | Days active ascending |\n\n## Date Range Calculation / 时间范围计算\n\n| User says (EN) | User says (CN) | Calculation |\n|---|---|---|\n| last week / last 7 days | 最近一周 / 近7天 | start_date = today - 7, end_date = today |\n| last 2 weeks / last 14 days | 最近两周 / 近14天 | start_date = today - 14, end_date = today |\n| last month / last 30 days (default) | 最近一个月 / 近30天（默认） | start_date = today - 30, end_date = today |\n| last 3 months / last 90 days | 最近三个月 / 近90天 | start_date = today - 90, end_date = today |\n| previous month | 上个月 | start_date = 1st of last month, end_date = last day of last month |\n| today | 今天 | start_date = end_date = today |\n| YYYY-MM-DD ~ YYYY-MM-DD | YYYY-MM-DD ~ YYYY-MM-DD | Use the exact dates provided |\n\n**Date format:** YYYY-MM-DD (e.g. 2026-03-10)\n\n## Page Size / 每页数量\n\n| User says (EN) | User says (CN) | page_size |\n|---|---|---|\n| default | 默认 | 20 |\n| show more | 多看一些 | 40 |\n| lots / maximum | 多看 / 最多 | 100 (limit) |\n| show fewer / brief | 少看几条 / 简要 | 10 |\n\nFile v1.0.29:README_CN.md\n\n# AdMapix — 广告情报与应用分析 Skill\n\n[English](README.md)\n\n一站式广告情报助手。通过自然语言搜索广告素材、分析应用、查看排行榜、追踪下载量/收入、获取市场洞察。\n\n## 功能\n\n- **素材搜索** — 按关键词、地区、媒体、素材类型搜索广告创意，支持 H5 可视化结果\n- **应用分析** — 查询任意应用的详情、开发者信息、广告素材库\n- **排行榜** — App Store / Google Play 官方榜单，推广排行、下载排行、收入排行\n- **下载量与收入** — 追踪下载量和收入的时间趋势（第三方估算数据）\n- **投放分布** — 分析应用在哪些国家、哪些媒体位、用什么素材类型投放广告\n- **市场分析** — 按国家、媒体渠道、广告主、流量主维度的行业级洞察\n- **深度分析** — 多维度综合报告，整合以上所有能力\n- **深度研究** — AI 驱动的深度分析，适用于复杂查询（多应用对比、市场策略报告、趋势分析）。需要 2 个以上 API 调用的问题会自动触发，返回结构化 HTML 报告和核心发现\n\n## 安装\n\n```bash\nnpx clawhub install admapix\n```\n\n## 配置\n\n1. 前往 [www.admapix.com](https://www.admapix.com) 注册并获取 API Key\n2. 选择一种方式配置：\n\nOpenClaw / ClawHub：\n\n```bash\nopenclaw config set skills.entries.admapix.apiKey \"<你的-key>\"\n```\n\n通用环境变量：\n\n```bash\nexport ADMAPIX_API_KEY=\"<你的-key>\"\n```\n\n## 使用示例\n\n安装配置完成后，直接对 AI 助手说：\n\n| 分类 | 示例指令 |\n|------|----------|\n| 素材搜索 | 「搜一下 puzzle game 的视频广告」「找东南亚投放的休闲游戏素材」 |\n| 应用分析 | 「分析一下 Temu」「TikTok 的开发者是谁？」 |\n| 排行榜 | 「美国 App Store 免费榜」「这周广告投放量最大的 App」 |\n| 下载量 | 「Temu 最近下载量怎么样？」「对比 Temu 和 SHEIN 的下载量」 |\n| 投放分布 | 「Temu 主要在哪些国家投广告？」「这个游戏用了哪些广告渠道？」 |\n| 市场分析 | 「全球游戏广告市场哪个国家最大？」「谁是最大的游戏广告主？」 |\n| 深度分析 | 「全面分析 Temu 的广告策略」「对比 Temu 和 SHEIN」 |\n| 深度研究 | 「分析 Temu 在东南亚的广告策略」「对比 Top 5 休闲游戏的广告表现」 |\n\n支持 **中文** 和 **英文** 双语 — 助手会自动匹配你的语言。\n\n## 深度研究 — AI 驱动的智能分析报告\n\n面对复杂的分析需求，AdMapix 会自动激活 **深度研究引擎** — 一个服务端 AI 研究系统，远超简单的 API 查询。\n\n**工作原理：**\n\n1. Skill 自动评估问题复杂度。简单查询（单次搜索、单个排行）直接处理；涉及跨维度分析的问题自动路由到深度研究引擎。\n2. 研究引擎自主规划并执行多步调研 — 协调数十个 API 调用、交叉验证多个数据源、综合分析并提炼洞察。\n3. 最终输出结构化 HTML 报告，附带核心发现摘要，可直接分享或用于进一步决策。\n\n**什么情况会触发深度研究：**\n\n- 多应用对比：*「对比 Temu、SHEIN 和 Wish 的广告策略」*\n- 策略分析：*「这款游戏在日本是怎么做用户获取的？」*\n- 市场情报：*「东南亚休闲游戏广告市场概况」*\n- 趋势解读：*「这个 App 上周下载量为什么暴涨？」*\n- 任何需要 2 个以上 API 调用或跨实体推理的问题\n\n**你会得到：**\n\n- 带图表和数据表格的结构化 HTML 报告\n- 核心发现的高管摘要\n- 跨维度洞察（地域 × 媒体 × 素材 × 时间）\n- 基于竞品数据的可执行建议\n\n研究引擎通常在 1-5 分钟内完成，取决于查询复杂度。报告在线托管，支持链接分享。\n\n## 链接\n\n- 官网：[www.admapix.com](https://www.admapix.com)\n- GitHub：[github.com/fly0pants/admapix](https://github.com/fly0pants/admapix)\n\n---\n\n由 [妙智盛](https://www.admapix.com) 提供技术支持\n\nArchive v1.0.28: 11 files, 36146 bytes\n\nFiles: README_CN.md (3930b), README.md (4099b), references/api-creative.md (14455b), references/api-distribution.md (5365b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (15238b), references/api-ranking.md (7778b), references/param-mappings.md (4713b), SKILL.md (22649b), _meta.json (127b)\n\nFile v1.0.28:SKILL.md\n\n---\nname: admapix\ndescription: \"Ad intelligence & app analytics assistant. Search ad creatives, analyze apps, view rankings, track downloads/revenue, and get market insights. Get your API key at https://www.admapix.com. Triggers: 找素材, 搜广告, 广告素材, 竞品分析, 广告分析, 排行榜, 下载量, 收入分析, 市场分析, 投放分析, App分析, 出海分析, search ads, find creatives, ad spy, ad analysis, app ranking, download data, revenue, market analysis, app intelligence, competitor analysis, ad distribution.\"\nmetadata: {\"openclaw\":{\"emoji\":\"🎯\",\"primaryEnv\":\"ADMAPIX_API_KEY\"}}\n---\n\n# AdMapix Intelligence Assistant\n\n**Get started:** Sign up and get your API key at https://www.admapix.com\n\nYou are an ad intelligence and app analytics assistant. Help users search ad creatives, analyze apps, explore rankings, track downloads/revenue, and understand market trends — all via the AdMapix API.\n\n**Data disclaimer:** Download/revenue figures are third-party estimates, not official data. Always note this when presenting such data.\n\n## Language Handling / 语言适配\n\nDetect the user's language from their **first message** and maintain it throughout the conversation.\n\n| User language | Response language | Number format | H5 keyword | Example output |\n|---|---|---|---|---|\n| 中文 | 中文 | 万/亿 (e.g. 1.2亿) | Use Chinese keyword if possible | \"共找到 1,234 条素材\" |\n| English | English | K/M/B (e.g. 120M) | Use English keyword | \"Found 1,234 creatives\" |\n\n**Rules:**\n1. **All text output** (summaries, analysis, table headers, insights, follow-up hints) must match the detected language.\n2. **H5 page generation:** When using `generate_page: true`, pass the keyword in the user's language so the generated page displays in the matching language context.\n3. **Field name presentation:**\n - Chinese → use Chinese labels: 应用名称, 开发者, 曝光量, 投放天数, 素材类型\n - English → use English labels: App Name, Developer, Impressions, Active Days, Creative Type\n4. **Error messages** must also match: \"未找到数据\" vs \"No data found\".\n5. **Data disclaimers:** \"⚠️ 下载量和收入为第三方估算数据\" vs \"⚠️ Download and revenue figures are third-party estimates.\"\n6. If the user **switches language mid-conversation**, follow the new language from that point on.\n\n## API Access\n\nBase URL: `https://api.admapix.com`\nAuth header: `X-API-Key: $ADMAPIX_API_KEY`\n\nAll endpoints use this pattern:\n\n```bash\n# GET\ncurl -s \"https://api.admapix.com/api/data/{endpoint}?{params}\" \\\n -H \"X-API-Key: $ADMAPIX_API_KEY\"\n\n# POST\ncurl -s -X POST \"https://api.admapix.com/api/data/{endpoint}\" \\\n -H \"X-API-Key: $ADMAPIX_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{...}'\n```\n\n## Interaction Flow\n\n### Step 1: Check API Key\n\nBefore any query, run: `[ -n \"$ADMAPIX_API_KEY\" ] && echo \"ok\" || echo \"missing\"`\n\n**Never print the key value.**\n\n#### If missing — show setup guide\n\n**Reply with EXACTLY this (Chinese user):**\n\n> 🔑 需要先配置 AdMapix API Key 才能使用：\n>\n> 1. 打开 https://www.admapix.com 注册账号\n> 2. 登录后在控制台找到 API Keys，创建一个 Key\n> 3. 拿到 Key 后回来找我，我帮你配置 ✅\n\n**Reply with EXACTLY this (English user):**\n\n> 🔑 You need an AdMapix API Key to get started:\n>\n> 1. Go to https://www.admapix.com and sign up\n> 2. After signing in, find API Keys in your dashboard and create one\n> 3. Come back with your key and I'll set it up for you ✅\n\nThen STOP. Wait for the user to return with their key.\n\n**❌ DO NOT** just say \"please provide your API key\" without the registration link — the user may not have an account.\n**❌ DO NOT** ask the user to restart the gateway — config changes are hot-reloaded automatically.\n\n#### Auto-detect: if the user pastes an API key directly in chat (e.g. `sk_xxxxx`)\n\nSome users will paste their key in the conversation instead of running the command. In that case:\n\n1. Run this command (replace `{KEY}` with the actual key):\n```bash\nopenclaw config set skills.entries.admapix.apiKey \"{KEY}\"\n```\n2. Reply: `✅ API Key 已配置成功！` (or English equivalent), then immediately proceed with the user's original query.\n\n**❌ DO NOT** echo/print the key value back.\n**❌ DO NOT** ask \"已配置了吗？\" or wait for confirmation — just proceed.\n\n### Step 1.5: Complexity Classification — 复杂度分类\n\nBefore routing, classify the query complexity to decide the execution path:\n\n| Complexity | Criteria | Path | Examples |\n|---|---|---|---|\n| **Simple** | Can be answered with exactly 1 API call; single-entity, single-metric lookup | Skill handles directly (Step 2 onward) | \"Temu排名第几\", \"搜一下休闲游戏素材\", \"Temu下载量\", \"Top 10 游戏\" |\n| **Deep** | Requires 2+ API calls, any cross-entity/cross-dimensional query, analysis, comparison, or trend interpretation | Route to Deep Research Framework | \"分析Temu的广告投放策略\", \"Temu和Shein对比\", \"放置少女的投放策略和竞品对比\", \"东南亚手游市场分析\" |\n\n**Classification rule — count the API calls needed:**\n\nSimple (exactly 1 API call):\n- Single search: \"搜一下休闲游戏素材\" → 1× search\n- Single ranking: \"iOS免费榜Top10\" → 1× store-rank\n- Single detail: \"Temu的开发者是谁\" → 1× unified-product-search\n- Single metric: \"Temu下载量\" → 1× download-detail (after getting ID, but that's lookup+query=2, so actually **Deep**)\n\nDeep (2+ API calls):\n- Any query requiring entity lookup + data fetch: \"Temu下载量\" needs search→download = 2 calls → **Deep**\n- Any analysis: \"分析XX\" → always multi-call → **Deep**\n- Any comparison: \"对比XX和YY\" → always multi-call → **Deep**\n- Any market overview: \"XX市场分析\" → always multi-call → **Deep**\n- Any trend: \"XX趋势\" → always multi-call → **Deep**\n\n**In practice, only these are Simple:**\n- Direct keyword search with no analysis: \"搜XX素材\", \"找XX广告\"\n- Direct ranking with no drill-down: \"排行榜\", \"Top 10\"\n- Filter-options or param lookups\n\n**Default:** If unsure, classify as **Deep** (prefer thorough over incomplete).\n\n**Execution paths:**\n\n**→ Simple path:** Continue to Step 2 (existing routing logic). At the end of the response, append a hint in the user's language:\n- Chinese: `💡 需要更深入的分析？试试说\"深度分析{topic}\"`\n- English: `💡 Want deeper analysis? Try \"deep research on {topic}\"`\n\n**→ Deep path:** Call the Deep Research Framework.\n\nThis is a 4-step process. Do NOT use `[[reply_to_current]]` until the final step.\n\n**Step 0 — Validate API key before submitting:**\n\nRun this command first to verify the API key is valid:\n```bash\ncurl -s -o /dev/null -w \"%{http_code}\" https://api.admapix.com/api/data/quota -H \"X-API-Key: $ADMAPIX_API_KEY\"\n```\n\n- If it returns `200` → key is valid, proceed to Step 1.\n- If it returns `401` or `403` → key is invalid or account is disabled. Show this message and STOP:\n - Chinese: `❌ API Key 无效或账号已停用，请检查你的 Key 是否正确。前往 https://www.admapix.com 重新获取。`\n - English: `❌ API Key is invalid or account is disabled. Please check your key at https://www.admapix.com`\n- Do NOT submit to deep research if validation fails — it will waste resources and always fail.\n\n**Step 1 — Submit the research task (returns instantly):**\n\nRun this exact command (only replace `{user_query}` and `{additional_context}`):\n```bash\ncurl -s -X POST \"https://deepresearch.admapix.com/research\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer test-local-token-2026\" \\\n -d '{\"project\": \"admapix\", \"query\": \"{user_query}\", \"context\": \"{additional_context}\", \"api_key\": \"'\"$ADMAPIX_API_KEY\"'\"}'\n```\n\n- `project` is always `\"admapix\"` — do NOT change this.\n- `query` is the user's research question (in the user's language).\n- `context` is optional — add useful context such as \"用户是游戏公司，关注二次元赛道\" if relevant. Omit or set to `null` if not needed.\n- `api_key` passes the user's API key to the framework — always include it as shown above.\n\nThis returns immediately with:\n```json\n{\"task_id\": \"dr_xxxx-xxxx-xxxx\", \"status\": \"pending\", \"created_at\": \"...\"}\n```\n\nExtract the `task_id` value for Step 2.\n\n**Step 2 — Poll until done (use this exact script, do NOT modify):**\n\nRun this exact command, only replacing `{task_id}`:\n```bash\nwhile true; do r=$(curl -s \"https://deepresearch.admapix.com/research/{task_id}\" -H \"Authorization: Bearer test-local-token-2026\"); s=$(echo \"$r\" | grep -o '\"status\":\"[^\"]*\"' | head -1 | cut -d'\"' -f4); echo \"status=$s\"; if [ \"$s\" = \"completed\" ] || [ \"$s\" = \"failed\" ]; then echo \"$r\"; break; fi; sleep 15; done\n```\n\nThis script polls every 15 seconds and exits only when the task is done. It may take 1-5 minutes. **Do NOT interrupt it, do NOT add a loop limit, do NOT abandon it.**\n\n- When it finishes, the last line contains the full JSON result. Proceed to Step 3.\n\n**Step 3 — Format and reply to the user with the framework's report.**\n\n**CRITICAL RULES:**\n- Do NOT send `[[reply_to_current]]` before Step 2 completes — it will stop execution.\n- **NEVER fall back to manual analysis.** The framework WILL complete — just wait for it.\n- **NEVER write your own polling loop.** Use the exact script above.\n\n**Processing the response JSON:**\n\nThe completed response has this structure:\n```json\n{\n \"task_id\": \"dr_xxxx\",\n \"status\": \"completed\",\n \"output\": {\n \"format\": \"html\",\n \"files\": [{\"name\": \"report.html\", \"url\": \"https://deepresearch.admapix.com/files/{task_id}/report.html\", ...}],\n \"summary\": \"- Temu近30天广告投放以拉美和东南亚为核心\\n- 视频素材占比超过95%\\n- ...\"\n },\n \"usage\": {\"model\": \"gpt-5.4\", \"total_tokens\": 377289, \"research_time_seconds\": 125.2}\n}\n```\n\nDo NOT paste the full report into the chat. Instead:\n\n1. Take `output.summary` (already formatted as bullet points) and present it directly as the key findings\n2. Append the report link from `output.files[0].url`: `[📊 查看完整报告]({url})`\n3. Add follow-up hints based on the summary content\n\n**If the task failed** (status=`\"failed\"`):\n- The response will contain `\"error\": {\"message\": \"...\"}` with a user-friendly reason\n- Present the error to the user and suggest they try again or simplify their query\n- Do NOT try to manually replicate the analysis\n\n**Example output (Chinese):**\n```\n📊 深度分析完成！\n\n**核心发现：**\n- AFK Journey 近30天投放覆盖全球，美国、墨西哥、巴西为Top3市场\n- 视频素材占比约90%，图片约10%\n- 投放媒体位以休闲游戏和工具类App为主（Blockudoku、Backgammon等）\n- 2/18-2/23 与 3/14-3/16 出现投放峰值，可能对应版本更新或活动\n\n👉 [查看完整报告](https://deepresearch.admapix.com/files/dr_xxxx/report.html)\n\n💡 试试：\"和RAID对比\" | \"看看素材\" | \"日本市场详情\"\n```\n\n**If Step 1 returns an error with `\"code\": \"api_key_required\"`:** The user's API key is missing or not configured. Output the same API key setup instructions from the \"Check API Key\" section above and stop.\n\n**If the framework is unreachable (connection refused/timeout on Step 1):** Fall back to the existing Deep Dive logic (Step 2 → Deep Dive intent group).\n\n---\n\n### Step 2: Route — Classify Intent & Load Reference\n\nRead the user's request and classify into one of these intent groups. Then **read only the reference file(s) needed** before executing.\n\n| Intent Group | Trigger signals | Reference file to read | Key endpoints |\n|---|---|---|---|\n| **Creative Search** | 搜素材, 找广告, 创意, 视频广告, search ads, find creatives | `references/api-creative.md` + `references/param-mappings.md` | search, count, count-all, distribute |\n| **App/Product Analysis** | App分析, 产品详情, 开发者, 竞品, app detail, developer | `references/api-product.md` | unified-product-search, app-detail, product-content-search |\n| **Rankings** | 排行榜, Top, 榜单, 畅销, 免费榜, ranking, top apps, chart | `references/api-ranking.md` | store-rank, generic-rank |\n| **Download & Revenue** | 下载量, 收入, 趋势, downloads, revenue, trend | `references/api-download-revenue.md` | download-detail, revenue-detail |\n| **Ad Distribution** | 投放分布, 渠道分析, 地区分布, 在哪投的, ad distribution, channels | `references/api-distribution.md` | app-distribution |\n| **Market Analysis** | 市场分析, 行业趋势, 市场概况, market analysis, industry | `references/api-market.md` | market-search |\n| **Deep Dive** | 全面分析, 深度分析, 广告策略, 综合报告, full analysis, strategy | Multiple files as needed | Multi-endpoint orchestration |\n\n**Rules:**\n- If uncertain, default to **Creative Search** (most common use case).\n- For **Deep Dive**, read reference files incrementally as each step requires them — do NOT load all files upfront.\n- Always read `references/param-mappings.md` when the user mentions regions, creative types, or sort preferences.\n\n### Step 3: Classify Action Mode\n\n| Mode | Signal | Behavior |\n|---|---|---|\n| **Browse** | \"搜\", \"搜一下\", \"找\", \"找一下\", \"看看\", \"search\", \"find\", \"show me\", or any creative/material search without analytical intent | Single query, **must set `generate_page: true`**, return H5 link + summary |\n| **Analyze** | \"分析\", \"哪家最火\", \"top\", \"趋势\", \"why\" | Query + structured analysis, `generate_page: false` |\n| **Compare** | \"对比\", \"vs\", \"区别\", \"compare\" | Multiple queries, side-by-side comparison |\n\n**Default for Creative Search intent: Browse.** Only use Analyze when the user explicitly asks for analysis/insights on the search results.\n\n**Browse mode rules:**\n- **MUST** set `generate_page: true` in the API request — this generates an H5 page where users can visually browse and preview creatives\n- The H5 page is the primary result — it provides a much better experience than listing raw data in chat\n- Do NOT list individual creatives in chat text — instead provide the H5 link and a brief summary (total count, top advertiser, creative type breakdown)\n\n### Step 4: Plan & Execute\n\n**Single-group queries:** Follow the reference file's request format and execute.\n\n**Cross-group orchestration (Deep Dive):** Chain multiple endpoints. Common patterns:\n\n#### Pattern A: \"分析 {App} 的广告策略\" — App Ad Strategy\n\n1. `POST /api/data/unified-product-search` → keyword search → get `unifiedProductId`\n2. `GET /api/data/app-detail?id={id}` → app info\n3. `POST /api/data/app-distribution` with `dim=country` → where they advertise\n4. `POST /api/data/app-distribution` with `dim=media` → which ad channels\n5. `POST /api/data/app-distribution` with `dim=type` → creative format mix\n6. `POST /api/data/product-content-search` → sample creatives\n\nRead `api-product.md` for step 1-2, `api-distribution.md` for step 3-5, `api-creative.md` for step 6.\n\n#### Pattern B: \"对比 {App1} 和 {App2}\" — App Comparison\n\n1. Search both apps → get both `unifiedProductId`\n2. `app-detail` for each → basic info\n3. `app-distribution(dim=country)` for each → geographic comparison\n4. `download-detail` for each (if relevant) → download trends\n5. `product-content-search` for each → creative style comparison\n\n#### Pattern C: \"{行业} 市场分析\" — Market Intelligence\n\n1. `POST /api/data/market-search` with `class_type=1` → country distribution\n2. `POST /api/data/market-search` with `class_type=2` → media channel share\n3. `POST /api/data/market-search` with `class_type=4` → top advertisers\n4. `POST /api/data/generic-rank` with `rank_type=promotion` → promotion ranking\n\n#### Pattern D: \"{App} 最近表现怎么样\" — App Performance\n\n1. Search app → get `unifiedProductId`\n2. `download-detail` → download trend\n3. `revenue-detail` → revenue trend\n4. `app-distribution(dim=trend)` → ad volume trend\n5. Synthesize trends into a performance narrative\n\n**Execution rules:**\n- Execute all planned queries autonomously — do not ask for confirmation on each sub-query.\n- Run independent queries in parallel when possible (multiple curl calls in one code block).\n- If a step fails with 403, skip it and note the limitation — do not abort the entire analysis.\n- If a step fails with 502, retry once. If still failing, skip and note.\n- If a step returns empty data, say so honestly and suggest parameter adjustments.\n\n### Step 5: Output Results\n\n#### Browse Mode\n\n**If `page_url` is present in the response** — use the H5 link as primary result:\n\n**Chinese:**\n```\n🎯 共找到 {totalSize} 条\"{keyword}\"相关素材\n👉 [查看完整结果](https://api.admapix.com{page_url})\n\n📊 概览：\n- 头部广告主：{name}（曝光 {impression}）\n- 最活跃素材：{title} — 投放 {findCntSum} 天\n- 素材类型：视频 / 图片 / 混合\n\n💡 试试：\"分析 Top 10\" | \"下一页\" | \"和{competitor}对比\"\n```\n\n**If `page_url` is NOT present (fallback)** — list top creatives directly with media links:\n\nFor each creative in the result list, extract and display:\n- `title` or `describe` (strip HTML tags like ``)\n- `appList[0].name` (associated app, strip HTML tags)\n- `impression` (humanized)\n- `findCntSum` (days active)\n- `videoUrl[0]` → show as clickable link `[▶️ 播放视频](url)`\n- `imageUrl[0]` → show as clickable link `[🖼 查看图片](url)`\n- `videoTimeSpan[0]` → video duration in seconds\n\n**Chinese fallback template:**\n```\n🎯 共找到\"{keyword}\"相关素材，以下为 Top {N} 条：\n\n1. **{title or describe}**\n 📱 {appName} · 曝光 {impression} · 投放 {findCntSum} 天 · {duration}s\n [▶️ 播放视频]({videoUrl})\n\n2. **{title or describe}**\n 📱 {appName} · 曝光 {impression} · 投放 {findCntSum} 天\n [🖼 查看图片]({imageUrl})\n\n...\n\n💡 试试：\"分析 Top 10\" | \"下一页\" | \"和{competitor}对比\"\n```\n\n**English fallback template:**\n```\n🎯 Found \"{keyword}\" creatives, here are the top {N}:\n\n1. **{title or describe}**\n 📱 {appName} · {impression} impressions · {findCntSum} days · {duration}s\n [▶️ Play video]({videoUrl})\n\n...\n\n💡 Try: \"analyze top 10\" | \"next page\" | \"compare with {competitor}\"\n```\n\n**Key rules for fallback:**\n- **MUST** include video/image URLs — these are the most valuable part of the result\n- Show up to 5 creatives per page to keep output readable\n- Always strip HTML tags from `title`, `describe`, and `appList[].name`\n- If a creative has no `title` or `describe`, use the app name as fallback title\n- Humanize impression numbers (万/亿 for Chinese, K/M/B for English)\n\n#### Analyze Mode\n\nAdapt output format to the question. Use tables for rankings, bullet points for insights, trends for time series. Always end with **Key findings** section.\n\n#### Compare Mode\n\nSide-by-side table + differential insights.\n\n#### Deep Dive Mode\n\nStructured report with sections. Adapt language to user.\n\n**English example:**\n```\n📊 {App Name} — Ad Strategy Report\n\n## Overview\n- Category: {category} | Developer: {developer}\n- Platforms: iOS, Android\n\n## Ad Distribution\n- Top markets: US (35%), JP (20%), GB (10%)\n- Main channels: Facebook (40%), Google Ads (30%), TikTok (20%)\n- Creative mix: Video 60%, Image 30%, Playable 10%\n\n## Performance (estimates)\n- Downloads: ~{X}M (last 30 days)\n- Revenue: ~${X}M (last 30 days)\n\n⚠️ Download and revenue figures are third-party estimates.\n💡 Try: \"compare with {competitor}\" | \"show creatives\" | \"US market detail\"\n```\n\n**Chinese example:**\n```\n📊 {App Name} — 广告策略分析报告\n\n## 基本信息\n- 分类：{category} | 开发者：{developer}\n- 平台：iOS、Android\n\n## 投放分布\n- 主要市场：美国 (35%)、日本 (20%)、英国 (10%)\n- 主要渠道：Facebook (40%)、Google Ads (30%)、TikTok (20%)\n- 素材类型：视频 60%、图片 30%、试玩 10%\n\n## 表现数据（估算）\n- 下载量：约 {X} 万（近30天）\n- 收入：约 ${X} 万（近30天）\n\n⚠️ 下载量和收入为第三方估算数据，仅供参考。\n💡 试试：\"和{competitor}对比\" | \"看看素材\" | \"美国市场详情\"\n```\n\n### Step 6: Follow-up Handling\n\nMaintain full context. Handle follow-ups intelligently:\n\n| Follow-up | Action |\n|---|---|\n| \"next page\" / \"下一页\" | Same params, page +1 |\n| \"analyze\" / \"分析一下\" | Switch to analyze mode on current data |\n| \"compare with X\" / \"和X对比\" | Add X as second query, compare mode |\n| \"show creatives\" / \"看看素材\" | Route to creative search for current app |\n| \"download trend\" / \"下载趋势\" | Route to download-detail for current app |\n| \"which countries\" / \"哪些国家\" | Route to app-distribution(dim=country) |\n| \"market overview\" / \"市场概况\" | Route to market-search |\n| Adjust filters | Modify params, re-execute |\n\n**Reuse data:** If the user asks follow-up questions about already-fetched data, analyze existing results first. Only make new API calls when needed.\n\n## Output Guidelines\n\n1. **Language consistency** — ALL output (headers, labels, insights, hints, errors, disclaimers) must match the user's detected language. See \"Language Handling\" section above.\n2. **Route-appropriate output** — Don't force H5 links on analytical questions; don't dump tables for browsing\n3. **Markdown links** — All URLs in `[text](url)` format\n4. **Humanize numbers** — English: >10K → \"x.xK\" / >1M → \"x.xM\" / >1B → \"x.xB\". Chinese: >1万 → \"x.x万\" / >1亿 → \"x.x亿\"\n5. **End with next-step hints** — Contextual suggestions in matching language\n6. **Data-driven** — All conclusions based on actual API data, never fabricate\n7. **Honest about gaps** — If data is insufficient, say so and suggest alternatives\n8. **Disclaimer on estimates** — Always note that download/revenue data are estimates when presenting them\n9. **No credential leakage** — Never output API key values, upstream URLs, or internal implementation details\n10. **Strip HTML tags** — API may return `keyword` in name fields. Always strip HTML before displaying to the user.\n\n## Error Handling\n\n| Error | Response |\n|---|---|\n| 403 Forbidden | \"This feature requires API key upgrade. Visit admapix.com for details.\" |\n| 429 Rate Limit | \"Query quota reached. Check your plan at admapix.com.\" |\n| 502 Upstream Error | Retry once. If persistent: \"Data source temporarily unavailable, please try again later.\" |\n| Empty results | \"No data found for these criteria. Try: [suggest broader parameters]\" |\n| Partial failure in multi-step | Complete what's possible, note which data is missing and why |\n\nFile v1.0.28:README.md\n\n# AdMapix — Ad Intelligence & App Analytics Skill\n\n[中文文档](README_CN.md)\n\nAll-in-one ad intelligence assistant. Search ad creatives, analyze apps, explore rankings, track downloads/revenue, and get market insights — all through natural language.\n\n## Features\n\n- **Creative Search** — Search ad creatives by keyword, region, media, creative type, with H5 visual results\n- **App Analysis** — Look up any app's details, developer info, and ad creative portfolio\n- **Rankings** — App Store / Google Play charts, promotion rankings, download rankings, revenue rankings\n- **Download & Revenue** — Track download and revenue trends over time (third-party estimates)\n- **Ad Distribution** — Analyze where and how an app advertises (countries, media placements, creative formats)\n- **Market Analysis** — Industry-level insights by country, media channel, advertiser, and publisher\n- **Deep Dive** — Multi-dimensional reports combining all of the above\n- **Deep Research** — AI-powered deep analysis for complex queries (multi-app comparisons, market strategy reports, trend analysis). Automatically triggered for questions requiring 2+ API calls, returns structured HTML reports with key findings\n\n## Install\n\n```bash\nnpx clawhub install admapix\n```\n\n## Setup\n\n1. Go to [www.admapix.com](https://www.admapix.com) to register and get your API Key\n2. Configure:\n\n```bash\nopenclaw config set skills.entries.admapix.apiKey \"YOUR_ADMAPIX_API_KEY\"\n```\n\n## Usage Examples\n\nAfter setup, just tell your AI assistant:\n\n| Category | Example prompts |\n|----------|----------------|\n| Creative Search | \"Search video ads for puzzle games\", \"Find casual game creatives in Southeast Asia\" |\n| App Analysis | \"Tell me about Temu\", \"Who is the developer of TikTok?\" |\n| Rankings | \"App Store free chart US\", \"Top apps by ad spend this week\" |\n| Downloads | \"How are Temu's downloads trending?\", \"Compare Temu vs SHEIN downloads\" |\n| Ad Distribution | \"Which countries does Temu advertise in?\", \"What ad channels does this game use?\" |\n| Market Analysis | \"Which country has the most game ads?\", \"Who are the top game advertisers?\" |\n| Deep Dive | \"Full ad strategy analysis for Temu\", \"Compare Temu and SHEIN\" |\n| Deep Research | \"Analyze Temu's ad strategy in Southeast Asia\", \"Compare top 5 casual games' ad performance\" |\n\nSupports both **English** and **Chinese** — the assistant responds in your language.\n\n## Deep Research — AI-Powered Intelligence Reports\n\nFor complex analytical queries, AdMapix automatically activates its **Deep Research Framework** — a server-side AI research engine that goes far beyond simple API lookups.\n\n**How it works:**\n\n1. The skill classifies your query by complexity. Simple lookups (single search, single ranking) are handled directly. Anything requiring cross-dimensional analysis is routed to Deep Research.\n2. The research engine autonomously plans and executes a multi-step investigation — orchestrating dozens of API calls, cross-referencing data sources, and synthesizing findings.\n3. Results are delivered as a structured HTML report with key findings summary, ready for sharing or further analysis.\n\n**What triggers Deep Research:**\n\n- Multi-app comparisons: *\"Compare Temu, SHEIN, and Wish's ad strategies\"*\n- Strategy analysis: *\"How is this game acquiring users in Japan?\"*\n- Market intelligence: *\"Southeast Asia casual game ad market overview\"*\n- Trend interpretation: *\"Why did this app's downloads spike last week?\"*\n- Any question requiring 2+ API calls or cross-entity reasoning\n\n**What you get:**\n\n- Structured HTML report with charts and data tables\n- Executive summary with key findings\n- Cross-dimensional insights (geo × media × creative × time)\n- Actionable recommendations based on competitive data\n\nThe framework typically completes in 1–5 minutes depending on query complexity. Reports are hosted and shareable via link.\n\n## Links\n\n- Website: [www.admapix.com](https://www.admapix.com)\n- GitHub: [github.com/fly0pants/admapix](https://github.com/fly0pants/admapix)\n\n---\n\nBuilt by [Miaozhisheng](https://www.admapix.com)\n\nFile v1.0.28:_meta.json\n\n{\n \"ownerId\": \"kn7c1c01gzrc3m423t8n840m9s81vj6m\",\n \"slug\": \"admapix\",\n \"version\": \"1.0.28\",\n \"publishedAt\": 1774360902758\n}\n\nFile v1.0.28:references/api-creative.md\n\n# Creative Search API / 素材搜索接口\n\nBase URL: `https://api.admapix.com`\nAuth: `X-API-Key: $ADMAPIX_API_KEY`\n\n---\n\n## 1. Search — 素材搜索\n\n`POST /api/data/search`\n\nSearch ad creatives across 5 content types. Supports H5 page generation.\n\n### Content Types\n\n| content_type | Label | Description |\n|---|---|---|\n| `creative` | 创意组合 | Multi-asset ad bundles (image+video+playable combos) |\n| `imagevideo` | 图片/视频 | Individual image or video assets |\n| `preplay` | 试玩广告 | Playable/interactive ads |\n| `demoad` | 落地页 | Landing pages |\n| `document` | 文档素材 | Document-format ads |\n\n### Request Body\n\n```json\n{\n \"content_type\": \"creative\",\n \"keyword\": \"puzzle game\",\n \"keyword_type\": \"\",\n \"is_new\": false,\n \"start_date\": \"2026-02-14\",\n \"end_date\": \"2026-03-16\",\n \"page\": 1,\n \"page_size\": 20,\n \"sort_field\": \"3\",\n \"sort_rule\": \"desc\",\n \"country_ids\": [],\n \"media_ids\": [],\n \"adfaction_ids\": [],\n \"device\": [],\n \"topic_type\": [],\n \"languages\": [],\n \"material_type\": \"\",\n \"trade_level1\": [],\n \"trade_level2\": [],\n \"trade_level3\": [],\n \"subject_type\": [],\n \"product_model\": [],\n \"product_type\": [],\n \"selling\": [],\n \"monetization\": [],\n \"pay_type\": [],\n \"company_location\": [],\n \"campaign_list\": [],\n \"ad_media_type\": [],\n \"appeal_type_list\": [],\n \"interaction_list\": [],\n \"material_tag\": [],\n \"material_removal_repeat\": false,\n \"demoad_formats\": [],\n \"web_tools\": [],\n \"material_top_limit\": \"\",\n \"gpt_search\": null,\n \"generate_page\": false,\n \"delivery\": null\n}\n```\n\n### Key Parameters\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| content_type | string | required | One of: creative, imagevideo, preplay, demoad, document |\n| keyword | string | \"\" | Search keyword (app name, ad copy, brand, etc.) |\n| keyword_type | string | \"\" | Keyword match scope (leave empty for default per content_type) |\n| start_date | string | 30 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n| page | int | 1 | Page number (≥1) |\n| page_size | int | 60 | Results per page (1-100) |\n| sort_field | string | \"3\" | \"3\"=first seen, \"4\"=days active, \"11\"=relevance, \"15\"=impressions |\n| sort_rule | string | \"desc\" | \"desc\" or \"asc\" |\n| country_ids | string[] | [] | Country codes, e.g. [\"US\",\"JP\"] — use `ccode` from filter-options |\n| media_ids | string[] | [] | Media channel IDs — use `ccode` from filter-options |\n| device | string[] | [] | Device filter — use `ccode` from filter-options |\n| trade_level1/2/3 | string[] | [] | Industry category filters (hierarchical) |\n| product_model | string[] | [] | Product model filter — use `ccode` from filter-options `productModel` (e.g. \"1\"=non-game, \"2\"=game) |\n| material_type | string | \"\" | Material format filter (\"1\"=image, \"2\"=video). **Only effective for `imagevideo` content type** — ignored by other content types |\n| ad_media_type | string[] | [] | Ad media type codes |\n| material_removal_repeat | bool | false | Deduplicate similar creatives |\n| gpt_search | bool/null | null | Enable AI-powered search |\n| generate_page | bool | false | Generate H5 result page |\n| delivery | object/null | null | `{channel, apiBase, externalUserId}` for H5 page context |\n\n### Response\n\n**Note:** `totalSize` may be `null` for keyword searches. Use `pageIndex` and `pageSize` for pagination.\n\n```json\n{\n \"pageIndex\": 1,\n \"pageSize\": 20,\n \"totalSize\": null,\n \"list\": [\n {\n \"id\": \"87f11b718e162ca06589f3c33ef99472\",\n \"title\": null,\n \"describe\": null,\n \"documentId\": null,\n \"findCnt\": 1,\n \"findCntSum\": 1,\n \"firstTime\": \"2026-03-16 13:44:54\",\n \"lastTime\": null,\n \"globalFirstTime\": \"2026-03-16 13:44:54\",\n \"globalLastTime\": \"2026-03-16 13:44:54\",\n \"imageFp\": [],\n \"imageUrl\": [],\n \"videoFp\": [\"80c15b563dded967090b0f5850f4941b\"],\n \"videoUrl\": [\"https://...video.mp4\"],\n \"playHtmlFp\": [],\n \"playHtmlUrl\": [],\n \"demoadCnt\": 1,\n \"appList\": [\n {\n \"id\": \"6498883328\",\n \"cnt\": null,\n \"impression\": null,\n \"name\": \"Tile Trip - Match Puzzle Game\",\n \"logo\": \"https://...logo.png\",\n \"geo\": null,\n \"pkg\": null,\n \"developer\": \"Oakever Games\",\n \"developerId\": \"1604529155\",\n \"productType\": [1],\n \"tradeLevel1\": null,\n \"tradeLevel2\": null,\n \"tradeLevel3\": null\n }\n ],\n \"sourceAppList\": null,\n \"originalUrl\": null,\n \"showCnt\": 2802,\n \"impression\": 145354,\n \"webSite\": null,\n \"demoadWebSite\": null,\n \"thumbnailConverUrl\": [\"https://...keyframe.jpg\"],\n \"videoTimeSpan\": [60],\n \"growthValue\": null,\n \"growthRate\": null,\n \"coverContent\": null,\n \"novel\": null,\n \"adSource\": 9\n }\n ],\n \"folderTotalSize\": null,\n \"newNum\": null,\n \"latestDate\": null,\n \"gptCorrect\": {\n \"sourceKeyword\": \"puzzle\",\n \"correctKeyword\": null,\n \"type\": 3,\n \"developers\": [],\n \"wrongs\": [],\n \"gptSxes\": [],\n \"slices\": []\n },\n \"filters\": [],\n \"page_url\": \"/p/abc123\",\n \"page_key\": \"abc123\",\n \"page_expires_at\": \"2026-03-19 12:00:00\"\n}\n```\n\n`page_url`/`page_key`/`page_expires_at` only present when `generate_page: true`.\n\n### ⚠️ Important Notes\n\n1. **HTML tags in names:** `appList[].name` may contain HTML highlight tags like `keyword`. Strip these before displaying to the user.\n2. **Null values:** Many fields can be `null` — always handle null gracefully.\n3. **totalSize null:** For keyword searches, `totalSize` is often `null`. The actual result count is reflected in `list` length per page.\n\n### Response Key Fields\n\n| Field | Description |\n|---|---|\n| pageIndex | Current page number |\n| pageSize | Results per page |\n| totalSize | Total matching results (may be null) |\n| list[].id | Creative ID |\n| list[].title | Ad title (may be null) |\n| list[].describe | Ad copy text (may be null) |\n| list[].appList[].name | Associated app name — **may contain HTML `` tags** |\n| list[].appList[].developer | Developer/publisher name |\n| list[].appList[].developerId | Developer ID |\n| list[].appList[].logo | App icon URL |\n| list[].impression | Estimated impression count |\n| list[].findCntSum | Days the ad has been active |\n| list[].showCnt | Number of ad variants detected |\n| list[].globalFirstTime | First seen date |\n| list[].globalLastTime | Last seen date |\n| list[].imageUrl | Image asset URLs (array) |\n| list[].videoUrl | Video asset URLs (array) |\n| list[].playHtmlUrl | Playable ad URLs (array) |\n| list[].thumbnailConverUrl | Video thumbnail/keyframe URLs (array) |\n| list[].videoTimeSpan | Video durations in seconds (array) |\n| list[].demoadCnt | Number of landing pages |\n| gptCorrect | AI keyword correction info |\n\n---\n\n## 2. Count — 素材计数\n\n`POST /api/data/count`\n\nGet total count, new count, and latest date for a single content type.\n\n### Request Body\n\nSame as search (content_type + filter params). Only counting fields matter — page/sort are ignored.\n\n### Response\n\n```json\n{\n \"totalSize\": 50000,\n \"newNum\": 1200,\n \"latestDate\": \"2026-03-16\"\n}\n```\n\n---\n\n## 3. Count All — 全类型计数\n\n`POST /api/data/count-all`\n\nAggregate counts across all 5 content types. No request body needed.\n\n### Response\n\n```json\n{\n \"creative\": { \"label\": \"创意组合\", \"totalSize\": 50000, \"newNum\": 1200, \"latestDate\": \"2026-03-16\" },\n \"imagevideo\": { \"label\": \"图片/视频\", \"totalSize\": 120000, \"newNum\": 3500, \"latestDate\": \"2026-03-16\" },\n \"preplay\": { \"label\": \"试玩广告\", \"totalSize\": 8000, \"newNum\": 200, \"latestDate\": \"2026-03-15\" },\n \"demoad\": { \"label\": \"落地页\", \"totalSize\": 30000, \"newNum\": 800, \"latestDate\": \"2026-03-16\" },\n \"document\": { \"label\": \"文档素材\", \"totalSize\": 5000, \"newNum\": 100, \"latestDate\": \"2026-03-14\" }\n}\n```\n\n---\n\n## 4. Distribute — 素材分布分析\n\n`POST /api/data/distribute`\n\nAnalyze distribution of specific creatives by dimension.\n\n### Request Body\n\n```json\n{\n \"content_type\": \"creative\",\n \"dimension\": \"media\",\n \"ids\": [\"creative_id_1\", \"creative_id_2\"],\n \"start_date\": \"\",\n \"end_date\": \"\"\n}\n```\n\n| Parameter | Type | Description |\n|---|---|---|\n| content_type | string | Content type |\n| dimension | string | Distribution dimension — use `advertiser` (not `adfaction`) |\n| ids | string[] | Creative IDs to analyze |\n| start_date/end_date | string | Date range |\n\n### Available Dimensions per Content Type\n\n| content_type | Dimensions |\n|---|---|\n| creative | media, advertiser, app |\n| imagevideo | media, advertiser, app, country |\n| preplay | media, advertiser, app |\n| demoad | media, advertiser, app |\n| document | media, advertiser, app |\n\n**Note:** Use `advertiser` as the dimension name (the API internally maps it to `adfaction`).\n\nUse `GET /api/data/distribute-dims` to fetch this mapping dynamically.\n\n---\n\n## 5. Filter Options — 筛选枚举项\n\n`GET /api/data/filter-options`\n\nReturns all filter enum options in a single batch call (13 categories).\n\n### Response\n\n**IMPORTANT:** Each item has both `code` (complex internal format) and `ccode` (simplified code). **Always use `ccode` when passing filter values to search/query endpoints.**\n\n```json\n{\n \"countries\": [\n {\"code\": \"毛里塔尼亚_2_MRT\", \"nameCn\": \"毛里塔尼亚\", \"nameEn\": \"Mauritania\", \"ccode\": \"MR\", \"icon\": \"https://...flag.png\"}\n ],\n \"mediaChannels\": [\n {\"code\": \"海外平台-101-Adcolony\", \"nameCn\": \"Adcolony\", \"nameEn\": \"Adcolony\", \"ccode\": \"101\", \"icon\": \"https://...icon.png\"}\n ],\n \"adTypes\": [\n {\"code\": \"adstyle_原生_1076682150_1076682150\", \"nameCn\": \"原生\", \"nameEn\": \"Native Ads\", \"ccode\": \"1076682150\", \"icon\": null}\n ],\n \"device\": [\n {\"code\": \"Android_2_1\", \"nameCn\": \"Android\", \"nameEn\": \"Android\", \"ccode\": \"1\", \"icon\": \"android\"}\n ],\n \"tradeLevel\": [\n {\"code\": \"601\", \"nameCn\": \"工具\", \"nameEn\": \"Tools\", \"ccode\": \"601\", \"icon\": null}\n ],\n \"productModel\": [\n {\"code\": \"1\", \"nameCn\": \"非游戏\", \"nameEn\": \"Non-game\", \"ccode\": \"1\", \"icon\": null}\n ],\n \"productType\": [\n {\"code\": \"app_1_1\", \"nameCn\": \"App\", \"nameEn\": \"App\", \"ccode\": \"1\", \"icon\": null}\n ],\n \"selling\": [\n {\"code\": \"5005_w2a\", \"nameCn\": \"W2A\", \"nameEn\": \"W2A\", \"ccode\": \"w2a\", \"icon\": null}\n ],\n \"subjectType\": [\n {\"code\": \"gold_0_1\", \"nameCn\": \"金币\", \"nameEn\": \"Gold\", \"ccode\": \"1\", \"icon\": null}\n ],\n \"topicType\": [\n {\"code\": \"传奇_9_64\", \"nameCn\": \"传奇\", \"nameEn\": \"Legend\", \"ccode\": \"90064\", \"icon\": null}\n ],\n \"languages\": [\n {\"code\": \"南非荷兰语_af\", \"nameCn\": \"南非荷兰语\", \"nameEn\": \"Afrikaans\", \"ccode\": \"af\", \"icon\": null}\n ],\n \"materialTag\": [\n {\"code\": \"AI_0_1\", \"nameCn\": \"AI\", \"nameEn\": \"AI\", \"ccode\": \"001\", \"icon\": \"\"}\n ],\n \"tradeLevel2\": [\n {\"code\": \"60301\", \"nameCn\": \"电商\", \"nameEn\": \"E-commerce\", \"ccode\": \"60301\", \"icon\": null}\n ],\n \"materialFormat\": [\n {\"code\": \"5006_100\", \"nameCn\": \"单图\", \"nameEn\": \"Single Image\", \"ccode\": \"100\", \"icon\": null}\n ]\n}\n```\n\n### Filter Code Usage\n\n| Filter parameter | Use `ccode` from | Example |\n|---|---|---|\n| country_ids | countries | \"US\", \"JP\", \"MR\" |\n| media_ids | mediaChannels | \"101\" (Adcolony) |\n| device | device | \"1\" (Android) |\n| trade_level1/2/3 | tradeLevel / tradeLevel2 | \"601\" (Tools), \"60301\" (E-commerce) |\n| product_model | productModel | \"1\" (Non-game), \"2\" (Game) |\n| ad_media_type | adTypes | \"1076682150\" (Native Ads) |\n| languages | languages | \"af\" (Afrikaans) |\n| material_tag | materialTag | \"001\" (AI) |\n\n### Additional Response Field: tradeLevelTree\n\nThe response also includes `tradeLevelTree` — a hierarchical tree structure of all industry categories (level 1 → 2 → 3), useful for building category pickers or understanding the category hierarchy.\n\n---\n\n## 6. Content Detail — 素材详情\n\n`GET /api/data/content-detail`\n\nGet detailed information about a specific creative, or its related content (associated media, trends, profile, etc.).\n\n### Query Parameters\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| content_type | string | required | creative, imagevideo, preplay, demoad, document |\n| id | string | required | Content ID |\n| related | string | (none) | Related data type (see below). Omit for base info. |\n| material_type | string | \"\" | Only for `related=imagevideo`: \"1\"=image, \"2\"=video |\n| start_date | string | 365 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n\n### Related Types\n\n| related | Description |\n|---|---|\n| *(omitted)* | Base info — creative metadata and asset URLs |\n| `imagevideo` | Related image/video assets |\n| `document` | Related document assets |\n| `trend` | Impression/activity trend over time |\n| `profile` | Audience profile data |\n| `preplay` | Related playable ads |\n| `demoad` | Related landing pages |\n\n### Examples\n\n```\n# Get base info for a creative\nGET /api/data/content-detail?content_type=creative&id=abc123\n\n# Get related videos\nGET /api/data/content-detail?content_type=creative&id=abc123&related=imagevideo&material_type=2\n\n# Get trend data\nGET /api/data/content-detail?content_type=creative&id=abc123&related=trend&start_date=2026-01-01&end_date=2026-03-16\n```\n\n---\n\n## 7. Item Apps — 素材关联应用\n\n`POST /api/data/item-apps`\n\nBatch-fetch the associated apps for a list of creative IDs. Useful for enriching search results with app info.\n\n### Request Body\n\n```json\n{\n \"content_type\": \"creative\",\n \"ids\": [\"id1\", \"id2\", \"id3\"]\n}\n```\n\n| Parameter | Type | Description |\n|---|---|---|\n| content_type | string | Content type |\n| ids | string[] | Creative IDs (max 100) |\n\n### Response\n\nReturns a mapping of creative ID → app list:\n\n```json\n{\n \"id1\": [\n {\"id\": \"com.example.app\", \"name\": \"App Name\", \"logo\": \"https://...\"}\n ],\n \"id2\": [\n {\"id\": \"6498883328\", \"name\": \"Another App\", \"logo\": \"https://...\"}\n ]\n}\n```\n\n---\n\n## 8. Screen Types — 单类筛选项\n\n`GET /api/data/screen-types?element_type=1`\n\nFetch a single filter category by element type ID.\n\n| element_type | Category |\n|---|---|\n| 1004 | tradeLevel (industry) |\n| 2002 | countries |\n| 2004 | device |\n| 2005 | languages |\n| 2006 | mediaChannels |\n| 2008 | materialTag |\n| 3000 | subjectType |\n| 3006 | productType |\n| 5001 | adTypes |\n| 5005 | selling |\n| 5006 | materialFormat |\n\n---\n\n## 7. Page Config — 页面配置\n\n`GET /api/data/page-config?scope=search`\n\nReturns page layout configuration for the specified scope.\n\nFile v1.0.28:references/api-distribution.md\n\n# App Distribution API / 应用投放分布接口\n\nBase URL: `https://api.admapix.com`\nAuth: `X-API-Key: $ADMAPIX_API_KEY`\n\n> These endpoints require a `unified_product_id`. Get it from `unified-product-search` first.\n\n---\n\n## 1. App Distribution — 应用推广分布\n\n`POST /api/data/app-distribution`\n\nAnalyze an app's ad distribution across different dimensions.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"dim\": \"country\",\n \"start_time\": \"\",\n \"end_time\": \"\",\n \"countries\": [],\n \"media_ids\": [],\n \"material_type\": \"\",\n \"index_type\": 0\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| unified_product_id | string | required | Target app ID |\n| dim | string | required | Distribution dimension (see below) |\n| start_time | string | 30 days ago | YYYY-MM-DD |\n| end_time | string | today | YYYY-MM-DD |\n| countries | string[] | [] | Country filter |\n| media_ids | string[] | [] | Media channel filter |\n| material_type | string/int | \"\" | Material type filter |\n| index_type | int | 0 | Index type selector |\n\n### Dimensions\n\n| dim | Description | Returns |\n|---|---|---|\n| `trend` | 投放趋势 | Time series of ad volume over time |\n| `country` | 投放国家分布 | Per-country ad placement distribution |\n| `media` | 投放媒体位分布 | Distribution across publisher apps/placements where ads are displayed. **Note:** This returns the specific apps where ads appear (e.g. \"Block Blast\", \"Snake.io\", \"Solitaire\"), NOT ad network names like Facebook/Google. These are the traffic sources/publisher apps carrying the ads. Present them as \"投放媒体位\" or \"广告展示位\". |\n| `platform` | 平台分布 | iOS vs Android breakdown |\n| `type` | 素材类型分布 | Image vs video vs playable distribution |\n| `image` | 图片尺寸分布 | Image size/aspect ratio breakdown |\n| `video` | 视频时长分布 | Video duration breakdown |\n| `lang` | 语言分布 | Ad language distribution |\n\n### Response Examples\n\n**dim=country:**\n```json\n{\n \"list\": [\n {\"code\": \"US\", \"name\": \"United States\", \"cnt\": 500, \"ratio\": 0.35},\n {\"code\": \"JP\", \"name\": \"Japan\", \"cnt\": 300, \"ratio\": 0.21}\n ]\n}\n```\n\n**dim=trend:**\n```json\n{\n \"list\": [\n {\"date\": \"2026-03-01\", \"cnt\": 50},\n {\"date\": \"2026-03-02\", \"cnt\": 65}\n ]\n}\n```\n\n**dim=media (publisher apps / ad placements):**\n```json\n{\n \"list\": [\n {\"id\": \"101\", \"name\": \"Block Blast Adventure Master\", \"cnt\": 400, \"ratio\": 0.15},\n {\"id\": \"102\", \"name\": \"Snake.io\", \"cnt\": 250, \"ratio\": 0.09},\n {\"id\": \"103\", \"name\": \"Solitaire\", \"cnt\": 180, \"ratio\": 0.07}\n ]\n}\n```\nThese are the apps where the target app's ads are being shown (publisher side). When presenting this data, you can categorize them (e.g. casual games, tools, content apps) to provide more actionable insights.\n\n---\n\n## 2. Distribute Dims — 素材分布维度\n\n`GET /api/data/distribute-dims`\n\nReturns which distribute dimensions are available per content type. This is for the creative-level distribute endpoint (`/api/data/distribute`), not for app-distribution.\n\n### Response\n\n```json\n{\n \"creative\": [\"media\", \"advertiser\", \"app\"],\n \"imagevideo\": [\"media\", \"advertiser\", \"app\", \"country\"],\n \"preplay\": [\"media\", \"advertiser\", \"app\"],\n \"demoad\": [\"media\", \"advertiser\", \"app\"],\n \"document\": [\"media\", \"advertiser\", \"app\"]\n}\n```\n\n---\n\n## 3. Global Promote — 全局推广分布\n\n`POST /api/data/global-promote`\n\nAnalyze the global promotion distribution for one or more products across countries, media, or advertisers.\n\n### Request Body\n\n```json\n{\n \"ids\": [\"product_id_1\", \"product_id_2\"],\n \"dim\": \"country\",\n \"keyword\": \"\",\n \"sort_field\": \"15\",\n \"sort_rule\": \"desc\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| ids | string[] | required | Product IDs (non-empty array) |\n| dim | string | \"country\" | Dimension: `country`, `media`, or `adfaction` |\n| keyword | string | \"\" | Optional keyword filter |\n| sort_field | string | \"15\" | Sort field (\"15\"=impressions) |\n| sort_rule | string | \"desc\" | Sort direction |\n\n### Response\n\nReturns distribution data for the specified dimension. Structure varies by `dim`.\n\n### Difference from app-distribution\n\n- **app-distribution** — Analyzes a single app's ad placement distribution (where/how it advertises)\n- **global-promote** — Analyzes one or more products' promotion footprint across the global market (country/media/advertiser breakdown)\n\n---\n\n## Common Workflows / 常用工作流\n\n### \"Temu 主要在哪些国家投广告？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"country\")\n```\n\n### \"Temu 用了哪些广告渠道？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"media\")\n```\n\n### \"Temu 的投放趋势怎么样？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"trend\", start_time=\"2026-01-01\", end_time=\"2026-03-16\")\n```\n\n### \"Temu 在美国投了多少视频广告 vs 图片广告？\"\n\n```\napp-distribution(unified_product_id=id, dim=\"type\", countries=[\"US\"])\n```\n\n### Full app advertising profile (multi-call)\n\n1. `dim=\"country\"` → where they advertise (target countries)\n2. `dim=\"media\"` → which publisher apps carry their ads (ad placements)\n3. `dim=\"type\"` → what creative formats they use\n4. `dim=\"trend\"` → how ad volume changes over time\n5. `dim=\"lang\"` → which languages they target\n\nCombine all 5 for a comprehensive advertising strategy overview.\n\nFile v1.0.28:references/api-download-revenue.md\n\n# Download & Revenue API / 下载量与收入接口\n\nBase URL: `https://api.admapix.com`\nAuth: `X-API-Key: $ADMAPIX_API_KEY`\n\n> These endpoints require a `unified_product_id`. Get it from `unified-product-search` first.\n\n---\n\n## 1. Download Date Range — 下载量可用日期\n\n`GET /api/data/download-date`\n\nReturns the available date range for download data queries.\n\n### Response\n\n```json\n{\n \"startDate\": \"2023-01-01\",\n \"endDate\": \"2026-03-15\"\n}\n```\n\n**Use this to validate date params before calling download-detail/download-country.**\n\n---\n\n## 2. Download Detail — 下载量趋势\n\n`POST /api/data/download-detail`\n\nFetch download trend data for a specific app over time.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"query_start_date\": \"2026-02-14\",\n \"query_end_date\": \"2026-03-16\",\n \"compare_start_date\": \"\",\n \"compare_end_date\": \"\",\n \"country_st\": [],\n \"day_type\": 1,\n \"flag\": true,\n \"is_all\": false\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| unified_product_id | string | required | Target app ID |\n| query_start_date | string | required | YYYY-MM-DD |\n| query_end_date | string | required | YYYY-MM-DD |\n| compare_start_date | string | \"\" | Compare period start (optional) |\n| compare_end_date | string | \"\" | Compare period end (optional) |\n| country_st | string[] | [] | Country filter (empty = global) |\n| day_type | int | 1 | Granularity: 1=daily, 2=weekly, 3=monthly |\n| flag | bool | true | Include trend data |\n| is_all | bool | false | All countries aggregated |\n\n### Response\n\nReturns time series data:\n```json\n{\n \"list\": [\n {\"date\": \"2026-03-01\", \"download\": 150000, \"compareDownload\": 120000},\n {\"date\": \"2026-03-02\", \"download\": 160000, \"compareDownload\": 125000}\n ]\n}\n```\n\n---\n\n## 3. Download Country — 按国家下载量\n\n`POST /api/data/download-country`\n\nFetch download data broken down by country.\n\n### Request Body\n\nSame as download-detail.\n\n### Response\n\nReturns per-country breakdown:\n```json\n{\n \"list\": [\n {\"country\": \"US\", \"countryName\": \"United States\", \"download\": 500000},\n {\"country\": \"JP\", \"countryName\": \"Japan\", \"download\": 300000}\n ]\n}\n```\n\n---\n\n## 4. Revenue Date Range — 收入可用日期\n\n`GET /api/data/revenue-date`\n\nReturns the available date range for revenue data queries.\n\n### Response\n\n```json\n{\n \"startDate\": \"2023-01-01\",\n \"endDate\": \"2026-03-15\"\n}\n```\n\n---\n\n## 5. Revenue Detail — 收入趋势\n\n`POST /api/data/revenue-detail`\n\nFetch revenue trend data for a specific app.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"query_start_date\": \"2026-02-14\",\n \"query_end_date\": \"2026-03-16\",\n \"compare_start_date\": \"\",\n \"compare_end_date\": \"\",\n \"country_st\": [],\n \"day_type\": 1,\n \"flag\": true,\n \"is_all\": false,\n \"revenue_type\": \"ALL\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| (same as download-detail, plus:) | | | |\n| revenue_type | string | \"ALL\" | Revenue type filter |\n\n---\n\n## 6. Revenue Country — 按国家收入\n\n`POST /api/data/revenue-country`\n\nFetch revenue data broken down by country.\n\n### Request Body\n\nSame as revenue-detail.\n\n---\n\n## Common Workflows / 常用工作流\n\n### \"Temu 最近下载量怎么样？\"\n\n1. `unified-product-search(keyword=\"temu\")` → get `unifiedProductId`\n2. `download-date` → confirm available range\n3. `download-detail(unified_product_id=id, query_start_date=\"2026-02-14\", query_end_date=\"2026-03-16\")` → trend\n4. Present trend data with insights\n\n### \"对比 Temu 在美国和日本的收入\"\n\n1. Get `unifiedProductId` (step 1 above)\n2. `revenue-country(unified_product_id=id, ...)` → per-country revenue\n3. Filter & compare US vs JP data\n\n### \"Temu vs SHEIN 下载量对比\"\n\n1. Search both apps → get both `unifiedProductId`\n2. `download-detail` for each → two trend datasets\n3. Present side-by-side comparison\n\n### Day Type Reference\n\n| day_type | Granularity | Best for |\n|---|---|---|\n| 1 | Daily | Short ranges (≤90 days) |\n| 2 | Weekly | Medium ranges (1-6 months) |\n| 3 | Monthly | Long ranges (6+ months) |\n\nFile v1.0.28:references/api-market.md\n\n# Market Analysis API / 市场分析接口\n\nBase URL: `https://api.admapix.com`\nAuth: `X-API-Key: $ADMAPIX_API_KEY`\n\n---\n\n## Market Search — 市场分析搜索\n\n`POST /api/data/market-search`\n\nAnalyze the advertising market from 5 different dimensions. Provides macro-level market intelligence.\n\n### Request Body\n\n```json\n{\n \"class_type\": 1,\n \"data_type\": \"1\",\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"trade_level3\": [],\n \"country_level2\": [],\n \"media_ids\": [],\n \"device\": [],\n \"ad_company_location\": [],\n \"traffic_company_location\": [],\n \"page\": 1,\n \"page_size\": 20\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| class_type | int | required | Analysis dimension (1-5, see below) |\n| data_type | string | \"1\" | \"1\"=game, \"2\"=app |\n| start_date | string | today | YYYY/MM/DD (note: slash format) |\n| end_date | string | today | YYYY/MM/DD (note: slash format) |\n| trade_level3 | string[] | [] | Sub-industry filter |\n| country_level2 | string[] | [] | Country filter |\n| media_ids | string[] | [] | Media channel filter |\n| device | string[] | [] | Device filter |\n| ad_company_location | string[] | [] | Advertiser company location filter |\n| traffic_company_location | string[] | [] | Publisher/traffic source location filter |\n| page | int | 1 | Page number |\n| page_size | int | 20 | Results per page (1-100) |\n\n### Dimensions (class_type)\n\n| class_type | Dimension | Description | Best for |\n|---|---|---|---|\n| 1 | 国家 Country | Market size by country | \"Which countries have the most game ads?\" |\n| 2 | 媒体 Media | Market share by ad network | \"Which ad platforms are most used?\" |\n| 3 | 子媒体 Sub-Media | Breakdown within media channels | \"What Facebook ad placements are popular?\" |\n| 4 | 广告主 Advertiser | Top advertisers in the market | \"Who are the biggest game advertisers?\" |\n| 5 | 流量主 Publisher | Top publishers / traffic sources | \"Which publishers carry the most ads?\" |\n\n### Data Type\n\n| data_type | Description |\n|---|---|\n| \"1\" | 游戏 Game — game industry data |\n| \"2\" | 应用 App — non-game app data |\n\n**Note:** Date format for this endpoint uses slashes (`YYYY/MM/DD`), not dashes.\n\n### Response\n\n**IMPORTANT:** This endpoint returns a different structure from other endpoints. The response uses `data_list` (not `list`) and nested dot-notation field names.\n\n**Pagination fields:** `page_total` (total pages), `page_num` (current page), `page_size`.\n\n#### class_type=1 (Country) response:\n```json\n{\n \"data_list\": [\n {\n \"market_query.list.id\": \"ID\",\n \"query.country_info.s_code\": \"ID\",\n \"query.country_info.c_code\": \"ID\",\n \"query.country_info.country_name\": \"印度尼西亚\",\n \"market_query.list.raw_impression\": 11578945855,\n \"market_query.list.impression\": \"116亿\",\n \"market_query.list.impressionRatio\": \"13.64%\",\n \"market_query.list.rank\": 1,\n \"query.country_info.image\": \"https://...flag.png\"\n }\n ],\n \"page_total\": 34,\n \"page_num\": 1,\n \"page_size\": 3\n}\n```\n\nKey fields to extract:\n- `query.country_info.country_name` — country name (Chinese)\n- `query.country_info.c_code` — country code\n- `market_query.list.impression` — impression count (pre-formatted string like \"116亿\")\n- `market_query.list.raw_impression` — raw numeric impression count\n- `market_query.list.impressionRatio` — percentage share\n- `market_query.list.rank` — rank position\n\n#### class_type=4 (Advertiser) response:\n```json\n{\n \"data_list\": [\n {\n \"market_query.list.market_query.list.advertiser\": \"275091615\",\n \"market_query.list.query.company_info.unified_company_name\": \"VGam.es\",\n \"market_query.list.query.company_info.unified_company_id\": \"275091615\",\n \"query.pkg_info.productName\": \"Math Crossword – Endless Fun\",\n \"query.pkg_info.productLogo\": \"https://...logo.png\",\n \"query.pkg_info.unifiedPkgId\": \"com.vgames.mathcrossword\",\n \"market_query.list.market_query.list.company_impression\": \"64亿\",\n \"market_query.list.market_query.list.raw_company_impression\": 6449946845,\n \"market_query.list.market_query.list.company_impressionRatio\": \"10.31%\",\n \"market_query.list.market_query.list.top1_app_impression\": \"64亿\",\n \"market_query.list.market_query.list.rank\": 1\n }\n ],\n \"page_total\": 500,\n \"page_num\": 1,\n \"page_size\": 2\n}\n```\n\nKey fields to extract:\n- `market_query.list.query.company_info.unified_company_name` — company name\n- `query.pkg_info.productName` — top product name\n- `market_query.list.market_query.list.company_impression` — total impression (formatted)\n- `market_query.list.market_query.list.company_impressionRatio` — market share %\n- `market_query.list.market_query.list.rank` — rank position\n\n---\n\n## Common Workflows / 常用工作流\n\n### \"全球游戏广告市场哪个国家最大？\"\n\n```json\n{\"class_type\": 1, \"data_type\": \"1\"}\n```\n\n### \"美国市场最大的游戏广告主是谁？\"\n\n```json\n{\"class_type\": 4, \"data_type\": \"1\", \"country_level2\": [\"US\"]}\n```\n\n### \"电商App广告市场对比：东南亚 vs 北美\"\n\nTwo queries:\n1. `{\"class_type\": 1, \"data_type\": \"2\", \"country_level2\": [\"TH\",\"VN\",\"ID\",\"MY\",\"PH\",\"SG\"]}`\n2. `{\"class_type\": 1, \"data_type\": \"2\", \"country_level2\": [\"US\",\"CA\"]}`\n\nCompare total counts, top advertisers, media distribution.\n\n### Market overview combo (multi-call)\n\nFor a comprehensive market report on a segment:\n1. `class_type=1` → geographic distribution\n2. `class_type=2` → media channel breakdown\n3. `class_type=4` → top advertisers\n4. `class_type=5` → top publishers\n\nCombine for a full market intelligence report.\n\n---\n\n## Filter Codes\n\nUse `GET /api/data/filter-options` to get valid codes for:\n- `trade_level3` — industry/sub-category codes\n- `country_level2` — country codes (use the `ccode` field, e.g. \"US\", \"JP\")\n- `media_ids` — media channel IDs (use the `ccode` field, e.g. \"101\" for Adcolony)\n- `device` — device type codes (use the `ccode` field, e.g. \"1\" for Android)\n\nSee `references/param-mappings.md` for common country/region mappings.\n\nFile v1.0.28:references/api-product.md\n\n# Product & Company API / 产品与公司接口\n\nBase URL: `https://api.admapix.com`\nAuth: `X-API-Key: $ADMAPIX_API_KEY`\n\n---\n\n## 1. Unified Product Search — 统一产品搜索\n\n`POST /api/data/unified-product-search`\n\nSearch for unified products (cross-platform aggregated apps). This is the primary entry point for finding apps/products.\n\n### Request Body\n\n```json\n{\n \"keyword\": \"temu\",\n \"type\": 1,\n \"page\": 1,\n \"page_size\": 20,\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"sort_field\": \"3\",\n \"sort_rule\": \"desc\",\n \"unified_product_id\": \"\",\n \"unified_developer_id\": \"\"\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| keyword | string | \"\" | Search keyword |\n| type | int | 1 | Search type |\n| page | int | 1 | Page number |\n| page_size | int | 20 | Results per page (1-100) |\n| start_date | string | 30 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n| sort_field | string | \"3\" | Sort field |\n| sort_rule | string | \"desc\" | Sort direction |\n| unified_product_id | string | \"\" | Filter by specific unified product |\n| unified_developer_id | string | \"\" | Filter by specific developer |\n| country_ids | string[] | [] | Country filter (mapped to countryLevel2) |\n| media_ids | string[] | [] | Media channel filter |\n| device | string[] | [] | Device filter |\n\n**Note:** `country_ids`, `media_ids`, and `device` also apply to `product-search` and `company-search`.\n\n### Response\n\n```json\n{\n \"pageIndex\": 1,\n \"pageSize\": 20,\n \"totalSize\": 96,\n \"list\": [\n {\n \"unifiedProductId\": \"1641486558\",\n \"unifiedProductName\": \"Temu: Shop Like a Billionaire\",\n \"unifiedCompanyId\": \"569338280\",\n \"unifiedCompanyName\": \"Temu\",\n \"productIds\": [\"com.einnovation.temu\", \"1641486558\", \"com.Temu_Team_Up.used_letgo_buy_app1\"],\n \"tradeLevel1\": [\"603\"],\n \"tradeLevel2\": [\"60301\", \"60303\"],\n \"tradeLevel3\": [\"6030102\", \"6030301\"],\n \"tradeLevel4\": [],\n \"showCost\": 23236263827,\n \"impression\": 2412399002696,\n \"materialUvCnt\": 7451078,\n \"productCnt\": 3,\n \"iconUrl\": \"https://...logo.png\",\n \"collectId\": null,\n \"formerNames\": null,\n \"adSource\": 9\n }\n ],\n \"folderTotalSize\": null,\n \"newNum\": 0,\n \"latestDate\": null,\n \"gptCorrect\": null,\n \"filters\": null\n}\n```\n\n### ⚠️ Important Notes\n\n1. **HTML tags in names:** `unifiedProductName` may contain HTML highlight tags `keyword`. Strip these before displaying.\n2. The `unifiedProductId` returned here is the key input for detail/distribution/download/revenue endpoints.\n3. `productIds` contains platform-specific IDs (Android package name, iOS app ID).\n\n### Key Fields\n\n| Field | Description |\n|---|---|\n| unifiedProductId | Unique cross-platform product ID — **use this for all detail/distribution queries** |\n| unifiedProductName | App name (may contain HTML `` tags for keyword highlighting) |\n| unifiedCompanyId | Developer/company ID |\n| unifiedCompanyName | Developer/company name |\n| productIds | Array of platform-specific product IDs |\n| iconUrl | App icon URL |\n| showCost | Total ad spend estimate (raw number) |\n| impression | Total impression count (raw number) |\n| materialUvCnt | Total unique creative count |\n|\n\nArchive v1.0.27: 11 files, 36122 bytes\n\nFiles: README_CN.md (3930b), README.md (4099b), references/api-creative.md (14455b), references/api-distribution.md (5365b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (15238b), references/api-ranking.md (7778b), references/param-mappings.md (4713b), SKILL.md (22550b), _meta.json (127b)\n\nArchive v1.0.26: 11 files, 36121 bytes\n\nFiles: README_CN.md (3930b), README.md (4099b), references/api-creative.md (14455b), references/api-distribution.md (5365b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (15238b), references/api-ranking.md (7778b), references/param-mappings.md (4713b), SKILL.md (22550b), _meta.json (127b)\n\nArchive v1.0.25: 11 files, 35828 bytes\n\nFiles: README_CN.md (3930b), README.md (4099b), references/api-creative.md (14455b), references/api-distribution.md (5365b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (15238b), references/api-ranking.md (7778b), references/param-mappings.md (4713b), SKILL.md (21804b), _meta.json (127b)\n\nArchive v1.0.24: 11 files, 35906 bytes\n\nFiles: README_CN.md (3930b), README.md (4099b), references/api-creative.md (14455b), references/api-distribution.md (5365b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (15238b), references/api-ranking.md (7778b), references/param-mappings.md (4713b), SKILL.md (21977b), _meta.json (127b)\n\nArchive v1.0.23: 11 files, 30743 bytes\n\nFiles: README_CN.md (2241b), README.md (2253b), references/api-creative.md (11746b), references/api-distribution.md (4265b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (11873b), references/api-ranking.md (7007b), references/param-mappings.md (4713b), SKILL.md (18543b), _meta.json (127b)\n\nArchive v1.0.22: 11 files, 28013 bytes\n\nFiles: README_CN.md (2241b), README.md (2253b), references/api-creative.md (11746b), references/api-distribution.md (4265b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (11873b), references/api-ranking.md (7007b), references/param-mappings.md (4713b), SKILL.md (12320b), _meta.json (127b)\n\nArchive v1.0.21: 11 files, 30761 bytes\n\nFiles: README_CN.md (2241b), README.md (2253b), references/api-creative.md (11746b), references/api-distribution.md (4265b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (11873b), references/api-ranking.md (7007b), references/param-mappings.md (4713b), SKILL.md (18519b), _meta.json (127b)\n\nArchive v1.0.20: 11 files, 30761 bytes\n\nFiles: README_CN.md (2241b), README.md (2253b), references/api-creative.md (11746b), references/api-distribution.md (4265b), references/api-download-revenue.md (4059b), references/api-market.md (6038b), references/api-product.md (11873b), references/api-ranking.md (7007b), references/param-mappings.md (4713b), SKILL.md (18519b), _meta.json (127b)","readmeExcerpt":"Skill: AdMapix Owner: fly0pants Summary: Ad intelligence and app analytics assistant for searching ad creatives, analyzing apps, rankings, downloads, revenue, and market insights. Use for 广告素材, 竞品分析... Tags: ad-intelligence:1.0.29, app-analytics:1.0.29, latest:1.0.29 Version history: v1.0.29 | 2026-05-11T04:23:38.170Z | user Security metadata cleanup: declared required env vars and network access, removed hardcoded b","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"curl -s \"https://api.admapix.com/api/data/{endpoint}?{params}\" \\\n -H \"$admapix_auth_header\""},{"language":"bash","snippet":"curl -s -X POST \"https://api.admapix.com/api/data/{endpoint}\" \\\n -H \"$admapix_auth_header\" \\\n -H \"Content-Type: application/json\" \\\n -d '{...}'"},{"language":"bash","snippet":"# Read the key from the environment and keep it out of command output.\nadmapix_auth_header=\"X-API-Key: ${ADMAPIX_API_KEY}\"\n\n# GET example\ncurl -s \"https://api.admapix.com/api/data/{endpoint}?{params}\" \\\n -H \"$admapix_auth_header\"\n\n# POST example\ncurl -s -X POST \"https://api.admapix.com/api/data/{endpoint}\" \\\n -H \"$admapix_auth_header\" \\\n -H \"Content-Type: application/json\" \\\n -d '{...}'"},{"language":"bash","snippet":"[ -n \"${ADMAPIX_API_KEY:-}\" ] && echo \"ok\" || echo \"missing\""},{"language":"bash","snippet":"curl -s -o /dev/null -w \"%{http_code}\" \"https://api.admapix.com/api/data/quota\" \\\n -H \"$admapix_auth_header\""},{"language":"bash","snippet":"admapix_auth_header=\"X-API-Key: ${ADMAPIX_API_KEY}\"\ncurl -s -o /dev/null -w \"%{http_code}\" \"https://api.admapix.com/api/data/quota\" \\\n -H \"$admapix_auth_header\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: admapix\ndescription: \"Ad intelligence and app analytics assistant for searching ad creatives, analyzing apps, rankings, downloads, revenue, and market insights. Use for 广告素材, 竞品分析, 排行榜, 下载量, 收入分析, 市场分析, App分析, 出海分析, ad spy, app intelligence, competitor analysis, and ad distribution.\"\nlicense: MIT-0\nmetadata:\n author: fly0pants\n version: \"1.0.29\"\n openclaw:\n emoji: \"🎯\"\n primaryEnv: ADMAPIX_API_KEY\n requires:\n env:\n - ADMAPIX_API_KEY\n bins:\n - curl\n env:\n - name: ADMAPIX_API_KEY\n description: \"API key for AdMapix data APIs. Get one at https://www.admapix.com\"\n required: true\n sensitive: true\n - name: ADMAPIX_DEEP_RESEARCH_TOKEN\n description: \"Optional bearer token for the AdMapix Deep Research service, if enabled for the account.\"\n required: false\n sensitive: true\n network:\n - https://api.admapix.com\n - https://deepresearch.admapix.com\n hermes:\n tags: [ads, app-analytics, market-intelligence, competitor-analysis, ad-creatives]\n category: productivity\n---\n\n# AdMapix Intelligence Assistant\n\n**Get started:** Sign up and get your API key at https://www.admapix.com\n\nYou are an ad intelligence and app analytics assistant. Help users search ad creatives, analyze apps, explore rankings, track downloads/revenue, and understand market trends — all via the AdMapix API.\n\n**Data disclaimer:** Download/revenue figures are third-party estimates, not official data. Always note this when presenting such data.\n\n## Language Handling / 语言适配\n\nDetect the user's language from their **first message** and maintain it throughout the conversation.\n\n| User language | Response language | Number format | H5 keyword | Example output |\n|---|---|---|---|---|\n| 中文 | 中文 | 万/亿 (e.g. 1.2亿) | Use Chinese keyword if possible | \"共找到 1,234 条素材\" |\n| English | English | K/M/B (e.g. 120M) | Use English keyword | \"Found 1,234 creatives\" |\n\n**Rules:**\n1. **All text output** (summaries, analysis, table headers, insights, follow-up hints) must match the detected language.\n2. **H5 page generation:** When using `generate_page: true`, pass the keyword in the user's language so the generated page displays in the matching language context.\n3. **Field name presentation:**\n - Chinese → use Chinese labels: 应用名称, 开发者, 曝光量, 投放天数, 素材类型\n - English → use English labels: App Name, Developer, Impressions, Active Days, Creative Type\n4. **Error messages** must also match: \"未找到数据\" vs \"No data found\".\n5. **Data disclaimers:** \"⚠️ 下载量和收入为第三方估算数据\" vs \"⚠️ Download and revenue figures are third-party estimates.\"\n6. If the user **switches language mid-conversation**, follow the new language from that point on.\n\n## API Access\n\nBase URL: `https://api.admapix.com`\n\nUse the configured `ADMAPIX_API_KEY` value as the `X-API-Key` request header for AdMapix API calls. Keep credentials in the environment or the host agent's secret store; guide users away from pasting API keys into chat and keep key value"},{"path":"README.md","content":"# AdMapix — Ad Intelligence & App Analytics Skill\n\n[中文文档](README_CN.md)\n\nAll-in-one ad intelligence assistant. Search ad creatives, analyze apps, explore rankings, track downloads/revenue, and get market insights — all through natural language.\n\n## Features\n\n- **Creative Search** — Search ad creatives by keyword, region, media, creative type, with H5 visual results\n- **App Analysis** — Look up any app's details, developer info, and ad creative portfolio\n- **Rankings** — App Store / Google Play charts, promotion rankings, download rankings, revenue rankings\n- **Download & Revenue** — Track download and revenue trends over time (third-party estimates)\n- **Ad Distribution** — Analyze where and how an app advertises (countries, media placements, creative formats)\n- **Market Analysis** — Industry-level insights by country, media channel, advertiser, and publisher\n- **Deep Dive** — Multi-dimensional reports combining all of the above\n- **Deep Research** — AI-powered deep analysis for complex queries (multi-app comparisons, market strategy reports, trend analysis). Automatically triggered for questions requiring 2+ API calls, returns structured HTML reports with key findings\n\n## Install\n\n```bash\nnpx clawhub install admapix\n```\n\n## Setup\n\n1. Go to [www.admapix.com](https://www.admapix.com) to register and get your API Key\n2. Configure it using one of these methods:\n\nOpenClaw / ClawHub:\n\n```bash\nopenclaw config set skills.entries.admapix.apiKey \"\"\n```\n\nGeneric shell environment:\n\n```bash\nexport ADMAPIX_API_KEY=\"\"\n```\n\n## Usage Examples\n\nAfter setup, just tell your AI assistant:\n\n| Category | Example prompts |\n|----------|----------------|\n| Creative Search | \"Search video ads for puzzle games\", \"Find casual game creatives in Southeast Asia\" |\n| App Analysis | \"Tell me about Temu\", \"Who is the developer of TikTok?\" |\n| Rankings | \"App Store free chart US\", \"Top apps by ad spend this week\" |\n| Downloads | \"How are Temu's downloads trending?\", \"Compare Temu vs SHEIN downloads\" |\n| Ad Distribution | \"Which countries does Temu advertise in?\", \"What ad channels does this game use?\" |\n| Market Analysis | \"Which country has the most game ads?\", \"Who are the top game advertisers?\" |\n| Deep Dive | \"Full ad strategy analysis for Temu\", \"Compare Temu and SHEIN\" |\n| Deep Research | \"Analyze Temu's ad strategy in Southeast Asia\", \"Compare top 5 casual games' ad performance\" |\n\nSupports both **English** and **Chinese** — the assistant responds in your language.\n\n## Deep Research — AI-Powered Intelligence Reports\n\nFor complex analytical queries, AdMapix automatically activates its **Deep Research Framework** — a server-side AI research engine that goes far beyond simple API lookups.\n\n**How it works:**\n\n1. The skill classifies your query by complexity. Simple lookups (single search, single ranking) are handled directly. Anything requiring cross-dimensional analysis is routed to Deep Research.\n2. The research engine autonomously plans and executes a mul"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7c1c01gzrc3m423t8n840m9s81vj6m\",\n \"slug\": \"admapix\",\n \"version\": \"1.0.29\",\n \"publishedAt\": 1778473418170\n}"},{"path":"references/api-creative.md","content":"# Creative Search API / 素材搜索接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n---\n\n## 1. Search — 素材搜索\n\n`POST /api/data/search`\n\nSearch ad creatives across 5 content types. Supports H5 page generation.\n\n### Content Types\n\n| content_type | Label | Description |\n|---|---|---|\n| `creative` | 创意组合 | Multi-asset ad bundles (image+video+playable combos) |\n| `imagevideo` | 图片/视频 | Individual image or video assets |\n| `preplay` | 试玩广告 | Playable/interactive ads |\n| `demoad` | 落地页 | Landing pages |\n| `document` | 文档素材 | Document-format ads |\n\n### Request Body\n\n```json\n{\n \"content_type\": \"creative\",\n \"keyword\": \"puzzle game\",\n \"keyword_type\": \"\",\n \"is_new\": false,\n \"start_date\": \"2026-02-14\",\n \"end_date\": \"2026-03-16\",\n \"page\": 1,\n \"page_size\": 20,\n \"sort_field\": \"3\",\n \"sort_rule\": \"desc\",\n \"country_ids\": [],\n \"media_ids\": [],\n \"adfaction_ids\": [],\n \"device\": [],\n \"topic_type\": [],\n \"languages\": [],\n \"material_type\": \"\",\n \"trade_level1\": [],\n \"trade_level2\": [],\n \"trade_level3\": [],\n \"subject_type\": [],\n \"product_model\": [],\n \"product_type\": [],\n \"selling\": [],\n \"monetization\": [],\n \"pay_type\": [],\n \"company_location\": [],\n \"campaign_list\": [],\n \"ad_media_type\": [],\n \"appeal_type_list\": [],\n \"interaction_list\": [],\n \"material_tag\": [],\n \"material_removal_repeat\": false,\n \"demoad_formats\": [],\n \"web_tools\": [],\n \"material_top_limit\": \"\",\n \"gpt_search\": null,\n \"generate_page\": false,\n \"delivery\": null\n}\n```\n\n### Key Parameters\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| content_type | string | required | One of: creative, imagevideo, preplay, demoad, document |\n| keyword | string | \"\" | Search keyword (app name, ad copy, brand, etc.) |\n| keyword_type | string | \"\" | Keyword match scope (leave empty for default per content_type) |\n| start_date | string | 30 days ago | YYYY-MM-DD |\n| end_date | string | today | YYYY-MM-DD |\n| page | int | 1 | Page number (≥1) |\n| page_size | int | 60 | Results per page (1-100) |\n| sort_field | string | \"3\" | \"3\"=first seen, \"4\"=days active, \"11\"=relevance, \"15\"=impressions |\n| sort_rule | string | \"desc\" | \"desc\" or \"asc\" |\n| country_ids | string[] | [] | Country codes, e.g. [\"US\",\"JP\"] — use `ccode` from filter-options |\n| media_ids | string[] | [] | Media channel IDs — use `ccode` from filter-options |\n| device | string[] | [] | Device filter — use `ccode` from filter-options |\n| trade_level1/2/3 | string[] | [] | Industry category filters (hierarchical) |\n| product_model | string[] | [] | Product model filter — use `ccode` from filter-options `productModel` (e.g. \"1\"=non-game, \"2\"=game) |\n| material_type | string | \"\" | Material format filter (\"1\"=image, \"2\"=video). **Only effective for `imagevideo` content type** — ignored by other content types |\n| ad_media_type | string[] | [] | Ad media type codes |\n| material_removal_repeat | bool | false | Deduplicate similar creatives |\n| gpt_search | bo"},{"path":"references/api-distribution.md","content":"# App Distribution API / 应用投放分布接口\n\nBase URL: `https://api.admapix.com`\nAuth: include the configured AdMapix API key in the `X-API-Key` request header.\n\n> These endpoints require a `unified_product_id`. Get it from `unified-product-search` first.\n\n---\n\n## 1. App Distribution — 应用推广分布\n\n`POST /api/data/app-distribution`\n\nAnalyze an app's ad distribution across different dimensions.\n\n### Request Body\n\n```json\n{\n \"unified_product_id\": \"xxx\",\n \"dim\": \"country\",\n \"start_time\": \"\",\n \"end_time\": \"\",\n \"countries\": [],\n \"media_ids\": [],\n \"material_type\": \"\",\n \"index_type\": 0\n}\n```\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| unified_product_id | string | required | Target app ID |\n| dim | string | required | Distribution dimension (see below) |\n| start_time | string | 30 days ago | YYYY-MM-DD |\n| end_time | string | today | YYYY-MM-DD |\n| countries | string[] | [] | Country filter |\n| media_ids | string[] | [] | Media channel filter |\n| material_type | string/int | \"\" | Material type filter |\n| index_type | int | 0 | Index type selector |\n\n### Dimensions\n\n| dim | Description | Returns |\n|---|---|---|\n| `trend` | 投放趋势 | Time series of ad volume over time |\n| `country` | 投放国家分布 | Per-country ad placement distribution |\n| `media` | 投放媒体位分布 | Distribution across publisher apps/placements where ads are displayed. **Note:** This returns the specific apps where ads appear (e.g. \"Block Blast\", \"Snake.io\", \"Solitaire\"), NOT ad network names like Facebook/Google. These are the traffic sources/publisher apps carrying the ads. Present them as \"投放媒体位\" or \"广告展示位\". |\n| `platform` | 平台分布 | iOS vs Android breakdown |\n| `type` | 素材类型分布 | Image vs video vs playable distribution |\n| `image` | 图片尺寸分布 | Image size/aspect ratio breakdown |\n| `video` | 视频时长分布 | Video duration breakdown |\n| `lang` | 语言分布 | Ad language distribution |\n\n### Response Examples\n\n**dim=country:**\n```json\n{\n \"list\": [\n {\"code\": \"US\", \"name\": \"United States\", \"cnt\": 500, \"ratio\": 0.35},\n {\"code\": \"JP\", \"name\": \"Japan\", \"cnt\": 300, \"ratio\": 0.21}\n ]\n}\n```\n\n**dim=trend:**\n```json\n{\n \"list\": [\n {\"date\": \"2026-03-01\", \"cnt\": 50},\n {\"date\": \"2026-03-02\", \"cnt\": 65}\n ]\n}\n```\n\n**dim=media (publisher apps / ad placements):**\n```json\n{\n \"list\": [\n {\"id\": \"101\", \"name\": \"Block Blast Adventure Master\", \"cnt\": 400, \"ratio\": 0.15},\n {\"id\": \"102\", \"name\": \"Snake.io\", \"cnt\": 250, \"ratio\": 0.09},\n {\"id\": \"103\", \"name\": \"Solitaire\", \"cnt\": 180, \"ratio\": 0.07}\n ]\n}\n```\nThese are the apps where the target app's ads are being shown (publisher side). When presenting this data, you can categorize them (e.g. casual games, tools, content apps) to provide more actionable insights.\n\n---\n\n## 2. Distribute Dims — 素材分布维度\n\n`GET /api/data/distribute-dims`\n\nReturns which distribute dimensions are available per content type. This is for the creative-level distribute endpoint (`/api/data/distribute`), not for app-distribution.\n\n### Response\n\n```json\n{\n \"creative\": [\"media\", \"advertise"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2018,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-05-22T06:54:31.856Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-05-22T06:54:31.856Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T01:01:36.633Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}