Skip to content

About

Google Trends API: interest over time for up to 5 keywords, interest by region, related queries and topics, and age and gender estimates as structured JSON for any country, period and search type. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Google Trends API

Semust Google Trends API: Google Trends data as JSON

Get API key Documentation MCP server License: MIT

The Semust Google Trends API returns Google Trends data as clean, structured JSON: interest over time for up to five keywords on one scale, interest by region, related queries and topics, plus age and gender estimates. Pick a country, a period from the past day to the past five years, and the Google property to measure (web, news, images, YouTube or Shopping). No CSV downloads, rate-limit workarounds or HTML parsing on your side.

It is built for SEO teams, analysts and developers who need keyword trend research, seasonality planning, regional demand data and content ideas from rising searches. The API is part of the Semust SEO platform.

How it works

Your code sends POST /v1/trends to Semust and receives Google Trends data as JSON. Long requests return 202 and are collected from /v1/tasks.

1. Get your API credentials

Create an API user on the Semust API access page. You get a username and a password. Every request sends them as two headers:

Header Value
SEMUST-API-USER Your API username
SEMUST-API-PASSWORD Your API password

The examples in this repository read them from environment variables, so they never end up in your code:

export SEMUST_API_USER="your_username"
export SEMUST_API_PASSWORD="your_password"

Tip

There is no subscription. You top up a prepaid balance and pay only for successful requests; failed requests are refunded automatically. Prices are on the Google Trends API page.

2. Send a request

import os, time, requests

HEADERS = {
    "SEMUST-API-USER": os.environ["SEMUST_API_USER"],
    "SEMUST-API-PASSWORD": os.environ["SEMUST_API_PASSWORD"],
}

resp = requests.post(
    "https://data.semust.com/v1/trends",
    params={"wait": 60},
    headers=HEADERS,
    json={"type": "interest", "keywords": ["seo", "ai search"], "country": "US", "period": "past_12_months"},
    timeout=90,
)
while resp.status_code == 202:  # still running: poll the task
    time.sleep(int(resp.headers.get("Retry-After", 5)))
    resp = requests.get(resp.json()["poll_url"], headers=HEADERS, timeout=30)

data = resp.json()
for point in data["items"]:
    print(point["time"][:10], dict(zip(data["keywords"], point["values"])))

3. Run the examples

Language File Run
Python examples/python/trends.py python trends.py "seo" "ai search"
Python, comparison to CSV examples/python/compare_trends.py python compare_trends.py "seo" "ai search" --period past_5_years
Node.js 18+ examples/node/trends.mjs node trends.mjs "seo" "ai search"
Go examples/go/main.go go run . "seo" "ai search"
PHP examples/php/trends.php php trends.php "seo" "ai search"
cURL examples/curl/trends.sh ./trends.sh

Request parameters

POST https://data.semust.com/v1/trends with a JSON body. One endpoint serves four reports, chosen with type:

type Returns Keywords
interest (default) Interest over time, one point per interval, plus each keyword's average 1–5
regions Interest by region, and how the keywords split each region's searches 1–5
related Top and rising related queries and related topics 1
demographics Interest by age group and gender (estimates) 1–5
Parameter Type Default Description
type string interest interest, regions, related or demographics.
keywords (required) string[] – 1–5 keywords to compare (related: exactly one). Each up to 100 characters, without commas. Repeats that differ only in case are dropped.
country string TR Two-letter country code. Send it explicitly; the default is Türkiye.
language string tr for TR, else en Not for demographics. Language of region names and related topics; it does not change which searches are counted.
period string past_12_months past_day, past_7_days, past_30_days, past_90_days, past_12_months or past_5_years.
search_type string web Not for demographics. Where searches are counted: web, news, images, youtube or shopping.
idempotency_key string – Optional, up to 128 characters. Same as the Idempotency-Key header; if you send both, this field wins.

A parameter the chosen type does not take is rejected with PARAMETER_NOT_ALLOWED instead of being ignored, and a misspelled one is named in the error with a suggestion. GET https://data.semust.com/v1/trends/markets lists every supported country and language, free of charge.

Query parameter Default Description
wait 60 Seconds to hold the connection before answering 202, 0–80. 0 answers 202 at once (fire and collect).
Header Description
Idempotency-Key Optional, up to 128 characters. Repeating a request with the same key returns the same task and is charged once.
Accept-Language Optional. tr returns error messages in Turkish.

Output sample

Google Trends interest over time for "seo" and "ai search" returned by the Semust Google Trends API

A shortened response for {"type": "interest", "keywords": ["seo", "ai search"], "country": "US", "period": "past_12_months"}. Lists are cut to two items; the complete response, 53 weekly points, is in output-google-trends-scraper.json. The per-call request_id is removed from the sample file.

