Page Summary
-
This guide demonstrates direct calls to REST endpoints using bash and curl.
-
Prerequisites include a developer token, test account access, a Google Ads manager account with a client account, and environment variable setup.
-
The guide covers search functionality, including both paginated and streaming methods.
-
Examples are provided for mutate operations, such as creating, updating, and removing objects, including handling partial failures and grouped operations.
-
Account management examples include creating new accounts, listing accessible accounts, and uploading binary assets.
This guide contains examples of calling the REST endpoints directly, without the use of a client library.
The scripts in this guide are in the REST code examples
GitHub repository, including the
rest_guide directory.
To view the request and response bodies for each API method, refer to the reference documentation for specific service endpoints.
For example, the reference page for GoogleAdsService.Search
shows the request and response bodies for the Search method.
Prerequisites
All the samples shown here are meant to be copy-and-pasted into a bash shell using the curl command.
You also need a Google Cloud project, test account access is fine, and a Google Ads manager account containing at least one client account.
Environment variables
Enter account credentials and IDs as shown, and then copy-and-paste into your terminal to configure the environment variables used in the subsequent examples. The Authorization guide provides instructions for generating an OAuth 2.0 access token.
API_VERSION="26"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"Additional optional object IDs
Some of the following examples work on pre-existing budgets or campaigns. If you have IDs of existing objects to use with these examples, enter them as shown.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_IDOtherwise, the two Mutates - Creates examples create a new budget and campaign.
Search
The Query Cookbook guide contains many reporting samples that correspond to some of the default Google Ads screens and work with the same environment variables used in this guide. Our interactive query builder tool is also a great resource for building custom queries interactively.
Paginated
The search method uses pagination, with a fixed page size of 10,000 items and
a page_token specified alongside the query.
For the first request, leave PAGE_TOKEN empty. To get the next page, set
PAGE_TOKEN to the nextPageToken value from the previous response, and then
run the request again.
PAGE_TOKEN=""curl
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token": "${PAGE_TOKEN}" } EOF
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Streaming
The searchStream method streams all results in a single response, thus, the
pageSize field is not supported.
curl
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<'EOF' { "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " } EOF
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Mutates
Multiple mutate operations (create, update, or remove) can be sent in a
single JSON request body by populating the operations array.
Creates
This example creates two shared campaign budgets in a single request.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "name": "My Campaign Budget #${RANDOM}", "amountMicros": 500000 } }, { "create": { "name": "My Campaign Budget #${RANDOM}", "amountMicros": 500000 } } ] } EOF
The next example uses a BUDGET_ID of an existing campaign budget; you can
copy-and-paste from the previous step's output.
BUDGET_ID=BUDGET_IDResources that refer to other resources do so by resource name.
The campaign created in the following example refers to a campaignBudget by
its string-valued resource name.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "status": "PAUSED", "advertisingChannelType": "SEARCH", "geoTargetTypeSetting": { "positiveGeoTargetType": "PRESENCE_OR_INTEREST", "negativeGeoTargetType": "PRESENCE" }, "name": "My Search campaign #${RANDOM}", "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}", "targetSpend": {}, "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING" } } ] } EOF
Updates
Update attributes of existing objects using update operations. The next
example uses an existing campaign; you can copy-and-paste from the previous
step's output.
CAMPAIGN_ID=CAMPAIGN_IDAll updates require an updateMask field, a comma-separated list of which JSON
attributes should be in the request, that should be applied as an update.
Attributes listed in the updateMask but not present in the request body are
cleared on an object. Attributes not listed in the updateMask, but present
in the request body, are ignored.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "update": { "resourceName": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}", "name": "A changed campaign name #${RANDOM}" }, "updateMask": "name" } ] } EOF
Removes
Objects are removed by specifying their resource name as a remove operation.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "remove": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}" } ] } EOF
Partial failures
When multiple operations are in a single request, optionally specify
partialFailure. If true, successful operations are carried out and invalid
operations return errors. If false, all operations in the request succeed if
and only if they are all valid.
The next example uses an existing campaign; you can copy-and-paste from the Creates example output.
CAMPAIGN_ID=CAMPAIGN_IDThe following request contains two operations: the first disables enhanced CPC
on the specified campaign, and the second attempts to remove a campaign with an
invalid ID. Because the partialFailure field is set to true, the first
operation succeeds while the response returns the error for the invalid second
operation in the partialFailureError field.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "partialFailure": true, "operations": [ { "update": { "resourceName": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}", "manualCpc": { "enhancedCpcEnabled": false } }, "updateMask": "manual_cpc.enhanced_cpc_enabled" }, { "remove": "customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID" } ] } EOF
Grouped operations
The googleAds:mutate method supports sending groups of operations with
multiple types of resources. You can send many operations of different types to
chain together a sequence of operations that should be carried out as a group.
The set of operations succeeds if no operation fails or all fail if any single
operation fails.
This example demonstrates creating a campaign budget, campaign, ad group, and ad together as a single set of actions. Each successive operation depends on the previous one. If one fails, the entire group of operations fails.
Negative integers (-1, -2, -3) are used as placeholders in the resource
names and are filled dynamically at runtime with the results from the sequence
of operations.
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "mutateOperations": [ { "campaignBudgetOperation": { "create": { "resourceName": "customers/${CUSTOMER_ID}/campaignBudgets/-1", "name": "My Campaign Budget #${RANDOM}", "deliveryMethod": "STANDARD", "amountMicros": 500000, "explicitlyShared": false } } }, { "campaignOperation": { "create": { "resourceName": "customers/${CUSTOMER_ID}/campaigns/-2", "status": "PAUSED", "advertisingChannelType": "SEARCH", "geoTargetTypeSetting": { "positiveGeoTargetType": "PRESENCE_OR_INTEREST", "negativeGeoTargetType": "PRESENCE" }, "name": "My Search campaign #${RANDOM}", "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/-1", "targetSpend": {}, "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING" } } }, { "adGroupOperation": { "create": { "resourceName": "customers/${CUSTOMER_ID}/adGroups/-3", "campaign": "customers/${CUSTOMER_ID}/campaigns/-2", "name": "My ad group #${RANDOM}", "status": "PAUSED", "type": "SEARCH_STANDARD" } } }, { "adGroupAdOperation": { "create": { "adGroup": "customers/${CUSTOMER_ID}/adGroups/-3", "status": "PAUSED", "ad": { "responsiveSearchAd": { "headlines": [ { "pinnedField": "HEADLINE_1", "text": "An example headline" }, { "text": "Another example headline" }, { "text": "Yet another headline" } ], "descriptions": [ { "text": "An example description" }, { "text": "Another example description" } ], "path1": "all-inclusive", "path2": "deals" }, "finalUrls": [ "https://www.example.com" ] } } } } ] } EOF
Account management
You can create accounts, list accessible accounts, and upload binary assets.
Create accounts
Create new accounts using the createCustomerClient method. Note that the URL
requires a manager account ID instead of a client account ID. A new client
account is created under the manager account.
curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "customerClient": { "descriptiveName": "Account created with CustomerService #${RANDOM}", "currencyCode": "USD", "timeZone": "America/New_York" } } EOF
List accessible accounts
Use a simple GET request to the listAccessibleCustomers method to get a list
of Google Ads accounts accessible with the given OAuth 2.0 access token. No manager
or client account IDs should be used in this request.
curl -f --request GET \ "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"
Upload binary assets
Use the assets:mutate method to upload and manage assets. Encode
binary data, such as an image, as a base64 string. The API accepts standard or
URL-safe base64 encoding with or without padding.
This example encodes a 1-pixel GIF image to keep the
payload concise. In practice, data payloads are much larger. Download the
image and use the base64 command-line utility to encode it:
curl -sLO https://developers.google.com/google-ads/api/images/1pixel.gif
IMAGE_CONTENT="$(base64 < 1pixel.gif | tr -d '[:space:]')"Send the base64-encoded value in the data field of an assets:mutate
request:
curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "imageAsset": { "data": "${IMAGE_CONTENT}" }, "name": "Marketing Image" } } ] } EOF