Google Trends Scraper in Python: Interest Over Time, Trending Now and Related Queries
Google Trends answers questions about direction and share, not about raw search counts. This guide shows a Python workflow that collects three kinds of Trends data through a rendering HTML API, checks each payload before it reaches storage, and reads the 0-100 index without drawing conclusions the numbers cannot support.
What this workflow collects
Three separate pulls cover most Trends questions:
- Interest over time — a 0-100 series per keyword, on a scale shared across one request.
- Trending now — terms spiking in a country right now, read from the RSS feed. No browser needed.
- Related queries — a top list and a rising list for one seed keyword.
The first and third run Google's internal JSON endpoints from inside a rendered Trends page. Those endpoints refuse requests that arrive without a Trends session, and a proxy changes your address rather than supplying a session. Running the fetch from the loaded page is what carries the cookies Google set. The trending feed is the exception: it needs no session, so it can also be called straight from your own machine.
Before you start you need an API key stored in an environment variable, and the custom_google flag set so Google domains are fetched. The exact request parameters, exception classes, chain script and parsers are supplied as protected modules and should be used as printed.
What the 0-100 number actually means
Each data point is divided by total searches for that geography and time range. The result is a share of all searching, scaled so the busiest point in the request is exactly 100. A value of 50 means half the busiest point in that request — not half of all searches, and not a count.
Three consequences matter in practice:
- A falling line is not proof of fewer searches. If overall search volume grows faster than your term, your term can gain searches while its share falls.
- Zero means below threshold. Google reports low-volume terms as zero. A flat zero line says the term did not clear Google's reporting threshold, not that nobody searched it.
- The series is a sample. Repeated searches by one person in a short window are removed, and the whole series comes from a sample, so two pulls can differ.
Use the following guide to decide whether Trends is the right source for a question.
Which question each source answers
A short decision table keeps you from asking Trends for something it cannot produce. The legal directory table below is the supplied comparison of question types and the tool that answers each.
Pulling interest over time
The call loads a Trends page and runs a two-step chain inside it. First it asks the explore endpoint for a widget token, then it passes that token to the multiline widget endpoint. Both requests leave from the page's own origin, so each carries the session the page already holds.
The geo, timeframe and category values belong to the Google Trends request built inside the page. They are not API parameters of the rendering service. A geo in the target URL is part of the page address, not the value that selects the data.
The chain is JavaScript because it has to run in the loaded page. It is stored as a Python format template; the keyword list and category fill its two placeholders before it is passed as one of the scenario instructions. The chain appends a marker element when the payload lands, and the scenario waits on that selector instead of a fixed timer.
A 12-month window returns 53 or 54 weekly points depending on where the current week falls. The last point covers an unfinished period and should be dropped before storage.
Reading the scale: a worked example
The same keyword can look very different depending on what it is measured beside. In the captured runs, ai agents peaked at 100 when fetched alone. Fetched beside machine learning, it peaked at 54, because the 100 goes to whichever term is busiest in the request. Its first weekly point showed the same collapse: 14 alone, 7 in the pair.
That is not an error. It is how a shared scale works. Two series fetched in separate calls have different peaks and cannot be ranked against each other without anchoring — running batches with one shared term in every batch and scaling each batch by that term. Anchoring only holds while the shared term keeps enough resolution in every batch it appears in.
A crowded comparison also costs resolution. A large keyword beside a small one pushes the small one into a handful of integers, and its whole year can end up inside two or three values. The series is not wrong, but it has too little resolution left to answer a question about that keyword. Compare terms of similar size when you need detail.
What the response contains
The fields Google returned in the captured pulls were time, formattedTime, formattedAxisTime, value, hasData and formattedValue, plus isPartial on the trailing point. Google can add or rename these without notice, which is why the parser raises a schema error the moment the shape stops matching.
Two details matter:
- Read the unfinished period from
isPartial, nothasData.hasDatareturned true on every point, including the last one. valueis a list because a comparison query returns one entry per keyword, in the order you passed them.
The coverage check below shows the response shape holding across regions and window lengths. Read it as a coverage check, not as a measured success rate.
Why validation belongs in the parser
The worst failures arrive looking like success. Google's refusals can come back inside an HTTP 200. A reordered payload still parses as JSON. A stale or mismatched series still contains plausible integers.
The parser raises a schema error when the shape stops matching, and a data-quality error when the shape is fine but a documented invariant fails. Neither can tell you the series belongs to the query you sent, because the data payload never names a keyword. The widget request that comes back beside it does name one, and an identity check holds it against what you sent.
Keep the failure types separate rather than using one catch-all:
- Retryable — a throttle, a 5xx, a render that never finished, or a request that returned no response. Worth another attempt.
- Rejected — a bad key, a malformed request, a bad geo, or a keyword past the comparison cap. Repeating it changes nothing.
- Schema changed — a response arrived but not in the shape the parser reads. Stop the run; a retry will not fix it.
- Data quality — the response parsed but failed an invariant. Route it to a re-run queue, never store it as a success.
Log the request ID header on every attempt, and log the cost header rather than inferring cost from the status, because only some statuses bill. A request that reaches Google and comes back counts as a delivered call even if the payload inside it is a refusal. A request that never completes leaves no cost to read, so record it as unknown and reconcile against your account usage.
Trending now from the RSS feed
Trending searches come from an RSS feed, so this call needs no browser. It bills the same flat credit cost per request as any other Google domain. It is also the one call in this workflow you can make straight from your own machine, because the feed needs no Trends session.
The traffic band on each row is Google's own approximate count for a spiking term. It is a different measure from the 0-100 index and the two never share a scale. It is the only search-volume estimate in this workflow, an approximate lower-bound bucket like 200+, and it covers only spiking terms, so it does not recover the count the index discards.
geo was the only parameter that changed the output in the captured runs. hours, category and hl each returned a body byte-identical to the geo-only response. The feed returned 10 items on every request, so the window it covers stretches or shrinks with how fast terms are trending.
When you need more than the feed returns, the /trending HTML page is the option. Its payload is a nested array where each field is found by position, so a reorder would keep the parser running and hand you the wrong column. Save one known-good response as a fixture and have a test parse it.
Related queries
The same explore call that returns the timeseries also carries a related-queries widget. Two lines of the chain change together: the widget ID moves from TIMESERIES to RELATED_QUERIES, and the endpoint moves from multiline to relatedsearches. Both have to move together, or the token and the endpoint will not match.
The response shape differs, so it gets its own parser. Two things in that payload will break a parser written from the timeseries:
hasDataappears on the top list and not on the rising one, so reading it raises on every rising entry.valuecarries two different scales under one name: a 0-100 rank on the top list, and a percentage rise on the rising one, which Google prints asBreakoutonce it passes the point where it stops showing a number.
Entry counts vary between pulls, so the parser validates the number of ranked blocks rather than the number of rows inside each block. In the captured pulls, the two lists were not equally reliable. For machine learning, the top list was on-topic, but the rising list put lidl near me first and cook pasta second. For ai agents, the rising list was much closer to the seed. Top queries were on-topic for every seed tried. Do not discard the rising list, but verify unexpected rising queries before you use them.
Request settings that change the data
Not every parameter you can set changes what comes back. The comparison table below is the supplied evidence for which settings had a real effect and which did not.
Pinning dates and watching timezones
Pin the dates so a scheduled job means the same window every time. A rolling today 12-m resolves to the same absolute range it covers, and writing absolute dates into a job removes the ambiguity of what "today" meant on the machine that ran it.
You no longer have to infer the resolution. The widget request that comes back beside the payload states it: a today 12-m pull carried the resolved absolute range, and on the related-queries widget the original string sits beside it. Log the resolved value so a job records the window it actually got.
Timezone handling needs care at short ranges. Per Google's documentation, windows of 30 days or more are reported in UTC, while windows of 7 days or less follow the viewer's local timezone. The chain sends tz=0, and it was not tested whether a short-range query routed through a proxy in another region shifts its buckets. Prefer a timeframe of 30 days or more where the question allows it; where it does not, record the region the request ran from.
Limits and maintenance
This workflow runs on Google's own internal endpoints, none of which are documented. The explore and multiline endpoints can be renamed without notice, and the positional array behind the /trending page can be reordered the same way. Treat the parser as application code with a version and a fixture, not as an API client.
The chain also depends on the JSON endpoints behind the classic Explore page, and it is not known whether those endpoints will outlive the interface. Google was steering users away from it when this was captured. The official Trends API was, as of September 2026, still an alpha you must be admitted to, so build as though you will not get in. Re-test the chain before you depend on it, and again whenever validation starts raising schema errors.
Not every limit is Google's. Delivered failures still bill, and your credit budget and concurrency come from your plan. Rates, plan sizes and the signup grant move on the provider's schedule, so take them from the pricing page and the cost header on your own calls.
Collecting this data automatically may also conflict with Google's Terms of Service. The legal question is covered in the FAQ below.
Alternatives
For a handful of queries from your own machine, the trendspyg library is free and actively released, and it already carries a Trends session because it drives a real browser. In the captured runs its numbers agreed with this workflow's, within the pull-to-pull variation Trends shows anyway.
Its limit is that every request comes from your own address. A back-to-back run of 12 keywords produced 3 successes and 9 failures. That run gave it no backoff, so read 3 of 12 as the cost of running flat out at a per-address limit. Google limits fresh sessions per address, at roughly 8 to 10 an hour according to the library's own error message, though the captured run was blocked after 3. The library has no proxy parameter, so there is no way to avoid this from inside it.
A hand-rolled requests call to the same endpoints fails for a separate reason: it arrives with no Trends session attached, and swapping proxies only changes the address, not the session. The interest-over-time call earlier on this page is the replacement for that approach.
Most older tutorials recommend pytrends. Its repository is archived, and 3 of its methods returned 404 when checked, because Google retired the endpoints behind them.
For trending terms specifically, Google's own Trends dataset in BigQuery is free inside the standard tier and carries top and rising queries across 210 US metro areas on a rolling five-year window. It does not cover interest over time for a keyword you choose.
Where to take it from here
Start with the trending-now call for your own country, which is one call and needs no browser. Then run interest over time on a keyword you already care about, and check the result against the Trends website to confirm your setup.
Carry the validation into production unchanged: on this source, incorrect numbers can arrive inside a clean 200 response. Before scheduling anything, work out the credit cost against your own keyword count.
| What you want | Use | Why |
|---|---|---|
| Monthly search volume for SEO | Google Keyword Planner, or a paid tool | Trends can't produce a number |
| Whether interest is rising or falling | Trends | Free, no account, back to 2004, and direction of share is exactly what a share index measures |
| Which terms are spiking | Trends | The trending feed is near-real-time, and we know of no free alternative with the same coverage |
| Which of these terms is bigger | Trends | Comparable within one query when the terms are of similar size |
| Regional differences | Trends | Sub-region and metro granularity, for free |
| An absolute forecast | Trends plus something else | The volume source supplies the number; check the relationship against your own history before relying on it |
Captured comparison of question types; no independent verification of the alternatives was performed.
| Parameter | Effect | Evidence |
|---|---|---|
| category | Real, and large on an ambiguous term. | On python, category 5 (Computers & Electronics) moved the series by a mean of 13.1 points and a maximum of 32. Category 7 (Finance) moved it by a mean of 43.7 and a maximum of 55. |
| geo sub-region | Real. State codes and DMA codes, Google's metro-area regions, both work. | On wildfire, national US differed from US-CA by up to 42 points, from US-NY by up to 38, and from US-CA-803 (Los Angeles) by up to 44. |
| geo country | Works outside the US. | GB, DE and IN each returned a full 12-month series peaking at 100, 52 points once the partial is dropped, on the same code and the same credit cost as US. |
| tz | No effect on the values, on the window we tested. | Across tz 0, -480 and 330, 6 calls returned 3 distinct responses, and the groupings didn't follow tz at all. The variation appears to come from the cache, not from the parameter. |
Captured September 2026 evidence; the Explore screenshots come from the classic interface and Google's redesigned Explore may behave differently.
Frequently asked questions
Is it legal to scrape Google Trends?
Trends data is public and unauthenticated, but automated collection may conflict with Google's Terms of Service. The version effective 30 July 2026 prohibits using automated means to access content in violation of the machine-readable instructions on a page, and names robots.txt as its example, so the crawler directives sit inside the Terms question. Both hosts publish rules and both are worth reading: trends.google.com/robots.txt disallows /explore? and /trends/explore?, and www.google.com/robots.txt disallows /trends/api among other paths. Whether a particular request is permitted is a question for your own counsel. None of this is legal advice. If you're building a commercial product on this, consult a lawyer.
Is there a dedicated Google Trends endpoint?
The general HTML API covers Trends. You send the Trends URL with custom_google=true, render it, and run the Trends request from inside the page, which is the workflow above. Any tutorial pointing you at a dedicated Trends endpoint is out of date, including the earlier version of this page. A Trends call bills at the flat Google-domain rate.
Why is my series different from what the website shows?
Trends reports a share of all searching, not a count, and it normalizes to each query's own peak, so a different keyword, timeframe or region produces a different scale. Check that the response contains a 100 somewhere. In a comparison it appears on whichever series is busiest overall, not necessarily the first one that you passed. The same query can also come back as a different cached variant from one pull to the next, so a small gap often comes from the sample, not from your code.
How often does Google Trends update?
The feed returned 10 items on every pull we made, so the window it covers stretches and shrinks with the news cycle. Two of our pulls covered 20 minutes and 110 minutes. Poll it every 15 minutes if you can't afford to miss a spike, which is 96 pulls a day, or use the /trending page with hours for a window that you control. On the timeframes we tested, interest-over-time buckets were daily or weekly for windows longer than a week. On daily buckets one pull a day picks up each new bucket, though partial and previously sampled values can still move. The now 7-d and now 1-H windows came back hourly and per-minute.
Does Google Trends have an API?
Google announced an official Trends API in 2025, and as of September 2026 it remained an alpha you have to apply for, so access still needed acceptance into that alpha. The website itself runs on undocumented JSON endpoints that anyone can call without a key, and the libraries and hosted scrapers we looked at build on those. They work, but they're not a supported product and Google can change them without notice.
Is there a free API for Google Trends?
The undocumented endpoints behind the Trends website are free to call, and Google publishes one official free path: the Trends dataset in BigQuery carries the top and rising queries by region inside BigQuery's standard free tier. It won't return interest over time for a keyword you choose; the workflow above handles those. In our trendspyg test, repeated calls from one residential address were rate-limited, which is the limit a free, single-address library eventually reaches. A paid API is a way around that per-address limit rather than around Google's rules, and a Trends call billed 15 credits in our testing.
Why is pytrends not working?
The project is archived, and its PyPI release history showed no release since 2023 when we checked. Its trending_searches, today_searches and realtime_trending_searches methods returned 404 when we checked, because Google retired the endpoints they call. Nothing you change in your own code fixes those. trendspyg was the maintained alternative we found, and it covers interest over time, trending searches and related queries. Its limit is the same per-address one the alternatives section above measures.
| Query | Points returned | Range |
|---|---|---|
| python, US, 12-m | 53 | Sep 7 2025 → Sep 6 2026 |
| coffee, GB, 3-m | 93 | Jun 10 → Sep 10 |
| cricket, IN, 12-m | 53 | Sep 7 2025 → Sep 6 2026 |
| sushi, JP, 5-y | 262 | Sep 5 2021 → Sep 6 2026 |
| bitcoin, US, 3-m | 93 | Jun 10 → Sep 10 |
Counts are what Google returned before dropping the partial point. Read as a coverage check, not a measured success rate.