# Trends Data

> Source: https://scrape.do/documentation/google-scraper-api/trends/trends/

Get search interest over time, by region, related queries, and related topics

Returns Google Trends data for a keyword: interest over time, interest by region, related queries, and related topics.

**Endpoint:** `GET https://api.scrape.do/plugin/google/trends`

---

## Parameters

### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | string | Your Scrape.do API token |
| `q` | string | Search keyword (e.g., `bitcoin`, `climate change`) |

### Optional

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `geo` | string | *(worldwide)* | Location code. Defaults to worldwide when empty. Examples: `US`, `GB`, `DE`, `US-CA` |
| `hl` | string | `en` | Language code for the interface (e.g., `en`, `es`, `fr`) |
| `date` | string | `today 12-m` | Time range. Examples: `today 12-m`, `today 3-m`, `today 5-y`, `2024-01-01 2024-12-31` |
| `tz` | string | `420` | Timezone offset in minutes from UTC |
| `data_type` | string | *(default)* | Widget filter. See table below. When omitted, returns TIMESERIES + GEO_MAP |
| `cat` | string | *(all)* | Category ID to narrow results (e.g., `71` for Food & Drink) |
| `gprop` | string | *(web search)* | Google property. Options: *(empty)* for Web Search, `images`, `news`, `youtube`, `froogle` |
| `region` | string | *(auto)* | Granularity for geo data: `COUNTRY`, `REGION`, `DMA`, `CITY` |

### `data_type` Options

| Value | Description |
|-------|-------------|
| *(omitted)* | Returns TIMESERIES + GEO_MAP (default) |
| `TIMESERIES` | Interest over time only |
| `GEO_MAP` | Compared breakdown by region (multiple queries) |
| `GEO_MAP_0` | Interest by region (single query only) |
| `RELATED_QUERIES` | Related queries (single query only) |
| `RELATED_TOPICS` | Related topics (single query only, uses separate embed endpoint) |

> [!NOTE]
> `RELATED_QUERIES` and `RELATED_TOPICS` are not included in the default response. Request them explicitly with `data_type=RELATED_QUERIES` or `data_type=RELATED_TOPICS`.

---

## Example Requests

```bash
# Default: interest over time + regional breakdown, US, last 12 months
curl "https://api.scrape.do/plugin/google/trends?q=bitcoin&token=YOUR_TOKEN&geo=US"

# Interest over time only
curl "https://api.scrape.do/plugin/google/trends?q=bitcoin&token=YOUR_TOKEN&geo=US&data_type=TIMESERIES"

# Regional breakdown at city level
curl "https://api.scrape.do/plugin/google/trends?q=bitcoin&token=YOUR_TOKEN&geo=US&data_type=GEO_MAP_0&region=CITY"

# Related queries
curl "https://api.scrape.do/plugin/google/trends?q=bitcoin&token=YOUR_TOKEN&geo=US&data_type=RELATED_QUERIES"

# Related topics
curl "https://api.scrape.do/plugin/google/trends?q=bitcoin&token=YOUR_TOKEN&geo=US&data_type=RELATED_TOPICS"

# YouTube trends, last 3 months
curl "https://api.scrape.do/plugin/google/trends?q=bitcoin&token=YOUR_TOKEN&geo=US&gprop=youtube&date=today%203-m"

# Last 5 years
curl "https://api.scrape.do/plugin/google/trends?q=bitcoin&token=YOUR_TOKEN&geo=US&date=today%205-y"
```

---

## Responses

### Default (no `data_type`)

Returns weekly interest over time and regional breakdown.

```json
{
  "search_parameters": {
    "q": "bitcoin",
    "geo": "US",
    "hl": "en",
    "date": "today 12-m",
    "tz": "420"
  },
  "interest_over_time": {
    "timeline_data": [
      {
        "date": "Apr 6 – 12, 2025",
        "timestamp": "1743897600",
        "values": [
          {
            "query": "bitcoin",
            "value": "40",
            "extracted_value": 40
          }
        ]
      },
      {
        "date": "Feb 1 – 7, 2026",
        "timestamp": "1769904000",
        "values": [
          {
            "query": "bitcoin",
            "value": "100",
            "extracted_value": 100
          }
        ]
      }
    ]
  },
  "interest_by_region": [
    {
      "geo": "US-HI",
      "location": "Hawaii",
      "max_value_index": 0,
      "value": "100",
      "extracted_value": 100
    },
    {
      "geo": "US-NV",
      "location": "Nevada",
      "max_value_index": 0,
      "value": "99",
      "extracted_value": 99
    }
  ]
}
```

### `data_type=RELATED_QUERIES`

```json
{
  "search_parameters": {
    "q": "bitcoin",
    "geo": "US",
    "hl": "en",
    "date": "today 12-m",
    "tz": "420",
    "data_type": "RELATED_QUERIES"
  },
  "related_queries": {
    "top": [
      {
        "query": "bitcoin price",
        "value": "100",
        "extracted_value": 100,
        "link": "https://trends.google.com/trends/explore?q=bitcoin+price&date=today+12-m&geo=US"
      }
    ],
    "rising": [
      {
        "query": "how to buy bitcoin safely",
        "value": "Breakout",
        "extracted_value": 9750,
        "link": "https://trends.google.com/trends/explore?q=how+to+buy+bitcoin+safely&date=today+12-m&geo=US"
      }
    ]
  }
}
```

### `data_type=RELATED_TOPICS`

```json
{
  "search_parameters": {
    "q": "bitcoin",
    "geo": "US",
    "hl": "en",
    "date": "today 12-m",
    "tz": "420",
    "data_type": "RELATED_TOPICS"
  },
  "related_topics": {
    "top": [
      {
        "topic": {
          "value": "/m/0vpj4_b",
          "title": "Bitcoin",
          "type": "Cryptocurrency"
        },
        "value": "100",
        "extracted_value": 100,
        "link": "https://trends.google.com/trends/explore?q=/m/0vpj4_b&date=today+12-m&geo=US"
      }
    ],
    "rising": [
      {
        "topic": {
          "value": "/g/11g8vsrxcc",
          "title": "NVIDIA",
          "type": "Topic"
        },
        "value": "Breakout",
        "extracted_value": 71150,
        "link": "https://trends.google.com/trends/explore?q=/g/11g8vsrxcc&date=today+12-m&geo=US"
      }
    ]
  }
}
```

---

## Response Fields

### `interest_over_time.timeline_data[]`

Weekly data points, normalized 0–100 relative to the peak. A value of `100` is the peak popularity for the time period. A value of `50` means half as popular.

| Field | Type | Description |
|-------|------|-------------|
| `date` | string | Human-readable date range |
| `timestamp` | string | Unix timestamp (start of period) |
| `values[].query` | string | The search keyword |
| `values[].value` | string | Normalized interest value (0–100) |
| `values[].extracted_value` | integer | Numeric version of value |

### `interest_by_region[]`

Breakdown by region (state, country, city depending on `geo` and `region` params).

| Field | Type | Description |
|-------|------|-------------|
| `geo` | string | Google region code (e.g., `US-CA`) |
| `location` | string | Human-readable location name |
| `value` | string | Normalized interest value (0–100) |
| `extracted_value` | integer | Numeric version of value |

### `related_queries`

Only returned when `data_type=RELATED_QUERIES`.

- **`top`**: Most popular related queries ranked by search volume
- **`rising`**: Queries with the biggest increase in frequency. `"Breakout"` means >5000% growth

### `related_topics`

Only returned when `data_type=RELATED_TOPICS`. Same structure as related queries but with topic entities (Knowledge Graph title, type, ID).