# simplified pytrends
[](https://pypi.python.org/pypi/simplifiedpytrends/)
[](https://pepy.tech/project/simplifiedpytrends)
[](https://github.com/Drakkar-Software/simplifiedpytrends/actions/workflows/main.yml)
Simplified version of https://github.com/GeneralMills/pytrends: removed pandas dependency.
## Introduction
Unofficial API for Google Trends
Allows simple interface for automating downloading of reports from Google Trends. Main feature is to allow the script to login to Google on your behalf to enable a higher rate limit. Only good until Google changes their backend again :-P. When that happens feel free to contribute!
## Table of contens
* [Installation](#installation)
* [API](#api)
* [API Methods](#api-methods)
* [Common API parameters](#common-api-parameters)
* [Interest Over Time](#interest-over-time)
* [Caveats](#caveats)
* [Credits](#credits)
## Installation
pip install simplifiedpytrends
## Requirements
* Written for both Python 2.7+ and Python 3.3+
* Requires Requests
## API
### Connect to Google
from simplifiedpytrends.request import TrendReq
pytrends = TrendReq(hl='en-US', tz=360)
or if you want to use proxies as you are blocked due to Google rate limit:
from simplifiedpytrends.request import TrendReq
pytrends = TrendReq(hl='en-US', tz=360, proxies = {'https': 'https://34.203.233.13:80'})
Note: only https proxies will work, and you need to add the port number after the proxy ip address
### Build Payload
kw_list = ["Blockchain"]
pytrends.build_payload(kw_list, cat=0, timeframe='today 5-y', geo='', gprop='')
Parameters
* `kw_list`
- *Required*
- Keywords to get data for
## API Methods
The following API methods are available:
* [Interest Over Time](#interest-over-time): returns historical, indexed data for when the keyword was searched most as shown on Google Trends' Interest Over Time section.
## Common API parameters
Many API methods use the following:
* `kw_list`
- keywords to get data for
- Example ```['Pizza']```
- Currently supports only one parameter
* Advanced Keywords
- When using Google Trends dashboard Google may provide suggested narrowed search terms.
- For example ```"iron"``` will have a drop down of ```"Iron Chemical Element, Iron Cross, Iron Man, etc"```.
- Find the encoded topic by using the get_suggestions() function and choose the most relevant one for you.
- For example: ```https://www.google.com/trends/explore#q=%2Fm%2F025rw19&cmpt=q```
- ```"%2Fm%2F025rw19"``` is the topic "Iron Chemical Element" to use this with pytrends
- You can also use `pytrends.suggestions()` to automate this.
* `cat`
- Category to narrow results
- Find available cateogies by inspecting the url when manually using Google Trends. The category starts after ```cat=``` and ends before the next ```&``` or view this [wiki page containing all available categories](https://github.com/pat310/google-trends-api/wiki/Google-Trends-Categories)
- For example: ```"https://www.google.com/trends/explore#q=pizza&cat=71"```
- ```'71'``` is the category
- Defaults to no category
* `geo`
- Two letter country abbreviation
- For example United States is ```'US'```
- Defaults to World
- More detail available for States/Provinces by specifying additonal abbreviations
- For example: Alabama would be ```'US-AL'```
- For example: England would be ```'GB-ENG'```
* `tz`
- Timezone Offset
- For example US CST is ```'360'```
* `timeframe`
- Date to start from
- Defaults to last 5yrs, `'today 5-y'`.
- Everything `'all'`
- Specific dates, 'YYYY-MM-DD YYYY-MM-DD' example `'2016-12-14 2017-01-25'`
- Specific datetimes, 'YYYY-MM-DDTHH YYYY-MM-DDTHH' example `'2017-02-06T10 2017-02-12T07'`
- Note Time component is based off UTC
- Current Time Minus Time Pattern:
- By Month: ```'today #-m'``` where # is the number of months from that date to pull data for
- For example: ``'today 3-m'`` would get data from today to 3months ago
- **NOTE** Google uses UTC date as *'today'*
- Seems to only work for 1, 2, 3 months only
- Daily: ```'now #-d'``` where # is the number of days from that date to pull data for
- For example: ``'now 7-d'`` would get data from the last week
- Seems to only work for 1, 7 days only
- Hourly: ```'now #-H'``` where # is the number of hours from that date to pull data for
- For example: ``'now 1-H'`` would get data from the last hour
- Seems to only work for 1, 4 hours only
* `gprop`
- What Google property to filter to
- Example ```'images'```
- Defaults to web searches
- Can be ```images```, ```news```, ```youtube``` or ```froogle``` (for Google Shopping results)
### Interest Over Time
pytrends.interest_over_time()
Returns a sorted list of dict: containing "timestamp" and "data"
# Caveats
* This is not an official or supported API
* Google may change aggregation level for items with very large or very small search volume
* Google will send you an email saying that you had a new login after running this.
* Rate Limit is not publicly known, let me know if you have a consistent estimate
* One user reports that 1,400 sequential requests of a 4 hours timeframe got them to the limit. (Replicated on 2 networks)
* It has been tested, and 60 seconds of sleep between requests (successful or not) is the correct amount once you reach the limit.
* For certain configurations the dependency lib certifi requires the environment variable REQUESTS_CA_BUNDLE to be explicitly set and exported. This variable must contain the path where the ca-certificates are saved or a SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] error is given at runtime.
# Credits
* Original pytrends lib:
- https://github.com/GeneralMills/pytrends
* Major JSON revision ideas taken from pat310's JavaScript library
- https://github.com/pat310/google-trends-api
* Connecting to google code heavily based off Stack Overflow post
- http://stackoverflow.com/questions/6754709/logging-in-to-google-using-python
* With some ideas pulled from Matt Reid's Google Trends API
- https://bitbucket.org/mattreid9956/google-trend-api/overview
Raw data
{
"_id": null,
"home_page": "https://github.com/Drakkar-Software/pytrends",
"name": "simplifiedpytrends",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "google trends api search",
"author": "['John Hogue', 'Burton DeWilde', 'DrakkarSoftware']",
"author_email": "drakkar.software@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/3a/59/fd12a6dcae2d7540a841ba7203d8db54b19c8316713ff456d36a6601a64b/simplifiedpytrends-1.1.2.tar.gz",
"platform": "",
"description": "# simplified pytrends\n[](https://pypi.python.org/pypi/simplifiedpytrends/)\n[](https://pepy.tech/project/simplifiedpytrends)\n[](https://github.com/Drakkar-Software/simplifiedpytrends/actions/workflows/main.yml)\n\nSimplified version of https://github.com/GeneralMills/pytrends: removed pandas dependency.\n\n## Introduction\n\nUnofficial API for Google Trends\n\nAllows simple interface for automating downloading of reports from Google Trends. Main feature is to allow the script to login to Google on your behalf to enable a higher rate limit. Only good until Google changes their backend again :-P. When that happens feel free to contribute!\n\n\n## Table of contens\n\n* [Installation](#installation)\n\n* [API](#api)\n\n * [API Methods](#api-methods)\n\n * [Common API parameters](#common-api-parameters)\n\n * [Interest Over Time](#interest-over-time)\n\n * [Caveats](#caveats)\n\n* [Credits](#credits)\n\n## Installation\n\n pip install simplifiedpytrends\n\n## Requirements\n\n* Written for both Python 2.7+ and Python 3.3+\n* Requires Requests\n\n\n## API\n\n### Connect to Google\n\n from simplifiedpytrends.request import TrendReq\n\n pytrends = TrendReq(hl='en-US', tz=360)\n\nor if you want to use proxies as you are blocked due to Google rate limit:\n\n\n from simplifiedpytrends.request import TrendReq\n\n pytrends = TrendReq(hl='en-US', tz=360, proxies = {'https': 'https://34.203.233.13:80'})\n\nNote: only https proxies will work, and you need to add the port number after the proxy ip address\n\n### Build Payload\n kw_list = [\"Blockchain\"]\n pytrends.build_payload(kw_list, cat=0, timeframe='today 5-y', geo='', gprop='')\n\nParameters\n\n* `kw_list`\n\n - *Required*\n - Keywords to get data for\n\n\n## API Methods\n\nThe following API methods are available:\n\n* [Interest Over Time](#interest-over-time): returns historical, indexed data for when the keyword was searched most as shown on Google Trends' Interest Over Time section.\n\n## Common API parameters\n\nMany API methods use the following:\n\n* `kw_list`\n\n - keywords to get data for\n - Example ```['Pizza']```\n - Currently supports only one parameter\n\n * Advanced Keywords\n\n - When using Google Trends dashboard Google may provide suggested narrowed search terms.\n - For example ```\"iron\"``` will have a drop down of ```\"Iron Chemical Element, Iron Cross, Iron Man, etc\"```.\n - Find the encoded topic by using the get_suggestions() function and choose the most relevant one for you.\n - For example: ```https://www.google.com/trends/explore#q=%2Fm%2F025rw19&cmpt=q```\n - ```\"%2Fm%2F025rw19\"``` is the topic \"Iron Chemical Element\" to use this with pytrends\n - You can also use `pytrends.suggestions()` to automate this.\n\n* `cat`\n\n - Category to narrow results\n - Find available cateogies by inspecting the url when manually using Google Trends. The category starts after ```cat=``` and ends before the next ```&``` or view this [wiki page containing all available categories](https://github.com/pat310/google-trends-api/wiki/Google-Trends-Categories)\n - For example: ```\"https://www.google.com/trends/explore#q=pizza&cat=71\"```\n - ```'71'``` is the category\n - Defaults to no category\n\n* `geo`\n\n - Two letter country abbreviation\n - For example United States is ```'US'```\n - Defaults to World\n - More detail available for States/Provinces by specifying additonal abbreviations\n - For example: Alabama would be ```'US-AL'```\n - For example: England would be ```'GB-ENG'```\n\n* `tz`\n\n - Timezone Offset\n - For example US CST is ```'360'```\n\n* `timeframe`\n\n - Date to start from\n - Defaults to last 5yrs, `'today 5-y'`.\n - Everything `'all'`\n - Specific dates, 'YYYY-MM-DD YYYY-MM-DD' example `'2016-12-14 2017-01-25'`\n - Specific datetimes, 'YYYY-MM-DDTHH YYYY-MM-DDTHH' example `'2017-02-06T10 2017-02-12T07'`\n - Note Time component is based off UTC\n\n - Current Time Minus Time Pattern:\n\n - By Month: ```'today #-m'``` where # is the number of months from that date to pull data for\n - For example: ``'today 3-m'`` would get data from today to 3months ago\n - **NOTE** Google uses UTC date as *'today'*\n - Seems to only work for 1, 2, 3 months only\n\n - Daily: ```'now #-d'``` where # is the number of days from that date to pull data for\n - For example: ``'now 7-d'`` would get data from the last week\n - Seems to only work for 1, 7 days only\n\n - Hourly: ```'now #-H'``` where # is the number of hours from that date to pull data for\n - For example: ``'now 1-H'`` would get data from the last hour\n - Seems to only work for 1, 4 hours only\n\n* `gprop`\n\n - What Google property to filter to\n - Example ```'images'```\n - Defaults to web searches\n - Can be ```images```, ```news```, ```youtube``` or ```froogle``` (for Google Shopping results)\n\n\n### Interest Over Time\n\n pytrends.interest_over_time()\n\nReturns a sorted list of dict: containing \"timestamp\" and \"data\"\n\n\n\n# Caveats\n\n* This is not an official or supported API\n* Google may change aggregation level for items with very large or very small search volume\n* Google will send you an email saying that you had a new login after running this.\n* Rate Limit is not publicly known, let me know if you have a consistent estimate\n * One user reports that 1,400 sequential requests of a 4 hours timeframe got them to the limit. (Replicated on 2 networks)\n * It has been tested, and 60 seconds of sleep between requests (successful or not) is the correct amount once you reach the limit.\n* For certain configurations the dependency lib certifi requires the environment variable REQUESTS_CA_BUNDLE to be explicitly set and exported. This variable must contain the path where the ca-certificates are saved or a SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] error is given at runtime. \n\n# Credits\n\n* Original pytrends lib:\n - https://github.com/GeneralMills/pytrends\n\n* Major JSON revision ideas taken from pat310's JavaScript library\n\n - https://github.com/pat310/google-trends-api\n\n* Connecting to google code heavily based off Stack Overflow post\n\n - http://stackoverflow.com/questions/6754709/logging-in-to-google-using-python\n\n* With some ideas pulled from Matt Reid's Google Trends API\n\n - https://bitbucket.org/mattreid9956/google-trend-api/overview",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Simplified Pseudo API for Google Trends",
"version": "1.1.2",
"split_keywords": [
"google",
"trends",
"api",
"search"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "2a77fbb6d83bf1175633a349a2d1c0a4",
"sha256": "5fb4e9a12aca99cf9d6823b90faa29e871d0875503822d84d5c5657f92a68be0"
},
"downloads": -1,
"filename": "simplifiedpytrends-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a77fbb6d83bf1175633a349a2d1c0a4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8617,
"upload_time": "2021-04-22T16:48:03",
"upload_time_iso_8601": "2021-04-22T16:48:03.003467Z",
"url": "https://files.pythonhosted.org/packages/d8/2a/06c4918f8c62d37fa9e53404f6225de487f1e4f889b7f36635132f18c9b3/simplifiedpytrends-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "29e9c4981aebec4fd9be9beb42ff0498",
"sha256": "bcffb270c02391d276d88cdfcce5f8264a24a4c2df50cc198f4c93db16cb9c06"
},
"downloads": -1,
"filename": "simplifiedpytrends-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "29e9c4981aebec4fd9be9beb42ff0498",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10579,
"upload_time": "2021-04-22T16:48:02",
"upload_time_iso_8601": "2021-04-22T16:48:02.746883Z",
"url": "https://files.pythonhosted.org/packages/3a/59/fd12a6dcae2d7540a841ba7203d8db54b19c8316713ff456d36a6601a64b/simplifiedpytrends-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-04-22 16:48:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Drakkar-Software",
"github_project": "pytrends",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "aiohttp",
"specs": []
}
],
"lcname": "simplifiedpytrends"
}
JSON
