{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends Scraper & API - Bulk, Trending Now",
    "description": "Reliable Google Trends API: interest over time, interest by region/city, related queries and topics (top + rising), and Trending Now by country. Compare up to 5 terms, batch hundreds, any geo, time range, category or YouTube/News/Shopping. Auto-retries with fresh sessions.",
    "version": "1.0",
    "x-build-id": "1xod1tYOGTkPGETcP"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/adyg~google-trends-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-adyg-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/adyg~google-trends-scraper/runs": {
      "post": {
        "operationId": "runs-sync-adyg-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/adyg~google-trends-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-adyg-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": "One search term (or Google Trends topic ID like <code>/m/02vqfm</code>) per line. To <b>compare</b> up to 5 terms on the same 0-100 scale, put them on one line separated by commas, e.g. <code>coffee, tea, matcha</code>. Add as many lines as you like - each line is scraped separately for every geo.",
            "items": {
              "type": "string"
            }
          },
          "geos": {
            "title": "Geo (country / region)",
            "type": "array",
            "description": "Country code (<code>US</code>, <code>GB</code>, <code>DE</code>), region (<code>US-CA</code>, <code>GB-SCT</code>) or US metro (<code>US-NY-501</code>). Leave a line empty or write <code>WORLDWIDE</code> for worldwide. Every search term is scraped for every geo.",
            "default": [
              "US"
            ],
            "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": "Preset period. Use <i>Custom time range</i> below for exact dates.",
            "default": "today 12-m"
          },
          "customTimeRange": {
            "title": "Custom time range",
            "type": "string",
            "description": "Optional, overrides the preset. <code>YYYY-MM-DD YYYY-MM-DD</code> (e.g. <code>2024-01-01 2024-12-31</code>) or hourly <code>YYYY-MM-DDTHH YYYY-MM-DDTHH</code> within the last 7 days (UTC)."
          },
          "category": {
            "title": "Category",
            "minimum": 0,
            "type": "integer",
            "description": "Google Trends category ID to narrow ambiguous terms (0 = all categories). Common: 3 Arts & Entertainment, 5 Computers & Electronics, 7 Finance, 18 Shopping, 20 Sports, 44 Beauty & Fitness, 45 Health, 47 Autos & Vehicles, 66 Pets & Animals, 67 Travel, 71 Food & Drink, 958 Jobs & Education (full list in the README).",
            "default": 0
          },
          "property": {
            "title": "Search property",
            "enum": [
              "web",
              "images",
              "news",
              "youtube",
              "shopping"
            ],
            "type": "string",
            "description": "Which Google search product the interest comes from.",
            "default": "web"
          },
          "includeInterestOverTime": {
            "title": "Interest over time",
            "type": "boolean",
            "description": "Timeline of search interest (0-100).",
            "default": true
          },
          "includeInterestByRegion": {
            "title": "Interest by region",
            "type": "boolean",
            "description": "Interest per country / subregion / metro / city. When comparing several terms, values are each term's share (%) of the compared searches in that region, as on the Google Trends website.",
            "default": true
          },
          "regionResolution": {
            "title": "Region resolution",
            "enum": [
              "auto",
              "COUNTRY",
              "REGION",
              "DMA",
              "CITY"
            ],
            "type": "string",
            "description": "Granularity of interest by region. Falls back to Google's default if the resolution isn't available for the geo.",
            "default": "auto"
          },
          "includeLowSearchVolumeRegions": {
            "title": "Include low search volume regions",
            "type": "boolean",
            "description": "Also return regions with too little data (value 0).",
            "default": false
          },
          "maxRegions": {
            "title": "Max regions per term",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Keep only the top N regions by interest.",
            "default": 250
          },
          "includeRelatedQueries": {
            "title": "Related queries",
            "type": "boolean",
            "description": "Top and rising related searches (rising includes Breakout terms).",
            "default": true
          },
          "includeRelatedTopics": {
            "title": "Related topics (opt-in)",
            "type": "boolean",
            "description": "Off by default. Top and rising related topics. Google returns empty related topics to regular automated sessions, so when enabled this option requests them through Google Trends' embeddable-widget endpoint, sending a Referer header from a pool of public websites. Enable it only if this method is acceptable for your use case. Adds 2 requests per term; if topics can't be retrieved, the term is still returned with its other data.",
            "default": false
          },
          "maxRelatedItems": {
            "title": "Max related items per list",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum rows per top / rising list.",
            "default": 25
          },
          "trendingGeos": {
            "title": "Trending now: countries",
            "type": "array",
            "description": "Get the current Trending Now / daily trending searches for these countries (e.g. <code>US</code>, <code>GB</code>, <code>IN</code>, or a region like <code>US-CA</code>). Works with or without search terms.",
            "items": {
              "type": "string"
            }
          },
          "trendingHours": {
            "title": "Trending time window",
            "enum": [
              "4",
              "24",
              "48",
              "168"
            ],
            "type": "string",
            "description": "Trends that started within this window.",
            "default": "24"
          },
          "trendingCategories": {
            "title": "Trending categories",
            "type": "array",
            "description": "Optional filter. Empty = all categories.",
            "items": {
              "type": "string",
              "enum": [
                "Autos and Vehicles",
                "Beauty and Fashion",
                "Business and Finance",
                "Climate",
                "Entertainment",
                "Food and Drink",
                "Games",
                "Health",
                "Hobbies and Leisure",
                "Jobs and Education",
                "Law and Government",
                "Other",
                "Pets and Animals",
                "Politics",
                "Science",
                "Shopping",
                "Sports",
                "Technology",
                "Travel and Transportation"
              ]
            }
          },
          "trendingActiveOnly": {
            "title": "Active trends only",
            "type": "boolean",
            "description": "Skip trends that have already ended.",
            "default": false
          },
          "maxTrendingPerGeo": {
            "title": "Max trending searches per country",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Google lists up to ~500 trends per day for big countries; ranked by relevance.",
            "default": 25
          },
          "includeTrendingNews": {
            "title": "Add news articles",
            "type": "boolean",
            "description": "Attach up to 3 news articles (title, URL, source, time, image) that Google links to each trending search. One extra request per 50 trends.",
            "default": true
          },
          "outputFormat": {
            "title": "Output format",
            "enum": [
              "flat",
              "perTerm"
            ],
            "type": "string",
            "description": "Flat: every timeline point, region, related query and topic is its own row with a <code>type</code> column. Per term: one row per search term + geo with arrays inside. Price is the same - you pay per term, not per row.",
            "default": "flat"
          },
          "advancedQueries": {
            "title": "Advanced queries (JSON)",
            "type": "array",
            "description": "Optional. Fine-grained list of queries, each with its own geo / time range / category / property, e.g. <code>[{\"terms\": \"nike, adidas\", \"geo\": \"DE\", \"timeRange\": \"today 5-y\", \"category\": 0, \"property\": \"youtube\"}]</code>. Missing fields use the values above."
          },
          "language": {
            "title": "Language (hl)",
            "type": "string",
            "description": "Language of region and topic names, e.g. <code>en-US</code>, <code>de</code>, <code>fr</code>.",
            "default": "en-US"
          },
          "timezoneOffsetMinutes": {
            "title": "Timezone offset (minutes)",
            "minimum": -840,
            "maximum": 840,
            "type": "integer",
            "description": "Google's tz parameter (minutes behind UTC, e.g. 300 = US Eastern standard time). Default 0 = UTC dates.",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Defaults to Apify datacenter proxy (cheapest) with automatic residential fallback when Google blocks it. Choose the RESIDENTIAL group to always use residential IPs.",
            "default": {
              "useApifyProxy": true
            }
          },
          "residentialFallback": {
            "title": "Residential fallback",
            "type": "boolean",
            "description": "When a request is rate-limited (HTTP 429) on datacenter IPs, retry it on a residential IP. Recommended - this is what keeps the success rate above 99%.",
            "default": true
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Queries processed in parallel.",
            "default": 5
          },
          "maxRetries": {
            "title": "Max attempts per request",
            "minimum": 2,
            "maximum": 15,
            "type": "integer",
            "description": "Each attempt uses a fresh session (new IP + new cookie) with exponential backoff.",
            "default": 8
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}