> ## Documentation Index
> Fetch the complete documentation index at: https://hub.ypym.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Mapping

> Keyword research and competitive intelligence platform for search authority engineering by YPYM.

## Overview

YPYM Keywords is a restricted-access keyword research and competitive intelligence platform. It powers the data layer behind YPYM's SEO service engagements, from market entry keyword mapping to Pre-IPO search authority audits.

Unlike generic keyword tools, YPYM Keywords is calibrated for **Indonesia and Southeast Asian markets**, with deep IDX sector coverage and YMYL-specific query intelligence.

<Warning>
  YPYM Keywords is a restricted-access product. For demo access, please email [research@ypym.app](mailto:research@ypym.app).

  Live instance: [query-mapping.ypym.app](https://query-mapping.ypym.app/)
</Warning>

## Core Capabilities

<ParamField body="keyword" type="string" required>
  The seed keyword or phrase to research. Supports Bahasa Indonesia, English, and mixed-language queries.
</ParamField>

<ParamField body="market" type="string" default="id">
  Target market for search volume and competition data. Supported: `id` (Indonesia), `sg`, `my`, `th`, `ph`, `vn`, `global`.
</ParamField>

<ParamField body="sector" type="string">
  IDX sector filter for industry-specific keyword intelligence. Examples: `IDXFINANCE`, `IDXHEALTH`, `IDXENERGY`, `IDXTECHNO`.
</ParamField>

<ParamField body="intent" type="string" default="all">
  Filter by search intent classification. Options: `informational`, `navigational`, `commercial`, `transactional`, `all`.
</ParamField>

<ParamField body="depth" type="string" default="standard">
  Analysis depth. `standard` returns volume and competition. `deep` adds SERP feature analysis, competitor mapping, and content gap scoring.
</ParamField>

<ParamField body="ymyl_flag" type="boolean" default="false">
  Enable YMYL (Your Money Your Life) compliance scoring for finance, health, legal, and government-related keywords.
</ParamField>

## Feature Matrix

| Feature                        | Description                                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Search Volume Intelligence** | Localised monthly search volume with seasonal trend data for ID and SEA markets                      |
| **Competition Scoring**        | Proprietary difficulty score calibrated against actual SERP composition, not generic estimates       |
| **SERP Feature Mapping**       | Identifies featured snippets, PAA, knowledge panels, local packs, and AI overviews per keyword       |
| **Intent Classification**      | Automated search intent scoring: informational, navigational, commercial, transactional              |
| **IDX Sector Mapping**         | Maps keywords to Indonesia Stock Exchange sector classifications for business intelligence alignment |
| **YMYL Scoring**               | Flags keywords under Google's elevated quality thresholds with E-E-A-T requirement signals           |
| **Competitor Gap Analysis**    | Identifies keyword opportunities where competitors rank but the target domain does not               |
| **Content Cluster Engine**     | Groups keywords into topical authority clusters for content strategy planning                        |

## Response Fields

<ParamField body="keyword" type="string">
  The queried keyword.
</ParamField>

<ParamField body="search_volume" type="integer">
  Monthly search volume in the target market.
</ParamField>

<ParamField body="competition" type="float">
  Competition score from 0.0 (low) to 1.0 (extremely competitive).
</ParamField>

<ParamField body="intent" type="string">
  Classified search intent.
</ParamField>

<ParamField body="serp_features" type="array">
  SERP features present for this keyword (e.g., featured\_snippet, people\_also\_ask, local\_pack, ai\_overview).
</ParamField>

<ParamField body="ymyl_score" type="float">
  YMYL compliance risk score from 0.0 to 1.0. Only present when `ymyl_flag` is enabled.
</ParamField>

## Access

<CardGroup cols={2}>
  <Card title="Live Instance" icon="lock" href="https://query-mapping.ypym.app/">
    Restricted access: password required
  </Card>

  <Card title="Request Demo" icon="envelope" href="mailto:research@ypym.app">
    Email [research@ypym.app](mailto:research@ypym.app) for demo credentials
  </Card>
</CardGroup>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://query-mapping.ypym.app/api/research \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "keyword": "jasa seo jakarta",
      "market": "id",
      "sector": "IDXTECHNO",
      "intent": "commercial",
      "depth": "deep",
      "ymyl_flag": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://query-mapping.ypym.app/api/research",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        keyword: "jasa seo jakarta",
        market: "id",
        sector: "IDXTECHNO",
        intent: "commercial",
        depth: "deep",
        ymyl_flag: false
      })
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://query-mapping.ypym.app/api/research",
      headers={
          "Authorization": "Bearer <token>",
          "Content-Type": "application/json"
      },
      json={
          "keyword": "jasa seo jakarta",
          "market": "id",
          "sector": "IDXTECHNO",
          "intent": "commercial",
          "depth": "deep",
          "ymyl_flag": False
      }
  )
  data = response.json()
  print(data)
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "keyword": "jasa seo jakarta",
    "market": "id",
    "search_volume": 2400,
    "competition": 0.72,
    "intent": "commercial",
    "trend": [1800, 2100, 2200, 2400, 2600, 2400, 2300, 2400, 2500, 2400, 2200, 2400],
    "serp_features": [
      "local_pack",
      "people_also_ask",
      "site_links",
      "ai_overview"
    ],
    "sector": "IDXTECHNO",
    "related_keywords": [
      {
        "keyword": "jasa seo profesional",
        "volume": 880,
        "competition": 0.65
      },
      {
        "keyword": "agency seo indonesia",
        "volume": 1200,
        "competition": 0.78
      },
      {
        "keyword": "harga jasa seo",
        "volume": 720,
        "competition": 0.58
      }
    ],
    "content_clusters": [
      {
        "cluster": "SEO Agency Services",
        "keywords": 24,
        "total_volume": 8400
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": "unauthorized",
    "message": "Invalid or expired token. Contact research@ypym.app for access."
  }
  ```
</ResponseExample>