{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper: Compare 100+ Keywords, Rising & Trending", "description": "Reliable Google Trends API: compare 100+ keywords on one 0–100 scale (auto-anchored), interest over time, by region/metro/city, top & rising queries, Trending Now with news, and change alerts. Flat, LLM-ready JSON. Pay per result, no start fee.", "version": "0.1", "x-build-id": "PdudL9Qg5QIajPHUN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/chaptersoft~google-trends-reliable/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-chaptersoft-google-trends-reliable", "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/chaptersoft~google-trends-reliable/runs": { "post": { "operationId": "runs-sync-chaptersoft-google-trends-reliable", "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/chaptersoft~google-trends-reliable/run-sync": { "post": { "operationId": "run-sync-chaptersoft-google-trends-reliable", "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": "One per line (or comma-separated). Keywords (\"cold brew\"), Google topic IDs (/m/0d6lp) or Google Trends explore URLs (their own location, time and category are kept). Any number of terms: more than 5 are put on ONE shared 0–100 scale automatically (overlapping anchor groups), so \"coffee\" and \"aeropress\" are directly comparable. Leave empty if you only want Trending Now.", "items": { "type": "string" } }, "spreadsheetId": { "title": "Google Sheet with search terms (optional)", "type": "string", "description": "ID or URL of a Google Sheet shared as \"Anyone with the link can view\". Terms are read from the first column (a header such as \"keyword\" is skipped) and added to the search terms. Add #gid=… to the URL to pick a tab." }, "geos": { "title": "Locations", "type": "array", "description": "Empty = Worldwide. ISO country codes (US, GB, DE), subregions (US-CA, GB-ENG), US metro codes (US-CA-807) or country names (\"Germany\"). Every term is fetched for every location.", "items": { "type": "string" } }, "timeRange": { "title": "Time range", "enum": [ "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" ], "type": "string", "description": "Same choices as the Google Trends website. For anything else use \"Custom time range\".", "default": "today 12-m" }, "customTimeRange": { "title": "Custom time range", "type": "string", "description": "Overrides Time range. \"2024-01-01 2024-06-30\" (dates), \"2026-10-18T08 2026-10-19T08\" (hourly, max 7 days), or \"today 3-m\" / \"now 7-d\" style. Dates from 2004-01-01." }, "category": { "title": "Category", "type": "string", "description": "Google Trends category ID or name: 0 = All, 71 = Food & Drink, 7 = Finance, 18 = Shopping, 5 = Computers & Electronics … (all 1,100+ categories accepted).", "default": "0" }, "property": { "title": "Search type", "enum": [ "web", "images", "news", "froogle", "youtube" ], "type": "string", "description": "Which Google search property to measure (as in the Trends website dropdown).", "default": "web" }, "searchAs": { "title": "Search terms as", "enum": [ "keyword", "topic" ], "type": "string", "description": "Topics include misspellings and translations. The resolved topic ID is reported on each item.", "default": "keyword" }, "compareTerms": { "title": "Put all terms on one scale", "type": "boolean", "description": "On: terms are compared (as when you type several terms into Google Trends) and, beyond 5 terms, stitched onto one scale through shared anchors; each item reports the scale quality. Off: every term is fetched on its own 0–100 scale (best for unrelated terms; enables related topics).", "default": true }, "anchorTerm": { "title": "Anchor term (optional)", "type": "string", "description": "Term placed in every 5-term group to stitch the scale. Default: the most popular of your terms is found automatically. Set one to compare runs with each other." }, "includeInterestOverTime": { "title": "Interest over time", "type": "boolean", "description": "Average, latest, peak, low, direction, change % and the full timeline per term.", "default": true }, "includeTimeline": { "title": "Include the timeline array in each item", "type": "boolean", "description": "Off keeps items small (stats only); the full table is always in TIMELINE.csv.", "default": true }, "includeInterestByRegion": { "title": "Interest by region", "type": "boolean", "description": "Where each term is most popular.", "default": true }, "regionLevels": { "title": "Region levels", "type": "array", "description": "Pick several to get e.g. states AND metros AND cities in one run.", "items": { "type": "string", "enum": [ "auto", "COUNTRY", "REGION", "DMA", "CITY" ], "enumTitles": [ "Auto (next level below the location)", "Countries (worldwide only)", "Subregions / states", "US metros (DMA)", "Cities" ] }, "default": [ "auto" ] }, "maxRegions": { "title": "Max regions per level", "minimum": 0, "maximum": 500, "type": "integer", "description": "0 = all regions Google returns.", "default": 25 }, "includeLowVolumeRegions": { "title": "Include low-search-volume regions", "type": "boolean", "description": "Same as the checkbox on the Trends website.", "default": false }, "includeRelatedQueries": { "title": "Related queries (top + rising)", "type": "boolean", "description": "Top and rising related searches with values, growth %, breakouts and links.", "default": true }, "risingQueriesFilter": { "title": "Rising queries", "enum": [ "all", "containingTerm" ], "type": "string", "description": "Google currently mixes generic, off-topic queries (\"pet care tips\") into rising lists served to automated clients. Each row has containsTerm; the headline fields (topRisingQuery, breakoutQueries) always use on-topic rows.", "default": "all" }, "includeRelatedTopics": { "title": "Related topics", "type": "boolean", "description": "Only available with \"one scale\" off. Google currently withholds related topics from automated sessions; they are returned when served and the item says \"withheld\" otherwise (never charged extra).", "default": true }, "trendingNowGeos": { "title": "Trending Now: countries", "type": "array", "description": "Country codes for Google's Trending Now page (US, GB, IN …). Each trending search is one item with search volume, growth %, start/end time, categories, related queries and news articles.", "items": { "type": "string" } }, "trendingNowHours": { "title": "Trending window", "enum": [ "4", "24", "48", "168" ], "type": "string", "description": "Same as the Trends website.", "default": "24" }, "trendingNowCategories": { "title": "Trending categories", "type": "array", "description": "Empty = all. Names or IDs: Sports (17), Entertainment (4), Business and Finance (3), Technology (18), Politics (14), Health (7), Food and Drink (5) …", "items": { "type": "string" } }, "trendingNowActiveOnly": { "title": "Only active trends", "type": "boolean", "description": "Skip trends that have ended.", "default": false }, "trendingNowMaxItems": { "title": "Max trending searches per country", "minimum": 0, "maximum": 1000, "type": "integer", "description": "0 = all (the US 24-hour list has ~500+).", "default": 25 }, "trendingNowSort": { "title": "Sort trending by", "enum": [ "relevance", "searchVolume", "recency", "growth" ], "type": "string", "description": "Relevance is the order of the Trends website.", "default": "relevance" }, "includeTrendingNews": { "title": "News articles for trends", "type": "boolean", "description": "Adds headline, source, link and picture where Google provides them.", "default": true }, "outputMode": { "title": "Output", "enum": [ "all", "new", "newOrChanged" ], "type": "string", "description": "Each term report is compared with the previous run of the same monitor: new on-topic rising/breakout queries (from the 3rd run; Google samples its rising list, so the first two runs build the baseline), direction change, top-region change, jumps/drops. Trending searches are new until seen. Unchanged items are not saved or charged in the filtered modes.", "default": "all" }, "monitorKey": { "title": "Monitor name", "type": "string", "description": "Optional. Default: derived from terms + locations + time + category, so a changed input starts fresh. Set it to keep history while editing the input." }, "changeThreshold": { "title": "Change threshold (points)", "minimum": 1, "maximum": 100, "type": "integer", "description": "Minimum change in latest-vs-peak interest (percentage points) that counts as a jump or drop.", "default": 15 }, "includeFailedItems": { "title": "Save error / no-data items", "type": "boolean", "description": "Terms that fail or have no data get an item with the reason (never charged).", "default": true }, "outputTimelineRows": { "title": "Also save one row per term per date", "type": "boolean", "description": "Long-format timeline dataset (\"timeline\") for spreadsheets and BI tools, one row per term per date. $0.02 per 1,000 rows. The same data is free in TIMELINE.csv and in each term report.", "default": false }, "language": { "title": "Language", "type": "string", "description": "Interface language for names of regions, categories and topics (en-US, de, ja …).", "default": "en-US" }, "timezoneOffsetMinutes": { "title": "Time zone offset (minutes)", "minimum": -840, "maximum": 840, "type": "integer", "description": "As Google uses it: minutes WEST of UTC (US Central = 300). Affects hourly/daily buckets.", "default": 0 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Parallel requests to Google. Higher is faster but triggers more rate limiting.", "default": 3 }, "maxRetries": { "title": "Max retries per request", "minimum": 1, "maximum": 12, "type": "integer", "description": "Rate-limited requests are retried with backoff, a fresh session and (if needed) a better proxy tier.", "default": 7 }, "maxRunSeconds": { "title": "Max run time (seconds)", "minimum": 60, "maximum": 21600, "type": "integer", "description": "Stop starting new requests after this many seconds and save what was fetched. Leave empty for automatic (about 4 min + 30 s per term, max 30 min). Terms not fetched are marked failed and not charged." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not needed: the Actor starts without a proxy and automatically escalates to Apify datacenter and then residential proxy if Google rate-limits (proxy cost is included in the price). Choose a proxy here to start on it.", "default": { "useApifyProxy": false } }, "autoProxyEscalation": { "title": "Automatic proxy escalation", "type": "boolean", "description": "Switch to a better proxy tier after repeated rate limits.", "default": true }, "debugForce429": { "title": "Test: simulate rate limits", "minimum": 0, "maximum": 20, "type": "integer", "description": "Testing only: the first N requests return a simulated HTTP 429 so you can see the retry logic work. Leave 0.", "default": 0 } } }, "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 } } } } } } } } } }