{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends API: Bulk Keyword Trends Export",
    "description": "Unofficial Google Trends API for bulk keyword research: export interest over time, interest by region and top and rising related queries for many keywords, countries and date windows to CSV or JSON. Resumable batches with quality notes. Values are relative interest, not search volume.",
    "version": "1.1",
    "x-build-id": "19CLmeZnpeyScla0Y"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/whoareyouanas~google-trends-batch-research/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-whoareyouanas-google-trends-batch-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/whoareyouanas~google-trends-batch-research/runs": {
      "post": {
        "operationId": "runs-sync-whoareyouanas-google-trends-batch-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/whoareyouanas~google-trends-batch-research/run-sync": {
      "post": {
        "operationId": "run-sync-whoareyouanas-google-trends-batch-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": {
          "mode": {
            "title": "Research mode",
            "enum": [
              "independent",
              "compare"
            ],
            "type": "string",
            "description": "Research each keyword independently or compare explicit groups on a native shared timeline scale."
          },
          "keywords": {
            "title": "Keywords or Google topic IDs",
            "minItems": 1,
            "maxItems": 200,
            "type": "array",
            "description": "Search terms or Google topic IDs. Required in independent mode.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          "comparisonGroups": {
            "title": "Comparison groups",
            "minItems": 1,
            "maxItems": 200,
            "type": "array",
            "description": "Compare mode only. Each object contains keywords (2–5 distinct terms) and an optional label. Related queries require independent mode.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "keywords"
              ],
              "properties": {
                "label": {
                  "type": "string",
                  "maxLength": 200,
                  "title": "label",
                  "description": "label",
                  "editor": "textfield"
                },
                "keywords": {
                  "type": "array",
                  "minItems": 2,
                  "maxItems": 5,
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "title": "keywords",
                  "description": "keywords",
                  "editor": "stringList"
                }
              }
            }
          },
          "geographies": {
            "title": "Countries or subregions",
            "minItems": 1,
            "maxItems": 10,
            "type": "array",
            "description": "Country/subregion codes, such as US, GB, IN or US-CA. Use an empty string for worldwide.",
            "items": {
              "type": "string",
              "pattern": "^$|^[A-Z]{2}(?:-[A-Z0-9]{1,8})?$"
            }
          },
          "timeWindows": {
            "title": "Date windows",
            "minItems": 1,
            "maxItems": 4,
            "type": "array",
            "description": "Google preset or YYYY-MM-DD YYYY-MM-DD. Use fixed dates for repeatable research.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            }
          },
          "surfaces": {
            "title": "Research surfaces",
            "minItems": 1,
            "maxItems": 3,
            "uniqueItems": true,
            "type": "array",
            "description": "Timeline is required. Related queries are available for independent keyword research.",
            "items": {
              "type": "string",
              "enum": [
                "timeline",
                "regions",
                "relatedQueries"
              ],
              "enumTitles": [
                "Interest over time",
                "Interest by region",
                "Top and rising related queries"
              ]
            }
          },
          "category": {
            "title": "Google category ID",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Google Trends category ID; zero includes all categories."
          },
          "property": {
            "title": "Search property",
            "enum": [
              "web",
              "images",
              "news",
              "youtube",
              "shopping"
            ],
            "type": "string",
            "description": "The Google search surface to measure."
          },
          "language": {
            "title": "Interface language",
            "pattern": "^[a-z]{2,3}(?:-[A-Za-z]{2,8})?$",
            "type": "string",
            "description": "Interface language for source labels; does not translate keywords."
          },
          "timezoneOffsetMinutes": {
            "title": "Time zone offset in minutes",
            "minimum": -1439,
            "maximum": 1439,
            "type": "integer",
            "description": "Google/JavaScript convention: India is -330, UTC is 0. Does not set research geography."
          },
          "maxAnalyses": {
            "title": "Maximum expanded analyses",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Reject a larger expanded matrix before any source requests; maximum 1,000."
          },
          "maxRunSeconds": {
            "title": "Maximum run seconds",
            "minimum": 30,
            "maximum": 3600,
            "type": "integer",
            "description": "Stop new work before this runtime budget and preserve results for resume."
          },
          "concurrency": {
            "title": "Concurrent analyses",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "Maximum analyses in flight; requests also follow a shared pacing limit."
          },
          "requestDelayMillis": {
            "title": "Minimum source request delay (ms)",
            "minimum": 250,
            "maximum": 60000,
            "type": "integer",
            "description": "Minimum time between source requests across all workers. Increase when Google rate-limits requests."
          },
          "maxRetries": {
            "title": "Retries per source operation",
            "minimum": 0,
            "maximum": 3,
            "type": "integer",
            "description": "Maximum additional attempts per source operation, excluding the first attempt."
          },
          "requestTimeoutSeconds": {
            "title": "HTTP timeout (seconds)",
            "minimum": 5,
            "maximum": 60,
            "type": "integer",
            "description": "Maximum duration of one HTTP request."
          },
          "reviewRelatedQueries": {
            "title": "Annotate related queries for review",
            "type": "boolean",
            "description": "Add literal seed-token overlap, URL-looking text and exact promotional-phrase annotations. Never filters or ranks relevance. Disable without changing the research plan, including on resume."
          },
          "planOnly": {
            "title": "Preview workload without fetching",
            "type": "boolean",
            "description": "Produce a workload and charge estimate without fetching Google or charging research events."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Residential sessions are recommended for production. Set useApifyProxy to false for direct local tests."
          },
          "resumeFromRunId": {
            "title": "Resume from a stopped run",
            "minLength": 1,
            "maxLength": 80,
            "type": "string",
            "description": "Imports the original plan. Remove keywords, geographies, date windows and other research fields when resuming."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}