Pseudo API for Google Trends
Python
Pull request Compare This branch is 40 commits behind GeneralMills:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
pytrends
.gitignore
LICENSE
MANIFEST.in
README.md
setup.py

README.md

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 BeautifulSoup4, Requests, lxml

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.

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"}]}}