{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends Scraper: Explore, Compare, Trending Now",
    "description": "Google Trends API without a browser: interest over time, by region/city/metro, related & rising queries, compare 5+ terms on one scale, daily data for 5 years, Trending Now with news, change alerts. Same input as apify/google-trends-scraper. Never pay for empty results.",
    "version": "0.1",
    "x-build-id": "l3qfPEQck5htggCZn"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/nat-labs~google-trends-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-nat-labs-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/nat-labs~google-trends-scraper/runs": {
      "post": {
        "operationId": "runs-sync-nat-labs-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/nat-labs~google-trends-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-nat-labs-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 or topics to analyse. Each entry becomes one trend report per geo: interest over time, interest by region and related queries. Topic ids like <code>/m/05z1_</code> work too. With <b>Compare terms in each entry</b> on, write <code>bitcoin, ethereum</code> to compare them on one 0–100 scale.",
            "items": {
              "type": "string"
            }
          },
          "isMultiple": {
            "title": "Compare terms in each entry (comma-separated)",
            "type": "boolean",
            "description": "When on, a comma inside one search-term entry separates up to 5 terms compared on one scale (Google's own limit). Same behaviour as apify/google-trends-scraper.",
            "default": false
          },
          "compareGroups": {
            "title": "Comparison groups (JSON)",
            "type": "array",
            "description": "Alternative to commas: a list of groups, e.g. <code>[[\"iphone\", \"pixel\", \"galaxy\"], [\"tea\", \"coffee\"]]</code>. Easier for API and AI-agent callers."
          },
          "compareAnchor": {
            "title": "Compare more than 5 terms: anchor term",
            "type": "string",
            "description": "Put any number of terms on ONE scale. Set a term that appears in your comparison group (for example the most popular one): the Actor queries Google in batches of the anchor + 4 terms and rescales every batch by the anchor. Each extra batch is billed as an <i>extra query</i>."
          },
          "startUrls": {
            "title": "Google Trends links",
            "type": "array",
            "description": "Paste links from trends.google.com — both the classic <code>/trends/explore?q=…</code> and the new <code>/explore?q=…</code> format. Each link keeps its own geo, date, category and property.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "geos": {
            "title": "Countries / regions",
            "type": "array",
            "description": "One report per term per geo. Country codes (<code>US</code>, <code>de</code>), names (<code>Germany</code>), regions (<code>US-CA</code>, <code>GB-ENG</code>), US metros (<code>US-CA-807</code>), or leave empty for Worldwide. All 3,681 Google Trends geos are supported.",
            "items": {
              "type": "string"
            }
          },
          "geo": {
            "title": "Country (single, compatibility)",
            "type": "string",
            "description": "Single geo, kept for compatibility with apify/google-trends-scraper. Ignored when <b>Countries / regions</b> is set. Empty = Worldwide."
          },
          "timeRange": {
            "title": "Time range",
            "type": "string",
            "description": "Google's tokens (<code>now 1-H</code>, <code>now 4-H</code>, <code>now 1-d</code>, <code>now 7-d</code>, <code>today 1-m</code>, <code>today 3-m</code>, <code>today 12-m</code>, <code>today 5-y</code>, <code>all</code>) or plain shortcuts like <code>7d</code>, <code>12m</code>, <code>5y</code>. Empty = past 12 months.",
            "default": "today 12-m"
          },
          "customTimeRange": {
            "title": "Custom time range",
            "type": "string",
            "description": "Overrides Time range. Daily: <code>2024-01-01 2024-06-30</code>. Hourly (max 7 days): <code>2026-10-01T00 2026-10-03T12</code>."
          },
          "dailyResolution": {
            "title": "Daily points for long ranges",
            "type": "boolean",
            "description": "Google returns weekly or monthly points for ranges over ~9 months. When on, the Actor fetches overlapping daily windows and stitches them onto one scale — a daily series for 5 years. Each window is billed as an <i>extra query</i> (5 years ≈ 9 windows).",
            "default": false
          },
          "category": {
            "title": "Category",
            "type": "string",
            "description": "Any of Google's ~1,100 categories, by id (<code>7</code>) or name (<code>Finance</code>, <code>Investing</code>). Empty = All categories."
          },
          "property": {
            "title": "Search type",
            "enum": [
              "web",
              "images",
              "news",
              "youtube",
              "shopping"
            ],
            "type": "string",
            "description": "Which Google search to measure.",
            "default": "web"
          },
          "includeRegions": {
            "title": "Interest by region",
            "type": "boolean",
            "description": "Include the regional breakdown. Turn off (with related queries) for a faster timeline-only report.",
            "default": true
          },
          "regionResolutions": {
            "title": "Extra region levels",
            "type": "array",
            "description": "On top of the default breakdown (countries for Worldwide, sub-regions for a country): <code>CITY</code>, <code>DMA</code> (US metros), <code>REGION</code>, <code>COUNTRY</code>. Included in the report price.",
            "items": {
              "type": "string"
            }
          },
          "includeLowVolumeRegions": {
            "title": "Keep regions without data",
            "type": "boolean",
            "description": "Google pads region and city lists with places that have too little search volume (value 0, no data). They are dropped by default.",
            "default": false
          },
          "includeRelated": {
            "title": "Related queries & topics",
            "type": "boolean",
            "description": "Top and rising related searches, with Breakout flags. Note: Google serves related <i>topics</i> only to browsers that pass reCAPTCHA; this Actor never bypasses CAPTCHAs, so topics are returned only when Google provides them.",
            "default": true
          },
          "resolveTopics": {
            "title": "Resolve terms to topics",
            "type": "boolean",
            "description": "Map each term to Google's topic entity first (e.g. <code>python</code> → <i>Python, programming language</i>), which includes misspellings and translations and avoids ambiguity. The chosen topic is shown in the output.",
            "default": false
          },
          "outputFormat": {
            "title": "Output format",
            "enum": [
              "report",
              "rows",
              "wide"
            ],
            "type": "string",
            "description": "<b>report</b>: one nested item per term and geo (same fields as apify/google-trends-scraper). <b>rows</b>: one row per term per date (long format for BI). <b>wide</b>: one row per date, one column per term (paste into Sheets and chart).",
            "default": "report"
          },
          "trendingGeos": {
            "title": "Trending Now: countries / regions",
            "type": "array",
            "description": "Get everything trending right now, as on trends.google.com/trending: search volume, % increase, start/end time, active flag, category, related searches and news articles. Countries (<code>US</code>) or regions (<code>US-CA</code>).",
            "items": {
              "type": "string"
            }
          },
          "trendingHours": {
            "title": "Trending window",
            "enum": [
              "4",
              "24",
              "48",
              "168"
            ],
            "type": "string",
            "description": "Trends started in the last 4, 24, 48 or 168 hours.",
            "default": "24"
          },
          "trendingMaxPerGeo": {
            "title": "Max trending searches per geo",
            "minimum": 0,
            "type": "integer",
            "description": "Ranked by Google's own order. 0 = all (a week in the US is ~3,000). The price is per country snapshot, so a bigger list costs nothing extra.",
            "default": 100
          },
          "trendingCategories": {
            "title": "Trending categories",
            "type": "array",
            "description": "Only these Trending Now categories, by id: 1 Autos, 2 Beauty & Fashion, 3 Business & Finance, 4 Entertainment, 5 Food & Drink, 6 Games, 7 Health, 8 Hobbies, 9 Jobs & Education, 10 Law & Government, 11 Other, 13 Pets, 14 Politics, 15 Science, 16 Shopping, 17 Sports, 18 Technology, 19 Travel, 20 Climate."
          },
          "trendingActiveOnly": {
            "title": "Only trends still active",
            "type": "boolean",
            "description": "Skip trends that have already ended; keep only those still trending now.",
            "default": false
          },
          "trendingMinVolume": {
            "title": "Minimum search volume",
            "minimum": 0,
            "type": "integer",
            "description": "Skip trends below this many searches (Google's lower bound, e.g. 10000 = 10K+).",
            "default": 0
          },
          "includeNews": {
            "title": "Attach news articles",
            "type": "boolean",
            "description": "Adds news headlines, links and pictures to the ~10 trends Google features in its official Trending RSS feed. Free.",
            "default": true
          },
          "onlyChanges": {
            "title": "Monitoring: deliver only changes",
            "type": "boolean",
            "description": "For scheduled runs. The first run is the baseline; later runs deliver a report only when a new rising/breakout query appears or interest spikes, and only Trending Now searches not delivered before. Unchanged checks cost a small <i>monitor check</i> instead of a full report.",
            "default": false
          },
          "monitorName": {
            "title": "Monitor name",
            "type": "string",
            "description": "Separate schedules need separate names so they keep separate memory.",
            "default": "default"
          },
          "spikeThreshold": {
            "title": "Spike alert threshold (%)",
            "minimum": 1,
            "type": "integer",
            "description": "Latest value vs the average of the period before it. 50 = alert when interest is 50% above normal.",
            "default": 50
          },
          "maxItems": {
            "title": "Max trend reports",
            "minimum": 0,
            "type": "integer",
            "description": "Stop after this many reports (Trending Now has its own cap). 0 = unlimited. Your run's maximum cost is always respected too: the Actor never starts a report it cannot pay for.",
            "default": 1000
          },
          "maxConcurrency": {
            "title": "Parallel reports",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many reports run in parallel, each on its own proxy IP. Higher is faster but trips Google rate limits sooner; 3 is a safe default.",
            "default": 3
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Language of names and labels, e.g. <code>en-US</code>, <code>de</code>, <code>ja</code>.",
            "default": "en-US"
          },
          "timezoneOffsetMinutes": {
            "title": "Timezone offset (minutes)",
            "type": "integer",
            "description": "Google's tz parameter: minutes WEST of UTC (New York = 300, Berlin = -60). Affects hourly ranges only. 0 = UTC.",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Optional. The Actor already rotates Apify residential proxies at no extra cost to you. Override only to use your own proxies."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}