{
  "success": true,
  "type": "interest",
  "keywords": [
    "seo",
    "ai search"
  ],
  "country": "US",
  "language": "en",
  "period": "past_12_months",
  "search_type": "web",
  "averages": [
    56,
    20
  ],
  "count": 53,
  "items": [
    {
      "time": "2025-11-16T00:00:00Z",
      "values": [
        57,
        17
      ],
      "partial": false
    },
    {
      "time": "2025-11-23T00:00:00Z",
      "values": [
        63,
        14
      ],
      "partial": false
    }
  ],
  "cost": 0.0121,
  "cached": false
}

Every per-keyword list (averages, values, interest, share) is in the same order as keywords, so you can read it by position.

JSON output structure

Envelope (every type)

Field Type Description
success boolean true for a successful request.
type string The report that ran.
keywords string[] The keywords as run, after duplicates were removed.
country, period string Market and period of the request.
language, search_type string Not for demographics. Language and Google property.
averages (integer | null)[] interest only. Each keyword's average over the period.
count integer Rows in items.
items array interest, regions and demographics rows.
data object related result.
cost number What this request cost, in USD.
cached boolean true when the answer came from cache.
request_id string Identifier of this request; quote it when you contact support.

interest row

Field Type Description
time string Start of the interval, ISO 8601 in UTC. Minutes for past_day, hours for past_7_days, days or weeks for longer periods (weeks for past_12_months).
values (integer | null)[] Interest per keyword, 0–100. 100 is the highest point of any keyword in the period, so keywords compare directly. null where there is no data.
partial boolean true for an interval still in progress; its value will change.

regions row

Field Type Description
region string Region name, in language.
region_code string | null ISO 3166-2 code, such as TR-34.
interest (integer | null)[] Each keyword's interest in this region, 0–100 on its own scale (100 is that keyword's strongest region).
share (integer | null)[] | null How the keywords split this region's searches, in percent. null for a single keyword.

related → data

Field Type Description
top_queries, rising_queries array Searches made alongside the keyword, each {query, value}.
top_topics, rising_topics array Topics searched alongside the keyword, each {topic, category, value}; category is the kind of topic, in language.

In the top lists value is relative interest, 0–100. In the rising lists it is growth over the previous period, in percent.

demographics row

Field Type Description
keyword string The keyword.
age array Age bands, each {group, value}, such as {"group": "25-34", "value": 97}.
gender array {group, value} for female and male.

Values are 0–100 against the keyword's largest group. A keyword without data has empty lists.

Long-running requests (202 and polling)

Most requests finish in a few seconds and return 200 with the result. If a request is still running after wait seconds (60 by default, maximum 80), the API returns 202 Accepted with a task_id instead. Nothing is lost and you are not charged twice:

  1. Read task_id from the body (also in the X-Task-Id header).
  2. Wait Retry-After seconds.
  3. Call GET https://data.semust.com/v1/tasks/{task_id} with the same headers until the status is no longer 202. The final answer is exactly what the original request would have returned.

Every example in examples/ already handles this. Results stay available for 72 hours, and fetching them again is free. Set your HTTP client's read timeout above wait (for example wait + 30 seconds). Send an Idempotency-Key header to retry a request safely without paying twice. Details: Tasks & long-running requests.

Errors

Errors return JSON with a readable error, a stable code and retryable; where it helps also field, hint and allowed. Errors are never charged.

HTTP code Meaning
400 INVALID_JSON, UNKNOWN_PARAMETER, INVALID_TYPE, PARAMETER_NOT_ALLOWED, INVALID_PARAMETER The body is not a JSON object, a parameter is misspelled or not taken by this type, or a value is invalid (a keyword with a comma, an unknown period). field names it and allowed lists the valid values.
400 KEYWORDS_REQUIRED, TOO_MANY_KEYWORDS No keywords, more than 5, or more than one for related.
400 UNSUPPORTED_MARKET Unknown country or language. GET /v1/trends/markets lists them.
401 MISSING_CREDENTIALS, INVALID_CREDENTIALS, CREDENTIALS_EXPIRED Check the two auth headers.
402 INSUFFICIENT_CREDITS Top up your balance.
403 IP_NOT_WHITELISTED, SERVICE_NOT_ENABLED Your API user only accepts listed IP addresses, or Trends is not enabled for it.
429 RATE_LIMIT_EXCEEDED, TOO_MANY_CONCURRENT_REQUESTS Slow down. At most 5 Trends requests per API user run at the same time; wait Retry-After seconds.
503 REQUEST_FAILED, SERVICE_BUSY, SERVICE_UNAVAILABLE, TIMEOUT Temporary failure. If retryable is true, retry with the same Idempotency-Key.

Pricing

Report Price
interest, regions, related $0.0121 per request
demographics $0.00264 per request

