Get Started with Google Ads API — Keyword Planning & Campaign Retrieval

The title pretty much summarizes it. In this article, I will demonstrate how to use the Google Ads API to-

• Generate keyword ideas
• Retrieve historical metrics for given keywords
• Fetch a list of campaigns from a Google Ads account

Courtesy- Freepik, DesignEasy

Why Use the Google Ads API?

If you’re new to marketing or only need to perform a few tasks — such as finding the right keywords for your website’s SEO or running occasional campaigns — you probably don’t need the API. The Google Ads Manager UI should suffice.

However, if you need to manage operations at scale using automation or want to build a custom workflow for your clients/customers, the Google Ads API is essential. For instance, I built this tool using Google APIs: GrowEasy Google Keyword Ideas Generator.

Prerequisites for Using Google Ads API

To access and use the Google Ads API, you’ll need a few things. Fortunately, many tutorials are available to help you get started. Below is a summary:

1. Create a Manager Account (different from an Ad account): Google Ads Manager Account allows you to view and manage multiple Google Ads accounts, including other manager accounts, from a single location. It enables you to create and manage campaigns, compare performance, etc.
2. Link Your Ad Account (Google Ads Client Account) to This Manager Account: Instructions
3. Obtain a Developer Token: This token allows your app to connect to the Google Ads API. Get Started Here
4. Apply for Basic Access
5. Set Up a Google API Console Project: This project will be used to generate OAuth 2.0 credentials for your app. Check Google API Console Setup
6. Enable the Google Ads API in Your Project
7. Obtain a Refresh Token: How to Get a Refresh Token

Once you have your refresh token, you can generate an access token using the following cURL command:

curl --location 'https://www.googleapis.com/oauth2/v3/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=YOUR_CLIENT_ID.apps.googleusercontent.com' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'refresh_token=YOUR_REFRESH_TOKEN'

The response will look like this:

{
  "access_token": "ACCESS_TOKEN_GOES_HERE",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/adwords https://www.googleapis.com/auth/youtube",
  "token_type": "Bearer"
}

Generate Keyword Ideas Using Google Ads API

Keyword research is essential for SEO and Google Search campaigns. Below is a cURL command to get started with generating keyword ideas using the Google Ads API. You can provide keyword seeds or URL seeds to generate ideas and set targeting parameters like locations, language, and network settings to refine your search.

curl --location 'https://googleads.googleapis.com/v18/customers/CUSTOMER_ID:generateKeywordIdeas' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'developer-token: YOUR_DEVELOPER_TOKEN' \
--header 'login-customer-id: MCC_ACCOUNT_ID' \
--data '{
  "geoTargetConstants": ["geoTargetConstants/2356"],
  "language": "languageConstants/1000",
  "keywordPlanNetwork": "GOOGLE_SEARCH",
  "keywordSeed": {
    "keywords": ["AI marketing", "digital advertising"]
  }
}'

Example response:

{
  "results": [
    {
      "keywordIdeaMetrics": {
        "competition": "MEDIUM",
        "monthlySearchVolumes": [
          {
            "month": "JANUARY",
            "year": "2024",
            "monthlySearches": "3600"
          }
        ],
        "avgMonthlySearches": "2400",
        "competitionIndex": "36",
        "lowTopOfPageBidMicros": "19780561",
        "highTopOfPageBidMicros": "85688212"
      },
      "text": "ai marketing",
      "closeVariants": ["AI marketing"]
    }
  ],
  "totalSize": "1143"
}

Parameters Explained

1. **CUSTOMER_ID**: Your Google Ads client account ID. You can find it in the top-right corner of the Google Ads Manager.
2. **ACCESS_TOKEN: An OAuth access token generated using a refresh token. It expires after 1 hour**, so automate its generation using the refresh token (which doesn’t expire unless revoked by the user).
3. **YOUR_DEVELOPER_TOKEN**: A token obtained for your MCC (Manager Customer Center) account after approval from Google.
4. **MCC_ACCOUNT_ID**: Your Manager Account ID.
5. **geoTargetConstants/2356**: Geo-target code for India. For the US, use geoTargetConstants/2840. You can pass multiple targeting locations (optional).
6. **languageConstants/1000**: Language code for English. This is another targeting parameter (optional).
7. **keywordPlanNetwork**: Possible values are GOOGLE_SEARCH and GOOGLE_SEARCH_AND_PARTNERS.
8. **keywordSeed**: Seed keywords for generating ideas.

Generate Keywords Relevant to Your Website

If you want keywords relevant to your website, use the following payload:

{
  "geoTargetConstants": ["geoTargetConstants/2356"],
  "language": "languageConstants/1000", 
  "keywordPlanNetwork": "GOOGLE_SEARCH",
  "keywordAndUrlSeed": {
    "keywords": ["AI marketing", "digital advertising"],
    "url": "https://groweasy.ai"
  }
}

For more details, refer to the official Google Ads API documentation: Generate Keyword Ideas

Generate Keyword Historical Metrics Using the Google Ads API

Historical metrics provide insights into how keywords have performed on Google Search in the past. These metrics include:

