Google Keyword Data Extractor

🔑 Google Keyword Data Extractor – Search Volume, CPC & Competition Metrics

The Google Keyword Data Extractor returns keyword planning metrics for a list of search terms — monthly search volume, competition level and index, top-of-page bid range, average CPC, and a twelve-month search volume history. It is built around the Google Ads API Keyword Planner service, and produces one structured record per keyword that drops straight into a spreadsheet or a keyword research database.

Please read this section before running the Actor. By default the Actor runs in mock mode and returns simulated keyword metrics, not live data from Google. Live Google Ads figures require you to supply your own Google Ads API credentials (a developer token, OAuth client ID and secret, refresh token, and customer ID). When valid credentials are present the Actor queries the Google Ads API directly; when they are absent, or when use_mock is left at its default of true, it generates deterministic placeholder records instead. The run log states which mode is active on every run.

This design makes the Actor useful in two distinct ways: as a live Keyword Planner client if you hold Google Ads API access, and as a schema-compatible test harness if you are building a keyword research pipeline and need realistic-shaped data before wiring up credentials.

---

📊 What Data Can You Extract with This Google Keyword Data Extractor?

Each keyword produces one record. The fields below are grouped by what they describe.

Category	Fields	What it gives you
🔤 Keyword identity	keyword, spell	The keyword the record describes and any spelling correction returned for it
📈 Search demand	search_volume, monthly_searches	Average monthly search volume plus a month-by-month history array
🥊 Competition	competition, competition_index	Competition band (such as LOW, MEDIUM, or HIGH) and its numeric index
💰 Bid and cost metrics	cpc, low_top_of_page_bid, high_top_of_page_bid	Average cost per click and the low and high top-of-page bid estimates
🌍 Targeting context	location_code, location_name, language_code, search_partners	The geographic and language targeting applied, and whether search partners were included
⚙️ Run configuration	keywords, use_mock, outputFile	The keyword list submitted, the mock-mode flag, and the local output file name

The monthly_searches array is the field that separates keyword research from keyword guessing. A single average volume figure hides seasonality entirely — a term that peaks in November and flatlines in June looks identical to a steady term with the same annual average. The twelve-month array lets you spot that pattern and time content and campaign launches against it.

---

🌟 Key Features of the Google Keyword Data Extractor

Feature	Description
📊 Keyword Planner metrics	Returns search volume, competition, competition index, bid range, and CPC per keyword
📅 Twelve-month history	The monthly_searches array carries a year, month, and search volume entry for each of the past twelve months
🔌 Google Ads API integration	Queries the Google Ads API directly when your own credentials are supplied
🧪 Mock mode by default	Runs without credentials and returns deterministic simulated records, clearly logged as mock
🌍 Location targeting	location_name is resolved to a Google geo target constant when running against the live API
🗣️ Language targeting	language_code restricts metrics to a specific language when running live
📦 Batch keyword input	Submit an array of keywords and receive one dataset record per keyword
🪵 Explicit mode logging	The run log states whether the run is live or mock, and why, before any records are produced
🔁 Graceful fallback	If a live API call fails mid-run, the Actor logs the error and falls back to generated records rather than crashing

---

🚀 Why Choose This Google Keyword Data Extractor?

Honest about its two modes. The Actor tells you in the run log whether it is returning live Google Ads data or generated placeholder data, and why. That transparency matters more than a marketing claim — you always know what you are looking at before you build a decision on it.

Uses your own Google Ads API access. When you supply a developer token, OAuth credentials, and a customer ID, metrics come from Google's own Keyword Planner service through the official API rather than from a scraped intermediary.

Twelve-month history, not just an average. monthly_searches returns a full year of month-level volume per keyword, which is what you need for seasonality analysis, budget phasing, and editorial calendar planning.

A usable development harness. Mock mode returns records with exactly the same field names and types as live mode, so you can build and test a keyword research pipeline end to end before credentials are provisioned.

---

📥 Input

