/pytrends

Pseudo API for Google Trends

Primary LanguagePythonOtherNOASSERTION

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