> ## 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.

# Connecting Google Ads & Keyword Planner to YPYM DBX

> Comprehensive guide to YPYM DBX v5.3 Google Ads API v26 integration for real-time monthly search volumes, CPC bid estimates, and Keyword Planner discovery.

## Executive Overview (DBX v5.3 Release)

With the release of **YPYM DBX v5.3**, institutional-grade **Google Ads Keyword Planner** capabilities are directly embedded into your YPYM DBX workspace. You no longer need to export spreadsheets from Google Ads Keyword Planner or purchase auxiliary keyword research tools.

By connecting directly to the **Google Ads API v26** (*KeywordPlanIdeaService* and *GenerateKeywordHistoricalMetrics*), DBX unlocks complete market demand and economic search telemetry:

* **Exact Monthly Search Volumes (SV)**: Real Google query frequencies across rolling 12-month historical windows with seasonal curve detection.
* **3-Month & Year-over-Year (YoY) Growth Velocity**: Dynamic percentage trajectories indicating trending opportunities vs. declining topics.
* **Granular Competition Indices**: Normalized 0–100 difficulty scores alongside Low, Medium, and High competitive classifications.
* **Top of Page Bid Economics**: Benchmark low-range and high-range Cost-Per-Click (CPC) valuations formatted in both Indonesian Rupiah (IDR) and USD.
* **Integrated Keyword Ideas Discovery**: Generate related search phrases from seed concepts or competitor website URLs directly inside the `/research` workspace and domain `Ideas` modal, pre-calibrated to Indonesia (`Country: ID / 2360`, `Language: id / 1025`).

> [!IMPORTANT]
>
> **Assisted Enterprise Onboarding Advisory**
> The Google Ads API integration requires multi-stage authorization across Google Cloud Console (OAuth 2.0 Client ID, Client Secret, Redirect URI) and Google Ads MCC (Developer Token and 10-digit Customer Account ID).
>
> Because this procedure involves technical developer verification and Google Cloud policy governance, **we strongly recommend contacting our engineering team at `support@ypym.app` or `dev@ypym.app`** for assisted setup. Our team provides white-glove onboarding and can deploy pre-authenticated credentials directly to your client tenant partition.