{
  "keywords": [
    "google",
    "web scraping",
    "houses for rent"
  ],
  "location_name": "",
  "language_code": "",
  "use_mock": true,
  "outputFile": "output.json"
}

🔧 Google Keyword Data Extractor Input Fields

Field	Type	Required	Default	Description
keywords	array	Yes in practice	["google", "web scraping", "houses for rent"]	The list of keywords to retrieve metrics for
location_name	string	No	"" (empty)	Location name resolved to a Google geo target constant when running against the live API
language_code	string	No	"" (empty)	Language code used to restrict metrics when running against the live API
use_mock	boolean	No	true	Force simulated keyword data. Automatically set to false when full Google Ads credentials are detected
outputFile	string	No	output.json	File name used when the scraper is run locally rather than on Apify
developer_token	string	No	—	Google Ads API developer token. Also readable from the GOOGLE_DEVELOPER_TOKEN environment variable
client_id	string	No	—	OAuth client ID. Also readable from GOOGLE_CLIENT_ID
client_secret	string	No	—	OAuth client secret. Also readable from GOOGLE_CLIENT_SECRET
refresh_token	string	No	—	OAuth refresh token. Also readable from GOOGLE_REFRESH_TOKEN
customer_id	string	No	—	Google Ads customer ID. Also readable from GOOGLE_CUSTOMER_ID
login_customer_id	string	No	falls back to customer_id	Manager account ID used for the API call. Also readable from GOOGLE_LOGIN_CUSTOMER_ID

Live mode requires all five of developer_token, client_id, client_secret, refresh_token, and customer_id. If any one is missing, the run proceeds in mock mode and says so in the log.

💡 Input Examples

Mock run for pipeline testing

{
  "keywords": ["web scraping", "data extraction", "api scraping"],
  "use_mock": true
}

Live run with Google Ads API credentials

{
  "keywords": ["running shoes", "trail running shoes", "marathon training plan"],
  "location_name": "United Kingdom",
  "language_code": "en",
  "use_mock": false,
  "developer_token": "YOUR_DEVELOPER_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "customer_id": "YOUR_CUSTOMER_ID"
}

Location and language targeted keyword research

{
  "keywords": ["zapatillas running", "maraton entrenamiento"],
  "location_name": "Spain",
  "language_code": "es",
  "use_mock": false
}

---

📤 Output

{
  "keyword": "google",
  "spell": null,
  "location_code": null,
  "language_code": null,
  "search_partners": false,
  "competition": "LOW",
  "competition_index": 0,
  "search_volume": 414000000,
  "low_top_of_page_bid": 0.35,
  "high_top_of_page_bid": 1.54,
  "cpc": 1.06,
  "monthly_searches": [
    { "year": 2026, "month": 6, "search_volume": 414000000 },
    { "year": 2026, "month": 5, "search_volume": 414000000 }
  ]
}

🧾 Keyword Metric Output Fields

Field	Type	Description
keyword	string | null	Keyword that produced this item
spell	string | null	Spelling correction returned for the keyword, if any
search_volume	integer | null	Average monthly search volume for the keyword
monthly_searches	array | null	Month-by-month search volume entries collected for the keyword
competition	string | null	Competition band reported for the keyword
competition_index	integer | null	Numeric competition index for the keyword
cpc	number | null	Cost per click for the keyword
low_top_of_page_bid	number | null	Low top-of-page bid estimate
high_top_of_page_bid	number | null	High top-of-page bid estimate
location_code	string | null	Location code applied to the query
language_code	string | null	Language code applied to the query
search_partners	boolean | null	Whether search partner networks were included

🧾 Run Configuration Fields

Field	Type	Description
keywords	array | null	The keyword list associated with the run
location_name	string | null	Name of the location targeted
use_mock	boolean | null	Whether mock data generation was used
outputFile	string | null	Output file name used for local runs

Each entry in monthly_searches is an object containing year, month, and search_volume. Some export formats flatten it into a JSON string, so parse it back before charting.

---

💻 How to Use the Google Keyword Data Extractor (Step by Step)

