{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends API: interest over time, related queries",
    "description": "Google Trends as clean JSON: interest over time, by region, related queries and topics, compare up to 5 terms, trending now. No browser, no login. Rate-limit aware: backs off on 429 and never rotates IP to dodge it. Charged only for terms that fully succeed.",
    "version": "1.0",
    "x-build-id": "h9g903YebQ8LIdiAl"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/pxdata~google-trends-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-pxdata-google-trends-api",
        "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/pxdata~google-trends-api/runs": {
      "post": {
        "operationId": "runs-sync-pxdata-google-trends-api",
        "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/pxdata~google-trends-api/run-sync": {
      "post": {
        "operationId": "run-sync-pxdata-google-trends-api",
        "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": "Mode",
            "enum": [
              "terms",
              "compare",
              "trendingNow"
            ],
            "type": "string",
            "description": "terms: one item per term, each term analysed on its own scale (0-100). compare: terms are grouped in sets of up to 5 and compared on the SAME scale. trendingNow: what people are searching for right now in a country.",
            "default": "terms"
          },
          "terms": {
            "title": "Search terms",
            "maxItems": 500,
            "type": "array",
            "description": "One per line, up to 500. Ignored in trendingNow mode. Duplicates are removed.",
            "items": {
              "type": "string"
            }
          },
          "geo": {
            "title": "Country or region",
            "type": "string",
            "description": "ISO code: BR, US, GB, or a region like US-CA, BR-SP. Empty means worldwide (trendingNow uses US when empty).",
            "default": ""
          },
          "timeRange": {
            "title": "Period",
            "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",
              "custom"
            ],
            "type": "string",
            "description": "Google presets, or custom with the two dates below. Short windows (past hour/4 hours) return minute-level data and are the most likely to be rate limited.",
            "default": "today 12-m"
          },
          "startDate": {
            "title": "Start date (custom)",
            "type": "string",
            "description": "YYYY-MM-DD. Only for Period = Custom dates."
          },
          "endDate": {
            "title": "End date (custom)",
            "type": "string",
            "description": "YYYY-MM-DD. Only for Period = Custom dates."
          },
          "category": {
            "title": "Category ID",
            "minimum": 0,
            "type": "integer",
            "description": "Google Trends category number. 0 is all categories. Examples: 7 Finance, 5 Computers & Electronics, 71 Food & Drink, 16 News, 18 Shopping, 3 Arts & Entertainment, 45 Health.",
            "default": 0
          },
          "property": {
            "title": "Search property",
            "enum": [
              "",
              "images",
              "news",
              "youtube",
              "froogle"
            ],
            "type": "string",
            "description": "Where the searches happened.",
            "default": ""
          },
          "language": {
            "title": "Language (hl)",
            "type": "string",
            "description": "Interface language for labels and formatted dates, e.g. en-US, pt-BR, es-419. It does not filter searches; use Country for that.",
            "default": "en-US"
          },
          "timezoneOffsetMinutes": {
            "title": "Timezone offset (minutes)",
            "type": "integer",
            "description": "Minutes behind UTC, as the Trends site sends it. 180 = Brasilia, 0 = UTC, 300 = New York (winter).",
            "default": 0
          },
          "blocks": {
            "title": "Data blocks",
            "type": "array",
            "description": "Which data to fetch for each term (terms and compare modes). Each extra block is one more request to Google, so fewer blocks means faster and less chance of rate limiting. The price per term is the same. relatedTopics is experimental: Google currently returns an empty list to anonymous API sessions, so it is off by default and the item carries a warning when empty.",
            "items": {
              "type": "string",
              "enum": [
                "timeline",
                "regions",
                "relatedQueries",
                "relatedTopics"
              ]
            },
            "default": [
              "timeline",
              "regions",
              "relatedQueries"
            ]
          },
          "regionResolution": {
            "title": "Region detail",
            "enum": [
              "",
              "COUNTRY",
              "REGION",
              "CITY",
              "DMA"
            ],
            "type": "string",
            "description": "Granularity for the by-region block. Empty lets Google pick (country-wide geo gives states/regions; worldwide gives countries).",
            "default": ""
          },
          "includeLowVolumeRegions": {
            "title": "Include low-volume regions",
            "type": "boolean",
            "description": "Also list regions with very little search volume.",
            "default": false
          },
          "maxTrendingItems": {
            "title": "Max trending items",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "trendingNow mode only.",
            "default": 50
          },
          "cacheTtlHours": {
            "title": "Cache results (hours)",
            "minimum": 0,
            "maximum": 720,
            "type": "integer",
            "description": "0 disables. When set, an identical request (same terms, geo, period, blocks) answered within this window is served from your own named key-value store 'google-trends-cache', is not sent to Google and is not charged. Items served from cache have fromCache: true.",
            "default": 0
          },
          "minDelayMs": {
            "title": "Minimum delay between requests (ms)",
            "minimum": 1000,
            "maximum": 60000,
            "type": "integer",
            "description": "Plus 0-1.5 s of random jitter. Lowest allowed is 1000. The default is deliberately slow: this actor favours finishing over speed.",
            "default": 2500
          },
          "maxRetriesOn429": {
            "title": "Retries on HTTP 429",
            "minimum": 0,
            "maximum": 8,
            "type": "integer",
            "description": "Waits 20 s, 40 s, 80 s... (or Retry-After if Google sends it) and retries on the same session. The actor never changes IP or session to get around a 429.",
            "default": 4
          },
          "stopAfterConsecutiveRateLimits": {
            "title": "Stop after N rate-limited terms in a row",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "If Google keeps answering 429 after all retries, the remaining terms are returned as SKIPPED (not charged) instead of hammering Google.",
            "default": 3
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Optional. Normally not needed. If used, the same proxy IP is kept for the whole run."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}