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.
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.
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"])))| 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 |
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. |
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.
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.
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:
- Read
task_idfrom the body (also in theX-Task-Idheader). - Wait
Retry-Afterseconds. - Call
GET https://data.semust.com/v1/tasks/{task_id}with the same headers until the status is no longer202. 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 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. |
| 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.
- 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. - Seasonality and content calendars. Use five years of weekly data to see when demand peaks, and publish or update pages before it does.
- Regional demand. Find the states, provinces or regions where a topic is searched most, for local landing pages and ad targeting.
- Content ideas from rising searches. Turn rising related queries and topics into new articles, FAQs and product pages while competition is still low.
- 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.
- 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.
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.
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.
Up to five for interest, regions and demographics, at the same price as one. related takes one keyword per request.
The interval is still in progress, so its value will change. Leave partial points out when you compare periods or look for peaks.
Yes. Set search_type to youtube, news, images or shopping. The default is web.
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.
- Google Trends API documentation · Turkish documentation
- Keyword research API guide
- How to do keyword research (Turkish)
- Long-tail keywords guide (Turkish)
- Free SEO tools
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 |
- Email: destek@semust.com
- Contact form
- LinkedIn · YouTube · Instagram
Found a problem with an example? Open an issue.
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.

