{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Trends Scraper - Reliable API",
    "description": "Reliable Google Trends API: interest over time, interest by region and related queries (top & rising) for many keywords. Retries and proxy fallback beat 429s.",
    "version": "1.0",
    "x-build-id": "wYz5XBuYQb0TS13iL"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/atlasdata~google-trends-scraper-reliable/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-atlasdata-google-trends-scraper-reliable",
        "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/atlasdata~google-trends-scraper-reliable/runs": {
      "post": {
        "operationId": "runs-sync-atlasdata-google-trends-scraper-reliable",
        "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/atlasdata~google-trends-scraper-reliable/run-sync": {
      "post": {
        "operationId": "run-sync-atlasdata-google-trends-scraper-reliable",
        "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": [
          "searchTerms"
        ],
        "properties": {
          "searchTerms": {
            "title": "Search terms",
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "description": "Keywords to look up on Google Trends, e.g. [\"bitcoin\", \"ethereum\"]. You can also paste Google Trends explore URLs (https://trends.google.com/trends/explore?q=...); their q, geo, date, cat and gprop parameters are used. Up to 500 terms per run.",
            "items": {
              "type": "string"
            }
          },
          "compareTerms": {
            "title": "Compare terms against each other",
            "type": "boolean",
            "description": "If enabled, terms are queried together (groups of up to 5, like the Google Trends compare view) so their 0-100 values are relative to each other. If disabled (default), each term is queried on its own and scaled 0-100 independently.",
            "default": false
          },
          "geo": {
            "title": "Location (geo)",
            "type": "string",
            "description": "Leave empty for Worldwide. Otherwise an ISO country code (\"US\", \"GB\", \"DE\", \"IN\"), a region (\"US-CA\", \"GB-ENG\") or a US metro/DMA (\"US-NY-501\").",
            "default": ""
          },
          "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",
              "custom"
            ],
            "type": "string",
            "description": "Preset time range, or \"custom\" to use Start date / End date below.",
            "default": "today 12-m"
          },
          "startDate": {
            "title": "Start date (custom range)",
            "type": "string",
            "description": "Used when Time range = Custom. Format YYYY-MM-DD (earliest 2004-01-01). For hourly data use YYYY-MM-DDTHH (max 7-day span)."
          },
          "endDate": {
            "title": "End date (custom range)",
            "type": "string",
            "description": "Used when Time range = Custom. Format YYYY-MM-DD. Defaults to today."
          },
          "category": {
            "title": "Category ID",
            "minimum": 0,
            "type": "integer",
            "description": "Google Trends category ID. 0 = All categories. Common IDs: 3 Arts & Entertainment, 5 Computers & Electronics, 7 Finance, 8 Games, 11 Home & Garden, 12 Business & Industrial, 13 Internet & Telecom, 14 People & Society, 16 News, 18 Shopping, 20 Sports, 22 Books & Literature, 44 Beauty & Fitness, 45 Health, 47 Autos & Vehicles, 66 Pets & Animals, 67 Travel, 71 Food & Drink, 174 Science, 958 Jobs & Education, 299 Online Communities, 533 Reference, 29 Real Estate, 19 Law & Government.",
            "default": 0
          },
          "property": {
            "title": "Google property",
            "enum": [
              "",
              "images",
              "news",
              "youtube",
              "froogle"
            ],
            "type": "string",
            "description": "Which Google search product the interest is measured on.",
            "default": ""
          },
          "timezone": {
            "title": "Timezone",
            "type": "string",
            "description": "Timezone used for dates in interest over time: IANA name (\"America/New_York\", \"Europe/Prague\"), \"UTC+2\", or Google's offset in minutes west of UTC (\"300\" = UTC-5). Default UTC.",
            "default": "UTC"
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Language for region and topic names (Google hl parameter), e.g. en-US, de, fr, es, ja.",
            "default": "en-US"
          },
          "includeInterestOverTime": {
            "title": "Interest over time",
            "type": "boolean",
            "description": "Timeline of search interest (0-100).",
            "default": true
          },
          "includeInterestByRegion": {
            "title": "Interest by region",
            "type": "boolean",
            "description": "Breakdown by country (worldwide) or subregion/metro/city (inside a country).",
            "default": true
          },
          "regionResolution": {
            "title": "Region resolution",
            "enum": [
              "AUTO",
              "COUNTRY",
              "REGION",
              "DMA",
              "CITY"
            ],
            "type": "string",
            "description": "Granularity of Interest by region. Auto = countries for Worldwide, subregions (states/provinces) inside a country. DMA = US metros. City: Google often withholds city-level data for automated sessions; the Actor then falls back to subregion-level data and says so in the run summary.",
            "default": "AUTO"
          },
          "includeLowSearchVolumeRegions": {
            "title": "Include low search volume regions",
            "type": "boolean",
            "description": "Also return regions with very low volume / value 0.",
            "default": false
          },
          "includeRelatedQueries": {
            "title": "Related queries",
            "type": "boolean",
            "description": "Top and rising related search queries (incl. Breakout).",
            "default": true
          },
          "includeRelatedTopics": {
            "title": "Related topics",
            "type": "boolean",
            "description": "Experimental, off by default. Google currently withholds the related topics list from automated (not logged-in) sessions, so this section is normally empty. The run summary tells you when it was withheld. Related queries are unaffected.",
            "default": false
          },
          "outputFormat": {
            "title": "Output format",
            "enum": [
              "flat",
              "perTerm"
            ],
            "type": "string",
            "description": "Flat = one clean row per data point (best for spreadsheets, BI tools and AI agents; every row has the same columns, filter by recordType). Per term = one item per search term with nested arrays.",
            "default": "flat"
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Google Trends rate-limits (HTTP 429) heavily. Apify Proxy is recommended. The Actor automatically falls back to other connection types if the selected one gets blocked.",
            "default": {
              "useApifyProxy": true
            }
          },
          "proxyFallback": {
            "title": "Automatic proxy fallback",
            "type": "boolean",
            "description": "When Google keeps blocking the current connection, automatically switch: your proxy -> Apify datacenter -> Apify residential (if your plan has it) -> direct connection.",
            "default": true
          },
          "maxRetries": {
            "title": "Max retries per request",
            "minimum": 0,
            "maximum": 20,
            "type": "integer",
            "description": "How many times a blocked/failed request is retried (with exponential backoff, a fresh cookie session and a new IP).",
            "default": 8
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Search terms processed in parallel. Keep low (1-3) to avoid Google rate limits.",
            "default": 2
          },
          "failOnNoData": {
            "title": "Fail run if no data",
            "type": "boolean",
            "description": "Mark the run as FAILED when Google has not enough data for any term (useful in pipelines). By default the run succeeds and the summary explains why it is empty.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}