Step 1: Decide whether you need live or mock keyword data

This is the first and most important decision. If you hold Google Ads API access, you can retrieve live Keyword Planner metrics. If you do not, the Actor still runs, but the numbers it returns are generated rather than real. Use mock mode to develop and test integrations; use live mode when the figures will inform an actual budget, bid, or content decision.

Step 2: Prepare your keyword list

Populate the keywords array with the terms you want metrics for. Keep the list focused: a coherent set of terms around one topic or campaign produces a dataset you can actually compare within, whereas a scattershot list of unrelated terms produces rows with nothing in common. Use the exact phrasing searchers use, not internal product names.

Step 3: Supply Google Ads API credentials for live mode

To run live, provide developer_token, client_id, client_secret, refresh_token, and customer_id. Each can be supplied in the input or through the corresponding environment variable, which is the safer option for secrets. If you use a manager account, set login_customer_id as well; otherwise it falls back to customer_id. When all five credentials are detected, the Actor sets live mode automatically regardless of the use_mock value.

Step 4: Set location and language targeting

location_name accepts a plain location name, which the Actor resolves to a Google geo target constant through the Geo Target Constant Service before querying. language_code narrows metrics to a single language. Both matter enormously for accuracy — search volume for the same keyword can differ by an order of magnitude between countries, and leaving both empty produces the broadest, least actionable figures.

Step 5: Run the Actor and read the mode line in the log

Press Start, then look at the first lines of the run log. The Actor prints the active mode explicitly — live, mock forced by user input, mock because the Google Ads library is unavailable, or mock because credentials are missing. Confirm that line says what you expect before you trust any figure in the dataset.

Step 6: Review the keyword metrics in the dataset

Open the Dataset tab. Each row is one keyword with its volume, competition, bid range, CPC, and monthly history. Sanity-check a keyword you already know: if the volume for a familiar term looks implausible for your market, the run is almost certainly in mock mode or targeting the wrong location.

Step 7: Export and analyse the keyword data

Export as JSON, CSV, Excel, XML, or HTML, or read the dataset through the API. For seasonality work, expand monthly_searches into one row per keyword-month and plot the series. For prioritisation, rank keywords by search_volume against competition_index to find high-demand, low-competition terms, and use cpc with low_top_of_page_bid and high_top_of_page_bid to estimate what paid coverage of each term would cost.

---

🔌 API Access & Integrations

Run the Google keyword data extractor synchronously and receive dataset items directly:

curl -X POST "https://api.apify.com/v2/acts/scrapers-hub~google-keyword-data-extractor/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["web scraping", "data extraction"],
    "location_name": "United Kingdom",
    "language_code": "en",
    "use_mock": true
  }'

Rank keywords by demand against competition with the Python client:

import json
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")

run = client.actor("scrapers-hub/google-keyword-data-extractor").call(run_input={
    "keywords": ["running shoes", "trail running shoes", "marathon training plan"],
    "location_name": "United Kingdom",
    "language_code": "en",
    "use_mock": True,
})

rows = []
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    if not item.get("keyword"):
        continue
    months = item.get("monthly_searches") or []
    if isinstance(months, str):
        months = json.loads(months)
    peak = max(months, key=lambda m: m["search_volume"]) if months else None
    rows.append((
        item["keyword"],
        item.get("search_volume") or 0,
        item.get("competition_index") or 0,
        item.get("cpc"),
        f"{peak['year']}-{peak['month']:02d}" if peak else None,
    ))

for keyword, volume, competition, cpc, peak_month in sorted(rows, key=lambda r: -r[1]):
    print(f"{keyword}: {volume:,} searches | competition {competition} | CPC {cpc} | peak {peak_month}")

The Actor also connects to Zapier, Make, Google Sheets, and Slack, and supports webhooks that fire when a run completes so keyword metrics can flow into a reporting sheet automatically.

---

💡 Best Use Cases for Google Keyword Data

📝 Content planning and editorial prioritisation

