{
  "openapi": "3.0.1",
  "info": {
    "title": "Bulk Google Trends Scraper | Compare, Export & Resume",
    "description": "Bulk Google Trends research across keywords, countries and dates. Get timeline, regions, related queries and topics. Preserve comparison scope, inspect every request, resume incomplete batches, and download tidy CSV/JSON plus an n8n workflow.",
    "version": "0.1",
    "x-build-id": "UgsyO3wANhlEelt7w"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/cauldo~google-trends-bulk-research/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-cauldo-google-trends-bulk-research",
        "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/cauldo~google-trends-bulk-research/runs": {
      "post": {
        "operationId": "runs-sync-cauldo-google-trends-bulk-research",
        "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/cauldo~google-trends-bulk-research/run-sync": {
      "post": {
        "operationId": "run-sync-cauldo-google-trends-bulk-research",
        "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": {
          "keywords": {
            "title": "Keywords or topic IDs",
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "description": "Each term is researched independently by default, across every selected location and date range. Enter plain keywords or Google topic IDs such as /m/02vqfm (Coffee). If omitted, the sample keyword is coffee. Do not supply this field together with advanced requests.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          "compareKeywords": {
            "title": "Compare keywords on one timeline scale",
            "type": "boolean",
            "description": "Group the keyword list into one Google comparison request per location/date range. Maximum five terms. Keep this off for independent keyword research. Groups are never silently split because separate requests do not share a 0–100 scale. Terms in a comparison must be distinct. Omit this field entirely when using advanced requests, which control their own groups."
          },
          "geos": {
            "title": "Locations",
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "description": "Country or subregion codes, such as US, GB, IN, or US-CA. Use an empty string for worldwide: [\"\"]. Defaults to [\"US\"] when omitted. Every location combines with every date range and keyword/group.",
            "items": {
              "type": "string",
              "maxLength": 12
            }
          },
          "timeRanges": {
            "title": "Date ranges",
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "description": "Supported ranges: 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, or YYYY-MM-DD YYYY-MM-DD. Fixed dates must be valid, ordered, on/after 2004-01-01, and not in the future (UTC). Defaults to [\"today 3-m\"].",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 21
            }
          },
          "surfaces": {
            "title": "Research outputs",
            "minItems": 1,
            "maxItems": 4,
            "type": "array",
            "description": "Select interest-over-time, regional interest, related search queries, and/or related topics. Defaults to timeline, regions, and relatedQueries. Every requested output receives an explicit status, including valid no-data and extraction failures. Related outputs and regional availability vary with the query and time range.",
            "items": {
              "type": "string",
              "enum": [
                "timeline",
                "regions",
                "relatedQueries",
                "relatedTopics"
              ],
              "enumTitles": [
                "Interest over time",
                "Interest by region",
                "Related queries",
                "Related topics"
              ]
            }
          },
          "category": {
            "title": "Google Trends category ID",
            "minimum": 0,
            "maximum": 99999,
            "type": "integer",
            "description": "Google's numeric category ID. Use 0 for all categories (the default). An invalid or unavailable category can lead to a source error or no data; this actor does not guess a replacement category."
          },
          "property": {
            "title": "Search property",
            "enum": [
              "",
              "images",
              "news",
              "youtube",
              "froogle"
            ],
            "type": "string",
            "description": "Choose the Google search property. Empty string means Web Search, the default. Shopping uses Google's API value froogle."
          },
          "language": {
            "title": "Language",
            "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,4})?$",
            "maxLength": 12,
            "type": "string",
            "description": "Google response language, such as en-US, de, or zh-TW. Defaults to en-US. This localizes source labels; it does not restrict searches to that language."
          },
          "timezone": {
            "title": "Timezone offset in minutes",
            "minimum": -840,
            "maximum": 720,
            "type": "integer",
            "description": "Google's minutes-west-of-UTC offset. Defaults to 0 (UTC). For UTC−5 use 300; for UTC+2 use −120. Affects source time buckets, especially hourly data."
          },
          "requests": {
            "title": "Advanced research requests",
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "description": "Optional explicit request list; cannot be combined with top-level keywords or compareKeywords. Each item requires one to five distinct keywords and may set label, geo, time, category, property, and surfaces. A single global geo/time is inherited; when a global list has multiple entries, every explicit request must set that dimension. The list never expands a matrix. Other missing values inherit global settings. Equivalent requests are collected once and preserve input indices and labels.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "keywords"
              ],
              "properties": {
                "label": {
                  "title": "Label",
                  "type": "string",
                  "description": "Optional label retained in output and duplicate aliases.",
                  "editor": "textfield",
                  "minLength": 1,
                  "maxLength": 200
                },
                "keywords": {
                  "title": "Keywords",
                  "type": "array",
                  "description": "One to five distinct terms or topic IDs sharing one comparison request. Duplicates differing only in case or surrounding spaces are rejected.",
                  "editor": "stringList",
                  "minItems": 1,
                  "maxItems": 5,
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "uniqueItems": true
                },
                "geo": {
                  "title": "Location",
                  "type": "string",
                  "description": "Country/subregion code, or empty string for worldwide.",
                  "editor": "textfield",
                  "maxLength": 12
                },
                "time": {
                  "title": "Date range",
                  "type": "string",
                  "description": "Supported relative range or YYYY-MM-DD YYYY-MM-DD.",
                  "editor": "textfield",
                  "minLength": 1,
                  "maxLength": 21
                },
                "category": {
                  "title": "Category ID",
                  "type": "integer",
                  "description": "Google's numeric category ID; 0 means all categories.",
                  "minimum": 0,
                  "maximum": 99999
                },
                "property": {
                  "title": "Search property",
                  "type": "string",
                  "description": "Google API property; empty string means Web Search.",
                  "editor": "select",
                  "enum": [
                    "",
                    "images",
                    "news",
                    "youtube",
                    "froogle"
                  ]
                },
                "surfaces": {
                  "title": "Outputs",
                  "type": "array",
                  "description": "Outputs to fetch for this request.",
                  "editor": "select",
                  "minItems": 1,
                  "maxItems": 4,
                  "items": {
                    "type": "string",
                    "enum": [
                      "timeline",
                      "regions",
                      "relatedQueries",
                      "relatedTopics"
                    ]
                  }
                }
              }
            }
          },
          "maxRequests": {
            "title": "Maximum unique research requests",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Validation guard for predictable batch size. The actor rejects a batch exceeding this limit before extraction; it never silently discards the excess. Identical requests are deduplicated. A keyword comparison counts as one request per location/date range. The un-deduplicated matrix is limited to 500 entries.",
            "default": 100
          },
          "maxRunSeconds": {
            "title": "Maximum processing time (seconds)",
            "minimum": 30,
            "maximum": 3600,
            "type": "integer",
            "description": "Stop starting new research requests after this time budget. Unfinished requests are accounted for and saved for resume. In-flight requests may take up to their timeout to finish. Set the Apify run timeout higher than this budget so the actor can save its report.",
            "default": 600
          },
          "concurrency": {
            "title": "Concurrent research requests",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Number of research requests processed concurrently. Low concurrency reduces Google rate limiting. Start with the default of 2; raising this does not guarantee faster or more complete results.",
            "default": 2
          },
          "maxRetries": {
            "title": "Retries per failed research request",
            "minimum": 0,
            "maximum": 3,
            "type": "integer",
            "description": "Additional attempts for retryable extraction failures. Retries are bounded; blocked or incomplete extraction is reported explicitly rather than treated as no data.",
            "default": 2
          },
          "requestTimeoutSecs": {
            "title": "HTTP request timeout (seconds)",
            "minimum": 10,
            "maximum": 60,
            "type": "integer",
            "description": "Timeout for an individual Google HTTP request. One research request can make several HTTP requests to retrieve its selected outputs.",
            "default": 30
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Residential Apify Proxy is the default because Google frequently rate-limits datacenter/direct requests. Configured Apify proxy and platform usage are included in the published pay-per-event price. If you supply your own proxies, your proxy provider charges under its own terms. You may disable proxy use, but successful Google access is not guaranteed.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "resumeFromRunId": {
            "title": "Resume from an earlier Apify run",
            "pattern": "^$|^[A-Za-z0-9]{17}$",
            "maxLength": 17,
            "type": "string",
            "description": "Optional 17-character run ID. Resume saved work from that run using the original research inputs. You must have access to the earlier run and its storage. Use either this field or resumeKeyValueStoreId. Omit new research fields to restore the earlier batch."
          },
          "resumeKeyValueStoreId": {
            "title": "Resume from a saved key-value store",
            "pattern": "^$|^[A-Za-z0-9]{17}$",
            "maxLength": 17,
            "type": "string",
            "description": "Optional 17-character key-value store ID containing this actor's RESUME-STATE. Use this alternative when granting access directly to the saved store. Use either this field or resumeFromRunId, and omit new research fields to restore the earlier batch."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}