Python package to examine trending, spatio and temporal google searching for input queries.

googletrends.googletrends.get_geo_names(url='https://erdogant.github.io/datasets/country_and_code.zip', verbose=3)

Import dataset from github.

Parameters

  • url (str) – url-Link to dataset.

  • verbose (int, optional) – Print message to screen. The default is 3.

Return type

tuple containing import status and resources.

googletrends.googletrends.plot(results, figsize='auto', cmap=['#ff0000'], color_by_searchword=True, group_by_searchword=False, showfig=True, verbose=3)

Plot results generated by trending, spatio or temporal.

Parameters

  • results (dict) – results are derived from the temporal() function.

  • figsize (tuple, optional) – Figure size (height, width). The default is ‘auto’.

  • cmap (str, optional) – colormap. The default is ‘Set1’.

  • color_by_searchword (bool, optional) – Color lines by searchwords. The default is True.

  • group_by_searchword (TYPE, optional) – Make subplots based on searchwords. The default is False.

  • showfig (bool, optional) – When True, auto open the map figures in your browser. The default is ‘True’.

  • verbose (int, optional) – Print message to screen. The default is 3.

Return type

None.

Examples

>>> # Trending results
>>> result = googletrends.trending(['corona','covid-19'], geo=['nl','italy'], date_start='01-12-2019')
>>> googletrends.plot(result)
>>> # Results on geogrpahical locations
>>> result = googletrends.spatio(['corona','covid-19'], geo=['nl','italy'], date_start='01-12-2019')
>>> googletrends.plot(result)
>>> # Results over time
>>> result = googletrends.temporal(['corona','covid-19'], geo=['nl','italy'], date_start='01-12-2019')
>>> googletrends.plot(result)
googletrends.googletrends.plot_spatio(results, figsize=(15, 8), showfig=True, verbose=3)

Plot the spatio results.

Parameters

  • results (dict) – results are derived from the temporal() function.

  • figsize (tuple, optional) – Figure size (height, width). The default is ‘auto’.

  • showfig (bool, optional) – When True, auto open the map figures in your browser. The default is ‘True’.

  • verbose (int, optional) – Print message to screen. The default is 3.

Returns

  • ax (object) – Axis.

  • out_map (dict) – DataFrame containing map data.

Examples

>>> result = googletrends.spatio(['corona','covid-19'], geo=['nl','italy'], date_start='01-12-2019')
>>> googletrends.plot_spatio(result)
googletrends.googletrends.plot_temporal(results, figsize='auto', cmap='Set1', color_by_searchword=True, group_by_searchword=False, verbose=3)

Plot the temporal results.

Parameters

  • results (dict) – results are derived from the temporal() function.

  • figsize (tuple, optional) – Figure size (height, width). The default is ‘auto’.

  • cmap (str, optional) – colormap. The default is ‘Set1’.

  • color_by_searchword (bool, optional) – Color lines by searchwords. The default is True.

  • group_by_searchword (TYPE, optional) – Make subplots based on searchwords. The default is False.

  • verbose (int, optional) – Print message to screen. The default is 3.

Returns

  • fig (object) – Figure.

  • ax (object) – Axis.

Examples

>>> result = googletrends.temporal(['corona','covid-19'], geo=['nl','italy'], date_start='01-12-2019')
>>> googletrends.plot_temporal(result)

Plot the trending results.

Parameters

  • results (dict) – results are derived from the temporal() function.

  • figsize (tuple, optional) – Figure size (height, width). The default is ‘auto’.

  • cmap (str, optional) – colormap. The default is ‘Set1’.

  • verbose (int, optional) – Print message to screen. The default is 3.

Return type

None.

Examples

>>> result = googletrends.trending(['corona','covid-19'], geo=['nl','italy'], date_start='01-12-2019')
>>> googletrends.plot_trending(result)
googletrends.googletrends.plot_worldmap(results, cmap=['#ff0000'], showfig=True, verbose=3)

Plot results on the worldmap derived from googletrends.spatio().

Parameters

  • results (dict) – results are derived from the temporal() function.

  • figsize (tuple, optional) – Figure size (height, width). The default is ‘auto’.

  • showfig (bool, optional) – When True, auto open the map figures in your browser. The default is ‘True’.

  • verbose (int, optional) – Print message to screen. The default is 3.

Return type

dict containing results.

Examples

