Google Keyword Planner API: Setup, Methods, and Practical Examples

Quick Answer
The Google Keyword Planner API is accessed through the Google Ads API, not a separate standalone API. Its main service, KeywordPlanIdeaService, lets developers discover keyword ideas, retrieve historical search metrics, organize keyword themes, and estimate potential advertising performance. You need an appropriately configured Google Cloud project, sufficient API access, OAuth 2.0 authentication, and an accessible Google Ads customer account. Importantly, Explorer access does not permit KeywordPlanIdeaService; Basic or Standard access is required.
Key Takeaways
- Google Keyword Planner functionality is available through the Google Ads API, primarily through
KeywordPlanIdeaService. - Use
GenerateKeywordIdeasto discover new keywords andGenerateKeywordHistoricalMetricsto evaluate an existing keyword list. - Keyword discovery supports keyword, URL, combined keyword-and-URL, and website seeds.
- Basic or Standard access is required for keyword-planning services; Explorer access explicitly restricts them.
- Geographic targeting, language, and search network settings help narrow results to a particular market.
- Historical search volume and advertiser competition are estimates, not organic SEO difficulty scores or guaranteed traffic.
- Google's September 9, 2026 developer-token sunset moved API access management to Google Cloud projects.
- Keyword planning methods have stricter request-rate limits than many other Google Ads API services.
What Is the Google Keyword Planner API?
Google Keyword Planner is a keyword research feature within Google Ads. It helps advertisers discover relevant search terms, examine historical search activity, and plan advertising campaigns.
Developers can access much of this functionality programmatically through the Google Ads API.
The important service is KeywordPlanIdeaService. It provides methods for generating keyword suggestions, retrieving historical keyword metrics, organizing keywords into advertising themes, and forecasting campaign performance.
There is no separate product that developers need to install called the Google Keyword Planner API. Instead, they integrate with the Google Ads API and select the keyword-planning operations that match their requirements.
Google documents these capabilities in its Keyword Planning overview.
What Can You Do With It?
A Google Keyword Planner API integration can support several practical applications:
- Build an automated keyword research dashboard.
- Generate keyword suggestions from a website or a list of seed terms.
- Collect historical monthly search estimates for thousands of keywords.
- Compare advertiser competition and estimated advertising bids.
- Organize keyword ideas into advertising themes.
- Build campaign planning and forecasting tools.
- Store keyword research results for reporting and future analysis.
For SEO software developers, the most useful capability is often the ability to generate and evaluate keyword lists without manually entering every search into the Google Ads interface.
However, the returned information primarily describes advertising-related search activity. It should not be presented as a direct measure of organic ranking difficulty or guaranteed website traffic.
Which Google Ads API Method Should You Use?
The right method depends on what your application needs to accomplish. Choosing the correct operation before building an integration helps avoid unnecessary requests and complicated processing.
Google Keyword Planner API Operation-Selection Worksheet
| Developer objective | API operation | Main input | Main output | Next action |
|---|---|---|---|---|
| Discover new keyword ideas | GenerateKeywordIdeas | Keyword, URL, combined, or site seed | Keyword suggestions and associated historical metrics | Filter and group relevant suggestions |
| Evaluate an existing keyword list | GenerateKeywordHistoricalMetrics | Existing keyword list and targeting settings | Historical search demand, competition, and bid estimates | Prioritize and segment keywords |
| Organize discovered keywords | GenerateAdGroupThemes | Keyword and advertising group information | Suggested advertising themes and modifications | Review campaign structure |
| Estimate future campaign performance | GenerateKeywordForecastMetrics | Campaign-to-forecast configuration | Estimated future advertising performance | Evaluate campaign assumptions |
| Maintain an integration | Project access, caching, and API version configuration | Application settings and stored responses | More reliable API operations | Monitor quotas and version changes |
For most keyword research applications, start with GenerateKeywordIdeas and GenerateKeywordHistoricalMetrics.
The first discovers opportunities. The second evaluates a list you already have. They solve related but different problems.
Before choosing an operation, also check your project's access level. A project with Explorer access cannot call KeywordPlanIdeaService, even though Explorer permits other production-account operations. You need Basic or Standard access for the keyword-planning service.
What You Need Before Making Your First API Request
Before sending requests, prepare the Google Cloud project, API access, authentication credentials, and Google Ads account information.
1. Configure a Google Cloud Project
Create or select a project in Google Cloud Console.
Enable the Google Ads API and open its API overview page. This is where you can inspect the project's current access level and request additional access when necessary.
Google's current access documentation describes four levels:
| Access level | Account access | Daily operation limit |
|---|---|---|
| Test | Test accounts only | 15,000 |
| Explorer | Test and production accounts | 2,880 production operations; 15,000 test operations |
| Basic | Test and production accounts | 15,000 |
| Standard | Test and production accounts | No general daily operation limit |
These are project-level daily limits, calculated over a sliding 24-hour period. They do not override individual service limits.
Important: Explorer is not sufficient for Keyword Planner API integration. Google's access-level documentation explicitly lists KeywordPlanIdeaService and related planning services among the features restricted at Explorer level. Basic or Standard access is required to use these services.
Basic access permits production-account requests and lifts the Explorer restriction on keyword-planning services, subject to its 15,000-operation daily limit. Standard access permits unlimited daily operations at the project level, subject to individual service rate limits and the applicable permissible-use requirements.
For Standard projects, permissible use determines which API features the application may access. Google identifies researching keywords and recommendations as a specific permissible-use category for tools providing suggestions to facilitate the creation and management of Google Ads campaigns. Check that the intended application and its use case satisfy Google's policy before applying.
Review Google's API access levels and permissible-use documentation before designing the integration.
2. Understand the 2026 Developer-Token Transition
Google changed its Google Ads API onboarding and access-management model on September 9, 2026.
Developer tokens were sunset, and access levels moved to Google Cloud projects. The project associated with your OAuth credentials determines the access level used for API requests.
This is important because some older tutorials, REST authentication instructions, and code samples still show a developer-token header.
Google's newer developer-token migration documentation clarifies that:
- New developers no longer need a developer token to get started with the general Google Ads API workflow.
- API access levels are assigned to Google Cloud projects.
- Existing developer-token access levels were transferred to associated projects as part of the transition.
- Sending an old developer-token header is optional and ignored by the API servers under the new model.
Therefore, do not automatically copy an old developer-token configuration into a new integration.
Follow the current project-based instructions and verify that the project used to generate your OAuth credentials has the required access, particularly Basic or Standard access for keyword-planning operations.
3. Configure OAuth 2.0 Authentication
OAuth 2.0 is the authorization mechanism used to authenticate Google Ads API requests.
Google's current first-call quickstart documents a service-account workflow. A service account is an application identity that can authenticate without relying on an individual developer's interactive session.
The general setup involves:
- Open the Google Cloud project.
- Enable the Google Ads API.
- Create a service account.
- Generate and securely store its JSON credentials.
- Add the service-account email to the relevant Google Ads customer account.
- Generate an OAuth access token with the Google Ads API scope.
- Include the access token in the request's authorization header.
The relevant OAuth scope is:
https://www.googleapis.com/auth/adwords
Google also supports user-based OAuth workflows. Select the authentication method appropriate to your application and follow the corresponding current setup instructions.
An important security rule: never publish private service-account keys, OAuth client secrets, or access tokens in frontend JavaScript, public repositories, or client-visible application code.
Read Google's Make your first API call quickstart and REST authentication documentation. Where older authentication pages still mention developer tokens, follow the newer migration instructions instead.
4. Identify Your Google Ads Customer ID
The customer ID identifies the Google Ads account against which you want to make requests.
It is a 10-digit identifier. Remove hyphens when using it in REST endpoint paths.
For example, a customer ID displayed as:
123-456-7890
must be represented as:
1234567890
When working through a manager account, requests may also need the login-customer-id header to identify the manager account used for access.
Make sure the authenticated identity has the necessary permissions on the target customer account. A valid OAuth token alone does not guarantee that the account is accessible.
How to Generate Keyword Ideas With the API
GenerateKeywordIdeas is the primary operation for discovering new keyword suggestions.
It accepts different seed configurations, allowing an application to begin with keywords, a specific webpage, or an entire website.
The Four Keyword Seed Types
| Seed type | What you provide | Best use |
|---|---|---|
keyword_seed | Between 1 and 20 keywords | Expand an existing topic or keyword list |
url_seed | A webpage URL | Discover terms related to a specific page |
keyword_and_url_seed | A URL and between 1 and 20 keywords | Combine page relevance with specific topic ideas |
site_seed | A website or domain | Discover ideas using publicly available website information |
A site seed can generate up to 250,000 keyword ideas from publicly available information. This is an upper capability, not a promise that every website will produce that number of suggestions.
The request must contain one appropriate seed configuration rather than combining all four seed types in the same request.
The Current REST Endpoint
The documented Google Ads API v26 endpoint for keyword idea generation is:
POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateKeywordIdeas
Replace {customer_id} with the 10-digit customer identifier without hyphens.
The endpoint uses API version v26. As of November 13, 2026, Google's release notes identify v26.2, released November 11, 2026, as the latest minor release. The endpoint retains the v26 major-version path.
See the official GenerateKeywordIdeas documentation for the current request schema and supported fields.
Understanding the Request Structure
A request generally needs the following information:
customer_id: The Google Ads customer account identifier.keyword_seed,url_seed,keyword_and_url_seed, orsite_seed: The selected discovery input.geo_target_constants: Geographic targeting resources.language: A supported language resource.keyword_plan_network: The search network configuration.include_adult_keywords: Whether adult keyword ideas should be included.historical_metrics_options: Optional settings for historical statistics.page_sizeandpage_token: Pagination controls.
Not every field is required in every request. Follow the method's current request schema and select the options that match your application.
Practical Request Example: United States Keyword Research
Suppose you are developing an SEO research application for the United States market.
You want to generate keyword suggestions using the seed term technical seo and target users in the United States.
The geographic resource for the United States is:
geoTargetConstants/2840
A simplified request body looks like this:
``json
{
"keywordSeed": {
"keywords": [
"technical seo"
]
},
"geoTargetConstants": [
"geoTargetConstants/2840"
],
"language": "languageConstants/YOUR_LANGUAGE_ID",
"keywordPlanNetwork": "GOOGLE_SEARCH",
"pageSize": 100
}
``
Replace YOUR_LANGUAGE_ID with the resource name for your intended language.
The example illustrates request structure, not a tested API response.
The HTTP request also needs an OAuth access token and the appropriate account context.
For example, its basic structure is:
``http
POST https://googleads.googleapis.com/v26/customers/YOUR_CUSTOMER_ID:generateKeywordIdeas
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
Content-Type: application/json
``
If you are using a manager account, add the appropriate login-customer-id header.
Do not copy this placeholder request as a complete production configuration. Confirm your project's Basic or Standard access, authentication workflow, account permissions, and request fields first.
Geographic and Language Targeting
Targeting is particularly important when building keyword research software for multiple countries.
The geo_target_constants field accepts supported geographic resource names. Google documents a maximum of 10 geographic targets for keyword idea generation.
Examples include:
- United States:
geoTargetConstants/2840 - Other countries and regions: use their corresponding supported Google Ads geo-target resources.
The language field accepts a supported language constant resource.
For example, a keyword research application could use different combinations of geographic and language settings to separate English-language searches in the United States from other markets.
Do not assume that choosing a country automatically guarantees the correct language or audience interpretation. Configure both deliberately.
Google provides the supported values through its keyword planning documentation and associated geographic and language constants.
Search Network Settings
The keyword_plan_network field controls the search network used for keyword planning.
One documented option is GOOGLE_SEARCH.
Your application should select the network that matches its reporting and campaign-planning requirements. Different settings can affect the resulting estimates, so keep network configuration consistent when comparing results over time.
Pagination: Retrieving More Keyword Ideas
Large keyword research requests may return results across multiple pages.
Google supports page sizes of up to 10,000 results for keyword idea generation.
When the response contains a next_page_token, submit another request using that token and preserve the other request parameters.
A reliable pagination workflow should:
- Send the initial request.
- Process the returned keyword ideas.
- Check whether
next_page_tokenis present. - Send the next request with the returned token.
- Continue until no further page token is returned.
- Store or process the accumulated results.
Do not assume that the first response contains every available keyword idea.
For large applications, use controlled pagination and database-level deduplication to avoid repeatedly processing identical keyword records.
How to Retrieve Historical Keyword Metrics
Finding keyword suggestions is only one part of keyword research.
If your application already has a list of terms, use GenerateKeywordHistoricalMetrics to retrieve their historical advertising-related statistics.
This operation is especially useful when evaluating a list collected from multiple sources or generated by an earlier discovery request.
Historical Metrics Request Limits
The method supports up to 10,000 input keywords in a request.
This makes it practical to process large keyword lists in batches.
For example, an application with 25,000 keywords can divide the input into three requests rather than attempting to submit the entire list at once.
Remember that close variants can be deduplicated in the returned data. Consequently, the number of returned results may be lower than the number of submitted keywords.
Important Historical Metric Fields
The response can include several fields that help developers understand search demand and advertising competition.
| API field | Meaning | How to use it |
|---|---|---|
avg_monthly_searches | Approximate average monthly searches | Compare estimated search demand |
monthly_search_volumes | Historical monthly search-volume estimates | Examine changes across months |
competition | Advertiser competition category | Understand advertising competition |
competition_index | Advertiser competition index from 0 to 100 | Compare relative advertising competition |
low_top_of_page_bid_micros | Historical 20th-percentile top-of-page bid | Examine the lower advertising bid estimate |
high_top_of_page_bid_micros | Historical 80th-percentile top-of-page bid | Examine the higher advertising bid estimate |
average_cpc_micros | Average cost-per-click metric where supported and requested | Analyze advertising cost information |
These fields serve different analytical purposes. Search volume estimates indicate demand, while competition and bid fields relate to advertising.
Understanding Bid Values in Micros
Google uses micros for monetary values in relevant API fields.
One currency unit equals 1,000,000 micros.
For example:
2500000 micros = 2.50 currency units
Your application must convert these values before displaying monetary amounts to users.
Do not label a bid value as dollars unless the associated account and currency information actually establish that currency.
How Much Historical Data Is Available?
Google's historical metrics documentation describes a default monthly average based on the preceding 12 months.
When configured appropriately, historical monthly data can cover up to four years.
The available history depends on the request configuration and returned data.
For recurring keyword research, store the retrieval date alongside the results. This makes it easier to distinguish a fresh API response from an older database snapshot.
See Google's Generate Historical Metrics documentation for the exact request and response fields.
How to Interpret Keyword Planner API Results Correctly
Getting data from the API is not the same as understanding what it measures.
Several Google Ads metrics are frequently misunderstood when developers reuse keyword data in SEO applications.
Search Volume Is an Estimate
Average monthly searches describe estimated historical search activity under the selected targeting configuration.
They are not a guaranteed count of unique people, website visits, or future clicks.
Search volume should be used as a planning indicator rather than a promise of traffic.
Advertiser Competition Is Not SEO Difficulty
The competition and competition_index fields describe competition among advertisers.
They do not directly measure how difficult it is to rank organically in Google Search.
For example, a keyword can have substantial advertiser competition but a relatively accessible organic search landscape. The reverse can also happen.
An SEO application should keep advertising competition separate from its own organic difficulty calculations.
If you combine Google Ads metrics with backlink data, search-result analysis, or other SEO signals, label each measurement clearly.
Historical Metrics Are Different From Forecasts
Historical metrics describe past search activity and advertising information.
GenerateKeywordForecastMetrics has a different purpose: it estimates potential future campaign performance using a campaign-to-forecast configuration and a future forecast period.
Forecasts depend on the assumptions and settings supplied to the operation. They are not guarantees of clicks, impressions, conversions, or revenue.
For a keyword research dashboard, avoid presenting a forecast as historical search volume.
Close Variants Can Change Result Counts
Google can group or deduplicate close keyword variants.
This means a request containing many input terms does not necessarily return one independent result for every submitted term.
When building reports, preserve the returned canonical keyword information and avoid assuming that input count and output count must match.
API Limits, Versioning, and Integration Maintenance
A production integration needs more than correct authentication and request formatting.
It must also respect project-level access limits, method-specific quotas, and Google's API release schedule.
Daily Project Limits
The current documented daily operation limits are:
- Test: 15,000 operations, limited to test accounts.
- Explorer: 2,880 operations for production accounts and 15,000 for test accounts.
- Basic: 15,000 operations for test and production accounts.
- Standard: no general daily operation limit for test and production accounts.
These limits do not mean every service can receive requests at unlimited speed. Individual service restrictions still apply. More importantly, Explorer access does not permit the keyword-planning service; Basic or Standard is needed for those methods.
Keyword Planning Has a Specific Rate Limit
Google's quota documentation identifies stricter limits for keyword planning methods.
| Keyword planning operation | Maximum request rate |
|---|---|
GenerateKeywordIdeas | 1 request per second per customer ID |
GenerateKeywordHistoricalMetrics | 1 request per second per customer ID |
GenerateKeywordForecastMetrics | 1 request per second per customer ID |
GenerateAdGroupThemes | 2 requests per second per customer ID |
Google calculates one request per second as 60 requests per 60 seconds.
Requests exceeding these method-specific restrictions can be rejected with RESOURCE_EXHAUSTED.
These limits are separate from the project's daily operation allowance. Your application needs to respect both.
Check the current Google Ads API quota documentation before setting production request schedules.
Use Caching to Reduce Unnecessary Requests
Keyword planning responses do not change frequently enough to justify repeatedly requesting identical data without a clear reason.
Google recommends storing or caching keyword-planning results.
A practical integration can:
- Save the request parameters alongside the response.
- Identify requests with identical targeting and seed configurations.
- Reuse suitable stored results instead of repeating identical calls.
- Refresh historical metrics periodically, taking their monthly update pattern into account.
- Record when each dataset was last retrieved.
- Apply appropriate retention and data-quality rules.
For example, a dashboard that generates the same keyword suggestions for the same country, language, and seed every day can often reuse an earlier result rather than consuming another request.
Caching should not prevent users from obtaining updated information when they genuinely need it. Make the data retrieval date visible where appropriate.
Monitor API Versions
Google Ads API versions have release and sunset schedules.
As of November 13, 2026, v26.2 is the latest published minor release. The major version is v26, released October 14, 2026.
Google's release policy states that minor versions do not introduce breaking changes, but major-version changes require closer compatibility review.
Developers should:
- Keep API endpoint versions in application configuration.
- Monitor Google's official release notes.
- Review breaking changes before upgrading major versions.
- Test request and response handling against supported versions.
- Plan upgrades before a version reaches its sunset date.
Useful references include Google Ads API release notes, API versioning guidance, and Google's 2026–2027 release and sunset schedule.
Common Integration Problems and How to Troubleshoot Them
Most integration problems come from incorrect project access, account permissions, request parameters, or quota handling.
The following troubleshooting matrix provides a practical starting point.
| Problem | Possible cause | Recommended action |
|---|---|---|
| Authentication failure | Invalid or expired OAuth access token | Generate a valid access token and verify the OAuth scope |
| Authorization failure | Insufficient project access or account permissions | Check the project's access level and service-account permissions |
| Keyword-planning method rejected | Project has Explorer access | Apply for Basic or Standard access and verify the applicable permissible-use requirements |
| Production requests rejected | Project has Test access only | Apply for the required production access level |
| Invalid customer ID | Incorrect format or wrong account identifier | Use the 10-digit customer ID without hyphens |
| Manager-account access failure | Missing or incorrect manager context | Check whether login-customer-id is required |
| Invalid geographic target | Unsupported or incorrectly formatted resource name | Verify the geo-target constant against Google's supported resources |
| Keyword request rejected | Too many seed keywords or invalid seed structure | Follow the method's seed-specific limits and request schema |
| Historical metrics missing | Unsupported options or unavailable data | Check request settings and inspect the returned fields rather than assuming every term has data |
RESOURCE_EXHAUSTED | Exceeded method-specific request rate or applicable quota | Reduce request frequency, queue work, and retry appropriately |
| Missing keyword ideas | Only the first page was processed | Follow next_page_token until pagination is complete |
| Unexpected result count | Close-variant deduplication | Compare canonical returned terms rather than relying on input count |
| Outdated API endpoint | Unsupported or sunset version | Review the current release notes and update the endpoint version |
Handle Retries Carefully
When an API request fails because of a temporary quota or service condition, use controlled retry logic.
A good retry strategy should:
- Distinguish temporary failures from invalid requests.
- Avoid repeatedly retrying authentication or permission errors without correcting their cause.
- Apply backoff between temporary retries.
- Respect the documented per-customer request-rate limits.
- Record errors for monitoring and investigation.
Do not automatically retry every failed request at the same speed. That can increase quota pressure and make the original problem worse.
Frequently Asked Questions
Does Google Keyword Planner Have an API?
Yes. Google provides its keyword-planning functionality through the Google Ads API, particularly KeywordPlanIdeaService. There is no separate standalone Google Keyword Planner API product.
Is the Google Keyword Planner API Free?
Google's API access is governed by project access levels, permissible-use rules, and operational quotas rather than a separate Keyword Planner API subscription. You should not assume unrestricted access or unlimited requests.
Check the current Google Ads API terms, access requirements, and applicable advertising-account conditions before deploying an application.
What Access Level Do I Need for Keyword Planner API?
Basic or Standard access is required to use KeywordPlanIdeaService. Explorer access permits certain production operations but explicitly restricts keyword-planning services. Standard access also has project-level permissible-use requirements. Check Google's current access documentation before applying.
Can I Retrieve Keyword Search Volume Programmatically?
Yes. GenerateKeywordIdeas can return keyword suggestions with associated historical metrics, while GenerateKeywordHistoricalMetrics retrieves historical metrics for an existing keyword list. The figures are estimates and depend on the selected targeting and request configuration.
What Is the Difference Between GenerateKeywordIdeas and GenerateKeywordHistoricalMetrics?
GenerateKeywordIdeas discovers new keyword opportunities using keyword, URL, combined, or site seeds. GenerateKeywordHistoricalMetrics evaluates an existing keyword list and returns historical search and advertising metrics. Use the first for discovery and the second for list analysis.
Can the API Return Keyword Data for a Specific Country?
Yes. Use geo_target_constants with supported geographic resource names. For example, geoTargetConstants/2840 identifies the United States. You can also configure a supported language to refine the research.
Does Advertiser Competition Indicate Organic SEO Difficulty?
No. Google's advertiser competition metric describes competition among advertisers. It is not a direct measurement of organic search ranking difficulty. SEO applications should treat the two measurements separately.
Do I Still Need a Developer Token in November 2026?
For the general Google Ads API workflow, Google's September 9, 2026 migration documentation states that developer tokens were sunset and are no longer required. Access levels are now associated with Google Cloud projects. Existing developer-token headers are optional and ignored under the new model. Follow the latest project-based setup instructions for your application.
Building a Reliable Google Keyword Planner API Integration
The most effective implementation begins with a clear distinction between keyword discovery, historical analysis, and campaign forecasting.
For a new keyword research application, configure the Google Cloud project and OAuth authentication first. Confirm that the project has Basic or Standard access before attempting to use keyword-planning methods. Also check the applicable permissible-use requirements, customer account permissions, and authentication configuration before sending requests.
Then use GenerateKeywordIdeas to discover relevant terms and GenerateKeywordHistoricalMetrics to evaluate the resulting list.
Build geographic and language targeting into your request configuration, process every pagination token, and store results with their retrieval dates.
Keep advertising competition separate from organic SEO difficulty, and respect both daily project limits and the stricter keyword-planning request rates.
Finally, monitor Google's API documentation and version schedule so that authentication changes, access requirements, and endpoint updates do not unexpectedly interrupt your application.
One final distinction matters when integrating multiple SEO services: Google's Keyword Planner functionality is for keyword research, not website URL indexing.
IndexNowFast provides a separate API documentation and URL-indexing workflow, while its Google Index Checker handles point-in-time checks of whether public URLs appear in Google's index. These services solve different technical problems and should be integrated according to the task each one performs.
A well-designed Google Keyword Planner API integration does more than retrieve keyword numbers. It turns Google's keyword-planning capabilities into a structured, maintainable research workflow while preserving the meaning and limitations of the underlying data.