{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends Scraper & Keyword Monitor",
    "description": "Enter keywords, get Google Trends interest over time, related queries and interest by region as flat rows, plus one summary row per keyword: latest value, change vs previous period, change since your last run, spike flag. No browser. Pay per keyword that returns data; no start fee.",
    "version": "0.1",
    "x-build-id": "fp61TZPPFXe8SFvfe"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/magenta_courser~google-trends-monitor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-magenta_courser-google-trends-monitor",
        "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/magenta_courser~google-trends-monitor/runs": {
      "post": {
        "operationId": "runs-sync-magenta_courser-google-trends-monitor",
        "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/magenta_courser~google-trends-monitor/run-sync": {
      "post": {
        "operationId": "run-sync-magenta_courser-google-trends-monitor",
        "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": [
          "keywords"
        ],
        "properties": {
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "Search terms to look up on Google Trends, one per item, in any language. Example: [\"bitcoin\", \"nvidia\", \"다이소\"] (다이소 = Daiso, a Korean retail chain). Write the term as people type it into Google; do not add operators or quotes. Max 100 characters per keyword; duplicates are removed. Each keyword is looked up on its own 0-100 scale unless \"Compare keywords\" is on. You pay one \"keyword\" event per keyword and geo that completes with data.",
            "items": {
              "type": "string"
            }
          },
          "geo": {
            "title": "Country (geo)",
            "type": "string",
            "description": "Where the searches come from. \"worldwide\" (default) or a two-letter ISO country code in upper case: \"US\", \"GB\", \"DE\", \"KR\" (South Korea), \"JP\" (Japan), \"TW\" (Taiwan). Several countries: one string separated by commas, e.g. \"US,KR,JP\" - every keyword is then looked up (and billed) once per country. A region code such as \"US-CA\" (California) also works. Country names such as \"Korea\" are not accepted.",
            "default": "worldwide"
          },
          "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": "How far back to look. Use exactly one of: \"now 1-H\" (past hour), \"now 4-H\" (past 4 hours), \"now 1-d\" (past day), \"now 7-d\" (past 7 days), \"today 1-m\" (past 30 days), \"today 3-m\" (past 90 days, default), \"today 12-m\" (past 12 months), \"today 5-y\" (past 5 years), \"all\" (2004 - present). The range decides the resolution: past hour / 4 hours = per minute, past day = 8 minutes, past 7 days = hourly, past 30 / 90 days = daily, past 12 months / 5 years = weekly, all = monthly. For daily monitoring use \"today 1-m\" or \"today 3-m\"; for hourly monitoring \"now 7-d\".",
            "default": "today 3-m"
          },
          "include": {
            "title": "What to output",
            "type": "array",
            "description": "Which detail rows to output, as an array. \"interestOverTime\" (default) = one row per point in time. \"relatedQueries\" = top and rising related searches (up to 25 each per keyword). \"interestByRegion\" = one row per country / region with data. Example: [\"interestOverTime\", \"relatedQueries\"]. The keywordSummary row (latest value, changes, spike flag) is always output; pass an empty array [] to get only summary rows - the smallest output, good for AI agents. The price per keyword is the same whatever you include.",
            "items": {
              "type": "string",
              "enum": [
                "interestOverTime",
                "relatedQueries",
                "interestByRegion"
              ],
              "enumTitles": [
                "Interest over time",
                "Related queries (top + rising)",
                "Interest by region"
              ]
            },
            "default": [
              "interestOverTime"
            ]
          },
          "compareMode": {
            "title": "Compare keywords (shared scale)",
            "type": "boolean",
            "description": "false (default): every keyword gets its own 0-100 scale, where 100 is that keyword's own peak - use this for monitoring. true: keywords are sent to Google in groups of up to 5 (in list order) and share one scale, where 100 is the peak of the most searched keyword in the group - use this to see which keyword is searched more. Google allows at most 5 keywords per comparison; values from different groups, or from compare on and off, are not comparable.",
            "default": false
          },
          "customTimeRange": {
            "title": "Custom time range",
            "type": "string",
            "description": "Optional. Two dates as \"YYYY-MM-DD YYYY-MM-DD\" (start, space, end), for example \"2026-01-01 2026-06-30\". The start must be before the end. When set, it overrides \"Time range\"."
          },
          "category": {
            "title": "Category",
            "enum": [
              "0",
              "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": "Optional Google Trends category ID as a string, to narrow an ambiguous word such as \"apple\" or \"jaguar\". \"0\" = all categories (default). Examples: \"7\" Finance, \"18\" Shopping, \"71\" Food & Drink, \"44\" Beauty & Fitness, \"5\" Computers & Electronics, \"67\" Travel. Only the listed top-level categories are accepted.",
            "default": "0"
          },
          "historyStoreName": {
            "title": "History store (change since last run)",
            "type": "string",
            "description": "Name of the key-value store that remembers the latest value of every keyword, so the next run can report the change since your last run and flag spikes. Letters, digits and hyphens, 3-63 characters, e.g. \"my-brand-keywords-daily\". Runs that use the same name share one history; use different names for separate schedules. Set to an empty string \"\" to turn the comparison off. Default: \"google-trends-monitor-history\".",
            "default": "google-trends-monitor-history"
          },
          "spikeThresholdPct": {
            "title": "Spike threshold (%)",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "The summary row gets spike = true when the latest value is at least this many percent - and at least 10 points - above the value at your last run (on a first run: above the previous period). Integer from 1 to 1000. Example: 50 flags a rise from 40 to 60 or more. Default 50.",
            "default": 50
          },
          "proxyMode": {
            "title": "Proxy mode",
            "enum": [
              "auto",
              "datacenter",
              "residential"
            ],
            "type": "string",
            "description": "\"auto\" (default, recommended): datacenter proxies first; retries and any rate-limited stretch go through residential proxies. \"datacenter\": datacenter proxies only - Google rate-limits a small proxy pool after about 100 keywords. \"residential\": every request through residential proxies. Proxy traffic is included in the price per keyword.",
            "default": "auto"
          },
          "maxRequests": {
            "title": "Max requests per run",
            "minimum": 10,
            "type": "integer",
            "description": "Optional safety limit: the maximum number of HTTP requests in this run, retries included (integer, minimum 10, e.g. 200). Leave empty for an automatic limit of about 3x what the keywords need. Keywords that do not fit get status \"budgetLimited\" and are not charged."
          },
          "proxyConfiguration": {
            "title": "Custom proxy (advanced)",
            "type": "object",
            "description": "Optional, advanced. Only used when you pick specific Apify Proxy groups or enter your own proxy URLs here; it then replaces \"Proxy mode\". Leave empty in normal use."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}