POST /search_google_trends • Credits: 1 credit per call
The Google Trends API returns the search interest of one keyword on Google, for one country and one date range. The response holds four data sets: timeline (interest over time), related (top related queries), rising (fast-growth related queries), and interest_by_region. Google Trends costs 1 credit per call, and 1 credit costs $0.02 on the 1,000 and 5,000 credit packs.
What does the Google Trends API do?
The Google Trends API answers one question: how much do people search for this term, and how does that number move over time. RichAPI reads the data from Google Trends and returns it as JSON. A single call covers one keyword, one geo value, and one timeframe value. The endpoint is synchronous, so the data arrives in the same response. Typical response time is 2 to 5 seconds. Every score in the response is a relative score on a 0 to 100 scale, not a search count.
Which endpoint does Google Trends use?
Method:
POSTURL:
https://api.richapi.ai/api/v1/search_google_trendsAuthentication:
x-api-keyheaderResponse: synchronous JSON
Credits: 1 credit per call
How to send a Google Trends request
Copy your API key from the RichAPI dashboard.
Set the
keywordparameter to the search term to measure.To limit the data to one country, set
geoto a country code.To change the date range, set
timeframeto an accepted value.Send a
POSTrequest tohttps://api.richapi.ai/api/v1/search_google_trends.Send the API key in the
x-api-keyheader.Read
data.timelinefor the interest scores over time.Read
data.risingfor the queries that grow fastest.
CAUTION: Send one keyword per call. RichAPI charges 1 credit for every 200 response, and a keyword with too little search data also costs 1 credit.
cURL
curl -X POST https://api.richapi.ai/api/v1/search_google_trends
-H "x-api-key: YOUR_API_KEY"
-H "Content-Type: application/json"
-d '{
"keyword": "ai agents",
"geo": "US",
"timeframe": "today 12-m"
}'
Python
import requests
response = requests.post(
"https://api.richapi.ai/api/v1/search_google_trends",
headers={"x-api-key": "YOUR_API_KEY"},
json={
"keyword": "ai agents",
"geo": "US",
"timeframe": "today 12-m",
},
timeout=60,
)
response.raise_for_status()
print(response.json())
Node.js
const response = await fetch("https://api.richapi.ai/api/v1/search_google_trends", {
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
keyword: "ai agents",
geo: "US",
timeframe: "today 12-m",
}),
});
const data = await response.json();
console.log(data);
Which parameters does the Google Trends API accept?
The table holds the fields of the HTTP request body. Send these names to https://api.richapi.ai/api/v1/search_google_trends. RichAPI rejects any other field name with a 400 error that names the unknown field.
Parameter | Type | Required | Default | Description |
| string | Yes | None | The search term to measure. One keyword per call. |
| string | No |
| A country code such as |
| string | No |
| The date range. The next table lists the six accepted values. |
The request body accepts these three fields and no other field. A body with any other key returns 400 Unknown input field(s), and the message names the key. A cache key is one such key. Older RichAPI reference material lists cache as a parameter, and the live endpoint does not accept it. A request with "cache": true returns 400 Unknown input field(s): cache.
The dashboard, the MCP tool search_google_trends, and the n8n operation search_google_trends use the same three names, so no name mapping applies.
Which timeframe values does the Google Trends API accept?
| Date range |
| The last day |
| The last 7 days |
| The last month |
| The last 3 months |
| The last 12 months. This is the default. |
| The last 5 years |
RichAPI passes the timeframe value to Google Trends without a check. An unknown value returns a 502 error and costs 0 credits.
The timeframe value also sets the size of each point in timeline. A 12-month range returns one point per week. A short range such as now 7-d returns one point per hour, and the API formats every point as a date. For a short range, several points therefore carry the same date value.
Which geo values does the Google Trends API accept?
The geo parameter takes a country code such as US, GB or DE.
Request |
|
|
|
|
|
|
|
|
|
RichAPI removes an empty value from the request before the call, so the default US applies. Worldwide data is therefore not available from this endpoint. The interest_by_region list holds the regions inside the geo country. For geoUS, the regions are the US states.
What does the Google Trends API return?
The next block is an example. It shows the response shape for the request body in the code samples above.
{
"data": {
"keyword": "ai agents",
"geo": "US",
"timeframe": "today 12-m",
"timeline": [
{ "date": "2025-08-10", "value": 38 },
{ "date": "2025-08-17", "value": 41 },
{ "date": "2025-11-16", "value": 67 },
{ "date": "2026-03-01", "value": 84 },
{ "date": "2026-08-02", "value": 100 }
],
"related": [
{ "query": "ai agents examples", "value": 100 },
{ "query": "best ai agents", "value": 62 },
{ "query": "ai agent framework", "value": 38 }
],
"rising": [
{ "query": "claude ai agents", "value": "Breakout" },
{ "query": "ai agent pricing", "value": 350 }
],
"interest_by_region": [
{ "region": "California", "value": 100 },
{ "region": "Washington", "value": 87 },
{ "region": "New York", "value": 74 }
]
},
"meta": {
"cache_hit": false,
"execution_time_ms": 3480,
"quality_warning": null
}
}
Which fields does the Google Trends response hold?
Field | Type | Description |
| string | The keyword that RichAPI sent to Google Trends. |
| string | The country code that RichAPI sent to Google Trends. |
| string | The date range that RichAPI sent to Google Trends. |
| array of objects | Interest over time. One object per date point. The array is empty for a keyword with too little search data. |
| string | The date of the point, in |
| integer | The relative interest score of that date, from |
| array of objects | The top related queries of the keyword. |
| string | The related query text. |
| integer | The relative score of the related query, from |
| array of objects | The related queries with the fastest growth in the date range. |
| string | The query text. |
| integer or string | The rise score from Google Trends. The value is the string |
| array of objects | Interest per region, from the highest score to the lowest. A region with a score of |
| string | The region name. |
| integer | The relative interest score of the region. |
| boolean |
|
| integer | The time that the call took, in milliseconds. |
| string or null | A warning about the result quality. |
What do the Google Trends numbers mean?
Every value in the response is a relative score. It is not a search count, and it is not a search volume. Google Trends divides the searches for the keyword by the total searches of the region and the period, then scales the result.
Score | Meaning |
| The peak point of the keyword in that date range and that region. |
| Half the search share of the peak point. |
| Too little data for the keyword at that point. |
Three consequences follow from the relative scale:
A score of
100means a peak, not a volume. Two keywords with100can differ by a factor of 1,000 in real searches.The same date returns a different score for a different
timeframe, because the peak of the range changes.Scores from two separate calls are not comparable. Google Trends scales each call against its own peak.
To rank two keywords against each other, do not compare the two responses. Google Trends compares terms only inside one query, and this endpoint takes one keyword per call.
How to use the Google Trends API for market research
The Google Trends API answers demand questions before a launch, and it costs 1 credit per answer.
Question | Field to read | How to read it |
Does interest in this category grow or fall? |
| Compare the first points of the array against the last points. |
Is the demand seasonal? |
| Look for the same peak month in each year. |
What do buyers search for next to my term? |
| The top entries name the established demand. |
Which new terms grow fastest? |
| A |
Where do I launch first? |
| The first entries hold the regions with the highest interest. |
A practical loop for a market study:
Send one call per candidate keyword with
timeframetoday 5-y, and read the seasonality.Send the same keywords with
timeframetoday 12-m, and read the current direction.Collect the
data.risingqueries of every keyword, and treat them as a list of new terms.Send one call per new term, and confirm the direction of each one.
Ten keywords across two date ranges cost 20 credits, that is $0.40.
Does the Google Trends API cache a response?
Yes. The Google Trends cache is always on, and the caller cannot turn it off. The request body accepts no cache field, so every call uses the cache.
Cache state: always on
Cache lifetime: 1 hour
Cache key: the
keywordvalue, thegeovalue and thetimeframevalue togetherCache indicator:
meta.cache_hitin the response
The first call for a keyword reads Google Trends and stores the result. A second call with the same keyword, geo and timeframe returns the stored result, and meta.cache_hit is true. If the stored result is older than 1 hour, RichAPI reads Google Trends again and stores the new result. A cached response still costs 1 credit, because RichAPI bills every 200 response.
How much does the Google Trends API cost?
The Google Trends API costs 1 credit per call, and 1 credit costs $0.02 on the 1,000 and 5,000 credit packs. Larger packs cost less per credit. The charge is flat. A response with 260 timeline points and a response with 0 timeline points both cost 1 credit. RichAPI charges the credit on a 2xx response only.
Calls | Credits | Cost |
1 | 1 | $0.02 |
10 | 10 | $0.20 |
100 | 100 | $2.00 |
1,000 | 1,000 | $20.00 |
10,000 | 10,000 | $200.00 |
Which errors can the Google Trends API return?
Status | Meaning | What to do |
| The request body holds an unknown field, | Send a JSON object with |
| The API key is missing, wrong or revoked. | Send a valid key in the |
|
| Buy credits in the RichAPI dashboard, or ask the organization owner to raise the spend limit. |
|
| Call |
| The endpoint name is wrong. | Send the request to |
| The request used a method other than | Send the request with |
| Your organization's rate limit was exceeded ( | Wait for the |
| The API failed. | Send the request again. If the failure repeats, contact support. |
| Google Trends data is not available, or the | Check the |
| Google Trends did not answer in time. | Send the request again after a short wait. |
Every error response holds an error field with the reason. RichAPI charges credits on a 2xx response only. A 400, 401, 402, 403, 404, 405, 429, 500, 502 or 504 response costs 0 credits.
Frequently asked questions
What do the Google Trends numbers mean?
Every score in the Google Trends response is relative, on a 0 to 100 scale, and it is not a count of searches. A score of 100 marks the peak point of the keyword inside the requested date range and region. A score of 50 marks half the search share of that peak.
How much does the Google Trends API cost?
The Google Trends API costs 1 credit per call, and 1 credit costs $0.02 on the 1,000 and 5,000 credit packs. The price is flat per call, so the number of timeline points, related queries and regions in the response does not change the charge.
Can the Google Trends API compare two keywords in one call?
No. The Google Trends API takes one keyword per call, and two keywords need two calls. The two responses are not comparable, because Google Trends scales each response against its own peak.
Can the Google Trends API return worldwide data?
No. The geo parameter defaults to US, and RichAPI removes an empty geo value before the call. Every response therefore covers one country.
Why is the timeline array empty?
Google Trends returns no data for a keyword with too little search traffic. In that case the Google Trends API returns a 200 response with empty timeline, related, rising and interest_by_region arrays, and the call costs 1 credit.
Does a cached Google Trends response cost a credit?
Yes. RichAPI charges 1 credit for every 200 response, and a cached response is a 200 response. The meta.cache_hit field is true for a cached response, and the cache lifetime is 1 hour. The request body accepts no cache field, so the caller cannot turn the cache off.
What does a Breakout value mean in the rising list?
Google Trends reports the string Breakout in place of a number for the queries with the fastest growth in the date range. The Google Trends API passes that string through, so data.rising[].value is an integer or the string Breakout.