![YPYM DBX Google Ads Integration Modal](https://mintcdn.com/ypymcompany/jnPr8A4nNf-pWW8z/images/platform/dbx/connect-google-ads.png?fit=max\&auto=format\&n=jnPr8A4nNf-pWW8z\&q=85\&s=f12f3414edc273f37588b6b1423e9036)

YPYM DBX Google Ads integration modal illustrating Step 1 (Google Cloud Project Client ID & Secret) and Step 2 (Developer Token & Customer Account ID) with Keyword Volume update capabilities.

***

## Architecture Overview

DBX synchronizes Google Ads intelligence through a dedicated three-stage pipeline:

```mermaid theme={null}
flowchart TD
    subgraph Step1["Stage 1: Google Cloud OAuth 2.0"]
        direction TB
        A1["Google Cloud Console: Create OAuth Client ID"] --> B1["Add Redirect URI: https://dbx.ypym.app/api/adwords"]
        B1 --> C1["DBX: Authorize Google Account Consent"]
        C1 --> D1["DBX Stores AES-256 Encrypted Refresh Token"]
    end

    subgraph Step2["Stage 2: Google Ads API Credentials"]
        direction TB
        A2["Google Ads MCC: Generate Developer Token"] --> B2["Input 10-Digit Customer Account ID"]
        B2 --> C2["Test Live Google Ads API Handshake"]
    end

    subgraph Step3["Stage 3: Keyword Planner Telemetry"]
        direction TB
        A3["Trigger 'Update Keyword Volume Data' / Research Ideas"] --> B3["Google Ads API v26 Endpoints"]
        B3 --> C3["Cache Volumes, CPC & Competition in TimescaleDB & Postgres"]
    end

    Step1 --> Step2 --> Step3

    style Step1 fill:#f8faff,stroke:#1A4BFF,stroke-width:1.5px
    style Step2 fill:#f8faff,stroke:#1A4BFF,stroke-width:1.5px
    style Step3 fill:#f8fffe,stroke:#00b4d8,stroke-width:1.5px
    style D1 fill:#1A4BFF,stroke:#1A4BFF,color:#fff
    style C2 fill:#1A4BFF,stroke:#1A4BFF,color:#fff
    style C3 fill:#00b4d8,stroke:#00b4d8,color:#fff
```

> **Stage 1: Cloud OAuth**
>
> Authenticates DBX via Google Cloud Console using client secrets and OAuth 2.0 refresh tokens.

> **Stage 2: Ads Token**
>
> Links your Google Ads MCC Developer Token and 10-digit Customer Account ID.

> **Stage 3: Volume & Ideas**
>
> Fetches real-time monthly search volume, CPC, and keyword ideas without consuming DataForSEO credits.

***

## Keyword Planner Capabilities in DBX v5.3

Once connected, your YPYM DBX instance unlocks four core capabilities:

### 1. High-Density Search Volume & Trends

In your domain's **SERP + AIO** table:

* **Search Volume (SV)**: Displays exact monthly search query volume.
* **Trend Curve**: Interactive sparklines detailing query trajectory over the past 12 months.
* **3-Month & YoY Growth Indicators**: Identifies fast-rising queries (e.g. `+120% YoY`) for immediate editorial or paid campaign prioritization.

### 2. Commercial Valuation & CPC Bids

* **Top of Page Bid (Low Range)**: Benchmark CPC for bottom page-one ad placements.
* **Top of Page Bid (High Range)**: Benchmark CPC for Top 3 ad placements.
* All monetary metrics automatically convert to your organization's primary currency (IDR benchmarked at official bank rates or USD).

### 3. Competition Index Analysis

* Granular 0–100 index assessing paid advertiser competition density.
* Categorized into standard **Low**, **Medium**, and **High** tiers to identify high-volume, low-competition organic keyword gaps.

### 4. Interactive Ideas Discovery (`/research`)

* Navigate to **Research** in the top navigation bar.
* Input a root seed keyword (e.g. `b2b marketplace indonesia`) or a competitor landing page URL.
* DBX queries the Google Ads API and generates up to 500 relevant keyword variations with volume, competition, and bid economics pre-populated.
* Click **+ Add to Domain** to instantly transition discovered keywords into active rank tracking.

***

## Technical Self-Service Setup Guide

For engineering teams wishing to self-provision their own Google Ads API credentials:

### Stage 1: Connect Google Cloud Project (OAuth 2.0)

1. Log in to the [Google Cloud Console](https://console.cloud.google.com/).
2. Select your organization project or create a project named `YPYM-DBX-Integration`.
3. Go to **APIs & Services → Library**, search for **Google Ads API**, and click **Enable**.
4. In **OAuth consent screen**:
   * Set **User Type** to **External** (or Internal for Workspace organizations).
   * Set App Name to `YPYM DBX`.
   * Add the scope:
     ```text theme={null}
     https://www.googleapis.com/auth/adwords
     ```
   * In **Test Users**, add your Google Ads login email.
5. In **Credentials → Create Credentials → OAuth client ID**:
   * Application Type: **Web application**.
   * Name: `DBX Google Ads Client`.
   * Authorized Redirect URIs:
     ```text theme={null}
     https://dbx.ypym.app/api/adwords
     ```
   * Click **Create** and copy your **Client ID** and **Client Secret**.
6. In YPYM DBX:
   * Navigate to **Settings (Gear icon) → Integrations → Google Ads**.
   * Paste the Client ID and Client Secret, then click **Connect with Google Ads**.
   * Complete Google's OAuth consent screen to store your encrypted refresh token.

***

### Stage 2: Configure Google Ads Developer Token & Account ID

1. Log in to your [Google Ads Manager (MCC) Account](https://ads.google.com/).
2. Go to **Tools and Settings → Setup → API Center**.
3. Copy your **Developer Token** (Test Account token or Basic/Standard Access token).
4. Identify your **10-digit Customer Account ID** (top-right of Google Ads dashboard, formatted `XXX-XXX-XXXX`).
5. In YPYM DBX:
   * Under Step 2 of the Google Ads settings modal, enter your Developer Token and 10-digit Customer ID (without hyphens).
   * Click **Verify & Save Credentials**.

***

### Stage 3: Synchronize Keyword Volumes

1. Open your domain dashboard.
2. In the domain action toolbar, click **Update Keyword Volume Data**.
3. DBX batches all tracked keywords, requests historical metrics from Google Ads API v26, and updates your search volume and CPC columns in real time.

***

## Support & Assisted Onboarding

Need assistance setting up your Google Cloud project or acquiring a Developer Token?

* **Email Support**: `support@ypym.app`
* **Engineering Desk**: `dev@ypym.app`
* **Response SLA**: Within 24 business hours for enterprise tenant onboarding.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.