{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends series by term, geo and time window, as flat rows",
    "description": "For each term, the Google Trends interest series over your time window, interest by country or region, and related queries, as flat rows: one data point per row with a stable id. Opens in Excel or Sheets or loads into a database without reshaping. Per-term session rotation on rate limits.",
    "version": "0.1",
    "x-build-id": "3aXN935Q7PsUc3d53"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/tallyrake~google-trends-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-tallyrake-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/tallyrake~google-trends-scraper/runs": {
      "post": {
        "operationId": "runs-sync-tallyrake-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/tallyrake~google-trends-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-tallyrake-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",
        "required": [
          "searchTerms"
        ],
        "properties": {
          "searchTerms": {
            "title": "Search terms",
            "minItems": 1,
            "type": "array",
            "description": "1 to 5 search terms per Google Trends comparison. More than 5 terms are automatically batched into separate comparison calls of up to 5.",
            "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 Google Trends time window. Ignored if Custom time range is set.",
            "default": "today 12-m"
          },
          "customTimeRange": {
            "title": "Custom time range",
            "type": "string",
            "description": "Overrides Time range. Format: \"YYYY-MM-DD YYYY-MM-DD\" (e.g. \"2023-01-01 2023-06-30\")."
          },
          "geo": {
            "title": "Geo (location)",
            "type": "string",
            "description": "Two-letter country code (e.g. \"US\"), or country-region code (e.g. \"US-CA\"). Leave empty for worldwide.",
            "default": ""
          },
          "category": {
            "title": "Category",
            "type": "integer",
            "description": "Google Trends category ID. 0 means all categories.",
            "default": 0
          },
          "searchType": {
            "title": "Search type",
            "enum": [
              "",
              "images",
              "news",
              "youtube",
              "froogle"
            ],
            "type": "string",
            "description": "Which Google property to pull trends from.",
            "default": ""
          },
          "outputs": {
            "title": "Data to fetch",
            "type": "array",
            "description": "Which data to fetch. Each selected output becomes its own row type in the dataset.",
            "items": {
              "type": "string",
              "enum": [
                "interestOverTime",
                "interestByRegion",
                "relatedQueries",
                "relatedTopics"
              ],
              "enumTitles": [
                "Interest over time",
                "Interest by region",
                "Related queries",
                "Related topics"
              ]
            },
            "default": [
              "interestOverTime",
              "relatedQueries"
            ]
          },
          "regionResolution": {
            "title": "Region resolution",
            "enum": [
              "COUNTRY",
              "REGION",
              "CITY",
              "DMA"
            ],
            "type": "string",
            "description": "Granularity used for Interest by region.",
            "default": "COUNTRY"
          },
          "compareTerms": {
            "title": "Compare terms",
            "type": "boolean",
            "description": "When enabled, all search terms are sent as a single Google Trends comparison so their values are relative to each other (one term is the 0-100 anchor). When disabled (default), each term is fetched on its own 0-100 scale.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Google Trends aggressively rate-limits by IP. Using Apify Proxy is strongly recommended for any run beyond a couple of terms.",
            "default": {
              "useApifyProxy": true
            }
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 3,
            "type": "integer",
            "description": "Maximum number of search terms processed in parallel. Keep at 3 or below to avoid Google rate limits.",
            "default": 2
          },
          "requestsPerSession": {
            "title": "Requests per session",
            "minimum": 1,
            "type": "integer",
            "description": "Reuse a Google Trends session for this many successful requests, then rotate to a fresh one. A session also rotates immediately on a rate-limit response.",
            "default": 8
          },
          "pacingMs": {
            "title": "Pacing (ms)",
            "minimum": 0,
            "type": "integer",
            "description": "Base jittered delay in milliseconds between Google Trends requests; 0 disables pacing.",
            "default": 500
          },
          "residentialForRelated": {
            "title": "Residential proxy for related queries and topics",
            "type": "boolean",
            "description": "Fetch the related queries and related topics slices through Apify residential proxy identities (datacenter stays in use for the series and regions). Google rate-limits that slice hardest; turn this on when runs report terms returned without related queries. Residential traffic is small here (tens of KB per term) but is billed as proxy usage. HTTP mode only; browser mode loads every widget on one page through Proxy configuration.",
            "default": false
          },
          "fetchMode": {
            "title": "Fetch mode",
            "enum": [
              "http",
              "browser"
            ],
            "type": "string",
            "description": "How to read Google Trends. \"http\" (default) calls the widget endpoints directly. \"browser\" opens the explore page in headless Chromium and reads the same widget JSON from the page's own traffic. Use browser only if HTTP runs start failing because Google changed the widget protocol or is serving a JavaScript challenge. Browser mode needs at least 2 GB of memory and costs more per term (see the README section Fallback mode).",
            "default": "http"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}