Google Ads API for Developers: Getting Started

The Google Ads API Landscape

The Google Ads API is the programmatic interface to Google's advertising platform -- Search, Display, YouTube, Shopping, and Performance Max campaigns. It replaced the older AdWords API in 2022 and brought a modern gRPC-based architecture with a custom query language called GAQL (Google Ads Query Language).

While the API is powerful, getting started requires significant setup. This guide walks through the prerequisites, authentication, first queries, and how Xylo can accelerate the process.

Prerequisites

Before you can make your first Google Ads API call, you need:

A Google Ads Manager (MCC) account. Individual advertiser accounts cannot directly access the API. You need a Manager account that oversees your advertiser accounts.
A Google Cloud project. The API is accessed through Google Cloud, so you need a project with the Google Ads API enabled.
OAuth 2.0 credentials. A client ID and client secret from the Google Cloud Console.
A developer token. Issued by Google after your API access application is approved. This can take days to weeks.
A refresh token. Generated through the OAuth consent flow for the Google account that manages your ads.

This is significantly more setup than most APIs. Each piece involves a different Google console, a different approval process, and different documentation.

Authentication Setup

Step 1: Create a Google Cloud Project

Go to the Google Cloud Console, create a new project, and enable the Google Ads API.

Step 2: Create OAuth 2.0 Credentials

In the Cloud Console, navigate to APIs & Services > Credentials. Create an OAuth 2.0 Client ID (type: Web Application). Note your client ID and client secret.

Step 3: Get a Developer Token

In your Google Ads Manager account, go to Tools & Settings > API Center. Apply for a developer token. Google reviews applications and may ask about your use case.

Developer token access levels:

Level	Rate Limits	Requirements
Test account	Low, test accounts only	Automatic
Basic	15,000 operations/day	Compliance review
Standard	100,000 operations/day	Advanced review

Step 4: Generate a Refresh Token

Use the OAuth 2.0 flow to generate a refresh token:

# Step 1: Get authorization URL
https://accounts.google.com/o/oauth2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/adwords&response_type=code&access_type=offline

# Step 2: Exchange auth code for tokens
curl -X POST https://oauth2.googleapis.com/token \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
  -d "grant_type=authorization_code"

The response includes a refresh_token. Store this securely -- it is used to generate access tokens for API calls.

Making Your First API Call

The Google Ads API uses gRPC (with REST fallback). The simplest way to interact with it in JavaScript/TypeScript is through the official client library:

import { GoogleAdsApi } from "google-ads-api";

const client = new GoogleAdsApi({
  client_id: process.env.GOOGLE_CLIENT_ID!,
  client_secret: process.env.GOOGLE_CLIENT_SECRET!,
  developer_token: process.env.GOOGLE_DEVELOPER_TOKEN!,
});

const customer = client.Customer({
  customer_id: "1234567890",
  refresh_token: process.env.GOOGLE_REFRESH_TOKEN!,
});

// Fetch campaigns using GAQL
const campaigns = await customer.query(`
  SELECT
    campaign.id,
    campaign.name,
    campaign.status,
    campaign.advertising_channel_type,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.conversions,
    metrics.cost_per_conversion
  FROM campaign
  WHERE campaign.status != 'REMOVED'
    AND segments.date DURING LAST_7_DAYS
  ORDER BY metrics.cost_micros DESC
`);

A few things to note:

Cost is in micros. cost_micros: 4872300 means $4.87. Divide by 1,000,000.
GAQL is required. You cannot just call an endpoint -- you write SQL-like queries. See our GAQL reference guide.
Campaign types use internal codes. SEARCH, DISPLAY, VIDEO, SHOPPING, PERFORMANCE_MAX.
Status values are uppercase. ENABLED, PAUSED, REMOVED.

The Same Query Through Xylo

All of that setup -- Cloud project, OAuth credentials, developer token, refresh token, client library, GAQL query construction -- is eliminated when using Xylo:

curl "https://api.xyloapi.dev/v1/campaigns?date_preset=last_7d" \
  -H "x-api-key: xylo_live_abc123" \
  -H "x-ad-account: customers/1234567890"

Response:

{
  "data": [
    {
      "id": "12345678901",
      "platform": "google",
      "name": "Search - Brand Terms",
      "status": "active",
      "objective": "search",
      "daily_budget": 150.00,
      "insights": {
        "impressions": 89432,
        "clicks": 12847,
        "spend": 1923.45,
        "cpc": 0.15,
        "cpm": 21.51,
        "ctr": 14.37,
        "conversions": 342,
        "cost_per_conversion": 5.62
      }
    }
  ],
  "meta": {
    "cached": false,
    "meta_api_version": "v16"
  }
}

The response format is identical to what you get from Meta campaigns. Numbers are numbers (not micros-as-integers). Status values are lowercase. No GAQL needed.

Campaign Management

Creating a Campaign

Google Ads campaign creation through the raw API requires multiple sequential operations: create a campaign budget, then the campaign, then ad groups, then ads. Each has its own endpoint and parameters.

Through Xylo:

const response = await fetch("https://api.xyloapi.dev/v1/campaigns", {
  method: "POST",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "customers/1234567890",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Search - Competitor Terms Q2",
    objective: "search",
    status: "paused",
    daily_budget: 75.00,
    bid_strategy: "maximize_conversions",
  }),
});

Updating Campaign Budget

await fetch(`https://api.xyloapi.dev/v1/campaigns/${campaignId}`, {
  method: "PATCH",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "customers/1234567890",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    daily_budget: 100.00,
    status: "active",
  }),
});

Pausing and Activating

// Pause
await fetch(`https://api.xyloapi.dev/v1/campaigns/${campaignId}`, {
  method: "PATCH",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "customers/1234567890",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ status: "paused" }),
});

Google Ads vs. Meta Ads API: Key Differences

Aspect	Google Ads API	Meta Ads API	Xylo (Both)
Protocol	gRPC + REST	REST (Graph API)	REST
Query language	GAQL (required)	Field selection	Query params
Currency format	Micros (int / 1M)	Cents (string / 100)	Dollars (number)
Auth setup	~4 credentials needed	OAuth token	Single API key
Rate limits	Operations/day	Usage percentage	Handled automatically
Campaign types	SEARCH, DISPLAY, etc.	OUTCOME_SALES, etc.	Normalized strings

The biggest practical difference is GAQL. Google requires you to learn a query language to interact with their API. Meta uses field selection parameters. Xylo abstracts both behind standard REST query parameters.

What You Can Do with Xylo + Google Ads

Pull campaign performance across Search, Display, YouTube, and Shopping campaigns
Manage budgets and bidding strategies
Pause and activate campaigns and ad groups
Read ad group and keyword performance
Cross-platform reporting with Meta and TikTok data in the same normalized format

For AI-powered Google Ads management, see our guide on Google Ads + AI Agents. For GAQL details (useful if you need raw API access), read the GAQL reference.

Getting Started

Option A: Raw Google Ads API

Create a Google Cloud project and enable the Google Ads API
Set up OAuth credentials and get a developer token
Generate a refresh token
Install the client library and write GAQL queries
Handle micros-to-dollars conversion, error parsing, and rate limits

Estimated time: 2-5 days for initial setup.

Option B: Xylo

Sign up for Xylo
Connect your Google Ads account through the dashboard
Generate an API key
Start making requests

Estimated time: 5 minutes.

Check the API documentation for the complete Google Ads endpoint reference, or explore cross-platform reporting to combine Google and Meta data in a single API.