Skip to main content

Pseudo API for Google Trends

Project description

pytrends
=========

### About

**Pseudo API for Google Trends**

* Allows simple interface for automating downloads of csv reports from Google Trends.
* Main feature is to help trick google into thinking the script is actually a browser.


* Only good until Google changes their backend again :-P

**Installation**

```pip install pytrends```

**Requirements**
* Written for both Python 2.7+ and Python 3.3+
* Requires a google account to use.
* Requires fake-useragent python library (installed automatically with pip)

**Caveats**
* This is not an official or supported API
* Google may change aggregation level for items with very large or very small search volume

## Connect to Google
**pyGTrends(google_username, google_password)**

**Parameters**
* username
- **Required**
- a valid gmail address
* password
- **Required**
- password for the gmail account
* custom_useragenet
- name to identify requests coming from your script

### Request a Report
**`request_report(payload)`**

**Parameters**
* payload
- a dictionary of key, values**

**Payload Keys**
* `q`
- **Required**
- keywords to get data for
- Example ```{'q': 'Pizza'}```
- Up to five terms in a list: ```{'q': ['Pizza', 'Italian', 'Spaghetti', 'Breadsticks', Sausage']```
* 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
* `hl`
- Language to return result headers in
- Two letter language abbreviation
- For example US English is ```{'hl': 'en-US'}```
- Defaults to US english
* `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 ```&```
- For example: ```"https://www.google.com/trends/explore#q=pizza&cat=0-71"```
- ```{'cat': '0-71'}``` is the category
- Defaults to no category
* `geo`
- Two letter country abbreviation
- For example United States is ```{'geo': 'US'```
- Defaults to World
- More detail available for States/Provinces by specifying additonal abbreviations
- For example: Alabama would be ```{'geo': 'US-AL'}```
- For example: England would be ```{'geo': 'GB-ENG'}```
* `tz`
- Timezone using Etc/GMT
- For example US CST is ```{'tz': 'Etc/GMT+5'}```
* `date`
- Date to start from
- Defaults to all available data, 2004 - present.
- Custom Timeframe Pattern:
- By Month: ```{'date': 'MM/YYYY #m'}``` where # is the number of months from that date to pull data for
- For example: ``{'date': '10/2009 61m'}`` would get data from October 2009 to October 2014
- Less than 4 months will return Daily level data
- More than 36 months will return monthly level data
- 4-36 months will return weekly level data
- Current Time Minus Time Pattern:
- By Month: ```{'date': 'today #-m'}``` where # is the number of months from that date to pull data for
- For example: ``{'date': 'today 61-m'}`` would get data from today to 61months ago
- 1-3 months will return daily intervals of data
- 4-36 months will return weekly intervals of data
- 36+ months will return monthly intervals of data
- **NOTE** Google uses UTC date as *'today'*
- Daily: ```{'date': 'today #-d'}``` where # is the number of days from that date to pull data for
- For example: ``{'date': 'today 7-d'}`` would get data from the last week
- 1 day will return 8min intervals of data
- 2-8 days will return Hourly intervals of data
- 8-90 days will return Daily level data
- Hourly: ```{'date': 'now #-H'}``` where # is the number of hours from that date to pull data for
- For example: ``{'date': 'now 1-H'}`` would get data from the last hour
- 1-3 hours will return 1min intervals of data
- 4-26 hours will return 8min intervals of data
- 27-34 hours will return 16min intervals of data
* `gprop`
- What search data we want
- Example ```{'gprop': 'images'}```
- Defaults to web searches
- Can be ```images```, ```news```, ```youtube``` or ```froogle``` (for Google Shopping results)

### Save a Report to file
**save_csv(path, trend_name)**

**Parameters**
* path
- Output path
* trend_name
- Human readable name for file

### Get Google Term Suggestions
**get_suggestions(keyword)**

**Parameters**
* keyword
- **Required**
- keyword to get suggestions for

**Returns JSON**
```{"default": {"topics": [{"mid": "/m/0663v","title": "Pizza","type": "Dish"}]}}```
* Use the ```mid``` value for the keyword in future searches for a more refined trend set
### Credits

* Connecting to google code heavily based off Sal Uryasev's pyGTrends

* With some ideas pulled from Matt Reid's Google Trends API
- https://bitbucket.org/mattreid9956/google-trend-api/overview


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

pytrends-2.0.1-py2.py3-none-any.whl (9.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page