Introduction
To analyze historical keyword performance on the Google Search Engine, the Google Ads Keyword Planner online tool is a common choice. However, if you aim to leverage this data to provide customers with detailed competitor insights (as illustrated below), the Google Ads API becomes essential. Setting up the API can be somewhat challenging, so this article aims to guide you through the process.
Download and Configure the Official API Client
When working with the Google Ads API, using the official client libraries is generally recommended over making direct REST HTTP calls. You can find official API client libraries here. This guide will demonstrate using the google-ads-python library.
- Install the
google-ads-pythonmodule:
python -m pip install google-ads==21.3.0
- Create a
google-ads.yamlconfiguration file. You can use the template available here. Populate the following fields:
developer_token: INSERT_YOUR_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_YOUR_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: INSERT_PATH_TO_YOUR_JSON_KEY_FILE_HERE
# For linked customer accounts (e.g., under an MCC), you might also need:
# linked_customer_id: INSERT_LINKED_CUSTOMER_ID_HERE
-
developer_token: Your unique token for accessing the API. -
login_customer_id: The ID of the Google Ads account (often your Manager Account ID if using one) that will authorize the API calls. Do not include hyphens (-) in this ID. -
json_key_file_path: The absolute path to the JSON key file you generated for your service account.
This guide focuses on service account authentication. For this method, ensure your
google-ads.yamlfile primarily contains the three fields listed above (developer_token,login_customer_id,json_key_file_path). Other authentication fields should be removed or commented out.
- Test your setup with example code.
Update "path/to/your/google-ads.yaml" to the actual path of your configuration file.
from google.ads.googleads.client import GoogleAdsClient
# Ensure this path points to your actual 'google-ads.yaml' file.
CLIENT_CONFIG_PATH = "path/to/your/google-ads.yaml"
# Replace with the customer ID you want to query (e.g., a specific Ads account ID).
# This might be different from the login_customer_id, especially if login_customer_id is an MCC.
CUSTOMER_ID_TO_QUERY = "1234567890"
def main(client_config_path, customer_id_to_query):
try:
client = GoogleAdsClient.load_from_storage(client_config_path)
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_to_query, query=query)
print(f"Campaigns for customer ID: {customer_id_to_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.'
)
if not stream: # Check if stream yielded anything
print(f" No campaigns found for customer ID {customer_id_to_query}.")
except Exception as e:
print(f"An error occurred: {e}")
print(
"Please ensure your 'google-ads.yaml' is correctly configured, "
"the service account has access to the specified customer ID, "
"and the Google Ads API is enabled in your Google Cloud project."
)
if __name__ == "__main__":
main(CLIENT_CONFIG_PATH, CUSTOMER_ID_TO_QUERY)
Remember to replace CUSTOMER_ID_TO_QUERY with the specific Google Ads account ID (without hyphens) you wish to query.
Key Concepts: Google Ads Accounts and API
Google Ads is structured with Manager Accounts (MCCs) and individual Ads Accounts. An MCC can manage multiple Ads Accounts, providing a hierarchical structure.
For service account authentication, it’s crucial to grant the service account access to both the MCC Account (if you’re using one as your login_customer_id) and any specific Ads Accounts you intend to query or manage via the API.
Using test accounts during development is highly recommended to avoid incurring costs on live campaigns.
A service account is an important concept for API access. It’s a special type of Google account that belongs to your project instead of an individual user. It’s used to authorize programmatic access to your Google Ads account. Service accounts often require minimal configuration and fewer approval steps compared to OAuth2 user flows, making them a preferred method for server-to-server interactions.
Setting Up Authentication
1. Getting the Developer Token
- Select or create a Google Ads Manager Account (MCC).
Ensure you use an active Manager Account (i.e., not one marked as “closed”).
- Apply for Google Ads API access via the API Center.
Navigate to the API Center in your MCC. You can obtain your developer token here, as shown below.
This developer token, even if obtained via a standard MCC, can be used with test accounts.
- Copy the developer token into the
developer_tokenfield in yourgoogle-ads.yamlfile.
2. Enabling the Google Ads API in Google Cloud
Ensure you have a Google Cloud Project set up.
- Click Enable Google Ads API to activate the API for your project.
3. Creating a Service Account and JSON Key
Follow the official instructions to Create access credentials for a service account.
- During this process, you will download a JSON file containing the service account’s private key. Store this file securely.
- Update the
json_key_file_pathin yourgoogle-ads.yamlfile to point to the location of this downloaded JSON key file.
4. Granting Service Account Access to Google Ads Accounts
[!NOTE]
This step is critical. Remember to add the email address associated with your newly created service account as a user with appropriate permissions in your Google Ads MCC and/or individual Ads accounts.
Follow the guide to Grant access to the service account.
This typically involves:
- Navigating to “Account access” or “Users” settings within your Google Ads MCC or specific Ads account.
- Inviting the service account’s email address (e.g.,
your-service-account-name@your-project-id.iam.gserviceaccount.com). - Granting at least “Standard” access, or “Admin” if necessary, depending on the API operations you intend to perform.
