# Google Trends (/docs/google_trends)

Google Trends Trending Now for a country or region with no keyword, interest over time for up to five keywords, and the rising and top related queries behind a trend

Search-demand data from Google Trends without scraping the site or fighting its rate limits: the Trending Now list for a country or region, with no keyword in; an interest-over-time series for up to five keywords compared head to head; and the related-query lists that tell you what is driving a trend. Every endpoint is 5 credits.

Base URL: `/v1/google_trends/...`

  The 0-100 numbers are an index, not a search volume, and each request is
  normalised to its own window. Two separate calls are not comparable. To
  compare terms, put all of them in one `explore` call.

## Quickstart

### 1. See what a market is searching for, with no keyword

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_trends/trending?location=DE&hours=24&sort=search_volume&limit=25" \
  -H "x-api-key: YOUR_API_KEY"
```

```json title="Response"
{
  "success": true,
  "data": {
    "items": [
      {
        "rank": 1,
        "title": "judith und mel",
        "search_volume": 50000,
        "increase_percent": 1000,
        "started_at": "2026-09-12T11:10:00.000Z",
        "ended_at": null,
        "active": true,
        "categories": ["entertainment"],
        "breakdown": ["mel jersey", "t online"],
        "news": [
          {
            "title": "Nach Herzinfarkt und Hausbrand: Schlagerstar schwer gestürzt",
            "url": "https://www.t-online.de/unterhaltung/stars/id_101432554/judith-und-mel-nach-herzinfarkt-und-hausbrand-schlagerstar-gestuerzt.html",
            "source": "T-Online",
            "domain": "t-online.de",
            "image_url": null,
            "published_at": "2026-09-12T09:44:47.000Z"
          }
        ]
      }
    ],
    "total": 431
  }
}
```

### 2. Size the trend

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_trends/explore?keywords=voice%20changer,reverse%20audio&timeframe=past_12_months&location=US" \
  -H "x-api-key: YOUR_API_KEY"
```

### 3. Find what is rising underneath it

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/google_trends/rising?keyword=voice%20changer&timeframe=past_90_days" \
  -H "x-api-key: YOUR_API_KEY"
```

## Trending now (no keyword)

| Endpoint                         | Credits | What it returns                                                                                                                          | Key parameters                                                         |
| -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `GET /v1/google_trends/trending` | 5       | The Trending Now list for one place: search volume, increase, start and end time, active status, categories, breakdown, and up to 3 news articles per trend | `location` (required), `hours`, `category`, `status`, `sort`, `limit` |

This is the same list trends.google.com/trending shows, and the filters are the ones that page offers. Use it when a keyword would bias what you find: you name a place and a window, and Google tells you what people there searched for.

- `location` is an ISO country code (`DE`), its English name (`Germany`), or an ISO 3166-2 region such as `DE-BY` or `US-CA`. Google covers 125 countries and has no worldwide list.
- `hours` is `4`, `24` (the default), `48`, or `168`. A trend is in the window when it started inside it.
- `category` takes Trending Now's own names (`sports`, `shopping`, `entertainment`, `technology`, and 15 more listed in the reference). These are not the numeric codes `explore` takes.
- `status=active` keeps only trends that are still trending. The default `all` also returns trends that have ended inside the window, with their `ended_at`.
- `sort` is `relevance` (Google's order, the default), `search_volume`, `recency`, or `title`. `rank` always keeps Google's relevance position, whatever order you ask for.
- `limit` is 1 to 500 and defaults to 100. `total` counts every trend that matched your filters, so `total` larger than the items you received means there is more in the window.

## Interest over time

| Endpoint                        | Credits | What it returns                                                                           | Key parameters                                                         |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `GET /v1/google_trends/explore` | 5       | Dated points scored 0-100 for each keyword, plus each keyword's average across the window | `keywords` (1-5, comma-separated), `timeframe`, `location`, `category` |

With more than one keyword the values are normalised **across the set**, which is what makes them directly comparable: the single highest point across all keywords in the window is the 100, and everything else is relative to it.

`category` scopes the query to one numeric Google Trends category code, defaulting to `0` for all categories. That matters for ambiguous terms. "jaguar" in the automotive category and "jaguar" overall are two different series.

## Rising and top related queries

| Endpoint                       | Credits | What it returns                                                                                               | Key parameters                                |
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `GET /v1/google_trends/rising` | 5       | Two lists: **rising** queries with their growth percentage, and **top** queries with a 0-100 popularity score | `keyword` (one only), `timeframe`, `location` |

Rising is where breakouts appear before they are big enough to move the main series. Top is what the demand is currently concentrated in.

It takes a single `keyword`, not a list, because Google Trends only returns related queries for one term at a time. The natural order is `explore` first to size a trend, then `rising` on the winner to find out what is behind it.

## All endpoints

## Platform notes

- **Trending Now volumes are buckets, not counts.** `search_volume` is the lower bound of Google's bucket, so `50000` means 50K+. `increase_percent` stops at `1000`, the largest figure Google shows. The list refreshes every few minutes and repeat calls inside 5 minutes are served from cache at 0 credits, so poll no faster than that.
- **An empty place is free.** A region or a short window with nothing trending returns `404` at 0 credits, and filters that match nothing return an empty list at 0 credits. Trending Now usually answers in under 2 seconds.
- **The 0-100 numbers are an index, not a volume.** Google publishes no absolute search counts, and neither `explore` nor `rising` returns one. Two separate requests are not comparable to each other, because each is normalised to its own window. To compare two terms, put both in one `explore` call rather than making two.
- **`timeframe` is a fixed preset list.** `past_hour`, `past_4_hours`, `past_day`, `past_7_days`, `past_30_days`, `past_90_days`, `past_12_months`, `past_5_years`. There is no arbitrary date range on this platform, and the default is `past_12_months`.
- **Short windows change the granularity.** `past_hour` and `past_4_hours` return minute-level points; `past_5_years` returns weekly ones. Do not assume a fixed point spacing when you chart the series.
- **For Korean demand, use Naver instead.** Google Trends underrepresents Korea because Naver carries much of the search volume there. [`/v1/naver/search-trend`](/docs/naver.md) is the equivalent, with the same relative-index caveat.
- `location` accepts an ISO country code (`US`), a full name (`United States`), or a numeric code (`2840`).
- **Set a client timeout of at least 60 seconds for `explore` and `rising`.** They are the slowest synchronous surface on the API: measured over 14 days of production traffic a billed refresh averages about 17 seconds and the slow tail reaches about 47. Repeat calls inside the 2-minute cache return in milliseconds at 0 credits.
- Each point carries `partial`. It is `true` on a bucket Google is still accumulating, normally the most recent one, so drop it before charting a trend rather than reading it as a fall in interest.
- A keyword with no measurable volume returns `404` and costs 0 credits, rather than a billed empty series. Send several keywords and the call still succeeds as long as one of them has data.

## Next steps

- [Naver](/docs/naver.md): Korean search-volume and shopping-click trends, where Google under-reads.
- [Content Analysis](/docs/content_analysis.md): Cross-web mention volume and sentiment for the same keyword.
- [Credits](/docs/credits.md): How billing, caching, and refunds work.