{ "openapi": "3.0.1", "info": { "title": "Google Trends Scraper & API: Interest, Regions, Trending Now", "description": "Scrape Google Trends: interest over time for one term or any number on one scale, by region, related queries and the full Trending now list with news. Daily data over years. Free summary row per term; errors not charged.", "version": "0.1", "x-build-id": "3kmQnfoOZSkWSUAdL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/quarra~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-quarra-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/quarra~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-quarra-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/quarra~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-quarra-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": { "mode": { "title": "What to scrape", "type": "string", "description": "\"explore\" works like the Explore page of Google Trends for your search terms. \"trendingNow\" returns the full Trending now list of one or more countries or regions (no search terms needed).", "default": "explore" }, "searchTerms": { "title": "Search terms", "type": "array", "description": "One term per line, up to 500; a comma also separates terms (not between digits, nor inside quotes). Google Trends syntax works and each term keeps its name: \"air fryer\" typed with its quotes = exact phrase, coffee + tea = OR (coffee OR tea is sent that way), coffee -starbucks = without starbucks; a lone + is OR too (c++ measures c, said in googleReadAs). Over 5 terms: linked batches, or comparisonMode \"calibrated\". Topic IDs (/m/02vqfm) work. Ignored in Trending now mode.", "items": { "type": "string" } }, "dataTypes": { "title": "Data to return", "type": "array", "description": "Any of interestOverTime, interestByRegion, relatedQueries. Each term x data type is one paid result. Every curve also gets a free summary row (trend, peak, year-over-year change, spike flag). Related topics are not available (see README).", "items": { "type": "string", "enumSuggestedValues": [ "interestOverTime", "interestByRegion", "relatedQueries" ], "enumTitles": [ "Interest over time (the curve)", "Interest by region (country, region, city or metro)", "Related queries (top + rising)" ] }, "default": [ "interestOverTime" ] }, "comparisonMode": { "title": "How to put terms on a scale", "type": "string", "description": "compare = Google comparison (1-5 terms; more in batches linked through the strongest term). separate = each term alone. calibrated = fixed scale per location and range (G-TAB anchor bank), any number of terms, comparable from run to run. compareLocations = one term in 2-5 places (geo \"US; GB; CA\") on one scale. comparePeriods = one term over 2-5 equal-length periods on one scale.", "default": "compare" }, "pivotTerm": { "title": "Pivot term (more than 5 compared terms)", "type": "string", "description": "Optional, only for compare with more than 5 terms. By default the batches of 5 are linked through the strongest term measured so far (exact links), and small terms are measured again next to a closer term. A term given here is put in the first batch; it is returned only if it is in your list." }, "geo": { "title": "Location", "type": "string", "description": "Empty = worldwide. A code (US, GB, US-CA, US-CA-807 metro) or a name in any language (\"United States\", \"California\", \"日本\", \"Georgia, US\"). Several locations: separate with \";\" (US; GB; JP): each is fetched separately, or on one scale with comparisonMode compareLocations.", "default": "" }, "timeRange": { "title": "Time range", "type": "string", "description": "A Google range (today 12-m) or plain text: \"past 12 months\", \"5y\", \"2024\", \"2019-2021\", \"Q1 2024\", \"YTD\", \"since 2020\", \"Jan 2024 - Jun 2024\", \"2024-01-01 2024-06-30\", \"all\". For daily points over more than 9 months, turn on dailyResolution.", "default": "today 12-m" }, "startDate": { "title": "Start date (custom range)", "type": "string", "description": "From 2004-01-01. Setting a start date switches the time range to custom dates." }, "endDate": { "title": "End date (custom range)", "type": "string", "description": "Defaults to today." }, "periods": { "title": "Periods to compare (comparePeriods)", "type": "array", "description": "For comparisonMode comparePeriods: 2 to 5 periods of about the same length, e.g. \"2024\" and \"2025\", or \"2025-01-01 2025-06-30\" and \"2026-01-01 2026-06-30\". Each term is returned once per period, all on one scale.", "items": { "type": "string" } }, "dailyResolution": { "title": "Daily values over long ranges", "type": "boolean", "description": "Daily points past ~9 months: overlapping 8-month windows, benchmarked to Google's weekly (and monthly) curve so they do not drift (Eichenauer et al. 2022). Several compared terms share one scale. One result per Google window with data: 12 months = 3, 5 years = 11 per term.", "default": false }, "category": { "title": "Category ID", "minimum": 0, "type": "integer", "description": "0 = all categories. Examples: 3 Arts & Entertainment, 7 Finance, 12 Business & Industrial, 18 Shopping, 20 Sports, 31 Programming, 44 Beauty & Fitness, 45 Health, 47 Autos & Vehicles, 71 Food & Drink, 174 Science. Every ID is checked against Google's list before the run.", "default": 0 }, "property": { "title": "Google property", "type": "string", "description": "Where the searches happened: web, images, news, youtube or shopping (\"Google Shopping\", \"YouTube search\" also work).", "default": "web" }, "regionResolution": { "title": "Region level (interest by region)", "type": "string", "description": "Level of the places in interest by region: auto (countries for worldwide, regions for a country), COUNTRY, REGION, CITY or DMA (US metro areas).", "default": "auto" }, "includeLowVolumeRegions": { "title": "Include low-volume regions", "type": "boolean", "description": "Also return places with little search volume (Google hides them by default).", "default": false }, "language": { "title": "Language", "type": "string", "description": "Language of labels (region names, date labels, trending list): a code (en-US, fr, de, ja, pt-BR...) or a language name (French, français, 日本語). Does not filter the data.", "default": "en-US" }, "trendingLocations": { "title": "Countries or regions", "type": "array", "description": "Codes or names in any language: US, GB, JP, \"Germany\", \"日本\", or a region such as US-CA or \"Bavaria\". One paid result per location: the whole list (often 100 to 500 trends), news included. Defaults to US (\"geo\" is used if this is empty).", "items": { "type": "string" } }, "trendingHours": { "title": "Trending in the past (hours)", "minimum": 4, "maximum": 168, "type": "integer", "description": "Time window of Trending now, in hours: 4, 24, 48 or 168 (7 days), as on the Google Trends page.", "default": 24 }, "trendingCategory": { "title": "Trending category", "type": "string", "description": "Keep only the trends of one Google category, by ID or name (\"Sports\", \"Technology\"). Empty = all.", "default": "" }, "trendingActiveOnly": { "title": "Only trends still active", "type": "boolean", "description": "Skip trends Google marks as ended.", "default": false }, "maxTrendsPerCountry": { "title": "Max trends per location", "minimum": 0, "type": "integer", "description": "0 = the whole list. Does not change the price (one result per location).", "default": 0 }, "trendingArticles": { "title": "News articles per trend", "minimum": 0, "maximum": 10, "type": "integer", "description": "Add up to this many news articles (title, source, URL, date, image) to each of the first 25 trends of each list. 0 = none. No extra charge.", "default": 0 }, "trendingOnlyNew": { "title": "Only new trends since the last run", "type": "boolean", "description": "Return only trends this Actor has not returned before for the same location, for scheduled runs and alerts. The memory is kept in a named key-value store of your own account (quarra-google-trends-memory). A location with nothing new is free.", "default": false }, "trendingMemoryName": { "title": "Memory name (only new trends)", "type": "string", "description": "Separate memories for separate schedules, e.g. \"newsroom\" and \"seo-alerts\" (lowercase letters, digits, dashes).", "default": "default" }, "stableSampling": { "title": "Stable values (several independent samples)", "type": "boolean", "description": "Google serves slightly different samples of the same data (about 7 samples in 10 show the same version, others up to 8 points off). With this on, each request is fetched several times independently and the version most of the samples show is returned, so identical runs return the same version of the data. No extra charge. Rows carry sampleAgreement, e.g. \"5/5\".", "default": true }, "sampleAggregation": { "title": "Combine samples by", "type": "string", "description": "majority = the version seen by most samples, exact Google integers. mean = the curve is the average of 5 samples, with valueStdError per point: less sampling noise, the estimator researchers use. Maps and related queries always use the majority. If a run has to move to the premium connection, mean counts 2 premium connection extras per result (see the pricing).", "default": "majority" }, "maxSampleIps": { "title": "Samples per request", "minimum": 3, "maximum": 15, "type": "integer", "description": "Upper bound on the samples taken for one request when the first ones do not show a clear majority (3 to 5 usually suffice). At most 9 are used (values up to 15 are accepted and lowered to 9); with sampleAggregation mean, 5.", "default": 9 }, "maxItems": { "title": "Max results", "minimum": 1, "type": "integer", "description": "Maximum number of paid results (default 1,000: raise it for big runs). One curve, map or query list per term, one calibrated term, one Google window of a long daily curve, one Trending now list per location. Points, places, queries, trends and summary, missing and error rows are free. A Trending now list is never cut.", "default": 1000 }, "proxyConfiguration": { "title": "Connection", "type": "object", "description": "Connection. Keep the default (automatic). Costs are included in the price.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }