### Install the package

Source: https://github.com/trendsmcp/google-search-trends-api/blob/main/README.md

Install the library using pip.

```bash
pip install google-search-trends-api
```

--------------------------------

### Quick start with synchronous client

Source: https://github.com/trendsmcp/google-search-trends-api/blob/main/README.md

Initialize the client and fetch historical trends, growth metrics, and current trending topics.

```python
from google_search_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# 5-year weekly time series, no sleep(), no proxies, no 429s
series = client.get_trends(source=SOURCE, keyword="bitcoin")
print(series[0])
# TrendsDataPoint(date='2026-03-28', value=72, keyword='bitcoin', source='google search')

# Period-over-period growth
growth = client.get_growth(
    source=SOURCE,
    keyword="bitcoin",
    percent_growth=["12M", "YTD"],
)
print(growth.results[0])
# GrowthResult(period='3M', growth=14.5, direction='increase', ...)

# What's trending right now
trending = client.get_top_trends(limit=10)
print(trending.data)
# [[1, 'topic one'], [2, 'topic two'], ...]
```

--------------------------------

### GET /get_growth

Source: https://github.com/trendsmcp/google-search-trends-api/blob/main/README.md

Calculates percentage growth for a keyword between two points in time using predefined growth periods.

```APIDOC
## GET /get_growth

### Description
Calculates percentage growth between two points in time. Pass preset strings or CustomGrowthPeriod objects.

### Parameters
#### Query Parameters
- **source** (string) - Required - The platform source
- **keyword** (string) - Required - The keyword to track
- **percent_growth** (array) - Required - List of growth periods (e.g., ['12M', 'YTD'])
- **data_mode** (string) - Optional - Granularity mode

### Response
#### Success Response (200)
- **results** (array) - List of GrowthResult objects containing period, growth percentage, and direction.
```

--------------------------------

### GET /get_top_trends

Source: https://github.com/trendsmcp/google-search-trends-api/blob/main/README.md

Returns today's live trending items across various supported platforms.

```APIDOC
## GET /get_top_trends

### Description
Returns today's live trending items. Omit type to get all feeds at once.

### Parameters
#### Query Parameters
- **type** (string) - Optional - The specific feed type
- **limit** (integer) - Optional - Maximum number of items to return

### Response
#### Success Response (200)
- **data** (array) - List of trending items and their associated ranks.
```

--------------------------------

### GET /api/top_trends - Get Live Trending Items

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Retrieves today's live trending items across multiple platforms. Can fetch all feeds or specific ones.

```APIDOC
## GET /api/top_trends

### Description
Returns today's live trending items across multiple platforms. Omit the `type` parameter to get all feeds at once, or specify a feed type for targeted results. Useful for content discovery and real-time trend monitoring.

### Method
GET

### Endpoint
/api/top_trends

### Parameters
#### Path Parameters
None

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of trending items to return.
- **type** (string) - Optional - Specifies a particular feed type to retrieve (e.g., "google search", "youtube"). If omitted, all feeds are returned.

### Request Example
```python
from google_search_trends_api import TrendsMcpClient

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# Get all trending items across all platforms
all_trending = client.get_top_trends(limit=10)
print(all_trending.data)

# Get trending from specific feeds
# Example: trending_youtube = client.get_top_trends(type="youtube", limit=5)
```

### Response
#### Success Response (200)
- **data** (list) - A list containing trending items. The structure may vary based on the source and type requested.

#### Response Example
```json
{
  "data": [
    [1, "topic one"],
    [2, "topic two"],
    ...
  ]
}
```
```

--------------------------------

### GET /api/trends - Get Historical Time Series

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Retrieves a historical time series for a specified keyword. Supports weekly (default) or daily data granularity.

```APIDOC
## GET /api/trends

### Description
Returns a historical time series for a keyword. Defaults to 5 years of weekly data points. Use `data_mode="daily"` to get the last 30 days at daily granularity. Each data point includes date, normalized value (0-100), keyword, and source.

### Method
GET

### Endpoint
/api/trends

### Parameters
#### Path Parameters
None

#### Query Parameters
- **source** (string) - Required - The data source (e.g., "google search", "youtube", "reddit").
- **keyword** (string) - Required - The search term or keyword to query.
- **data_mode** (string) - Optional - Specifies the data granularity. Accepts "daily" for the last 30 days, otherwise defaults to weekly.

### Request Example
```python
from google_search_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# Get 5-year weekly time series for Google Search
series = client.get_trends(source=SOURCE, keyword="bitcoin")
print(series[0])

# Get last 30 days of daily data
daily_series = client.get_trends(source=SOURCE, keyword="bitcoin", data_mode="daily")
for point in daily_series[:5]:
    print(f"{point.date}: {point.value}")

# Query different platforms
youtube_data = client.get_trends(source="youtube", keyword="bitcoin")
reddit_data = client.get_trends(source="reddit", keyword="bitcoin")
amazon_data = client.get_trends(source="amazon", keyword="wireless headphones")
```

### Response
#### Success Response (200)
- **date** (string) - The date of the data point.
- **value** (integer) - The normalized trend value (0-100).
- **keyword** (string) - The queried keyword.
- **source** (string) - The data source.

#### Response Example
```json
[
  {
    "date": "2026-03-28",
    "value": 72,
    "keyword": "bitcoin",
    "source": "google search"
  }
]
```
```

--------------------------------

### GET /api/growth - Calculate Percentage Growth

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Calculates the percentage growth of a keyword's trend data between specified time periods.

```APIDOC
## GET /api/growth

### Description
Calculates percentage growth between two points in time using preset periods or custom date ranges. Returns growth percentage, direction (increase/decrease), and metadata. Useful for comparing keyword performance across different time windows.

### Method
GET

### Endpoint
/api/growth

### Parameters
#### Path Parameters
None

#### Query Parameters
- **source** (string) - Required - The data source (e.g., "google search", "youtube").
- **keyword** (string) - Required - The search term or keyword to query.
- **percent_growth** (list of strings) - Required - A list of time periods for which to calculate growth (e.g., ["12M", "YTD", "3M"]). Available presets: 7D, 14D, 30D, 1M, 2M, 3M, 6M, 9M, 12M, 1Y, 18M, 24M, 2Y, 36M, 3Y, 48M, 60M, 5Y, MTD, QTD, YTD.

### Request Example
```python
from google_search_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# Calculate growth using preset periods
growth = client.get_growth(
    source=SOURCE,
    keyword="bitcoin",
    percent_growth=["12M", "YTD", "3M"],
)

for result in growth.results:
    print(f"{result.period}: {result.growth}% ({result.direction})")

# Compare growth across platforms
google_growth = client.get_growth(source="google search", keyword="AI", percent_growth=["12M"])
youtube_growth = client.get_growth(source="youtube", keyword="AI", percent_growth=["12M"])
print(f"Google Search 12M growth: {google_growth.results[0].growth}%")
print(f"YouTube 12M growth: {youtube_growth.results[0].growth}%")
```

### Response
#### Success Response (200)
- **results** (list) - A list of growth calculation results.
  - **period** (string) - The time period for the growth calculation.
  - **growth** (float) - The calculated percentage growth.
  - **direction** (string) - The direction of growth ("increase" or "decrease").

#### Response Example
```json
{
  "results": [
    {
      "period": "12M",
      "growth": 45.2,
      "direction": "increase"
    },
    {
      "period": "YTD",
      "growth": 12.8,
      "direction": "increase"
    },
    {
      "period": "3M",
      "growth": -5.3,
      "direction": "decrease"
    }
  ]
}
```
```

--------------------------------

### GET /get_trends

Source: https://github.com/trendsmcp/google-search-trends-api/blob/main/README.md

Retrieves a historical time series for a specific keyword. Defaults to 5 years of weekly data, with an option for daily granularity for the last 30 days.

```APIDOC
## GET /get_trends

### Description
Returns a historical time series for a keyword. Defaults to 5 years of weekly data. Pass data_mode="daily" for the last 30 days at daily granularity.

### Parameters
#### Query Parameters
- **source** (string) - Required - The platform source (e.g., 'google search')
- **keyword** (string) - Required - The keyword to track
- **data_mode** (string) - Optional - Granularity mode (e.g., 'daily')

### Response
#### Success Response (200)
- **data** (array) - List of TrendsDataPoint objects containing date, value, keyword, and source.
```

--------------------------------

### Compare Keywords Across Platforms

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Initialize the client and compare keyword performance across multiple supported data sources.

```python
from google_search_trends_api import TrendsMcpClient

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# All supported sources
sources = [
    "google search",     # Google Search volume
    "google images",     # Google Images search volume
    "google news",       # Google News search volume
    "google shopping",   # Google Shopping purchase intent
    "youtube",           # YouTube search volume
    "tiktok",            # TikTok hashtag volume
    "reddit",            # Reddit mention volume
    "amazon",            # Amazon product search volume
    "wikipedia",         # Wikipedia page views
    "news volume",       # News article mention count
    "news sentiment",    # News sentiment score (positive/negative)
    "npm",               # npm package weekly downloads
    "steam",             # Steam concurrent player count
]

# Compare a keyword across multiple platforms
keyword = "machine learning"
for source in ["google search", "youtube", "reddit", "wikipedia"]:
    data = client.get_trends(source=source, keyword=keyword)
    latest = data[0] if data else None
    print(f"{source}: {latest.value if latest else 'N/A'}")
```

