{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends Scraper — Interest Over Time & By Region",
    "description": "Scrape Google Trends search interest as flat, spreadsheet-ready rows: one per keyword and date, one per keyword and region. Any country or subregion, any timeframe from the last hour back to 2004, and web / news / YouTube / image / shopping search. No browser, no API key, no login.",
    "version": "0.1",
    "x-build-id": "ayxajPkRaOnAxLuzR"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapersdelight~google-trends-interest-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapersdelight-google-trends-interest-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/scrapersdelight~google-trends-interest-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapersdelight-google-trends-interest-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/scrapersdelight~google-trends-interest-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapersdelight-google-trends-interest-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": "The keywords to measure. Each term is scraped as its own Google Trends query, so its 0-100 interest values are scaled to its OWN peak — switch on 'Compare terms against each other' if you need the values to be comparable BETWEEN terms. Leave empty and the actor runs the documented sample (\"bitcoin\", US, past 12 months) so it never returns nothing.",
            "default": [
              "bitcoin"
            ],
            "items": {
              "type": "string"
            }
          },
          "geos": {
            "title": "Locations",
            "type": "array",
            "description": "One or more Google Trends location codes. Empty string \"\" = Worldwide. Use an ISO country code for a country (`US`, `GB`, `DE`, `IN`), or `COUNTRY-SUBDIVISION` for a state / province / region (`US-CA`, `US-NY`, `GB-ENG`, `CA-ON`). Every search term is scraped once per location, so 10 terms x 3 locations = 30 queries.",
            "default": [
              "US"
            ],
            "items": {
              "type": "string"
            }
          },
          "timeframe": {
            "title": "Timeframe",
            "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": "How far back to measure. Google picks the data granularity from this: 'Past hour' and 'Past 4 hours' return one point per minute, 'Past day' every 8 minutes, 'Past 7 days' hourly, 'Past 1/3 months' daily, 'Past 12 months' and 'Past 5 years' weekly, and '2004 - present' monthly. Ignored when 'Custom date range' is filled in.",
            "default": "today 12-m"
          },
          "customTimeRange": {
            "title": "Custom date range",
            "type": "string",
            "description": "Overrides 'Timeframe' when set. Two ISO dates separated by a space, e.g. `2024-01-01 2024-12-31`. Google chooses the granularity from the span: under ~9 months returns daily points, longer returns weekly, several years returns monthly. Data starts at 2004-01-01.",
            "default": ""
          },
          "category": {
            "title": "Google Trends category ID",
            "minimum": 0,
            "type": "integer",
            "description": "Restrict the measurement to one Google Trends topic category, which strips out same-spelling searches from other subjects. 0 = All categories. Common IDs: 7 Finance, 12 Business & Industrial, 5 Computers & Electronics, 45 Health, 71 Food & Drink, 20 Games, 174 Autos & Vehicles, 958 Sports, 8 Arts & Entertainment, 67 Travel, 29 Jobs & Education.",
            "default": 0
          },
          "searchProperty": {
            "title": "Google property",
            "enum": [
              "",
              "images",
              "news",
              "youtube",
              "froogle"
            ],
            "type": "string",
            "description": "Which Google surface to measure interest on. Web search is the default; the others measure the same term inside Google Images, Google News, YouTube search and Google Shopping, and their curves can differ sharply from web search.",
            "default": ""
          },
          "includeInterestOverTime": {
            "title": "Interest over time",
            "type": "boolean",
            "description": "Return one row per search term and date — the Google Trends line chart, flattened. This is the main output; switching it off leaves only the by-region rows.",
            "default": true
          },
          "includeInterestByRegion": {
            "title": "Interest by region",
            "type": "boolean",
            "description": "Also return one row per search term and region — the Google Trends map, flattened, with each region's 0-100 value and its rank. Worldwide gives ~250 countries, a country gives its states/provinces, and a state gives its metro areas. Costs one extra request per query.",
            "default": true
          },
          "includeRegionsWithNoData": {
            "title": "Include regions with no data",
            "type": "boolean",
            "description": "Google pads the region list with entries it flags as having no data. Measured 2026-09-02: a worldwide query returned 250 countries of which only 54 carried data, and City detail returned 200 cities of which only 10 did. Those blanks are dropped by default — not delivered and not charged. Switch this on if you are drawing a map and need every shape returned.",
            "default": false
          },
          "regionResolution": {
            "title": "Region detail level",
            "enum": [
              "auto",
              "REGION",
              "DMA",
              "CITY"
            ],
            "type": "string",
            "description": "How finely to break down 'Interest by region'. 'Automatic' uses the level Google shows for your location (countries worldwide, states for a country, metros for a state). You can force a FINER level — Metro or City — but not a coarser one; if the level you pick is unavailable for that location the actor logs it and falls back to Automatic.",
            "default": "auto"
          },
          "compareKeywords": {
            "title": "Compare terms against each other",
            "type": "boolean",
            "description": "Put the search terms into ONE Google Trends comparison (max 5 per group) so their values are scaled to a single shared peak and are directly comparable — 'brand A is 3x brand B'. Off by default, because each term measured on its own is scaled to its own peak, which is what you want for tracking a large keyword list.",
            "default": false
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "The `hl` locale Google answers in. It changes the human-readable labels only — `formattedTime`, `timeframeLabel` and the region names in `regionName`. The numbers are identical in every language.",
            "default": "en-US"
          },
          "maxItems": {
            "title": "Max rows",
            "minimum": 0,
            "type": "integer",
            "description": "Stop after this many rows and end the run cleanly. A 12-month weekly series is 53 rows per term, and interest by region adds ~50 more for a US query or ~250 for a worldwide one. 0 = no limit.",
            "default": 5000
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "How many queries to run at once. Google Trends rate-limits hard: measured over 20 keywords, 1 at a time succeeded on 18/20 first attempts while 4 at a time succeeded on only 8/20. Raising this makes a run faster but pushes more queries into the retry path. Leave at 2 unless you are re-running a small list.",
            "default": 2
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify Proxy is ON by default and should stay on. Google Trends rate-limits per IP, and this actor takes a fresh proxy session for every query and again for every retry — that rotation is the whole defence against the 429s. Any proxy group works; no residential requirement was measured.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}