{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends API & Scraper — pytrends alternative",
    "description": "Google Trends API & pytrends alternative: bulk Google Trends data for any keyword list — interest over time, regions, related queries & topics, CSV or JSON. 50 terms on one scale, daily historical data for years. Works from AI agents via MCP.",
    "version": "1.0",
    "x-build-id": "nf7gZtzf6fY6u6a7L"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/insanedev~google-trends-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-insanedev-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/insanedev~google-trends-scraper/runs": {
      "post": {
        "operationId": "runs-sync-insanedev-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/insanedev~google-trends-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-insanedev-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": "Words or phrases to look up in Google Trends, one per line. Each line is one result row per region. With **Compare terms** checked, separate terms with commas (for example `python, javascript`) to get them on one shared 0–100 scale, like the Compare button on Google Trends — and unlike Google, not limited to 5 terms (up to 50 per line).",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Google Trends URLs",
            "type": "array",
            "description": "Alternatively, paste Google Trends Explore URLs copied from your browser (for example `https://trends.google.com/trends/explore?q=python&geo=US`). The terms, region, time range, category and search type are read from the URL.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "isMultiple": {
            "title": "Compare terms",
            "type": "boolean",
            "description": "If checked, a comma inside a search term separates terms that are compared on one scale. Up to 5 terms are one Google comparison; for 6–50 terms the Actor chains several comparisons through a shared anchor term and puts all terms on one 0–100 scale (see `normalization` in the output). If unchecked, commas are part of the term.",
            "default": false
          },
          "timeRange": {
            "title": "Time range",
            "pattern": "^(|all|now \\d+-[Hd]|today \\d+-[my]|\\d{4}-\\d{2}-\\d{2}( \\d{4}-\\d{2}-\\d{2})?)$",
            "type": "string",
            "description": "Period to fetch (past 12 months by default). Pick a preset or type any Google Trends time expression, e.g. `today 2-y`, `now 4-H` or `2024-01-01 2024-06-30`. Google chooses the data frequency by the length of the period. Ignored when a custom time range is set.",
            "default": "today 12-m"
          },
          "customTimeRange": {
            "title": "Custom time range",
            "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Optional exact period in the format `YYYY-MM-DD YYYY-MM-DD`. Takes precedence over Time range. Periods shorter than about 9 months return daily data."
          },
          "dailyData": {
            "title": "Daily data for long periods",
            "type": "boolean",
            "description": "Google Trends gives daily points only for periods up to about 9 months (269 days); longer periods come weekly or monthly. With this on, the Actor also fetches the period in daily windows of up to 269 days and stitches them into one daily series on a common 0–100 scale, calibrated on the weekly (or monthly) series of the whole period so errors don't add up. Applies to interest over time for up to 5 terms. **Billing:** interest over time counts as one result per window and term (5 years ≈ 7 windows) — every window is a separate Google request. Has no effect on periods that already are daily or hourly.",
            "default": false
          },
          "geo": {
            "title": "Region",
            "pattern": "^(|[A-Za-z]{2}(-[A-Za-z0-9]{1,3})?|[Ww]orldwide)$",
            "type": "string",
            "description": "Country to get data for (Worldwide by default). You can also type a region code such as a US state (`US-CA`) or a subdivision like `GB-SCT`.",
            "default": "worldwide"
          },
          "geos": {
            "title": "More regions",
            "type": "array",
            "description": "Optional extra regions to fetch in the same run, as country codes (`DE`), US state codes (`US-CA`) or `worldwide`. Every term is fetched for every region; each region is a separate result row.",
            "items": {
              "type": "string",
              "pattern": "^(worldwide|[A-Za-z]{2}(-[A-Za-z0-9]{1,3})?)$"
            }
          },
          "category": {
            "title": "Category",
            "enum": [
              "",
              "3",
              "47",
              "44",
              "22",
              "12",
              "5",
              "7",
              "71",
              "8",
              "45",
              "65",
              "11",
              "13",
              "958",
              "19",
              "16",
              "299",
              "14",
              "66",
              "29",
              "533",
              "174",
              "18",
              "20",
              "67"
            ],
            "type": "string",
            "description": "Limit the data to searches in one Google Trends category.",
            "default": ""
          },
          "property": {
            "title": "Search type",
            "enum": [
              "",
              "youtube",
              "news",
              "images",
              "froogle"
            ],
            "type": "string",
            "description": "Which Google search to analyze, same as the search-type menu on Google Trends.",
            "default": ""
          },
          "includeInterestOverTime": {
            "title": "Interest over time",
            "type": "boolean",
            "description": "Timeline of search interest on a 0–100 scale, plus average, peak and change for the period.",
            "default": true
          },
          "includeInterestBySubregion": {
            "title": "Interest by subregion",
            "type": "boolean",
            "description": "Interest for each state/province of the selected country (or each country for Worldwide).",
            "default": true
          },
          "includeInterestByCity": {
            "title": "Interest by city",
            "type": "boolean",
            "description": "Interest for individual cities — best effort. Google shares city data for anonymous access only for popular terms (for example \"coffee\" returns dozens of US cities, niche terms none); only cities with data are returned and billed.",
            "default": false
          },
          "includeInterestByMetro": {
            "title": "Interest by metro area (US)",
            "type": "boolean",
            "description": "Interest for US metro areas (DMA), for Region = United States. For a US state, Interest by subregion already returns its metro areas.",
            "default": false
          },
          "includeRelatedQueries": {
            "title": "Related queries",
            "type": "boolean",
            "description": "Top and rising queries that people also searched for, as returned by Google.",
            "default": true
          },
          "includeRelatedTopics": {
            "title": "Related topics",
            "type": "boolean",
            "description": "Top and rising related topics — best effort. Google serves topics to anonymous visitors only while its public embed quota lasts, which is often used up, so many runs return none. You are billed only for topics that are returned (`relatedTopicsStatus` shows what happened).",
            "default": false
          },
          "includeLowSearchVolumeRegions": {
            "title": "Include low search volume regions",
            "type": "boolean",
            "description": "Same as the checkbox on Google Trends: adds regions with little search volume to Interest by subregion/country (for example 183 instead of 34 countries for \"pickleball\"). Note that Google then rescales the map, so a tiny region can become 100.",
            "default": false
          },
          "samples": {
            "title": "Samples per term",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Google Trends is computed from a random sample of searches, so the same request can return slightly different numbers (in our tests 1 in 5 single requests differed from the most common result). We fetch the interest-over-time series this many times from independent IP addresses and return the per-point median, plus `samplingSpread`. 1 = fastest; 3 (default) gives stable, reproducible values; up to 10 for research. The price is the same.",
            "default": 3
          },
          "outputFormat": {
            "title": "Output format",
            "enum": [
              "nested",
              "flat"
            ],
            "type": "string",
            "description": "`nested` keeps all data for a term in one row and uses the same field names as the Google Trends Scraper by Apify, so existing integrations keep working. `flat` produces one row per date of the timeline.",
            "default": "nested"
          },
          "viewedFrom": {
            "title": "Country to view Trends from",
            "type": "string",
            "description": "Compatibility field. Proxy country used to fetch data (default: US)."
          },
          "maxItems": {
            "title": "Max items",
            "minimum": 0,
            "type": "integer",
            "description": "Compatibility field. Maximum number of result rows; 0 means no limit."
          },
          "spreadsheetId": {
            "title": "Google Sheet ID",
            "type": "string",
            "description": "Compatibility field. Not supported yet; use Search terms."
          },
          "maxConcurrency": {
            "title": "maxConcurrency",
            "type": "integer",
            "description": "Compatibility field. Accepted and ignored: this Actor manages concurrency and retries itself."
          },
          "maxRequestRetries": {
            "title": "maxRequestRetries",
            "type": "integer",
            "description": "Compatibility field. Accepted and ignored: this Actor manages concurrency and retries itself."
          },
          "pageLoadTimeoutSecs": {
            "title": "pageLoadTimeoutSecs",
            "type": "integer",
            "description": "Compatibility field. Accepted and ignored: this Actor manages concurrency and retries itself."
          },
          "skipDebugScreen": {
            "title": "skipDebugScreen",
            "type": "boolean",
            "description": "Compatibility field. Accepted and ignored."
          },
          "strictStatus": {
            "title": "Strict run status",
            "type": "boolean",
            "description": "For monitoring: the run fails when more than half of the queries are incomplete (partial, failed or without data), so a run-status alert catches a broken data type early."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}