--------------------------------

### Initialize AsyncTrendsMcpClient

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Asynchronous client for concurrent trend data requests.

```python
import asyncio
from google_search_trends_api import AsyncTrendsMcpClient, SOURCE

async def main():
    client = AsyncTrendsMcpClient(api_key="YOUR_API_KEY")

    # Run multiple platform queries concurrently
    google, youtube, reddit = await asyncio.gather(
        client.get_trends(source="google search", keyword="bitcoin"),
        client.get_trends(source="youtube", keyword="bitcoin"),
        client.get_trends(source="reddit", keyword="bitcoin"),
    )

    print(f"Google: {google[0]}")
    print(f"YouTube: {youtube[0]}")
    print(f"Reddit: {reddit[0]}")

asyncio.run(main())
```

--------------------------------

### Initialize TrendsMcpClient

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Synchronous client initialization using an API key.

```python
from google_search_trends_api import TrendsMcpClient, SOURCE

# Initialize client with API key
client = TrendsMcpClient(api_key="YOUR_API_KEY")

# SOURCE constant is pre-set to "google search" for this package
print(SOURCE)  # "google search"
```

--------------------------------

### AsyncTrendsMcpClient Initialization and Usage

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Initialize the asynchronous client for non-blocking trend data requests and demonstrate concurrent queries.

```APIDOC
## AsyncTrendsMcpClient Initialization and Usage

### Description
Initialize the asynchronous client for non-blocking trend data requests. Ideal for concurrent queries across multiple platforms or integration with async web frameworks.

### Method
Instantiation and Async Function Call

### Endpoint
N/A (Client-side library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from google_search_trends_api import AsyncTrendsMcpClient

async def main():
    client = AsyncTrendsMcpClient(api_key="YOUR_API_KEY")

    # Run multiple platform queries concurrently
    google, youtube, reddit = await asyncio.gather(
        client.get_trends(source="google search", keyword="bitcoin"),
        client.get_trends(source="youtube", keyword="bitcoin"),
        client.get_trends(source="reddit", keyword="bitcoin"),
    )

    print(f"Google: {google[0]}")
    print(f"YouTube: {youtube[0]}")
    print(f"Reddit: {reddit[0]}")

asyncio.run(main())
```

### Response
None (Client-side object creation and async operations)
```

--------------------------------

### Calculate growth with get_growth()

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Compute percentage growth over specific time periods or compare performance across platforms.

```python
from google_search_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# Calculate growth using preset periods
# Available presets: 7D, 14D, 30D, 1M, 2M, 3M, 6M, 9M, 12M, 1Y, 18M, 24M, 2Y, 36M, 3Y, 48M, 60M, 5Y, MTD, QTD, YTD
growth = client.get_growth(
    source=SOURCE,
    keyword="bitcoin",
    percent_growth=["12M", "YTD", "3M"],
)

for result in growth.results:
    print(f"{result.period}: {result.growth}% ({result.direction})")
# 12M: 45.2% (increase)
# YTD: 12.8% (increase)
# 3M: -5.3% (decrease)

# Compare growth across platforms
google_growth = client.get_growth(source="google search", keyword="AI", percent_growth=["12M"])
youtube_growth = client.get_growth(source="youtube", keyword="AI", percent_growth=["12M"])
print(f"Google Search 12M growth: {google_growth.results[0].growth}%")
print(f"YouTube 12M growth: {youtube_growth.results[0].growth}%")
```

--------------------------------

### TrendsMcpClient Initialization

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Initialize the synchronous client for making trend data requests using your API key.

```APIDOC
## TrendsMcpClient Initialization

### Description
Initialize the synchronous client for making trend data requests. Requires an API key from trendsmcp.ai.

### Method
Instantiation