• Average monthly searches (past 12 months)
• Approximate monthly search volume (per month)
• Competition level (e.g., LOW, MEDIUM, HIGH)
• Top-of-page bid estimates (low and high range)

Use the cURL command below to get started.

curl --location 'https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/:generateKeywordHistoricalMetrics' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'developer-token: YOUR_DEVELOPER_TOKEN' \
--header 'Content-Type: application/json' \
--header 'login-customer-id: MCC_ACCOUNT_ID' \
--data '{
    "geoTargetConstants": [
        "geoTargetConstants/2840"
    ],
    "language": "languageConstants/1000",
    "keywordPlanNetwork": "GOOGLE_SEARCH",
    "keywords": [
        "AI marketing",
        "digital advertising"
    ]
}'

Example Response

{
  "results": [
    {
      "text": "ai marketing",
      "keywordMetrics": {
        "competition": "MEDIUM",
        "monthlySearchVolumes": [
          {
            "month": "JANUARY",
            "year": "2025",
            "monthlySearches": "5400"
          }
        ],
        "avgMonthlySearches": "4400",
        "competitionIndex": "55",
        "lowTopOfPageBidMicros": "462144312",
        "highTopOfPageBidMicros": "1712448437"
      },
      "closeVariants": [
        "AI marketing"
      ]
    },
    {
      "text": "digital advertising",
      "keywordMetrics": {
        "competition": "LOW",
        "monthlySearchVolumes": [
          {
            "month": "FEBRUARY",
            "year": "2024",
            "monthlySearches": "9900"
          }
        ],
        "avgMonthlySearches": "8100",
        "competitionIndex": "15",
        "lowTopOfPageBidMicros": "471681999",
        "highTopOfPageBidMicros": "1853779624"
      }
    }
  ]
}

Key Metrics in the Response

1. **text**: The keyword for which metrics are provided.
2. **competition**: Competition level (LOW, MEDIUM, HIGH).
3. **monthlySearchVolumes**: Monthly search volumes for the past 12 months.
4. **avgMonthlySearches**: Average monthly searches over the past 12 months.
5. **competitionIndex**: Competition index (0–100), indicating how competitive the keyword is.
6. **lowTopOfPageBidMicros**: Low range bid estimate for the top-of-page ad position.
7. **highTopOfPageBidMicros**: High range bid estimate for the top-of-page ad position.
8. **closeVariants**: Close variants of the keyword.

For more details, refer to the official Google Ads API documentation: Generate Historical Metrics

Retrieve Campaigns List Using the Google Ads API

The Google Ads API allows you to perform almost all actions available in the Google Ads Manager UI, such as:

1. Create Campaigns
2. List Campaigns
3. Create Assets
4. Retrieve Analytics
5. Modify Campaign Settings etc

Below is a cURL command to retrieve a list of campaigns from your Google Ads account.

curl --location 'https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/googleAds:searchStream' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'developer-token: DEVELOPER_TOKEN' \
--header 'login-customer-id: MCC_ACCOUNT_ID' \
--data '{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id DESC"
}'

Response-

[
  {
    "results": [
      {
        "campaign": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/22040584258",
          "networkSettings": {
            "targetContentNetwork": true
          },
          "name": "Information Technology (IT)_1734441260952",
          "id": "22040584258"
        }
      }
    ],
    "fieldMask": "campaign.id,campaign.name,campaign.networkSettings.targetContentNetwork",
    "requestId": "l9nRCfp0s_07e8UGe76Rcw",
    "queryResourceConsumption": "70"
  }
]

Customizing the Query

You can modify the query to retrieve additional fields or filter campaigns based on specific criteria. For example:

Retrieve Campaign Status:

SELECT campaign.id, campaign.name, campaign.status 
FROM campaign 
WHERE campaign.status = 'PAUSED'

Retrieve Campaign Budget:

SELECT campaign.id, campaign.name, campaign.budget 
FROM campaign

Retrieve Campaign Metrics:

SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS

For more details, refer to the official Google Ads API documentation: Google Ads API Documentation

Conclusion

Using the Google Ads API, you can automate marketing workflows, streamline ad management, and build custom tools to enhance your advertising efforts. Whether it’s keyword planning, retrieving historical keyword data, or managing ad campaigns, the API provides powerful capabilities to scale and optimize your Google Ads strategy.

Thank you for being a part of the community

Before you go:

• Be sure to clap and follow the writer ️👏️️
• Follow us: **X | [LinkedIn](https://www.linkedin.com/company/inplainenglish/) | [YouTube](https://www.youtube.com/channel/UCtipWUghju290NWcn8jhyAw) | [Newsletter](https://newsletter.plainenglish.io/) | [Podcast](https://open.spotify.com/show/7qxylRWKhvZwMz2WuEoua0) | [Differ](https://differ.blog/inplainenglish)**
• **Check out CoFeed, the smart way to stay up-to-date with the latest in tech 🧪**
• **Start your own free AI-powered blog on Differ** 🚀
• **Join our content creators community on Discord** 🧑🏻‍💻
• For more content, visit **plainenglish.io + [stackademic.com](https://stackademic.com/)**