getting-started-rest.org

Getting Started with the REST API

Overview

The Google Ads API supports two transports: gRPC (Protocol Buffers) and REST (JSON). This guide covers REST basics for read-only exploration using tools like cURL.

Reference: Working with REST Video

Transport Comparison

Aspect	REST	gRPC
Format	JSON	Protocol Buffers
Tools	cURL, any HTTP client	gRPC clients
Ease of use	Simpler to start	More efficient
Best for	Exploration, debugging	Production

For exploration purposes, REST is often easier to work with directly.

Base URL

All REST endpoints use this base URL:

https://googleads.googleapis.com/v23/

Authentication

Every request requires:

1. OAuth 2.0 Access Token - Bearer token in Authorization header
2. Developer Token - In developer-token header
3. Customer ID - In URL path (without hyphens)

Headers Required

Authorization: Bearer <access_token>
developer-token: <your_developer_token>
Content-Type: application/json

Resource Naming

Google Ads API uses hierarchical resource names:

customers/{customer_id}/campaigns/{campaign_id}
customers/{customer_id}/adGroups/{ad_group_id}
customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}

Making Requests with cURL

Search Request (Read-Only)

The primary method for exploration is GoogleAdsService.Search:

curl -X POST \
  "https://googleads.googleapis.com/v23/customers/1234567890/googleAds:search" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "developer-token: ${DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT campaign.id, campaign.name FROM campaign LIMIT 10"
  }'

SearchStream (Streaming Results)

For larger result sets:

curl -X POST \
  "https://googleads.googleapis.com/v23/customers/1234567890/googleAds:searchStream" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "developer-token: ${DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT campaign.id, campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_30_DAYS"
  }'

Response Format

Responses are JSON with this structure:

{
  "results": [
    {
      "campaign": {
        "resourceName": "customers/1234567890/campaigns/111111",
        "id": "111111",
        "name": "My Campaign"
      }
    }
  ],
  "fieldMask": "campaign.id,campaign.name",
  "requestId": "abc123"
}

List Accessible Customers

Find which accounts you can access:

curl -X GET \
  "https://googleads.googleapis.com/v23/customers:listAccessibleCustomers" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "developer-token: ${DEVELOPER_TOKEN}"

Response:

{
  "resourceNames": [
    "customers/1234567890",
    "customers/9876543210"
  ]
}

Error Handling

Errors return standard HTTP status codes with details:

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.ads.googleads.v23.errors.GoogleAdsFailure",
        "errors": [
          {
            "errorCode": {
              "queryError": "INVALID_SELECT_CLAUSE"
            },
            "message": "Invalid field in SELECT clause"
          }
        ]
      }
    ]
  }
}

Pagination

For Search (not SearchStream), handle pagination:

# First request
curl -X POST \
  "https://googleads.googleapis.com/v23/customers/1234567890/googleAds:search" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "developer-token: ${DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT campaign.id FROM campaign",
    "pageSize": 100
  }'

# Subsequent requests with pageToken
curl -X POST \
  "https://googleads.googleapis.com/v23/customers/1234567890/googleAds:search" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "developer-token: ${DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT campaign.id FROM campaign",
    "pageSize": 100,
    "pageToken": "<token_from_previous_response>"
  }'

Environment Setup

Create a shell script for common variables:

#!/bin/bash
# env.sh - Source this before making API calls

export CUSTOMER_ID="1234567890"
export DEVELOPER_TOKEN="your-developer-token"

# Get access token (requires gcloud auth)
export ACCESS_TOKEN=$(gcloud auth print-access-token)

Usage:

source env.sh

curl -X POST \
  "https://googleads.googleapis.com/v23/customers/${CUSTOMER_ID}/googleAds:search" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "developer-token: ${DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT campaign.id, campaign.name FROM campaign LIMIT 5"}'

Tools

Tool	Purpose
API Explorer	Interactive REST exploration
Query Builder	Build GAQL queries
Query Validator	Validate GAQL syntax

Resources

• REST Overview
• REST Authentication
• Search Method Reference