### Endpoint
N/A (Client-side library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from google_search_trends_api import TrendsMcpClient

client = TrendsMcpClient(api_key="YOUR_API_KEY")
```

### Response
None (Client-side object creation)
```

--------------------------------

### Fetch live trends with get_top_trends()

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Retrieve current trending items across platforms.

```python
from google_search_trends_api import TrendsMcpClient

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# Get all trending items across all platforms
all_trending = client.get_top_trends(limit=10)
print(all_trending.data)
# [[1, 'topic one'], [2, 'topic two'], ...]
```

--------------------------------

### Retrieve historical trends with get_trends()

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Fetch time series data for keywords, supporting weekly or daily granularity across different platforms.

```python
from google_search_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# Get 5-year weekly time series for Google Search
series = client.get_trends(source=SOURCE, keyword="bitcoin")
print(series[0])
# TrendsDataPoint(date='2026-03-28', value=72, keyword='bitcoin', source='google search')

# Get last 30 days of daily data
daily_series = client.get_trends(source=SOURCE, keyword="bitcoin", data_mode="daily")
for point in daily_series[:5]:
    print(f"{point.date}: {point.value}")

# Query different platforms
youtube_data = client.get_trends(source="youtube", keyword="bitcoin")
reddit_data = client.get_trends(source="reddit", keyword="bitcoin")
amazon_data = client.get_trends(source="amazon", keyword="wireless headphones")
```

--------------------------------

### Async support for concurrent requests

Source: https://github.com/trendsmcp/google-search-trends-api/blob/main/README.md

Use the AsyncTrendsMcpClient for non-blocking operations and concurrent platform queries.

```python
import asyncio
from google_search_trends_api import AsyncTrendsMcpClient, SOURCE

async def main():
    client = AsyncTrendsMcpClient(api_key="YOUR_API_KEY")
    series = await client.get_trends(source=SOURCE, keyword="bitcoin")
    print(series[0])

asyncio.run(main())
```

```python
google, youtube, reddit = await asyncio.gather(
    client.get_trends(source="google search", keyword="bitcoin"),
    client.get_trends(source="youtube",       keyword="bitcoin"),
    client.get_trends(source="reddit",        keyword="bitcoin"),
)
```

--------------------------------

### Integrate with Pandas

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Convert trend data points into a Pandas DataFrame for analysis and CSV export.

```python
import pandas as pd
from google_search_trends_api import TrendsMcpClient, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

# Get trend data
series = client.get_trends(source=SOURCE, keyword="bitcoin")

# Convert to DataFrame
df = pd.DataFrame([
    {"date": p.date, "value": p.value, "keyword": p.keyword, "source": p.source}
    for p in series
])

# Analyze trends
print(df.head())
print(f"Average: {df['value'].mean():.1f}")
print(f"Max: {df['value'].max()} on {df.loc[df['value'].idxmax(), 'date']}")
print(f"Min: {df['value'].min()} on {df.loc[df['value'].idxmin(), 'date']}")

# Export to CSV
df.to_csv("bitcoin_trends.csv", index=False)
```

--------------------------------

### Retrieve Top Trending Items

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Fetch top trending data from various platforms using the get_top_trends method.

```python
# Available feeds: Google Trends, YouTube, TikTok Trending Hashtags, Reddit Hot Posts,
# Amazon Best Sellers Top Rated, App Store Top Free, Wikipedia Trending, Spotify Top Podcasts, X (Twitter)
google_trending = client.get_top_trends(type="Google Trends", limit=5)
youtube_trending = client.get_top_trends(type="YouTube", limit=5)
reddit_trending = client.get_top_trends(type="Reddit Hot Posts", limit=5)

for item in google_trending.data:
    print(f"#{item[0]}: {item[1]}")
```

--------------------------------

### Handle API Errors with TrendsMcpError

Source: https://github.com/trendsmcp/google-search-trends-api/blob/main/README.md

Demonstrates how to catch and process specific errors from the TrendsMcp API, such as rate limiting. Ensure you have the TrendsMcpClient and TrendsMcpError classes imported.

```python
from google_search_trends_api import TrendsMcpClient, TrendsMcpError, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

try:
    series = client.get_trends(source=SOURCE, keyword="bitcoin")
except TrendsMcpError as e:
    print(e.status)   # e.g. 429 if you exceed your plan quota
    print(e.code)     # e.g. "rate_limited"
    print(e.message)
```

--------------------------------

### Handle API Errors

Source: https://context7.com/trendsmcp/google-search-trends-api/llms.txt

Use the TrendsMcpError exception to manage rate limits and authentication issues.

```python
from google_search_trends_api import TrendsMcpClient, TrendsMcpError, SOURCE

client = TrendsMcpClient(api_key="YOUR_API_KEY")

try:
    series = client.get_trends(source=SOURCE, keyword="bitcoin")
    print(f"Retrieved {len(series)} data points")
except TrendsMcpError as e:
    print(f"Status: {e.status}")    # HTTP status code (e.g., 429, 401, 400)
    print(f"Code: {e.code}")        # Error code (e.g., "rate_limited", "unauthorized")
    print(f"Message: {e.message}")  # Human-readable error description

    if e.status == 429:
        print("Rate limit exceeded. Upgrade plan or wait.")
    elif e.status == 401:
        print("Invalid API key. Get one at trendsmcp.ai")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.