Skip to main content

Abstraction to manage Google Alerts from code

Project description

The google-alerts Python module provides an abstract interface for the Google Alerts service. Google does not provide an official API for this service, so interactions are done through web scripting.

WARNING: Your account password will be obfuscated and saved on the file system. Additionally, post-authentication, a session cookie will also be saved. These can be stolen and re-used to compromise your account. As a best practice, register a new email to manage alerts.

For detailed explanations of the library, please see the wiki.

Quick Start

Install the library:

pip install google-alerts or python install

Save your configuration:

google-alerts setup --email <> --password 'password'

Seed your session (driver download,, do NOT use the pip package as the version is old):

google-alerts seed --driver /tmp/chromedriver --timeout 60

Create a monitor:

google-alerts create --term "hello world" --delivery 'rss' --frequency 'realtime'

List monitors:

google-alerts list

Delete a monitor:

google-alerts delete --id '89e517961a3148c7:c395b7d271b4eccc:com:en:US'

Sample Code

This sample code shows some of the range of functionality within the module:

from google_alerts import GoogleAlerts

# Create an instance
ga = GoogleAlerts('', '**password**')

# Authenticate your user

# List configured monitors

# Add a new monitor
ga.create("Hello World", {'delivery': 'RSS'})

# Modify an existing monitor
ga.modify("89e517961a3148c7:c395b7d271b4eccc:com:en:US", {'delivery': 'RSS', 'monitor_match': 'ALL'})

# Delete a monitor

Example Output

Below is an example monitor:

    "term": "hello world",
    "user_id": "09738342945634096720",
    "language": "en",
    "monitor_id": "89e517961a3148c7:c395b7d271b4eccc:com:en:US",
    "region": "US",
    "rss_link": "",
    "delivery": "RSS",
    "match_type": "BEST"


  • Add new monitors (RSS or Mail)

  • Modify existing monitors

  • Delete monitors by ID or term

  • List all monitors with details



  • Bugfix: Adjusted the seeding process to use Stackoverflow in order to handle initial Google authentication to bypass bot checks


  • Change: Captured all results by default instead of best


  • Bugfix: Handle issues in exception definition

  • Bugfix: Provide alert_frequency with a default option if not supplied


  • Change: Wrap state parsing functions and have them raise exception on failures

  • Bugfix: Account for state changed pushed by Google, breaking all processing


  • Feature: Add a new command line argument to allow a user to specify a seed timeout time


  • Feature: Add a new command line argument to seed a session through the browser

  • Change: Added python version detection to the manage script as well


  • Feature: Detect when user changes between Python versions during setup

  • Bugfix: Setup process appears to finally be bug-free, screw python2 support


  • Feature: Added the ability to set the frequency when creating alerts

  • Bugfix: Fixed frequency settings when using the mail delivery method


  • Change: Explicitly detect when a CAPTCHA is being thrown


  • Feature: Take advantage of the config file concept inside of the class

  • Feature: Authenticate users with a session file if it’s available

  • Change: Tell Chrome to avoid using Javascript so we get the old form


  • Change: Added headers to all calls to look like less of a bot

  • Bugfix: Wrapped a problem area when inspecting the forms in a page

  • Bugfix: Handled setup error for Python3


  • Feature: Allow users to setup exact match queries

  • Change: Added support for Python3

  • Bugfix: Removed extra calls causing an error in the decrypt process


  • Feature: Added a command line utility to the code for easy testing

  • Bugfix: Removed clobbering error inside of delete routine

Project details

Download files

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

Source Distribution

google-alerts-0.2.9.tar.gz (12.9 kB view hashes)

Uploaded Source

Built Distribution

google_alerts-0.2.9-py3-none-any.whl (16.0 kB view hashes)

Uploaded 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