# Google Trends (/docs/google_trends)



Google Trends [#google-trends]

Search-demand data from Google Trends without scraping the site or fighting its rate limits: an
interest-over-time series for up to five keywords compared head to head, and the related-query
lists that tell you what is actually driving a trend. Both endpoints are 5 credits.

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

<Callout>
  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.
</Callout>

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header.

```bash
# How big is this term, and how does it compare?
curl "https://www.socialcrawl.dev/v1/google_trends/explore?keywords=voice%20changer,reverse%20audio&timeframe=past_12_months&location=US" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# What is rising underneath it?
curl "https://www.socialcrawl.dev/v1/google_trends/rising?keyword=voice%20changer&timeframe=past_90_days" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Interest over time [#interest-over-time]

`GET /v1/google_trends/explore` takes 1-5 comma-separated `keywords` and returns dated points
scored 0-100 for each, plus each keyword's average across the window. 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 [#rising-and-top-related-queries]

`GET /v1/google_trends/rising` expands one keyword into two lists: **rising** queries with their
growth percentage, and **top** queries with a 0-100 popularity score. Rising is where breakouts
appear before they are big enough to move the main series, and 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.

Endpoints [#endpoints]

<PlatformEndpoints platform="google_trends" />

Read this before you build [#read-this-before-you-build]

**The 0-100 numbers are an index, not a volume.** Google publishes no absolute search counts,
and neither endpoint returns one. Two separate requests are not comparable to each other,
because each is normalised to its own window. If you need 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.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `location` accepts an ISO country code (`US`), a full name (`United States`), or a numeric
  code (`2840`)
* A keyword with no measurable volume returns an empty series rather than an error