Rank a topic's keyword list by search_volume and competition_index to decide what to write first. High volume paired with a low competition index points to content opportunities where organic ranking is realistic; the monthly_searches array then tells you when in the year that piece should be published to catch the peak.

💷 Paid search budget estimation

cpc, low_top_of_page_bid, and high_top_of_page_bid together give you a cost envelope for a keyword. Multiplying the bid range by an assumed click share of search_volume produces a defensible budget estimate for a proposed campaign, and comparing the low and high bid spread shows how volatile auction pricing is for that term.

📅 Seasonality and demand forecasting

The monthly_searches history is the basis for any seasonality analysis. Plotting twelve months of volume per keyword reveals which terms peak around holidays, weather changes, or fiscal cycles, letting you phase both content publication and paid spend rather than distributing them evenly across the year.

🥊 Competitive keyword gap analysis

Run a batch containing both your own target keywords and those you believe competitors are bidding on, then compare competition and competition_index across the set. Terms with strong search_volume but a low competition index are the gaps worth taking; terms with a high index and a high cpc are where a challenger is likely to lose money.

🌍 International and multi-market research

Because location_name and language_code are per-run settings, running the same keyword list against several markets produces directly comparable datasets. The differences in search_volume and cpc between markets are often the deciding evidence in a localisation or market-entry decision.

🛠️ Keyword pipeline development and testing

Mock mode returns records with the same field names and types as live mode, which makes it a practical fixture generator. Build your ingestion, deduplication, and charting layers against mock output, then switch to live credentials once the pipeline is proven — without changing a line of parsing code.

📊 SEO reporting and client deliverables

The combination of volume, competition, and bid data per keyword is the standard evidence base in an SEO audit or a pitch document. Exporting to CSV and joining against your rank tracking gives you a single table showing what each keyword is worth, how contested it is, and where you currently stand on it.

---

⚙️ Tips for Better Google Keyword Data Extraction

• Check the mode line in the log every single run. It is the only reliable way to know whether the numbers in front of you are live Google Ads data or generated placeholders.
• Always set location_name and language_code for live runs. Leaving them empty produces undifferentiated global figures that are rarely actionable for a specific market.
• Store credentials as environment variables, not in the input. GOOGLE_DEVELOPER_TOKEN, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN, and GOOGLE_CUSTOMER_ID are all read from the environment, which keeps secrets out of saved run inputs.
• Group keywords into coherent batches. One run per topic cluster or per campaign gives you datasets where cross-keyword comparison is meaningful.
• Parse monthly_searches before charting. Some export formats serialise the array as a JSON string. Parse it back into objects rather than treating it as text.
• Treat competition and CPC as paid-search signals. They describe advertiser demand in the Google Ads auction, not organic ranking difficulty. High CPC indicates commercial value, not that a page is hard to rank.

---

🛠️ Troubleshooting

The numbers look wrong or suspiciously round — what happened? The run was almost certainly in mock mode. Check the run log for the mode line. Mock mode is active whenever use_mock is true, when any of the five required Google Ads credentials is missing, or when the Google Ads library is unavailable in the environment.

I supplied credentials but the run still used mock data. Live mode requires all five of developer_token, client_id, client_secret, refresh_token, and customer_id. Missing any one of them sends the run to mock mode. The log states which condition triggered it.

The live API call failed partway through the run. The Actor logs the API error and falls back to generated records so the run does not crash. That means a dataset can contain generated rows even when you intended a live run — read the log before trusting the output.

My location name was not recognised. location_name is resolved through Google's Geo Target Constant Service. If the name cannot be matched, the log records a warning and the run continues without geo targeting. Use a standard, unambiguous location name such as a country or major city name.

monthly_searches appears as a long string rather than an array. That is an export artefact. The field is an array of objects containing year, month, and search_volume; parse the string back to JSON in your analysis step.

---

❓ Frequently Asked Questions About Google Keyword Data Extraction

