AdMapix API Access Layer

The Problem: How to Access Programmable Raw Data from Ad Platforms?

When needing to extract raw data from an advertising platform like AdMapix for custom analysis, directly integrating with its API presents several hurdles: managing API_KEY authentication, manually assembling parameters from documentation, and handling differing response shapes across endpoints. The core requirement for engineers or data pipelines isn't another analysis tool, but a reliable data layer that returns raw, structured JSON. This enables seamless integration into custom analytics pipelines, report generators, or databases.

How It Works: A Pure API Data Access Layer

This skill is designed as a thin client whose sole responsibility is to encapsulate communication with the AdMapix Read API. It solves the data acquisition phase's pain points but never oversteps by performing analysis, summarization, or report generation on behalf of the caller (you or your Agent).

Core Workflow & Capabilities:

1. Authentication & Configuration: The skill first verifies that the environment variable ADMAPIX_API_KEY is set. If missing, it provides clear setup instructions (in English/Chinese) and halts execution. It never stores, logs, or echoes back the key, ensuring security.

2. Endpoint Routing & Invocation: It exposes a rich catalog of API endpoints, covering four primary domains:

   • Ad Creatives: Search via POST /api/data/search, get details via GET /api/data/content-detail. Note the page_size for creative search is capped at 10.
   • Apps & Companies: Perform unified searches with POST /api/data/unified-product-search, or fetch specific app info via GET /api/data/app-detail.
   • Rankings & Market: Obtain store rankings via POST /api/data/store-rank, or aggregate market data with POST /api/data/market-search.
   • Estimates: Fetch third-party estimated download and revenue figures via endpoints like /api/data/download-date.

3. Parameter Mapping: The skill natively understands references/param-mappings.md, translating natural language (e.g., "video ad", "gaming industry") into the codes the API requires (e.g., creative_type=010, trade_level1=602). For finer-grained dimensions (devices, sub-industries), it dynamically calls GET /api/data/filter-options to discover valid values.

4. Raw Output: This is the most critical point. The skill must return the API response untouched as JSON. This means: preserving all original field names (e.g., pageIndex, list), with no renaming, filtering, summarization, or added analytical commentary. An empty list ([]) is a valid "no results" response.

Scope, Boundaries, and Key Caveats

This is a data collection tool, not an analysis or decision-making tool. Understanding its boundaries is essential:

• Explicitly Out of Scope: The skill never generates HTML/H5 pages, dashboards, reports, summaries, or recommendations. It does not initiate autonomous, multi-step "deep research". Any request for analysis must be made after the raw data has been returned to the calling application.
• Error Handling: If the API returns a non-2xx status, the skill forwards the error details. A 401 INVALID_API_KEY specifically indicates an authentication issue and should prompt the user to check their configuration, not to retry.
• Nature of Data: Download and revenue figures are third-party estimates. When presenting this data, the calling agent is responsible for noting its estimated nature.
• Call Granularity: The skill is designed for one API call per request, returning the result of that single call. Complex analytical workflows (e.g., search, then fetch details, then aggregate) must be orchestrated by the caller (e.g., an Agent) through multiple consecutive invocations of this skill.

In essence, it enables engineers to collect raw ad platform data programmatically, efficiently, and securely, leaving the analytical intelligence to the higher-level application logic.