# Google Trends API in Python: extract Google Trends data with apify-client

> The Google Trends API runs from Python with the apify-client library: install it with pip, call the Actor kwerix/google-trends-api with a keyword list and read one row per keyword from the run's dataset. The same script returns the trend, the seasonality, the breakout queries and the regions, and a max_total_charge_usd option caps what the run can cost.

Canonical: https://kwerix.com/trends/python/

## How to call the Google Trends API from Python

There are 4 steps to call the Google Trends API from Python.

1. **Install** the client with `pip install apify-client`.
2. **Copy** your API token from Apify Console → Settings → API & Integrations.
3. **Call** the Actor `kwerix/google-trends-api` with a keyword list, a location and a time range.
4. **Iterate** over the items of the run's dataset, one row per keyword.

```python
from decimal import Decimal
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("kwerix/google-trends-api").call(
    run_input={"keywords": ["sunscreen", "retinol"], "geo": "US"},
    max_total_charge_usd=Decimal("0.50"),
)
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["keyword"], row["trendSlopePctPerYear"], row["breakoutQueries"][:3])
```

## Which fields does the Python client receive?

The Python client receives 6 groups of fields in every row of the Google Trends API.

| Field | Type | Example (sunscreen) |
|---|---|---|
| `averageInterest`, `peakDate` | float, date | 26.3, 2026-06-07 |
| `trendSlopePctPerYear`, `yoyChangePct` | float | 21.6, 55.9 |
| `seasonality` | dict | `{"isSeasonal": True, "publishBy": "2027-04-24"}` |
| `breakoutQueries` | list of str | `["beauty of joseon", …]` |
| `risingQueries`, `topQueries` | list of dict | `{"query": "best sunscreen", "value": 100}` |
| `interestByRegion` | list of dict | `{"geoName": "Wyoming", "value": 100}` |

## How to compare keywords in Python

Comparing keywords in Python takes one switch: `compareKeywords`, with an anchor keyword of medium popularity.

```python
rows = run({"keywords": keywords, "geo": "US", "timeRange": "today 12-m",
            "compareKeywords": True, "anchorKeyword": "retinol", "includeRelatedQueries": False})
ranked = sorted((r for r in rows if r.get("comparison")), key=lambda r: r["comparison"]["rank"])
for r in ranked:
    print(r["comparison"]["rank"], r["keyword"], r["comparison"]["averageOnCommonScale"])
```

## Which Python examples are ready to run?

4 Python examples are ready to run in the Kwerix repository on GitHub, under the MIT license.

1. **keyword_analysis.py**: trend, year-over-year change, seasonality and breakout queries for a keyword list.
2. **compare_keywords.py**: any number of keywords ranked on one scale.
3. **seasonal_calendar.py**: an SEO content calendar with the keywords to publish for and the dates.
4. **trending_now.py**: what is trending now in one or more countries, by category.

## How to cap the cost of a Python run

A Python run caps its cost with `max_total_charge_usd`, which stops charging at the amount set; at $0.0015 per keyword, `Decimal("0.50")` covers up to 333 keywords.

## Google Trends API in Python FAQ

## Frequently asked questions

### Is there an official Google Trends library for Python?

No. Google publishes no Python library for Google Trends; pytrends was unofficial and archived on April 17, 2025, and the official API is an alpha with access by application.

### Does the Google Trends API need pandas in Python?

No. The rows come back as Python dictionaries, and pandas is optional for anyone who wants a DataFrame.

## Sources

- [Kwerix, Google Trends API examples: Python scripts (GitHub, MIT license)](https://github.com/Kwerix/google-trends-api)
- [Kwerix, Google Trends API & Scraper (README: fields and Python client)](https://apify.com/kwerix/google-trends-api)