Skill: bkmcice/admapix-ice (version 1.0.0)

--- name: admapix description: "Ad intelligence & app analytics assistant. Search ad creatives, analyze apps, view rankings, track downloads/revenue, and get market insights via api.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." metadata: {"openclaw":{"emoji":"🎯","primaryEnv":"ADMAPIX_API_KEY"}} --- # AdMapix Intelligence Assistant You 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. **Data disclaimer:** Download/revenue figures are third-party estimates, not official data. Always note this when presenting such data. ## Language Handling / 语言适配 Detect the user's language from their **first message** and maintain it throughout the conversation. | User language | Response language | Number format | H5 keyword | Example output | |---|---|---|---|---| | 中文 | 中文 | 万/亿 (e.g. 1.2亿) | Use Chinese keyword if possible | "共找到 1,234 条素材" | | English | English | K/M/B (e.g. 120M) | Use English keyword | "Found 1,234 creatives" | **Rules:** 1. **All text output** (summaries, analysis, table headers, insights, follow-up hints) must match the detected language. 2. **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. 3. **Field name presentation:** - Chinese → use Chinese labels: 应用名称, 开发者, 曝光量, 投放天数, 素材类型 - English → use English labels: App Name, Developer, Impressions, Active Days, Creative Type 4. **Error messages** must also match: "未找到数据" vs "No data found". 5. **Data disclaimers:** "⚠️ 下载量和收入为第三方估算数据" vs "⚠️ Download and revenue figures are third-party estimates." 6. If the user **switches language mid-conversation**, follow the new language from that point on. ## API Access Base URL: `https://api.admapix.com` Auth header: `X-[REDACTED_SECRET]` All endpoints use this pattern: ```bash # GET curl -s "https://api.admapix.com/api/data/{endpoint}?{params}" \ -H "X-[REDACTED_SECRET]" # POST curl -s -X POST "https://api.admapix.com/api/data/{endpoint}" \ -H "X-[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{...}' ``` ## Interaction Flow ### Step 1: Check API Key Before any query, run: `[ -n "$ADMAPIX_API_KEY" ] && echo "ok" || echo "missing"` **Never print the key value.** If missing, output: ``` 🔑 You need an AdMapix API Key. 1. Go to https://www.admapix.com to register 2. Configure: openclaw config set skills.entries.admapix.apiKey "YOUR_KEY" 3. Try again 🎉 ``` ### Step 1.5: Complexity Classification — 复杂度分类 Before routing, classify the query complexity to decide the execution path: | Complexity | Criteria | Path | Examples | |---|---|---|---| | **Simple** | Can be answered with exactly 1 API call; single-entity, single-metric lookup | Skill handles directly (Step 2 onward) | "Temu排名第几", "搜一下休闲游戏素材", "Temu下载量", "Top 10 游戏" | | **Deep** | Requires 2+ API calls, any cross-entity/cross-dimensional query, analysis, comparison, or trend interpretation | Route to Deep Research Framework | "分析Temu的广告投放策略", "Temu和Shein对比", "放置少女的投放策略和竞品对比", "东南亚手游市场分析" | **Classification rule — count the API calls needed:** Simple (exactly 1 API call): - Single search: "搜一下休闲游戏素材" → 1× search - Single ranking: "iOS免费榜Top10" → 1× store-rank - Single detail: "Temu的开发者是谁" → 1× unified-product-search - Single metric: "Temu下载量" → 1× download-detail (after getting ID, but that's lookup+query=2, so actually **Deep**) Deep (2+ API calls): - Any query requiring entity lookup + data fetch: "Temu下载量" needs search→download = 2 calls → **Deep** - Any analysis: "分析XX" → always multi-call → **Deep** - Any comparison: "对比XX和YY" → always multi-call → **Deep** - Any market overview: "XX市场分析" → always multi-call → **Deep** - Any trend: "XX趋势" → always multi-call → **Deep** **In practice, only these are Simple:** - Direct keyword search with no analysis: "搜XX素材", "找XX广告" - Direct ranking with no drill-down: "排行榜", "Top 10" - Filter-options or param lookups **Default:** If unsure, classify as **Deep** (prefer thorough over incomplete). **Execution paths:** **→ Simple path:** Continue to Step 2 (existing routing logic). At the end of the response, append a hint in the user's language: - Chinese: `💡 需要更深入的分析？试试说"深度分析{topic}"` - English: `💡 Want deeper analysis? Try "deep research on {topic}"` **→ Deep path:** Call the Deep Research Framework. This is a 3-step process. Do NOT use `[[reply_to_current]]` until Step 3. **Step 1 — Submit the research task (returns instantly):** Run this exact command (only replace `{user_query}` and `{additional_context}`): ```bash curl -s -X POST "https://deepresearch.admapix.com/research" \ -H "Content-Type: application/json" \ -H "[REDACTED_SECRET]" \ -d '{"project": "admapix", "query": "{user_query}", "context": "{additional_context}", "api_key": "'"$ADMAPIX_API_KEY"'"}' ``` - `project` is always `"admapix"` — do NOT change this. - `query` is the user's research question (in the user's language). - `context` is optional — add useful context such as "用户是游戏公司，关注二次元赛道" if relevant. Omit or set to `null` if not needed. - `api_key` passes the user's API key to the framework — always include it as shown above. This returns immediately with: ```json {"task_id": "dr_xxxx-xxxx-xxxx", "status": "pending", "created_at": "..."} ``` Extract the `task_id` value for Step 2. **Step 2 — Poll until done (use this exact script, do NOT modify):** Run this exact command, only replacing `{task_id}`: ```bash while true; do r=$(curl -s "https://deepresearch.admapix.com/research/{task_id}" -H "[REDACTED_SECRET]"); 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 ``` This 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.** - When it finishes, the last line contains the full JSON result. Proceed to Step 3. **Step 3 — Format and reply to the user with the framework's report.** **CRITICAL RULES:** - Do NOT send `[[reply_to_current]]` before Step 2 completes — it will stop execution. - **NEVER fall back to manual analysis.** The framework WILL complete — just wait for it. - **NEVER write your own polling loop.** Use the exact script above. **Processing the response JSON:** The completed response has this structure: ```json { "task_id": "dr_xxxx", "status": "completed", "output": { "format": "html", "files": [{"name": "report.html", "url": "https://deepresearch.admapix.com/files/{task_id}/report.html", ...}], "summary": "- Temu近30天广告投放以拉美和东南亚为核心\n- 视频素材占比超过95%\n- ..." }, "usage": {"model": "gpt-5.4", "total_tokens": 377289, "research_time_seconds": 125.2} } ``` Do NOT paste the full report into the chat. Instead: 1. Take `output.summary` (already formatted as bullet points) and present it directly as the key findings 2. Append the report link from `output.files[0].url`: `[📊 查看完整报告]({url})` 3. Add follow-up hints based on the summary content **If the task failed** (status=`"failed"`): - The response will contain `"error": {"message": "..."}` with a user-friendly reason - Present the error to the user and suggest they try again or simplify their query - Do NOT try to manually replicate the analysis **Example output (Chinese):** ``` 📊 深度分析完成！ **核心发现：** - AFK Journey 近30天投放覆盖全球，美国、墨西哥、巴西为Top3市场 - 视频素材占比约90%，图片约10% - 投放媒体位以休闲游戏和工具类App为主（Blockudoku、Backgammon等） - 2/18-2/23 与 3/14-3/16 出现投放峰值，可能对应版本更新或活动 👉 [查看完整报告](https://deepresearch.admapix.com/files/dr_xxxx/report.html) 💡 试试："和RAID对比" | "看看素材" | "日本市场详情" ``` **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. **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). --- ### Step 2: Route — Classify Intent & Load Reference Read the user's request and classify into one of these intent groups. Then **read only the reference file(s) needed** before executing. | Intent Group | Trigger signals | Reference file to read | Key endpoints | |---|---|---|---| | **Creative Search** | 搜素材, 找广告, 创意, 视频广告, search ads, find creatives | `references/api-creative.md` + `references/param-mappings.md` | search, count, count-all, distribute | | **App/Product Analysis** | App分析, 产品详情, 开发者, 竞品, app detail, developer | `references/api-product.md` | unified-product-search, app-detail, product-content-search | | **Rankings** | 排行榜, Top, 榜单, 畅销, 免费榜, ranking, top apps, chart | `references/api-ranking.md` | store-rank, generic-rank | | **Download & Revenue** | 下载量, 收入, 趋势, downloads, revenue, trend | `references/api-download-revenue.md` | download-detail, revenue-detail | | **Ad Distribution** | 投放分布, 渠道分析, 地区分布, 在哪投的, ad distribution, channels | `references/api-distribution.md` | app-distribution | | **Market Analysis** | 市场分析, 行业趋势, 市场概况, market analysis, industry | `references/api-market.md` | market-search | | **Deep Dive** | 全面分析, 深度分析, 广告策略, 综合报告, full analysis, strategy | Multiple files as needed | Multi-endpoint orchestration | **Rules:** - If uncertain, default to **Creative Search** (most common use case). - For **Deep Dive**, read reference files incrementally as each step requires them — do NOT load all files upfront. - Always read `references/param-mappings.md` when the user mentions regions, creative types, or sort preferences. ### Step 3: Classify Action Mode | Mode | Signal | Behavior | |---|---|---| | **Browse** | "搜一下", "search", "find", vague exploration | Single query, `generate_page: true`, return H5 link + summary | | **Analyze** | "分析", "哪家最火", "top", "趋势", "why" | Query + structured analysis, `generate_page: false` | | **Compare** | "对比", "vs", "区别", "compare" | Multiple queries, side-by-side comparison | Default to **Analyze** when uncertain. ### Step 4: Plan & Execute **Single-group queries:** Follow the reference file's request format and execute. **Cross-group orchestration (Deep Dive):** Chain multiple endpoints. Common patterns: #### Pattern A: "分析 {App} 的广告策略" — App Ad Strategy 1. `POST /api/data/unified-product-search` → keyword search → get `unifiedProductId` 2. `GET /api/data/app-detail?id={id}` → app info 3. `POST /api/data/app-distribution` with `dim=country` → where they advertise 4. `POST /api/data/app-distribution` with `dim=media` → which ad channels 5. `POST /api/data/app-distribution` with `dim=type` → creative format mix 6. `POST /api/data/product-content-search` → sample creatives Read `api-product.md` for step 1-2, `api-distribution.md` for step 3-5, `api-creative.md` for step 6. #### Pattern B: "对比 {App1} 和 {App2}" — App Comparison 1. Search both apps → get both `unifiedProductId` 2. `app-detail` for each → basic info 3. `app-distribution(dim=country)` for each → geographic comparison 4. `download-detail` for each (if relevant) → download trends 5. `product-content-search` for each → creative style comparison #### Pattern C: "{行业} 市场分析" — Market Intelligence 1. `POST /api/data/market-search` with `class_type=1` → country distribution 2. `POST /api/data/market-search` with `class_type=2` → media channel share 3. `POST /api/data/market-search` with `class_type=4` → top advertisers 4. `POST /api/data/generic-rank` with `rank_type=promotion` → promotion ranking #### Pattern D: "{App} 最近表现怎么样" — App Performance 1. Search app → get `unifiedProductId` 2. `download-detail` → download trend 3. `revenue-detail` → revenue trend 4. `app-distribution(dim=trend)` → ad volume trend 5. Synthesize trends into a performance narrative **Execution rules:** - Execute all planned queries autonomously — do not ask for confirmation on each sub-query. - Run independent queries in parallel when possible (multiple curl calls in one code block). - If a step fails with 403, skip it and note the limitation — do not abort the entire analysis. - If a step fails with 502, retry once. If still failing, skip and note. - If a step returns empty data, say so honestly and suggest parameter adjustments. ### Step 5: Output Results #### Browse Mode **English user:** ``` 🎯 Found {totalSize} results for "{keyword}" 👉 [View full results](https://api.admapix.com{page_url}) 📊 Quick overview: - Top advertiser: {name} ({impression} impressions) - Most active: {title} — {findCntSum} days - Creative types: video / image / mixed 💡 Try: "analyze top 10" | "next page" | "compare with {competitor}" ``` **Chinese user:** ``` 🎯 共找到 {totalSize} 条"{keyword}"相关素材 👉 [查看完整结果](https://api.admapix.com{page_url}) 📊 概览： - 头部广告主：{name}（曝光 {impression}） - 最活跃素材：{title} — 投放 {findCntSum} 天 - 素材类型：视频 / 图片 / 混合 💡 试试："分析 Top 10" | "下一页" | "和{competitor}对比" ``` #### Analyze Mode Adapt output format to the question. Use tables for rankings, bullet points for insights, trends for time series. Always end with **Key findings** section. #### Compare Mode Side-by-side table + differential insights. #### Deep Dive Mode Structured report with sections. Adapt language to user. **English example:** ``` 📊 {App Name} — Ad Strategy Report ## Overview - Category: {category} | Developer: {developer} - Platforms: iOS, Android ## Ad Distribution - Top markets: US (35%), JP (20%), GB (10%) - Main channels: Facebook (40%), Google Ads (30%), TikTok (20%) - Creative mix: Video 60%, Image 30%, Playable 10% ## Performance (estimates) - Downloads: ~{X}M (last 30 days) - Revenue: ~${X}M (last 30 days) ⚠️ Download and revenue figures are third-party estimates. 💡 Try: "compare with {competitor}" | "show creatives" | "US market detail" ``` **Chinese example:** ``` 📊 {App Name} — 广告策略分析报告 ## 基本信息 - 分类：{category} | 开发者：{developer} - 平台：iOS、Android ## 投放分布 - 主要市场：美国 (35%)、日本 (20%)、英国 (10%) - 主要渠道：Facebook (40%)、Google Ads (30%)、TikTok (20%) - 素材类型：视频 60%、图片 30%、试玩 10% ## 表现数据（估算） - 下载量：约 {X} 万（近30天） - 收入：约 ${X} 万（近30天） ⚠️ 下载量和收入为第三方估算数据，仅供参考。 💡 试试："和{competitor}对比" | "看看素材" | "美国市场详情" ``` ### Step 6: Follow-up Handling Maintain full context. Handle follow-ups intelligently: | Follow-up | Action | |---|---| | "next page" / "下一页" | Same params, page +1 | | "analyze" / "分析一下" | Switch to analyze mode on current data | | "compare with X" / "和X对比" | Add X as second query, compare mode | | "show creatives" / "看看素材" | Route to creative search for current app | | "download trend" / "下载趋势" | Route to download-detail for current app | | "which countries" / "哪些国家" | Route to app-distribution(dim=country) | | "market overview" / "市场概况" | Route to market-search | | Adjust filters | Modify params, re-execute | **Reuse data:** If the user asks follow-up questions about already-fetched data, analyze existing results first. Only make new API calls when needed. ## Output Guidelines 1. **Language consistency** — ALL output (headers, labels, insights, hints, errors, disclaimers) must match the user's detected language. See "Language Handling" section above. 2. **Route-appropriate output** — Don't force H5 links on analytical questions; don't dump tables for browsing 3. **Markdown links** — All URLs in `[text](url)` format 4. **Humanize numbers** — English: >10K → "x.xK" / >1M → "x.xM" / >1B → "x.xB". Chinese: >1万 → "x.x万" / >1亿 → "x.x亿" 5. **End with next-step hints** — Contextual suggestions in matching language 6. **Data-driven** — All conclusions based on actual API data, never fabricate 7. **Honest about gaps** — If data is insufficient, say so and suggest alternatives 8. **Disclaimer on estimates** — Always note that download/revenue data are estimates when presenting them 9. **No credential leakage** — Never output API key values, upstream URLs, or internal implementation details 10. **Strip HTML tags** — API may return `<font color='red'>keyword</font>` in name fields. Always strip HTML before displaying to the user. ## Error Handling | Error | Response | |---|---| | 403 Forbidden | "This feature requires API key upgrade. Visit admapix.com for details." | | 429 Rate Limit | "Query quota reached. Check your plan at admapix.com." | | 502 Upstream Error | Retry once. If persistent: "Data source temporarily unavailable, please try again later." | | Empty results | "No data found for these criteria. Try: [suggest broader parameters]" | | Partial failure in multi-step | Complete what's possible, note which data is missing and why |

path: README.md
content: # AdMapix — Ad Intelligence & App Analytics Skill

[中文文档](README_CN.md)

All-in-one ad intelligence assistant. Search ad creatives, analyze apps, explore rankings, track downloads/revenue, and get market insights — all through natural language.

## Features

- **Creative Search** — Search ad creatives by keyword, region, media, creative type, with H5 visual results
- **App Analysis** — Look up any app's details, developer info, and ad creative portfolio
- **Rankings** — App Store / Google Play charts, promotion rankings, download rankings, revenue rankings
- **Download & Revenue** — Track download and revenue trends over time (third-party estimates)
- **Ad Distribution** — Analyze where and how an app advertises (countries, media placements, creative formats)
- **Market Analysis** — Industry-level insights by country, media channel, advertiser, and publisher
- **Deep Dive** — Multi-dimensional reports combining all of the above

## Install

```bash
npx clawhub install admapix
```

## Setup

1. Go to [www.admapix.com](https://www.admapix.com) to register and get your API Key
2. Configure:

```bash
openclaw config set skills.entries.admapix.apiKey "YOUR_ADMAPIX_API_KEY"
```

## Usage Examples

After setup, just tell your AI assistant:

| Category | Example prompts |
|----------|----------------|
| Creative Search | "Search video ads for puzzle games", "Find casual game creatives in Southeast Asia" |
| App Analysis | "Tell me about Temu", "Who is the developer of TikTok?" |
| Rankings | "App Store free chart US", "Top apps by ad spend this week" |
| Downloads | "How are Temu's downloads trending?", "Compare Temu vs SHEIN downloads" |
| Ad Distribution | "Which countries does Temu advertise in?", "What ad channels does this game use?" |
| Market Analysis | "Which country has the most game ads?", "Who are the top game advertisers?" |
| Deep Dive | "Full ad strategy analysis for Temu", "Compare Temu and SHEIN" |

Supports both **English** and **Chinese** — the assistant responds in your language.

## Links

- Website: [www.admapix.com](https://www.admapix.com)
- GitHub: [github.com/fly0pants/admapix](https://github.com/fly0pants/admapix)

---

Built by [Miaozhisheng](https://www.admapix.com)


path: README_CN.md
content: # AdMapix — 广告情报与应用分析 Skill

[English](README.md)

一站式广告情报助手。通过自然语言搜索广告素材、分析应用、查看排行榜、追踪下载量/收入、获取市场洞察。

## 功能

- **素材搜索** — 按关键词、地区、媒体、素材类型搜索广告创意，支持 H5 可视化结果
- **应用分析** — 查询任意应用的详情、开发者信息、广告素材库
- **排行榜** — App Store / Google Play 官方榜单，推广排行、下载排行、收入排行
- **下载量与收入** — 追踪下载量和收入的时间趋势（第三方估算数据）
- **投放分布** — 分析应用在哪些国家、哪些媒体位、用什么素材类型投放广告
- **市场分析** — 按国家、媒体渠道、广告主、流量主维度的行业级洞察
- **深度分析** — 多维度综合报告，整合以上所有能力

## 安装

```bash
npx clawhub install admapix
```

## 配置

1. 前往 [www.admapix.com](https://www.admapix.com) 注册并获取 API Key
2. 配置环境变量：

```bash
openclaw config set skills.entries.admapix.apiKey "你的ADMAPIX_API_KEY"
```

## 使用示例

安装配置完成后，直接对 AI 助手说：

| 分类 | 示例指令 |
|------|----------|
| 素材搜索 | 「搜一下 puzzle game 的视频广告」「找东南亚投放的休闲游戏素材」 |
| 应用分析 | 「分析一下 Temu」「TikTok 的开发者是谁？」 |
| 排行榜 | 「美国 App Store 免费榜」「这周广告投放量最大的 App」 |
| 下载量 | 「Temu 最近下载量怎么样？」「对比 Temu 和 SHEIN 的下载量」 |
| 投放分布 | 「Temu 主要在哪些国家投广告？」「这个游戏用了哪些广告渠道？」 |
| 市场分析 | 「全球游戏广告市场哪个国家最大？」「谁是最大的游戏广告主？」 |
| 深度分析 | 「全面分析 Temu 的广告策略」「对比 Temu 和 SHEIN」 |

支持 **中文** 和 **英文** 双语 — 助手会自动匹配你的语言。

## 链接

- 官网：[www.admapix.com](https://www.admapix.com)
- GitHub：[github.com/fly0pants/admapix](https://github.com/fly0pants/admapix)

---

由 [妙智盛](https://www.admapix.com) 提供技术支持


path: _meta.json
content: ownerId: kn7c1c01gzrc3m423t8n840m9s81vj6m
slug: admapix-ice
version: 1.0.26
publishedAt: 1773899066560

path: references/api-creative.md
content: # Creative Search API / 素材搜索接口

Base URL: `https://api.admapix.com`
Auth: `X-[REDACTED_SECRET]`

---

## 1. Search — 素材搜索

`POST /api/data/search`

Search ad creatives across 5 content types. Supports H5 page generation.

### Content Types

| content_type | Label | Description |
|---|---|---|
| `creative` | 创意组合 | Multi-asset ad bundles (image+video+playable combos) |
| `imagevideo` | 图片/视频 | Individual image or video assets |
| `preplay` | 试玩广告 | Playable/interactive ads |
| `demoad` | 落地页 | Landing pages |
| `document` | 文档素材 | Document-format ads |

### Request Body

```json
{
  "content_type": "creative",
  "keyword": "puzzle game",
  "keyword_type": "",
  "is_new": false,
  "start_date": "2026-02-14",
  "end_date": "2026-03-16",
  "page": 1,
  "page_size": 20,
  "sort_field": "3",
  "sort_rule": "desc",
  "country_ids": [],
  "media_ids": [],
  "adfaction_ids": [],
  "device": [],
  "topic_type": [],
  "languages": [],
  "material_type": "",
  "trade_level1": [],
  "trade_level2": [],
  "trade_level3": [],
  "subject_type": [],
  "product_model": [],
  "product_type": [],
  "selling": [],
  "monetization": [],
  "pay_type": [],
  "company_location": [],
  "campaign_list": [],
  "ad_media_type": [],
  "appeal_type_list": [],
  "interaction_list": [],
  "material_tag": [],
  "material_removal_repeat": false,
  "demoad_formats": [],
  "web_tools": [],
  "material_top_limit": "",
  "gpt_search": null,
  "generate_page": false,
  "delivery": null
}
```

### Key Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| content_type | string | required | One of: creative, imagevideo, preplay, demoad, document |
| keyword | string | "" | Search keyword (app name, ad copy, brand, etc.) |
| keyword_type | string | "" | Keyword match scope (leave empty for default per content_type) |
| start_date | string | 30 days ago | YYYY-MM-DD |
| end_date | string | today | YYYY-MM-DD |
| page | int | 1 | Page number (≥1) |
| page_size | int | 60 | Results per page (1-100) |
| sort_field | string | "3" | "3"=first seen, "4"=days active, "11"=relevance, "15"=impressions |
| sort_rule | string | "desc" | "desc" or "asc" |
| country_ids | string[] | [] | Country codes, e.g. ["US","JP"] — use `ccode` from filter-options |
| media_ids | string[] | [] | Media channel IDs — use `ccode` from filter-options |
| device | string[] | [] | Device filter — use `ccode` from filter-options |
| trade_level1/2/3 | string[] | [] | Industry category filters (hierarchical) |
| material_type | string | "" | Material format filter ("1"=image, "2"=video). **Only effective for `imagevideo` content type** — ignored by other content types |
| ad_media_type | string[] | [] | Ad media type codes |
| material_removal_repeat | bool | false | Deduplicate similar creatives |
| gpt_search | bool/null | null | Enable AI-powered search |
| generate_page | bool | false | Generate H5 result page |
| delivery | object/null | null | `{channel, apiBase, externalUserId}` for H5 page context |

### Response

**Note:** `totalSize` may be `null` for keyword searches. Use `pageIndex` and `pageSize` for pagination.

```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "totalSize": null,
  "list": [
    {
      "id": "87f11b718e162ca06589f3c33ef99472",
      "title": null,
      "describe": null,
      "documentId": null,
      "findCnt": 1,
      "findCntSum": 1,
      "firstTime": "2026-03-16 13:44:54",
      "lastTime": null,
      "globalFirstTime": "2026-03-16 13:44:54",
      "globalLastTime": "2026-03-16 13:44:54",
      "imageFp": [],
      "imageUrl": [],
      "videoFp": ["80c15b563dded967090b0f5850f4941b"],
      "videoUrl": ["https://...video.mp4"],
      "playHtmlFp": [],
      "playHtmlUrl": [],
      "demoadCnt": 1,
      "appList": [
        {
          "id": "6498883328",
          "cnt": null,
          "impression": null,
          "name": "Tile Trip - Match <font color='red'>Puzzle</font> Game",
          "logo": "https://...logo.png",
          "geo": null,
          "pkg": null,
          "developer": "Oakever Games",
          "developerId": "1604529155",
          "productType": [1],
          "tradeLevel1": null,
          "tradeLevel2": null,
          "tradeLevel3": null
        }
      ],
      "sourceAppList": null,
      "originalUrl": null,
      "showCnt": 2802,
      "impression": 145354,
      "webSite": null,
      "demoadWebSite": null,
      "thumbnailConverUrl": ["https://...keyframe.jpg"],
      "videoTimeSpan": [60],
      "growthValue": null,
      "growthRate": null,
      "coverContent": null,
      "novel": null,
      "adSource": 9
    }
  ],
  "folderTotalSize": null,
  "newNum": null,
  "latestDate": null,
  "gptCorrect": {
    "sourceKeyword": "puzzle",
    "correctKeyword": null,
    "type": 3,
    "developers": [],
    "wrongs": [],
    "gptSxes": [],
    "slices": []
  },
  "filters": [],
  "page_url": "/p/abc123",
  "page_key": "abc123",
  "page_expires_at": "2026-03-19 12:00:00"
}
```

`page_url`/`page_key`/`page_expires_at` only present when `generate_page: true`.

### ⚠️ Important Notes

1. **HTML tags in names:** `appList[].name` may contain HTML highlight tags like `<font color='red'>keyword</font>`. Strip these before displaying to the user.
2. **Null values:** Many fields can be `null` — always handle null gracefully.
3. **totalSize null:** For keyword searches, `totalSize` is often `null`. The actual result count is reflected in `list` length per page.

### Response Key Fields

| Field | Description |
|---|---|
| pageIndex | Current page number |
| pageSize | Results per page |
| totalSize | Total matching results (may be null) |
| list[].id | Creative ID |
| list[].title | Ad title (may be null) |
| list[].describe | Ad copy text (may be null) |
| list[].appList[].name | Associated app name — **may contain HTML `<font>` tags** |
| list[].appList[].developer | Developer/publisher name |
| list[].appList[].developerId | Developer ID |
| list[].appList[].logo | App icon URL |
| list[].impression | Estimated impression count |
| list[].findCntSum | Days the ad has been active |
| list[].showCnt | Number of ad variants detected |
| list[].globalFirstTime | First seen date |
| list[].globalLastTime | Last seen date |
| list[].imageUrl | Image asset URLs (array) |
| list[].videoUrl | Video asset URLs (array) |
| list[].playHtmlUrl | Playable ad URLs (array) |
| list[].thumbnailConverUrl | Video thumbnail/keyframe URLs (array) |
| list[].videoTimeSpan | Video durations in seconds (array) |
| list[].demoadCnt | Number of landing pages |
| gptCorrect | AI keyword correction info |

---

## 2. Count — 素材计数

`POST /api/data/count`

Get total count, new count, and latest date for a single content type.

### Request Body

Same as search (content_type + filter params). Only counting fields matter — page/sort are ignored.

### Response

```json
{
  "totalSize": 50000,
  "newNum": 1200,
  "latestDate": "2026-03-16"
}
```

---

## 3. Count All — 全类型计数

`POST /api/data/count-all`

Aggregate counts across all 5 content types. No request body needed.

### Response

```json
{
  "creative": { "label": "创意组合", "totalSize": 50000, "newNum": 1200, "latestDate": "2026-03-16" },
  "imagevideo": { "label": "图片/视频", "totalSize": 120000, "newNum": 3500, "latestDate": "2026-03-16" },
  "preplay": { "label": "试玩广告", "totalSize": 8000, "newNum": 200, "latestDate": "2026-03-15" },
  "demoad": { "label": "落地页", "totalSize": 30000, "newNum": 800, "latestDate": "2026-03-16" },
  "document": { "label": "文档素材", "totalSize": 5000, "newNum": 100, "latestDate": "2026-03-14" }
}
```

---

## 4. Distribute — 素材分布分析

`POST /api/data/distribute`

Analyze distribution of specific creatives by dimension.

### Request Body

```json
{
  "content_type": "creative",
  "dimension": "media",
  "ids": ["creative_id_1", "creative_id_2"],
  "start_date": "",
  "end_date": ""
}
```

| Parameter | Type | Description |
|---|---|---|
| content_type | string | Content type |
| dimension | string | Distribution dimension |
| ids | string[] | Creative IDs to analyze |
| start_date/end_date | string | Date range |

### Available Dimensions per Content Type

| content_type | Dimensions |
|---|---|
| creative | media, adfaction, app |
| imagevideo | media, adfaction, app, country |
| preplay | media, adfaction, app |
| demoad | media, adfaction, app |
| document | media, adfaction, app |

Use `GET /api/data/distribute-dims` to fetch this mapping dynamically.

---

## 5. Filter Options — 筛选枚举项

`GET /api/data/filter-options`

Returns all filter enum options in a single batch call (13 categories).

### Response

**IMPORTANT:** Each item has both `code` (complex internal format) and `ccode` (simplified code). **Always use `ccode` when passing filter values to search/query endpoints.**

```json
{
  "countries": [
    {"code": "毛里塔尼亚_2_MRT", "nameCn": "毛里塔尼亚", "nameEn": "Mauritania", "ccode": "MR", "icon": "https://...flag.png"}
  ],
  "mediaChannels": [
    {"code": "海外平台-101-Adcolony", "nameCn": "Adcolony", "nameEn": "Adcolony", "ccode": "101", "icon": "https://...icon.png"}
  ],
  "adTypes": [
    {"code": "adstyle_原生_1076682150_1076682150", "nameCn": "原生", "nameEn": "Native Ads", "ccode": "1076682150", "icon": null}
  ],
  "device": [
    {"code": "Android_2_1", "nameCn": "Android", "nameEn": "Android", "ccode": "1", "icon": "android"}
  ],
  "tradeLevel": [
    {"code": "601", "nameCn": "工具", "nameEn": "Tools", "ccode": "601", "icon": null}
  ],
  "productModel": [
    {"code": "1", "nameCn": "非游戏", "nameEn": "Non-game", "ccode": "1", "icon": null}
  ],
  "productType": [
    {"code": "app_1_1", "nameCn": "App", "nameEn": "App", "ccode": "1", "icon": null}
  ],
  "selling": [
    {"code": "5005_w2a", "nameCn": "W2A", "nameEn": "W2A", "ccode": "w2a", "icon": null}
  ],
  "subjectType": [
    {"code": "gold_0_1", "nameCn": "金币", "nameEn": "Gold", "ccode": "1", "icon": null}
  ],
  "topicType": [
    {"code": "传奇_9_64", "nameCn": "传奇", "nameEn": "Legend", "ccode": "90064", "icon": null}
  ],
  "languages": [
    {"code": "南非荷兰语_af", "nameCn": "南非荷兰语", "nameEn": "Afrikaans", "ccode": "af", "icon": null}
  ],
  "materialTag": [
    {"code": "AI_0_1", "nameCn": "AI", "nameEn": "AI", "ccode": "001", "icon": ""}
  ],
  "tradeLevel2": [
    {"code": "60301", "nameCn": "电商", "nameEn": "E-commerce", "ccode": "60301", "icon": null}
  ],
  "materialFormat": [
    {"code": "5006_100", "nameCn": "单图", "nameEn": "Single Image", "ccode": "100", "icon": null}
  ]
}
```

### Filter Code Usage

| Filter parameter | Use `ccode` from | Example |
|---|---|---|
| country_ids | countries | "US", "JP", "MR" |
| media_ids | mediaChannels | "101" (Adcolony) |
| device | device | "1" (Android) |
| trade_level1/2/3 | tradeLevel | "601" (Tools) |
| ad_media_type | adTypes | "1076682150" (Native Ads) |
| languages | languages | "af" (Afrikaans) |
| material_tag | materialTag | "001" (AI) |

---

## 6. Screen Types — 单类筛选项

`GET /api/data/screen-types?element_type=1`

Fetch a single filter category by element type ID.

| element_type | Category |
|---|---|
| 1004 | tradeLevel (industry) |
| 2002 | countries |
| 2004 | device |
| 2005 | languages |
| 2006 | mediaChannels |
| 2008 | materialTag |
| 3000 | subjectType |
| 3006 | productType |
| 5001 | adTypes |
| 5005 | selling |
| 5006 | materialFormat |

---

## 7. Page Config — 页面配置

`GET /api/data/page-config?scope=search`

Returns page layout configuration for the specified scope.


path: references/api-distribution.md
content: # App Distribution API / 应用投放分布接口

Base URL: `https://api.admapix.com`
Auth: `X-[REDACTED_SECRET]`

> These endpoints require a `unified_product_id`. Get it from `unified-product-search` first.

---

## 1. App Distribution — 应用推广分布

`POST /api/data/app-distribution`

Analyze an app's ad distribution across different dimensions.

### Request Body

```json
{
  "unified_product_id": "xxx",
  "dim": "country",
  "start_time": "",
  "end_time": "",
  "countries": [],
  "media_ids": [],
  "material_type": "",
  "index_type": 0
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| unified_product_id | string | required | Target app ID |
| dim | string | required | Distribution dimension (see below) |
| start_time | string | 30 days ago | YYYY-MM-DD |
| end_time | string | today | YYYY-MM-DD |
| countries | string[] | [] | Country filter |
| media_ids | string[] | [] | Media channel filter |
| material_type | string/int | "" | Material type filter |
| index_type | int | 0 | Index type selector |

### Dimensions

| dim | Description | Returns |
|---|---|---|
| `trend` | 投放趋势 | Time series of ad volume over time |
| `country` | 投放国家分布 | Per-country ad placement distribution |
| `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 "广告展示位". |
| `platform` | 平台分布 | iOS vs Android breakdown |
| `type` | 素材类型分布 | Image vs video vs playable distribution |
| `image` | 图片尺寸分布 | Image size/aspect ratio breakdown |
| `video` | 视频时长分布 | Video duration breakdown |
| `lang` | 语言分布 | Ad language distribution |

### Response Examples

**dim=country:**
```json
{
  "list": [
    {"code": "US", "name": "United States", "cnt": 500, "ratio": 0.35},
    {"code": "JP", "name": "Japan", "cnt": 300, "ratio": 0.21}
  ]
}
```

**dim=trend:**
```json
{
  "list": [
    {"date": "2026-03-01", "cnt": 50},
    {"date": "2026-03-02", "cnt": 65}
  ]
}
```

**dim=media (publisher apps / ad placements):**
```json
{
  "list": [
    {"id": "101", "name": "Block Blast Adventure Master", "cnt": 400, "ratio": 0.15},
    {"id": "102", "name": "Snake.io", "cnt": 250, "ratio": 0.09},
    {"id": "103", "name": "Solitaire", "cnt": 180, "ratio": 0.07}
  ]
}
```
These 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.

---

## 2. Distribute Dims — 素材分布维度

`GET /api/data/distribute-dims`

Returns which distribute dimensions are available per content type. This is for the creative-level distribute endpoint (`/api/data/distribute`), not for app-distribution.

### Response

```json
{
  "creative": ["media", "adfaction", "app"],
  "imagevideo": ["media", "adfaction", "app", "country"],
  "preplay": ["media", "adfaction", "app"],
  "demoad": ["media", "adfaction", "app"],
  "document": ["media", "adfaction", "app"]
}
```

---

## Common Workflows / 常用工作流

### "Temu 主要在哪些国家投广告？"

```
app-distribution(unified_product_id=id, dim="country")
```

### "Temu 用了哪些广告渠道？"

```
app-distribution(unified_product_id=id, dim="media")
```

### "Temu 的投放趋势怎么样？"

```
app-distribution(unified_product_id=id, dim="trend", start_time="2026-01-01", end_time="2026-03-16")
```

### "Temu 在美国投了多少视频广告 vs 图片广告？"

```
app-distribution(unified_product_id=id, dim="type", countries=["US"])
```

### Full app advertising profile (multi-call)

1. `dim="country"` → where they advertise (target countries)
2. `dim="media"` → which publisher apps carry their ads (ad placements)
3. `dim="type"` → what creative formats they use
4. `dim="trend"` → how ad volume changes over time
5. `dim="lang"` → which languages they target

Combine all 5 for a comprehensive advertising strategy overview.


path: references/api-download-revenue.md
content: # Download & Revenue API / 下载量与收入接口

Base URL: `https://api.admapix.com`
Auth: `X-[REDACTED_SECRET]`

> These endpoints require a `unified_product_id`. Get it from `unified-product-search` first.

---

## 1. Download Date Range — 下载量可用日期

`GET /api/data/download-date`

Returns the available date range for download data queries.

### Response

```json
{
  "startDate": "2023-01-01",
  "endDate": "2026-03-15"
}
```

**Use this to validate date params before calling download-detail/download-country.**

---

## 2. Download Detail — 下载量趋势

`POST /api/data/download-detail`

Fetch download trend data for a specific app over time.

### Request Body

```json
{
  "unified_product_id": "xxx",
  "query_start_date": "2026-02-14",
  "query_end_date": "2026-03-16",
  "compare_start_date": "",
  "compare_end_date": "",
  "country_st": [],
  "day_type": 1,
  "flag": true,
  "is_all": false
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| unified_product_id | string | required | Target app ID |
| query_start_date | string | required | YYYY-MM-DD |
| query_end_date | string | required | YYYY-MM-DD |
| compare_start_date | string | "" | Compare period start (optional) |
| compare_end_date | string | "" | Compare period end (optional) |
| country_st | string[] | [] | Country filter (empty = global) |
| day_type | int | 1 | Granularity: 1=daily, 2=weekly, 3=monthly |
| flag | bool | true | Include trend data |
| is_all | bool | false | All countries aggregated |

### Response

Returns time series data:
```json
{
  "list": [
    {"date": "2026-03-01", "download": 150000, "compareDownload": 120000},
    {"date": "2026-03-02", "download": 160000, "compareDownload": 125000}
  ]
}
```

---

## 3. Download Country — 按国家下载量

`POST /api/data/download-country`

Fetch download data broken down by country.

### Request Body

Same as download-detail.

### Response

Returns per-country breakdown:
```json
{
  "list": [
    {"country": "US", "countryName": "United States", "download": 500000},
    {"country": "JP", "countryName": "Japan", "download": 300000}
  ]
}
```

---

## 4. Revenue Date Range — 收入可用日期

`GET /api/data/revenue-date`

Returns the available date range for revenue data queries.

### Response

```json
{
  "startDate": "2023-01-01",
  "endDate": "2026-03-15"
}
```

---

## 5. Revenue Detail — 收入趋势

`POST /api/data/revenue-detail`

Fetch revenue trend data for a specific app.

### Request Body

```json
{
  "unified_product_id": "xxx",
  "query_start_date": "2026-02-14",
  "query_end_date": "2026-03-16",
  "compare_start_date": "",
  "compare_end_date": "",
  "country_st": [],
  "day_type": 1,
  "flag": true,
  "is_all": false,
  "revenue_type": "ALL"
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| (same as download-detail, plus:) | | | |
| revenue_type | string | "ALL" | Revenue type filter |

---

## 6. Revenue Country — 按国家收入

`POST /api/data/revenue-country`

Fetch revenue data broken down by country.

### Request Body

Same as revenue-detail.

---

## Common Workflows / 常用工作流

### "Temu 最近下载量怎么样？"

1. `unified-product-search(keyword="temu")` → get `unifiedProductId`
2. `download-date` → confirm available range
3. `download-detail(unified_product_id=id, query_start_date="2026-02-14", query_end_date="2026-03-16")` → trend
4. Present trend data with insights

### "对比 Temu 在美国和日本的收入"

1. Get `unifiedProductId` (step 1 above)
2. `revenue-country(unified_product_id=id, ...)` → per-country revenue
3. Filter & compare US vs JP data

### "Temu vs SHEIN 下载量对比"

1. Search both apps → get both `unifiedProductId`
2. `download-detail` for each → two trend datasets
3. Present side-by-side comparison

### Day Type Reference

| day_type | Granularity | Best for |
|---|---|---|
| 1 | Daily | Short ranges (≤90 days) |
| 2 | Weekly | Medium ranges (1-6 months) |
| 3 | Monthly | Long ranges (6+ months) |


path: references/api-market.md
content: # Market Analysis API / 市场分析接口

Base URL: `https://api.admapix.com`
Auth: `X-[REDACTED_SECRET]`

---

## Market Search — 市场分析搜索

`POST /api/data/market-search`

Analyze the advertising market from 5 different dimensions. Provides macro-level market intelligence.

### Request Body

```json
{
  "class_type": 1,
  "data_type": "1",
  "start_date": "",
  "end_date": "",
  "trade_level3": [],
  "country_level2": [],
  "media_ids": [],
  "device": [],
  "ad_company_location": [],
  "traffic_company_location": [],
  "page": 1,
  "page_size": 20
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| class_type | int | required | Analysis dimension (1-5, see below) |
| data_type | string | "1" | "1"=game, "2"=app |
| start_date | string | today | YYYY/MM/DD (note: slash format) |
| end_date | string | today | YYYY/MM/DD (note: slash format) |
| trade_level3 | string[] | [] | Sub-industry filter |
| country_level2 | string[] | [] | Country filter |
| media_ids | string[] | [] | Media channel filter |
| device | string[] | [] | Device filter |
| ad_company_location | string[] | [] | Advertiser company location filter |
| traffic_company_location | string[] | [] | Publisher/traffic source location filter |
| page | int | 1 | Page number |
| page_size | int | 20 | Results per page (1-100) |

### Dimensions (class_type)

| class_type | Dimension | Description | Best for |
|---|---|---|---|
| 1 | 国家 Country | Market size by country | "Which countries have the most game ads?" |
| 2 | 媒体 Media | Market share by ad network | "Which ad platforms are most used?" |
| 3 | 子媒体 Sub-Media | Breakdown within media channels | "What Facebook ad placements are popular?" |
| 4 | 广告主 Advertiser | Top advertisers in the market | "Who are the biggest game advertisers?" |
| 5 | 流量主 Publisher | Top publishers / traffic sources | "Which publishers carry the most ads?" |

### Data Type

| data_type | Description |
|---|---|
| "1" | 游戏 Game — game industry data |
| "2" | 应用 App — non-game app data |

**Note:** Date format for this endpoint uses slashes (`YYYY/MM/DD`), not dashes.

### Response

**IMPORTANT:** This endpoint returns a different structure from other endpoints. The response uses `data_list` (not `list`) and nested dot-notation field names.

**Pagination fields:** `page_total` (total pages), `page_num` (current page), `page_size`.

#### class_type=1 (Country) response:
```json
{
  "data_list": [
    {
      "market_query.list.id": "ID",
      "query.country_info.s_code": "ID",
      "query.country_info.c_code": "ID",
      "query.country_info.country_name": "印度尼西亚",
      "market_query.list.raw_impression": 11578945855,
      "market_query.list.impression": "116亿",
      "market_query.list.impressionRatio": "13.64%",
      "market_query.list.rank": 1,
      "query.country_info.image": "https://...flag.png"
    }
  ],
  "page_total": 34,
  "page_num": 1,
  "page_size": 3
}
```

Key fields to extract:
- `query.country_info.country_name` — country name (Chinese)
- `query.country_info.c_code` — country code
- `market_query.list.impression` — impression count (pre-formatted string like "116亿")
- `market_query.list.raw_impression` — raw numeric impression count
- `market_query.list.impressionRatio` — percentage share
- `market_query.list.rank` — rank position

#### class_type=4 (Advertiser) response:
```json
{
  "data_list": [
    {
      "market_query.list.market_query.list.advertiser": "275091615",
      "market_query.list.query.company_info.unified_company_name": "VGam.es",
      "market_query.list.query.company_info.unified_company_id": "275091615",
      "query.pkg_info.productName": "Math Crossword – Endless Fun",
      "query.pkg_info.productLogo": "https://...logo.png",
      "query.pkg_info.unifiedPkgId": "com.vgames.mathcrossword",
      "market_query.list.market_query.list.company_impression": "64亿",
      "market_query.list.market_query.list.raw_company_impression": 6449946845,
      "market_query.list.market_query.list.company_impressionRatio": "10.31%",
      "market_query.list.market_query.list.top1_app_impression": "64亿",
      "market_query.list.market_query.list.rank": 1
    }
  ],
  "page_total": 500,
  "page_num": 1,
  "page_size": 2
}
```

Key fields to extract:
- `market_query.list.query.company_info.unified_company_name` — company name
- `query.pkg_info.productName` — top product name
- `market_query.list.market_query.list.company_impression` — total impression (formatted)
- `market_query.list.market_query.list.company_impressionRatio` — market share %
- `market_query.list.market_query.list.rank` — rank position

---

## Common Workflows / 常用工作流

### "全球游戏广告市场哪个国家最大？"

```json
{"class_type": 1, "data_type": "1"}
```

### "美国市场最大的游戏广告主是谁？"

```json
{"class_type": 4, "data_type": "1", "country_level2": ["US"]}
```

### "电商App广告市场对比：东南亚 vs 北美"

Two queries:
1. `{"class_type": 1, "data_type": "2", "country_level2": ["TH","VN","ID","MY","PH","SG"]}`
2. `{"class_type": 1, "data_type": "2", "country_level2": ["US","CA"]}`

Compare total counts, top advertisers, media distribution.

### Market overview combo (multi-call)

For a comprehensive market report on a segment:
1. `class_type=1` → geographic distribution
2. `class_type=2` → media channel breakdown
3. `class_type=4` → top advertisers
4. `class_type=5` → top publishers

Combine for a full market intelligence report.

---

## Filter Codes

Use `GET /api/data/filter-options` to get valid codes for:
- `trade_level3` — industry/sub-category codes
- `country_level2` — country codes (use the `ccode` field, e.g. "US", "JP")
- `media_ids` — media channel IDs (use the `ccode` field, e.g. "101" for Adcolony)
- `device` — device type codes (use the `ccode` field, e.g. "1" for Android)

See `references/param-mappings.md` for common country/region mappings.


path: references/api-ranking.md
content: # Ranking API / 排行榜接口

Base URL: `https://api.admapix.com`
Auth: `X-[REDACTED_SECRET]`

---

## 1. Store Rank — 应用商店排行

`POST /api/data/store-rank`

Fetch App Store / Google Play official rankings.

### Request Body

```json
{
  "market": "appstore",
  "rank_type": "free",
  "cat_type": "game",
  "cat_code": "games",
  "country": ["US"],
  "page": 1,
  "page_size": 20
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| market | string | "appstore" | `appstore` or `googleplay` |
| rank_type | string | "free" | `free`, `paid`, `grossing` |
| cat_type | string | "game" | `game` or `app` |
| cat_code | string | "games" | Category code (from store-categories API) |
| country | string[] | ["US"] | Country codes |
| page | int | 1 | Page number |
| page_size | int | 20 | Results per page (1-100) |

### Response

**Note:** Uses nested dot-notation field names.

```json
{
  "totalSize": 25,
  "pageIndex": 1,
  "pageSize": 2,
  "maxDate": "2026-03-16",
  "list": [
    {
      "query.info.query.info.productNameEn": "Solitaire Associations Journey",
      "query.info.query.info.productNameCn": null,
      "query.info.query.info.productNameDefault": "Solitaire Associations Journey",
      "query.info.query.info.productLogo": "https://...logo.png",
      "query.info.query.info.unifiedPkgId": "6748950306",
      "query.info.query.info.developerId": 1049188906,
      "query.info.query.companyInfo.companyId": "1049188906",
      "query.info.query.companyInfo.companyName": "Hitapps Games LTD",
      "query.list.rank": 1,
      "query.list.id": "6748950306"
    }
  ]
}
```

Key fields to extract:
- `query.info.query.info.productNameDefault` or `productNameEn` — app name
- `query.info.query.info.productLogo` — app icon URL
- `query.info.query.companyInfo.companyName` — developer name
- `query.info.query.info.unifiedPkgId` — unified product ID (use this for detail/distribution queries)
- `query.list.rank` — ranking position

---

## 2. Generic Rank — 通用排行榜

`POST /api/data/generic-rank`

Unified endpoint for 6 ranking types based on ad intelligence data.

### Request Body

```json
{
  "rank_type": "promotion",
  "category_id": "6014",
  "date_type": 1,
  "page": 1,
  "page_size": 50,
  "start_date": "",
  "end_date": "",
  "country": [],
  "sort_field": "",
  "sort_rule": "desc",
  "day_mode": ""
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| rank_type | string | required | See ranking types below |
| 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 |
| date_type | int | 1 | Date range type: 1 = last 30 days, 2 = last 7 days, 3 = last 3 days |
| page | int | 1 | Page number |
| page_size | int | 50 | Results per page (1-100) |
| start_date | string | 30 days ago | YYYY-MM-DD (overrides date_type if set) |
| end_date | string | today | YYYY-MM-DD (overrides date_type if set) |
| country | string[] | [] | Country filter |
| sort_field | string | varies | Sort field (default varies by rank_type) |
| sort_rule | string | "desc" | Sort direction |
| day_mode | string | "" | Time window: "D3", "D7", "D30" (promotion only) |

### Ranking Types

| rank_type | Description | Default sort_field |
|---|---|---|
| `promotion` | 推广排行 — apps by ad promotion volume | "15" |
| `download` | 下载排行 — apps by download estimates | "1" |
| `revenue` | 收入排行 — apps by revenue estimates | "1" |
| `newapp` | 新应用排行 — recently launched apps | "15" |
| `overseas` | 出海排行 — Chinese apps going global | "15" |
| `drama` | 短剧排行 — short drama/content apps | "2" |

### Response — varies by rank_type!

**IMPORTANT:** Different rank types return different response structures.

#### promotion / newapp / overseas response:

Uses nested dot-notation field names (same style as store-rank):
```json
{
  "totalSize": 1000,
  "list": [
    {
      "query.info.query.info.productNameDefault": "App Name",
      "query.info.query.info.productLogo": "https://...logo.png",
      "query.info.query.info.unifiedPkgId": "123456",
      "query.info.query.companyInfo.companyName": "Developer Name",
      "query.list.rank": 1,
      "query.list.id": "123456"
    }
  ]
}
```

#### download response:

Uses flat field names:
```json
{
  "totalSize": 505970,
  "list": [
    {
      "productId": "6448311069",
      "appCode": "6448311069",
      "appName": "ChatGPT",
      "developer": "OpenAI OpCo, LLC",
      "developerId": "620366005",
      "iconUrl": "https://...logo.png",
      "queryDownloadCnt": 78578987,
      "compareDownloadCnt": 85509701,
      "downloadGrowth": -6930714,
      "growthPercent": -8.11,
      "isAd": "1",
      "productCnt": 3
    }
  ]
}
```

Key fields:
- `appName` — app name
- `queryDownloadCnt` — download count in query period
- `compareDownloadCnt` — download count in compare period
- `downloadGrowth` — absolute growth
- `growthPercent` — growth percentage (negative = decline)

#### revenue response:

Similar flat structure to download, with revenue-specific fields.

### Rank Type Details

**promotion** — Ranks apps by advertising intensity. "Which apps are spending the most on ads?"
- Supports `day_mode`: "D3" (3 days), "D7" (7 days), "D30" (30 days)

**download** — Ranks apps by estimated download volume. "Which apps are downloaded the most?"
- Includes auto-calculated compare period for growth calculation
- ⚠️ Download/revenue figures are third-party estimates

**revenue** — Ranks apps by estimated revenue. "Which apps earn the most?"
- ⚠️ Revenue figures are third-party estimates

**newapp** — Tracks newly launched apps. "What new apps just launched?"

**overseas** — Tracks Chinese companies' apps in global markets. "Which Chinese apps are going overseas?"

**drama** — Tracks short drama / content apps. "What's trending in short drama?"

---

## 3. Store Categories — 商店分类

`GET /api/data/store-categories`

Fetch available app store categories for use with store-rank.

---

## 4. Store Countries — 商店国家列表

`GET /api/data/store-countries`

Fetch available countries for store ranking filter.

---

## User Intent Mapping / 用户意图映射

| User says | rank_type | Extra params |
|---|---|---|
| "App Store 免费榜" | → use store-rank | market=appstore, rank_type=free |
| "Google Play 畅销榜" | → use store-rank | market=googleplay, rank_type=grossing |
| "哪个App广告投得最多" | promotion | sort by default |
| "下载量最高的游戏" | download | — |
| "收入最高的App" | revenue | — |
| "最近新上线的App" | newapp | — |
| "出海做得好的中国App" | overseas | — |
| "短剧排行" | drama | — |
| "美国市场推广排行" | promotion | country=["US"] |
| "最近3天广告量最大的" | promotion | day_mode="D3" |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)