{"id":5039,"library":"pytrends","title":"pytrends","description":"Pytrends is an unofficial Python library that provides a pseudo-API for Google Trends, allowing users to automate the downloading of search interest data. The current version, 4.9.2, was released in April 2023. Due to its unofficial nature, it does not adhere to a fixed release cadence but rather updates as needed to adapt to changes in Google's backend, which can frequently introduce breaking changes.","status":"active","version":"4.9.2","language":"en","source_language":"en","source_url":"https://github.com/GeneralMills/pytrends","tags":["google-trends","api","data-science","web-scraping"],"install":[{"cmd":"pip install pytrends","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Handles HTTP requests to Google Trends.","package":"requests","optional":false},{"reason":"Used for parsing HTML responses.","package":"lxml","optional":false},{"reason":"Provides DataFrame structures for data manipulation and output.","package":"pandas","optional":false}],"imports":[{"symbol":"TrendReq","correct":"from pytrends.request import TrendReq"}],"quickstart":{"code":"from pytrends.request import TrendReq\nimport pandas as pd\n\n# Initialize pytrends object\n# hl: host language, tz: timezone offset (e.g., 360 for US CST, NOT -360)\npytrends = TrendReq(hl='en-US', tz=360)\n\n# Define keyword list\nkw_list = [\"Python programming\", \"Data Science\"]\n\n# Build payload for the request\n# timeframe: e.g., 'today 5-y' for last 5 years\npytrends.build_payload(kw_list, cat=0, timeframe='today 5-y', geo='US', gprop='')\n\n# Get Interest Over Time data\ninterest_over_time_df = pytrends.interest_over_time()\n\n# Print the first few rows of the DataFrame\nprint(\"Interest Over Time (first 5 rows):\")\nprint(interest_over_time_df.head())\n\n# Get Interest by Region data\ninterest_by_region_df = pytrends.interest_by_region(resolution='COUNTRY', inc_low_vol=True, inc_geo_code=True)\nprint(\"\\nInterest By Region (first 5 rows):\")\nprint(interest_by_region_df.head())","lang":"python","description":"This quickstart demonstrates how to initialize the `TrendReq` object, build a search payload for multiple keywords, and retrieve 'Interest Over Time' and 'Interest by Region' data from Google Trends. The data is returned as pandas DataFrames. Note the `tz` parameter for timezone offset, where '360' represents UTC-6 (e.g., US Central Standard Time) and not '-360'."},"warnings":[{"fix":"Always check for the latest `pytrends` version and consult the GitHub repository for recent fixes or workarounds. Installing directly from GitHub might be necessary for the latest patches.","message":"Pytrends is an unofficial API and is prone to frequent breaking changes when Google updates its backend or internal API. This can lead to unexpected errors (e.g., 404, 500) or changes in expected behavior without prior notice.","severity":"breaking","affected_versions":"All versions"},{"fix":"Introduce delays between requests (`time.sleep()`), reduce the number of requests, use proxies, or configure `retries` and `backoff_factor` when initializing `TrendReq`. Consider batching requests.","message":"Frequent HTTP 429 (Too Many Requests) errors are common due to Google's rate limiting. This can occur even with seemingly low request volumes, especially from shared IP addresses (e.g., school networks).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always include all keywords you wish to compare within a single `kw_list` parameter when calling `build_payload()`.","message":"Google Trends data is relative and scaled from 0-100. This means that if you pull data for a keyword in two separate requests, the absolute popularity between them cannot be directly compared. Comparisons are only valid when multiple keywords are requested within the *same* `build_payload` call.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully determine the correct `tz` value for your target region. For example, US Central Standard Time (UTC-6) is `tz=360`. Refer to `pytrends` documentation or community resources for a list of common `hl` and `tz` pairs.","message":"Incorrect timezone handling is a common pitfall. By default, Pytrends data is based on UTC. The `tz` parameter in `TrendReq` expects the timezone offset in minutes, but Google's internal handling often means positive values for 'west' of UTC (e.g., '360' for UTC-6, not '-360').","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review your `kw_list`, `timeframe`, `geo`, `cat`, and `gprop` parameters to ensure they are valid and correctly formatted according to Google Trends' expectations.","message":"HTTP 400 (Bad Request) errors can occur if the structure of the request payload is incorrect, unrelated to rate limits. This might involve invalid keyword combinations, unsupported timeframes, or malformed parameters.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}