The price is flat: comparing five keywords costs the same as one, whatever the period or search type. A keyword with no data is a valid answer (empty items, null values) and is billed like any other. Answers are cached for 1 hour (past_day), 6 hours (past_7_days) or 24 hours (longer periods); a cached answer is marked "cached": true and costs the same as a live one. Failed requests are refunded automatically. Current prices are on the Google Trends API page.

Use cases

  1. Keyword trend research. Compare up to five keywords on one scale and see which one is growing before you commit content to it. Start from compare_trends.py.
  2. Seasonality and content calendars. Use five years of weekly data to see when demand peaks, and publish or update pages before it does.
  3. Regional demand. Find the states, provinces or regions where a topic is searched most, for local landing pages and ad targeting.
  4. Content ideas from rising searches. Turn rising related queries and topics into new articles, FAQs and product pages while competition is still low.
  5. Market and product research. Track brands, products or categories on web, news, YouTube or Shopping search, and add age and gender estimates to audience profiles.

Why Semust

  • Pay as you go. No monthly plan or minimum commitment for the API. Top up once, pay per successful request, and get failed requests refunded automatically.
  • One account, every SEO dataset. SERP, keyword data, backlinks, domain research, YouTube, Google Trends, Lighthouse and Google Business data use the same credentials, the same error format and the same task system.
  • Any country, any language. Localised results for every Google market, including strong coverage of Türkiye and Turkish-language queries.
  • Built for AI workflows. Plug the same data into Claude, Cursor or ChatGPT with the open-source Semust MCP server.

FAQ

Is collecting Google Trends data legal?

Google Trends data is publicly available, and collecting public data is generally lawful in many jurisdictions. Laws differ by country, and how you store and use the data matters. Check the rules that apply to you, or ask a lawyer. This is not legal advice.

Are the values search volumes?

No. Google Trends values are relative interest on a 0–100 scale, not search counts. In interest, 100 is the highest point of any requested keyword in the period, so the keywords can be compared directly. For absolute monthly search volumes, use the Semust Keyword Research API.

How many keywords can I compare in one request?

Up to five for interest, regions and demographics, at the same price as one. related takes one keyword per request.

Why does the last point say partial?

The interval is still in progress, so its value will change. Leave partial points out when you compare periods or look for peaks.

Can I get trends for YouTube, News or Shopping searches?

Yes. Set search_type to youtube, news, images or shopping. The default is web.

Can I use it from Claude, ChatGPT or Cursor?

Yes, through a tool your agent can call: the Python example is a ready-made starting point. The Semust MCP server also connects AI assistants to your Semust account data; see Semust MCP for what it covers.

Learn more

Related repositories

SEO data APIs

Repository What it does Product page
google-serp-scraper Organic results, People Also Ask, AI Overviews, ads and more as JSON Google SERP API
google-images-scraper Google Images results with titles, source pages and image URLs Google Images API
youtube-scraper YouTube search, video details, transcripts and comments YouTube API
google-business-scraper Google Business profiles, local search and reviews Google Business Data API
keyword-research-api Search volume, CPC, competition, intent and related keywords Keyword Research API
backlinks-api Backlinks, referring domains, anchors and link history Backlinks API
domain-research-api Organic keywords, competitors, top pages and keyword gaps for any domain Domain Research API
technical-seo-api 27 technical SEO checks for any URL in one call Technical SEO API
lighthouse-on-page-api Lighthouse scores, on-page audits and page content extraction Lighthouse & On-Page API

MCP servers for AI assistants

Repository What it does Product page
semust-mcp One MCP server for Search Console, GA4, Google Ads, rank tracking and social posting Semust MCP Server
seo-mcp Search Console, rank tracking, indexing and competitor tools for AI assistants SEO MCP
google-search-console-mcp Ask your AI assistant about clicks, queries and pages Google Search Console MCP
google-analytics-mcp GA4 traffic, channels and conversions in your AI assistant Google Analytics MCP
google-ads-mcp Campaigns, search terms and spend in your AI assistant Google Ads MCP
rank-tracker-mcp Keyword rankings and AI-search visibility for AI assistants Rank Tracker MCP
web-analytics-mcp Privacy-friendly first-party analytics in your AI assistant Web Analytics MCP
bing-webmaster-mcp Bing queries, pages, links and crawl issues Bing Webmaster MCP
yandex-metrica-mcp Yandex Metrica traffic and search phrases Yandex Metrica MCP
social-media-mcp Draft and schedule LinkedIn, Facebook and Instagram posts Social Media MCP

Support

Found a problem with an example? Open an issue.

License

The code examples in this repository are released under the MIT License. Use of the Semust API is subject to the Semust Terms of Service.

About

Google Trends API: interest over time for up to 5 keywords, interest by region, related queries and topics, and age and gender estimates as structured JSON for any country, period and search type. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors