This guide requires several prerequisite settings that were configured in previous steps. Start with Introduction if you haven't done so.
This guide also uses refresh tokens, a workflow where a user with sufficient access to the Google Ads account can authorize your app, in a one-time setup, to make offline API calls to the account without any further user intervention. You can use refresh tokens to build both offline workflows, such as cron jobs or data pipelines, and interactive workflows, such as web or mobile apps.
Fetch a refresh token
The Google Ads API uses OAuth 2.0 as the authorization mechanism. By default, OAuth 2.0 authentication issues an access token that expires after a limited time. To renew the access token automatically, you should issue a refresh token instead.
Generate the refresh token by running the oauth2l tool:
oauth2l fetch --credentials credentials.json --scope adwords \ --output_format refresh_token
The
credentials.json
file is from a previous step.The
oauth2l
command opens a Google Account login window in a new browser window and takes you through the OAuth 2.0 authentication steps.Make sure you sign in using the email address from the step where you identified your login customer ID.
If your app is unverified, you might see a warning screen. In such cases, it's safe to click the Show Advanced link and click the Go to PROJECT_NAME (unverified) option.
After you verify the scopes, grant the permission by clicking the Continue button.
A prompt is displayed in the browser with the following text:
Authorization code granted. Please close this tab.
The
oauth2l
command outputs the following JSON snippet:{ "client_id": "******.apps.googleusercontent.com", "client_secret": "******", "token_uri": "https://oauth2.googleapis.com/token", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "refresh_token": "******", "type": "authorized_user" }
Make an API call
Select your client of choice for instructions on how to make an API call:
Java
The client library artifacts are published to the Maven central repository. Add the client library as a dependency to your project as follows:
The Maven dependency is:
<dependency>
<groupId>com.google.api-ads</groupId>
<artifactId>google-ads</artifactId>
<version>33.0.0</version>
</dependency>
The Gradle dependency is:
implementation 'com.google.api-ads:google-ads:33.0.0'
Create a file ~/ads.properties
with the following content:
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
Create a GoogleAdsClient
object as follows:
GoogleAdsClient googleAdsClient = null;
try {
googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
System.err.printf(
"Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
fnfe);
System.exit(1);
} catch (IOException ioe) {
System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
System.exit(1);
}
Next, run a campaign report using the
GoogleAdsService.SearchStream
method to retrieve the campaigns in your account. This guide doesn't cover the
details of reporting.
private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
// Constructs the SearchGoogleAdsStreamRequest.
SearchGoogleAdsStreamRequest request =
SearchGoogleAdsStreamRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.setQuery(query)
.build();
// Creates and issues a search Google Ads stream request that will retrieve all campaigns.
ServerStream<SearchGoogleAdsStreamResponse> stream =
googleAdsServiceClient.searchStreamCallable().call(request);
// Iterates through and prints all of the results in the stream response.
for (SearchGoogleAdsStreamResponse response : stream) {
for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
System.out.printf(
"Campaign with ID %d and name '%s' was found.%n",
googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
}
}
}
}
C#
The client library packages are published to the Nuget.org
repository. Start by adding a
nuget reference to Google.Ads.GoogleAds
package.
dotnet add package Google.Ads.GoogleAds --version 18.1.0
Create a GoogleAdsConfig
object with the relevant settings, and use it to
create a GoogleAdsClient
object.
GoogleAdsConfig config = new GoogleAdsConfig()
{
DeveloperToken = "******",
OAuth2Mode = "APPLICATION",
OAuth2ClientId = "******.apps.googleusercontent.com",
OAuth2ClientSecret = "******",
OAuth2RefreshToken = "******",
LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);
Next, run a campaign report using the
GoogleAdsService.SearchStream
method to retrieve the campaigns in your account. This guide doesn't cover the
details of reporting.
public void Run(GoogleAdsClient client, long customerId)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V17.GoogleAdsService);
// Create a query that will retrieve all campaigns.
string query = @"SELECT
campaign.id,
campaign.name,
campaign.network_settings.target_content_network
FROM campaign
ORDER BY campaign.id";
try
{
// Issue a search request.
googleAdsService.SearchStream(customerId.ToString(), query,
delegate (SearchGoogleAdsStreamResponse resp)
{
foreach (GoogleAdsRow googleAdsRow in resp.Results)
{
Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
}
}
);
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
PHP
The client library packages are published to the Packagist
repository. Change into
the root directory of your project and run the following command to install
the library and all its dependencies in the vendor/
directory of your
project's root directory.
composer require googleads/google-ads-php:22.0.0
Make a copy of the
google_ads_php.ini
file from the GitHub repository and modify it to include your credentials.
[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"
Create an instance of GoogleAdsClient
object.
$oAuth2Credential = (new OAuth2TokenBuilder())
->fromFile('/path/to/google_ads_php.ini')
->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
->fromFile('/path/to/google_ads_php.ini')
->withOAuth2Credential($oAuth2Credential)
->build();
Next, run a campaign report using the
GoogleAdsService.SearchStream
method to retrieve the campaigns in your account. This guide doesn't cover the
details of reporting.
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves all campaigns.
$query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
// Issues a search stream request.
/** @var GoogleAdsServerStreamDecorator $stream */
$stream = $googleAdsServiceClient->searchStream(
SearchGoogleAdsStreamRequest::build($customerId, $query)
);
// Iterates over all rows in all messages and prints the requested field values for
// the campaign in each row.
foreach ($stream->iterateAllElements() as $googleAdsRow) {
/** @var GoogleAdsRow $googleAdsRow */
printf(
"Campaign with ID %d and name '%s' was found.%s",
$googleAdsRow->getCampaign()->getId(),
$googleAdsRow->getCampaign()->getName(),
PHP_EOL
);
}
}
Python
The client library is distributed on PyPI
can be installed using the pip
command
as follows:
python -m pip install google-ads==21.3.0
Make a copy of the google-ads.yaml
file from the GitHub repository and modify it to include your credentials.
client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
Create a GoogleAdsClient
instance by calling the
GoogleAdsClient.load_from_storage
method. Pass the path to your
google-ads.yaml
as a string to the method when calling it:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")
Next, run a campaign report using the
GoogleAdsService.SearchStream
method to retrieve the campaigns in your account. This guide doesn't cover the
details of reporting.
def main(client, customer_id):
ga_service = client.get_service("GoogleAdsService")
query = """
SELECT
campaign.id,
campaign.name
FROM campaign
ORDER BY campaign.id"""
# Issues a search request using streaming.
stream = ga_service.search_stream(customer_id=customer_id, query=query)
for batch in stream:
for row in batch.results:
print(
f"Campaign with ID {row.campaign.id} and name "
f'"{row.campaign.name}" was found.'
)
Ruby
The Ruby gems for the client library are published to the Rubygems gem hosting site. The recommended way to install is using bundler. Add a line to your Gemfile:
gem 'google-ads-googleads', '~> 30.0.0'
Then run:
bundle install
Make a copy of the
google_ads_config.rb
file from the GitHub repository and modify it to include your credentials.
Google::Ads::GoogleAds::Config.new do |c|
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end
Create a GoogleAdsClient
instance by passing the path to where you keep this
file.
client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')
Next, run a campaign report using the
GoogleAdsService.SearchStream
method to retrieve the campaigns in your account. This guide doesn't cover the
details of reporting.
def get_campaigns(customer_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
responses = client.service.google_ads.search_stream(
customer_id: customer_id,
query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
)
responses.each do |response|
response.results.each do |row|
puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
end
end
end
Perl
The library is distributed on
CPAN. Start by cloning the
google-ads-perl
repository in the directory of your choice.
git clone https://github.com/googleads/google-ads-perl.git
Change into the google-ads-perl
directory and run the following command at
the command prompt to install all dependencies needed for using the library.
cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps
Make a copy of the
googleads.properties
file from the GitHub repository and modify it to include your credentials.
clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
Create a Client
instance by passing the path to where you keep this file.
my $properties_file = "/path/to/googleads.properties";
my $api_client = Google::Ads::GoogleAds::Client->new({
properties_file => $properties_file
});
Next, run a campaign report using the
GoogleAdsService.SearchStream
method to retrieve the campaigns in your account. This guide doesn't cover the
details of reporting.
sub get_campaigns {
my ($api_client, $customer_id) = @_;
# Create a search Google Ads stream request that will retrieve all campaigns.
my $search_stream_request =
Google::Ads::GoogleAds::V17::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
->new({
customerId => $customer_id,
query =>
"SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $search_stream_handler =
Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
service => $google_ads_service,
request => $search_stream_request
});
# Issue a search request and process the stream response to print the requested
# field values for the campaign in each row.
$search_stream_handler->process_contents(
sub {
my $google_ads_row = shift;
printf "Campaign with ID %d and name '%s' was found.\n",
$google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
});
return 1;
}
REST
Start by using an HTTP client to fetch an OAuth 2.0 access token. This guide
uses the curl
command.
curl \
--data "grant_type=refresh_token" \
--data "client_id=CLIENT_ID" \
--data "client_secret=CLIENT_SECRET" \
--data "refresh_token=REFRESH_TOKEN" \
https://www.googleapis.com/oauth2/v3/token
Next, run a campaign report using the
GoogleAdsService.SearchStream
method to retrieve the campaigns in your account. This guide doesn't cover the
details of reporting.
curl -i -X POST https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/googleAds:searchStream \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "developer-token: DEVELOPER_TOKEN" \
-H "login-customer-id: LOGIN_CUSTOMER_ID" \
--data-binary "@query.json"
The contents of query.json
are as follows:
{
"query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}