{
"openapi": "3.0.1",
"info": {
"title": "Google Trends Scraper — Google Trends Data, Interest Over Time",
"description": "Google Trends data as JSON: interest over time, related queries and region breakdown by default; compare, related topics (billed as its own report) and trending now on request. One row per keyword and surface, API and MCP ready. No start fee, no minimum, never charged for a failed or empty fetch.",
"version": "1.1",
"x-build-id": "0gdkhw3Ee0ZK5IyVL"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/steadyfetch~google-trends-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-steadyfetch-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/steadyfetch~google-trends-scraper/runs": {
"post": {
"operationId": "runs-sync-steadyfetch-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/steadyfetch~google-trends-scraper/run-sync": {
"post": {
"operationId": "run-sync-steadyfetch-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"properties": {
"searchTerms": {
"title": "Search terms",
"type": "array",
"description": "Keywords to look up, one per entry, e.g. [\"bitcoin\", \"ethereum\"] — up to 300 per run. A failed, blocked or empty fetch is never charged; it is named in the run's ERRORS record. Leave this empty and set \"Category ID\" instead and the run explores that whole category rather than a keyword. Send more than 300 and the run still starts: it uses the first 300 and writes one uncharged row saying what you asked for and what bound it, so run the rest separately. Each term is fetched independently unless Compare is on. Pricing: you are billed at most one trend report per term — one keyword's full timeline, its complete related-queries set and its region table settle together as ONE report, however many of those three you ask for, so all three cost the same as one. Related topics is a separate event, billed on its own. Omit the field entirely (an API call with no input) and the run takes a real, small sample instead — one example keyword (\"bitcoin\") on the three default surfaces, worldwide, over the last 12 months, inside a three-minute window, charged like any run at one trend report. Change a setting but still leave this empty and you get that SAME live sample, run under what you set — your location, time range, category, search property and choice of surfaces — with one uncharged note naming the settings it ran under. The one thing it cannot do is compare, which needs 2-5 of your own terms: that asks you for search terms on an uncharged row instead.",
"items": {
"type": "string"
}
},
"surfaces": {
"title": "Data surfaces",
"type": "array",
"description": "Which Trends surfaces to fetch per term. Defaults to the three shown. A category-only run (a category with no search terms) is served interestOverTime and relatedQueries only — Google offers no region table and no topics without a search term, and the run ships one uncharged row naming what it left out. relatedQueries is the surface Google most often has nothing for: it is computed only where a term carries enough search volume, so lower-volume keywords — and any keyword narrowed to a smaller region or a shorter time window — frequently have none at all. That is an honest no-data answer rather than a fault: the keyword is named in the run's ERRORS record, nothing is charged for it, and re-running the same term returns the same answer. interestOverTime is charted for terms far below the level related queries needs, so keep it selected and a term with no related queries still comes back with its trend line. relatedTopics is opt-in — add it to also get the top + rising topic entities (with knowledge-graph ids) for each term. Google serves its topics feed to a limited number of lookups at a time, so this one surface can come back empty on a busy moment: it is never charged when it does, and a re-run a minute or two later normally delivers.",
"items": {
"type": "string",
"enum": [
"interestOverTime",
"relatedQueries",
"interestByRegion",
"relatedTopics"
],
"enumTitles": [
"Interest over time",
"Related queries (top + rising)",
"Interest by region",
"Related topics (top + rising entities)"
]
},
"default": [
"interestOverTime",
"relatedQueries",
"interestByRegion"
]
},
"compare": {
"title": "Compare terms on one scale",
"type": "boolean",
"description": "Scores 2-5 terms on one shared 0-100 scale, exactly like the Trends UI compare view. Related queries are per-term and therefore unavailable in compare mode.",
"default": false
},
"geo": {
"title": "Location",
"type": "string",
"description": "ISO country/region code, e.g. US, GB, US-CA, DE. Leave empty for worldwide. A country's three-letter code (IND), English name (India) or its own name in its own language (Deutschland) is read too, and the run tells you on an uncharged note row which market it used. Region codes are passed to Google exactly as typed.",
"default": ""
},
"timeRange": {
"title": "Time range",
"type": "string",
"description": "A Google preset — now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all — or a custom range like 2025-01-01 2025-06-01. Shorthand that names one preset, like 12m or 7 days, is read as that preset.",
"default": "today 12-m"
},
"category": {
"title": "Category ID",
"type": "integer",
"description": "Google Trends category ID. Set it with NO search terms and the run explores that category itself — Google's own category view, billed as ONE trend report: the interest-over-time series and the top 25 and rising 25 queries for the whole category. Interest by region and related topics are not served without a search term, and one uncharged row says so. Set it beside search terms and it simply narrows them. Common IDs: 7 Finance, 45 Health, 12 Business, 16 News. 0 = all categories.",
"default": 0
},
"property": {
"title": "Search property",
"type": "string",
"description": "Which Google property to measure interest on.",
"default": ""
},
"includeTrendingNow": {
"title": "Include trending now",
"type": "boolean",
"description": "Also fetch the current trending searches for a country (at most 1 trend report per trend returned, with traffic estimate and news links). A trending feed has no keyword to belong to, so each trending row is its own report rather than riding on a keyword's.",
"default": false
},
"trendingNowGeo": {
"title": "Trending now country",
"type": "string",
"description": "Country code for trending now, e.g. US, GB, SA, JP. A three-letter code (IND), the country's English name (India) or its own name in its own language (Deutschland) is read too, on an uncharged note row naming the market used.",
"default": "US"
},
"proxyCountry": {
"title": "Proxy country",
"type": "string",
"description": "Country for the backup proxy exit used only when Google rate-limits a request. Normal requests go out on the run's own IP at no proxy cost, so most runs never touch this — leave it as US unless you need a specific retry country.",
"default": "US"
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
},
"PROXY_UNBLOCKER_UNITS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
},
"PROXY_UNBLOCKER_UNITS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}