Skill: modestyrichards/modesty-admapix (version 1.0.0)

--- name: admapix version: "1.0.0" 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":"SKILLBOSS_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 "$SKILLBOSS_API_KEY" ] && echo "ok" || echo "missing"` **Never print the key value.** If missing, output: ``` 🔑 You need a SkillBoss API Key to use this skill. 1. Go to https://www.admapix.com to register and get your AdMapix API Key 2. Configure: openclaw config set skills.entries.admapix.env.SKILLBOSS_API_KEY "YOUR_KEY" 3. Try again 🎉 ``` ### 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.env.SKILLBOSS_API_KEY "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.env.SKILLBOSS_API_KEY "你的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: 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-200) |
| 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 |
| 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": ""}
  ],
  "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-200) |

### 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-product.md
content: # Product & Company API / 产品与公司接口

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

---

## 1. Unified Product Search — 统一产品搜索

`POST /api/data/unified-product-search`

Search for unified products (cross-platform aggregated apps). This is the primary entry point for finding apps/products.

### Request Body

```json
{
  "keyword": "temu",
  "type": 1,
  "page": 1,
  "page_size": 20,
  "start_date": "",
  "end_date": "",
  "sort_field": "3",
  "sort_rule": "desc",
  "unified_product_id": "",
  "unified_developer_id": ""
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| keyword | string | "" | Search keyword |
| type | int | 1 | Search type |
| page | int | 1 | Page number |
| page_size | int | 20 | Results per page (1-200) |
| start_date | string | 30 days ago | YYYY-MM-DD |
| end_date | string | today | YYYY-MM-DD |
| sort_field | string | "3" | Sort field |
| sort_rule | string | "desc" | Sort direction |
| unified_product_id | string | "" | Filter by specific unified product |
| unified_developer_id | string | "" | Filter by specific developer |

### Response

```json
{
  "pageIndex": 1,
  "pageSize": 20,
  "totalSize": 96,
  "list": [
    {
      "unifiedProductId": "1641486558",
      "unifiedProductName": "<font color='red'>Temu</font>: Shop Like a Billionaire",
      "unifiedCompanyId": "569338280",
      "unifiedCompanyName": "Temu",
      "productIds": ["com.einnovation.temu", "1641486558", "com.Temu_Team_Up.used_letgo_buy_app1"],
      "tradeLevel1": ["603"],
      "tradeLevel2": ["60301", "60303"],
      "tradeLevel3": ["6030102", "6030301"],
      "tradeLevel4": [],
      "showCost": 23236263827,
      "impression": 2412399002696,
      "materialUvCnt": 7451078,
      "productCnt": 3,
      "iconUrl": "https://...logo.png",
      "collectId": null,
      "formerNames": null,
      "adSource": 9
    }
  ],
  "folderTotalSize": null,
  "newNum": 0,
  "latestDate": null,
  "gptCorrect": null,
  "filters": null
}
```

### ⚠️ Important Notes

1. **HTML tags in names:** `unifiedProductName` may contain HTML highlight tags `<font color='red'>keyword</font>`. Strip these before displaying.
2. The `unifiedProductId` returned here is the key input for detail/distribution/download/revenue endpoints.
3. `productIds` contains platform-specific IDs (Android package name, iOS app ID).

### Key Fields

| Field | Description |
|---|---|
| unifiedProductId | Unique cross-platform product ID — **use this for all detail/distribution queries** |
| unifiedProductName | App name (may contain HTML `<font>` tags for keyword highlighting) |
| unifiedCompanyId | Developer/company ID |
| unifiedCompanyName | Developer/company name |
| productIds | Array of platform-specific product IDs |
| iconUrl | App icon URL |
| showCost | Total ad spend estimate (raw number) |
| impression | Total impression count (raw number) |
| materialUvCnt | Total unique creative count |
| productCnt | Number of platform versions |
| tradeLevel1/2/3/4 | Industry category codes |

---

## 2. Product Search — 产品搜索

`POST /api/data/product-search`

Search for individual products (platform-specific). Same request body as unified product search.

---

## 3. Company Search — 公司/开发者搜索

`POST /api/data/company-search`

Search for companies/developers. Same request body as unified product search.

### Response

```json
{
  "pageIndex": 1,
  "pageSize": 1,
  "totalSize": 7,
  "list": [
    {
      "unifiedCompanyId": "1773957248",
      "unifiedCompanyName": "<font color='red'>Bytedance</font> 字节跳动",
      "unifiedCompanyRegion": "CN",
      "uaList": [1, 2, 3],
      "showCost": 10768429037,
      "impression": 2844436033460,
      "collectId": null,
      "productIds": ["com.zhiliaoapp.musically", "com.ss.android.ugc.trill", "1235601864", "..."],
      "productCnt": 53,
      "downloadCnt": null,
      "hitDeveloper": false,
      "unifiedCompanyNameDefault": null,
      "developerList": [
        {"id": "640989321", "name": "Bytedance Pte. Ltd", "status": 0, "productCnt": 9, "collectId": null}
      ],
      "unifiedCompanyNameOrigin": "Bytedance 字节跳动",
      "adSource": 9
    }
  ]
}
```

### Key Fields

| Field | Description |
|---|---|
| unifiedCompanyId | Unified company ID — **use for developer-detail queries** |
| unifiedCompanyName | Company name (may contain HTML `<font>` tags) |
| unifiedCompanyNameOrigin | Original company name without highlighting |
| unifiedCompanyRegion | Company region code (e.g. "CN") |
| showCost | Total ad spend estimate |
| impression | Total impressions |
| productCnt | Total number of products |
| productIds | All product IDs under this company |
| developerList | List of developer accounts under the company |
| developerList[].id | Developer ID |
| developerList[].name | Developer name |
| developerList[].productCnt | Products under this developer |

---

## 4. App Detail — 应用详情

`GET /api/data/app-detail?id={unifiedProductId}`

Get comprehensive detail for a specific app/product.

| Parameter | Type | Description |
|---|---|---|
| id | string | unified product ID (from unified-product-search) |

### Response

```json
{
  "unifiedProductId": "com.einnovation.temu",
  "unifiedProductName": "Temu: Shop Like a Billionaire",
  "unifiedCompanyId": "569338280",
  "unifiedCompanyName": "Temu",
  "productIds": ["com.einnovation.temu", "1641486558", "com.Temu_Team_Up.used_letgo_buy_app1"],
  "tradeLevel1": ["603"],
  "tradeLevel2": ["60301", "60303"],
  "tradeLevel3": ["6030102", "6030301"],
  "tradeLevel4": null,
  "showCost": null,
  "impression": null,
  "materialUvCnt": null,
  "productCnt": 3,
  "iconUrl": "https://...logo.png",
  "collectId": null,
  "formerNames": null,
  "adSource": 9
}
```

**Note:** `showCost`, `impression`, `materialUvCnt` are `null` in app-detail (these are only available in search results). Use unified-product-search to get these metrics.

---

## 5. Developer Detail — 开发者详情

`GET /api/data/developer-detail?id={unifiedCompanyId}`

Get developer/company detail.

| Parameter | Type | Description |
|---|---|---|
| id | string | unified company ID (from unified-product-search or company-search) |

### Response

```json
{
  "unifiedCompanyId": "569338280",
  "unifiedCompanyName": "Temu",
  "unifiedCompanyRegion": "美国",
  "uaList": [1, 2, 3],
  "showCost": null,
  "impression": null,
  "collectId": null,
  "productIds": ["com.einnovation.temu", "1641486558", "com.Temu_Team_Up.used_letgo_buy_app1"],
  "productCnt": 6,
  "downloadCnt": null,
  "hitDeveloper": null,
  "unifiedCompanyNameDefault": null,
  "developerList": [
    {"id": "444696740", "name": "HY Dev LLC", "status": 0, "productCnt": 7, "collectId": null},
    {"id": "480100326", "name": "Temu", "status": 0, "productCnt": 2, "collectId": null}
  ],
  "unifiedCompanyNameOrigin": null,
  "adSource": 9
}
```

### Key Fields

| Field | Description |
|---|---|
| unifiedCompanyName | Company name |
| unifiedCompanyRegion | Company location (Chinese name, e.g. "美国") |
| productIds | All product IDs |
| productCnt | Total product count |
| developerList | Sub-developer accounts |

---

## 6. Product List — 子产品列表

`POST /api/data/product-list`

Get individual products (per platform) under a unified product.

### Request Body

```json
{
  "unified_product_id": "xxx",
  "page": 1,
  "page_size": 20
}
```

---

## 7. Product Agg List — 开发者产品聚合列表

`POST /api/data/product-agg-list`

Get aggregated products under a specific developer.

### Request Body

```json
{
  "unified_developer_id": "xxx",
  "page": 1,
  "page_size": 20
}
```

---

## 8. Product Content Search — 产品维度素材搜索

`POST /api/data/product-content-search`

Search for ad creatives specifically associated with a product.

### Request Body

```json
{
  "content_type": "creative",
  "unified_product_id": "xxx",
  "keyword": "",
  "page": 1,
  "page_size": 20,
  "start_date": "",
  "end_date": "",
  "sort_field": "3",
  "sort_rule": "desc"
}
```

| Parameter | Type | Description |
|---|---|---|
| content_type | string | creative, imagevideo, preplay, demoad, document |
| unified_product_id | string | Required — the target product |
| keyword | string | Optional further keyword filter |

### Response

Same structure as `/api/data/search` response — `pageIndex`, `pageSize`, `totalSize` + `list[]` of creatives. See api-creative.md for full field documentation.

---

## 9. App Profile — 应用商店画像

`GET /api/data/app-profile?id={productId}&type=1`

Get app store profile and audience data.

| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Product ID |
| type | int | 1 | Profile type |

### Response

Returns store information, audience demographics, category rankings, etc.

---

## ⚠️ Common Pitfalls

1. **HTML tags in names:** Both `unifiedProductName` and `unifiedCompanyName` may contain `<font color='red'>keyword</font>` HTML tags when returned from search endpoints. Always strip HTML before displaying.
2. **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.
3. **ID types:** `unifiedProductId` and `unifiedCompanyId` are strings, not integers. Some may look like iOS app IDs (numeric) while others are Android package names.

---

## Common Workflow / 常用工作流

### Finding an app's full data

1. **Search** → `unified-product-search(keyword="temu")` → get `unifiedProductId`
2. **Detail** → `app-detail(id=unifiedProductId)` → full app info
3. **Creatives** → `product-content-search(unified_product_id=id, content_type="creative")` → app's ads
4. **Sub-products** → `product-list(unified_product_id=id)` → iOS/Android versions

### Finding a developer's portfolio

1. **Search** → `company-search(keyword="ByteDance")` → get `unifiedCompanyId`
2. **Detail** → `developer-detail(id=unifiedCompanyId)` → company info
3. **Products** → `product-agg-list(unified_developer_id=id)` → all their apps


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-200) |

### 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",
  "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 |
| page | int | 1 | Page number |
| page_size | int | 50 | Results per page (1-200) |
| start_date | string | 30 days ago | YYYY-MM-DD |
| end_date | string | today | YYYY-MM-DD |
| 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" |


path: references/param-mappings.md
content: # Parameter Mapping Reference / 参数映射参考表

## Creative Type (creative_team) / 创意组类型

| User says (EN) | User says (CN) | Code | Meaning |
|---|---|---|---|
| image, single image | 图片、单图 | "100" | Single image |
| double image | 双图 | "200" | Double image |
| triple image | 三图 | "300" | Triple image |
| multi-image | 多图 | "400" | Multi-image (3+) |
| video | 视频 | "010" | Video |
| playable, playable ad | 试玩、试玩广告、playable | "001" | Playable ad |
| image + video | 单图+视频 | "110" | Image + video combo |
| double image + video | 双图+视频 | "210" | Double image + video |
| video + playable | 视频+试玩 | "011" | Video + playable |
| all images | 所有图片 | ["100","200","300","400"] | All image types |

**Combination rule:** Three-digit code represents "image_count - video - playable". E.g. "110" = 1 image + video + no playable.

## Region → Country Code Mapping / 地区 → 国家代码映射

| Region (EN) | Region (CN) | Country Codes |
|---|---|---|
| Southeast Asia | 东南亚 | TH, VN, ID, MY, PH, SG, MM, KH, LA, BN |
| South Asia | 南亚 | IN, PK, BD, LK, NP, BT, MV |
| East Asia | 东亚 | JP, KR, CN, TW, HK, MO |
| Japan & Korea | 日韩 | JP, KR |
| HK/Macau/Taiwan | 港澳台 | HK, MO, TW |
| North America | 北美 | US, CA |
| United States | 美国 | US |
| Europe | 欧洲 | GB, DE, FR, IT, ES, NL, PL, SE, NO, DK, FI, AT, CH, BE, PT, IE, CZ, RO, HU, GR |
| Western Europe | 西欧 | GB, DE, FR, IT, ES, NL, BE, AT, CH, PT, IE |
| Northern Europe | 北欧 | SE, NO, DK, FI, IS |
| Middle East | 中东 | SA, AE, QA, KW, BH, OM, IL, TR, EG, JO, LB, IQ |
| Latin America | 拉美 | BR, MX, AR, CO, CL, PE, VE, EC |
| Africa | 非洲 | ZA, NG, KE, EG, GH, TZ, ET, MA |
| Oceania | 大洋洲 | AU, NZ |
| CIS/Eastern Europe | 独联体/东欧 | RU, UA, KZ, BY, UZ, GE, AZ, AM |
| Global (no filter) | 全球（无需过滤） | Omit country_ids parameter |

### Common Country Quick Reference / 常见单个国家速查

| Country (EN) | Country (CN) | Code |
|---|---|---|
| United States | 美国 | US |
| United Kingdom | 英国 | GB |
| Japan | 日本 | JP |
| South Korea | 韩国 | KR |
| India | 印度 | IN |
| Brazil | 巴西 | BR |
| Germany | 德国 | DE |
| France | 法国 | FR |
| Indonesia | 印尼 | ID |
| Thailand | 泰国 | TH |
| Vietnam | 越南 | VN |
| Philippines | 菲律宾 | PH |
| Malaysia | 马来西亚 | MY |
| Singapore | 新加坡 | SG |
| Saudi Arabia | 沙特 | SA |
| UAE | 阿联酋 | AE |
| Turkey | 土耳其 | TR |
| Australia | 澳大利亚 | AU |
| Canada | 加拿大 | CA |
| Mexico | 墨西哥 | MX |
| Russia | 俄罗斯 | RU |
| Spain | 西班牙 | ES |
| Italy | 意大利 | IT |
| Netherlands | 荷兰 | NL |
| Poland | 波兰 | PL |
| Egypt | 埃及 | EG |
| South Africa | 南非 | ZA |
| New Zealand | 新西兰 | NZ |

## Sort Options / 排序方式

| User says (EN) | User says (CN) | sort_field | sort_rule | Meaning |
|---|---|---|---|---|
| newest, by date (default) | 最新、按时间（默认） | "3" | "desc" | First seen descending |
| oldest, date ascending | 最早、时间正序 | "3" | "asc" | First seen ascending |
| most relevant, relevance | 最相关、相关性 | "11" | "desc" | By relevance |
| most popular, most impressions | 最热、曝光最多 | "15" | "desc" | Est. impressions descending |
| least impressions | 曝光最少 | "15" | "asc" | Est. impressions ascending |
| longest running | 投放最久、持续时间最长 | "4" | "desc" | Days active descending |
| shortest running | 投放最短 | "4" | "asc" | Days active ascending |

## Date Range Calculation / 时间范围计算

| User says (EN) | User says (CN) | Calculation |
|---|---|---|
| last week / last 7 days | 最近一周 / 近7天 | start_date = today - 7, end_date = today |
| last 2 weeks / last 14 days | 最近两周 / 近14天 | start_date = today - 14, end_date = today |
| last month / last 30 days (default) | 最近一个月 / 近30天（默认） | start_date = today - 30, end_date = today |
| last 3 months / last 90 days | 最近三个月 / 近90天 | start_date = today - 90, end_date = today |
| previous month | 上个月 | start_date = 1st of last month, end_date = last day of last month |
| today | 今天 | start_date = end_date = today |
| YYYY-MM-DD ~ YYYY-MM-DD | YYYY-MM-DD ~ YYYY-MM-DD | Use the exact dates provided |

**Date format:** YYYY-MM-DD (e.g. 2026-03-10)

## Page Size / 每页数量

| User says (EN) | User says (CN) | page_size |
|---|---|---|
| default | 默认 | 20 |
| show more | 多看一些 | 40 |
| maximum | 最多 | 60 (limit) |
| show fewer / brief | 少看几条 / 简要 | 10 |


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