AdMapix Data Layer

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

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

Auth

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

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

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

Step 1 — Check the key

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

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

Step 2 — If missing, show the setup guide

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

中文用户：

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

1. 打开 https://www.admapix.com 注册账号
2. 登录后在控制台找到 API Keys，创建一个 Key
3. 选择一种方式配置：
   • OpenClaw / ClawHub：在终端运行 openclaw config set skills.entries.admapix.apiKey "你的_API_KEY"
   • 通用环境变量：在终端运行 export ADMAPIX_API_KEY="你的_API_KEY"
4. 配置完成后重新发起查询 ✅

English users:

🔑 You need an AdMapix API Key to get started:

1. Sign up at https://www.admapix.com
2. After signing in, open API Keys in your dashboard and create one
3. Configure it one of these ways:
   • OpenClaw / ClawHub: run openclaw config set skills.entries.admapix.apiKey "YOUR_API_KEY" in your terminal
   • Generic env var: run export ADMAPIX_API_KEY="YOUR_API_KEY" in your terminal
4. Re-run your query after setup ✅

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

Endpoint Catalog

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

Creatives / ads — references/api-creative.md

| Endpoint | Method | Purpose | |---|---|---| | /api/data/search | POST | Search ad creatives | | /api/data/count | POST | Count creatives for a query | | /api/data/count-all | POST | Counts broken down by dimension | | /api/data/distribute | POST | Creative distribution breakdown | | /api/data/distribute-dims | GET | Available distribute dimensions | | /api/data/content-detail | GET | Single creative detail (related=imagevideo|trend) | | /api/data/item-apps | POST | Apps associated with a creative | | /api/data/screen-types | GET | Screen / element type codes | | /api/data/page-config | GET | Search page config |

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

| Endpoint | Method | Purpose | |---|---|---| | /api/data/filter-options | GET | All filter metadata: countries, mediaChannels, adTypes, device, tradeLevel(Tree), productModel, etc. Pull this to discover valid codes for any filter. |

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

| Endpoint | Method | Purpose | |---|---|---| | /api/data/unified-product-search | POST | Unified app/product search | | /api/data/product-search | POST | Product search | | /api/data/company-search | POST | Developer / company search | | /api/data/app-detail | GET | App detail by unifiedProductId | | /api/data/developer-detail | GET | Developer detail | | /api/data/app-profile | GET | App profile | | /api/data/similar-apps | POST | Similar apps | | /api/data/sdk-detail | GET | SDKs used by a package | | /api/data/product-content-search | POST | Creatives for a product | | /api/data/product-content-counts | POST | Creative counts for a product | | /api/data/product-list, /for-product-list, /product-agg-list | POST | Product lists / aggregations |

Rankings — references/api-ranking.md

| Endpoint | Method | Purpose | |---|---|---| | /api/data/store-rank | POST | App-store rankings (free / paid / grossing) | | /api/data/generic-rank | POST | Generic ranking lists | | /api/data/store-categories | GET | Store category codes | | /api/data/store-countries | GET | Store country codes |

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

| Endpoint | Method | Purpose | |---|---|---| | /api/data/download-date, download-detail, download-country | GET/POST | Download estimates by date / detail / country | | /api/data/revenue-date, revenue-detail, revenue-country | GET/POST | Revenue estimates by date / detail / country |

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

Distribution — references/api-distribution.md

| Endpoint | Method | Purpose | |---|---|---| | /api/data/app-distribution | POST | App-level distribution | | /api/data/global-promote | POST | Global promotion data |

Market — references/api-market.md

| Endpoint | Method | Purpose | |---|---|---| | /api/data/market-search | POST | Market-level search / aggregation |

Parameter Mapping

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

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

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

Output Rules

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

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

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

Error Handling

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

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

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

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