Does this Actor return real Google keyword data? It returns live Google Ads Keyword Planner data when you supply your own Google Ads API credentials. Without them it runs in mock mode and returns generated records, and the run log states which mode was used.

What credentials do I need for live keyword data? Five: a developer token, an OAuth client ID and client secret, a refresh token, and a Google Ads customer ID. A login_customer_id is optional and falls back to customer_id.

Can I supply credentials through environment variables? Yes, and it is the recommended approach. The Actor reads GOOGLE_DEVELOPER_TOKEN, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN, GOOGLE_CUSTOMER_ID, and GOOGLE_LOGIN_CUSTOMER_ID.

What does use_mock do? Setting it to true forces simulated keyword data. It defaults to true, and is automatically overridden to false when all required Google Ads credentials are detected.

How many keywords can I submit in one run? Provide as many as you need in the keywords array. When running live, the Google Ads API applies its own per-request limits, so very large lists are best split across runs.

What is competition_index? A numeric representation of how contested a keyword is in the Google Ads auction, alongside the categorical competition band. Both describe paid competition rather than organic ranking difficulty.

What is the difference between cpc and the top-of-page bid fields? cpc is the average cost per click for the keyword, while low_top_of_page_bid and high_top_of_page_bid bracket the bid range advertisers pay to appear at the top of the results page.

What does monthly_searches contain? An array of objects, each with year, month, and search_volume, covering the past twelve months. It is the field to use for seasonality analysis.

Can I get keyword data for a specific country? Yes, through location_name, which is resolved to a Google geo target constant on live runs. Pair it with language_code for language-specific metrics.

Does the Google keyword data extractor use a proxy or a browser? No. It calls the Google Ads API directly and does not launch a headless browser.

Why would I use mock mode at all? Because mock records match the live schema exactly. That makes them useful fixtures for building and testing an ingestion pipeline before Google Ads API access is provisioned.

What is spell used for? It carries a spelling correction associated with the keyword when one is returned. It is frequently null.

What export formats are supported? Apify datasets export to JSON, CSV, Excel, XML, and HTML, and are also readable through the dataset API. Zapier, Make, Google Sheets, Slack, and webhook integrations are supported.

Does the search volume include Google search partners? The search_partners field records whether search partner networks were included in the query for that record.

Can I request a customised version of this Actor? Yes. Email scraperhubapi@gmail.com to discuss keyword research pipelines, additional metrics, or integration with your own reporting stack.

---

🆘 Support & Feedback

If a run behaves unexpectedly, or live mode does not activate despite valid credentials, report it on the Issues tab of the Actor page. Include the run ID and the mode line from the log — not your credentials — so the behaviour can be diagnosed.

For custom work — larger keyword research pipelines, additional Google Ads metrics, or a tailored version of this Google keyword data extractor — email scraperhubapi@gmail.com.

If this Actor is useful in your SEO or paid search work, please leave a review on the Apify Store. Feedback shapes which improvements are built next.

---

⚖️ Disclaimer

The Google Keyword Data Extractor retrieves keyword planning metrics through the official Google Ads API using credentials that you supply. It does not bypass authentication, scrape Google's search results pages, or circumvent any access control. When credentials are not provided, it generates simulated records instead and states this clearly in the run log.

You are responsible for how you use this Actor and the keyword data it produces. Your use of the Google Ads API is governed by your own Google Ads API terms of service and developer token conditions, including any restrictions on how retrieved data may be stored, displayed, or shared. Verify that your intended use complies with those terms before deploying at scale.

Keyword metrics are aggregate search demand figures and do not identify individuals. Where any data you handle alongside these results relates to identifiable people, data protection law including the GDPR applies to you as the data controller, and you must establish a lawful basis and apply appropriate retention limits.

Data is provided as-is. Live figures reflect Google's estimates at the time of the query and mock figures are generated placeholders — confirm which mode produced your dataset before relying on it for budget, bid, or commercial decisions.

If you believe data returned by this Actor should be removed or corrected, email scraperhubapi@gmail.com with the details and the request will be reviewed.