>>> # Trending results
>>> result = googletrends.spatio(['corona','covid-19'], geo=['nl','italy'], date_start='01-12-2019')
>>> googletrends.plot_worldmap(results_spatio)
googletrends.googletrends.spatio(searchwords, geo='', date_start=None, date_stop=None, method='news', include_suggestions=False, verbose=3)

Gather data for google searches over geographical locations and time.

Parameters

  • searchwords (list) – Lookup each input word and return the (normalized) frequency of google searches. Example: [‘Corona’,’earth quake’]

  • geo (list, optional) – Filter on geographical locations. ‘NL’ (only netherlands) [‘NL’,’germany’,’IT’]

  • date_start (str [dd-mm-yyyy]) – String: Start date for counting.

  • date_stop (str [dd-mm-yyyy], optional) – String: Stop date for counting. If nothing is filled in, date of today is used.

  • method (str, optional) – Type of google search. The default is ‘news’. Choose on of those: ‘images’,’news’,’youtube’,’froogle’

  • include_suggestions (bool, optional) – Include suggestions. The default is False.

  • verbose (int, optional) – Print message to screen. The default is 3.

Raises

Exception – code 429: Too Many google requests in a given amount of time (“rate limiting”).

Returns

Each input country has the following keys:

  • method (str) : Type of method.

  • dict of dataframes : Per country the counts for searchwords.

  • geo (list): The abrevations of the country names.

  • geo_names (list): The full name of the countries.

  • searchwords (list): The input searchwords.

  • date_range (str): The date: [from To].

Return type

dict containing results.

Examples

>>> result = googletrends.spatio(['bitcoin','ethereum'], geo=['nl','italy'], date_start='01-12-2012')
>>> googletrends.plot(result)
googletrends.googletrends.temporal(searchwords, geo=None, date_start=None, date_stop=None, method='news', verbose=3)

Gather data for google searches over time.

Parameters

  • searchwords (list) – Lookup each input word and return the (normalized) frequency of google searches. Example: [‘Corona’,’earth quake’]

  • geo (list, optional) – Filter on geographical locations. ‘NL’ (only netherlands) [‘NL’,’germany’,’IT’]

  • date_start (str [dd-mm-yyyy]) – String: Start date for counting.

  • date_stop (str [dd-mm-yyyy], optional) – String: Stop date for counting. If nothing is filled in, date of today is used.

  • method (str, optional) – Type of google search. The default is ‘news’. Choose on of those: ‘images’,’news’,’youtube’,’froogle’

  • verbose (int, optional) – Print message to screen. The default is 3.

Raises

Exception – code 429: Too Many google requests in a given amount of time (“rate limiting”).

Returns

  • method (str) : Type of method.

  • dict of dataframes : Per country the counts for searchwords.

  • geo (list): The abrevations of the country names.

  • geo_names (list): The full name of hte countries.

  • searchwords (list): The input searchwords.

  • date_range (str): The date: [from To].

Return type

dict containing results.

Examples

>>> result = googletrends.temporal(['bitcoin','ethereum'], geo=['nl', 'united states'], date_start='01-12-2019')
>>> googletrends.plot(result)
googletrends.googletrends.trending(searchwords, geo=None, date_start=None, date_stop=None, method='news', verbose=3)

Trending google searches.

Description

If you choose a time period that is 3 months or shorter you get daily data, otherwise you get weekly data. If the time period is 3 years or longer, the monthly data is plotted, otherwise it is weekly data.

param searchwords

Lookup each input word and return the (normalized) frequency of google searches. Example: [‘Corona’,’earth quake’]

type searchwords

list

param geo

Filter on geographical locations. ‘NL’ (only netherlands), [‘NL’,’germany’,’IT’], ‘world’ to examine all countries

type geo

list, optional

param date_start

String: Start date for counting.

type date_start

str [dd-mm-yyyy]

param date_stop

String: Stop date for counting. If nothing is filled in, date of today is used.

type date_stop

str [dd-mm-yyyy], optional

param method

Type of google search. The default is ‘news’. Choose on of those: ‘images’,’news’,’youtube’,’froogle’

type method

str, optional

param verbose

Print message to screen. The default is 3.

type verbose

int, optional

raises Exception

code 429: Too Many google requests in a given amount of time (“rate limiting”).

rtype

dict containing results.

Examples

>>> result = googletrends.spatio(['bitcoin','ethereum'], geo=['nl','italy'], date_start='01-12-2012')
>>> googletrends.plot(result)
>>> # Plot only on the worldmap
>>> googletrends.plot_worldmap(result)