googlealertsDocumentation Release 0.1.0 Brandon Dixon May 09, 2021 Contents 1 Features 3 2 Code Documentation 5 2.1 Getting Started..............................................5 2.2 Code Documentation...........................................6 2.3 Exceptions................................................8 2.4 Changelog................................................8 3 License 11 4 Indices and tables 13 Index 15 i ii googlealertsDocumentation; Release0:1:0 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. Questions, comments or for support needs, please use the issues page on Github. Contents 1 googlealertsDocumentation; Release0:1:0 2 Contents CHAPTER 1 Features • Add new monitors (RSS or Mail) • Modify existing monitors • Delete monitors by ID or term • List all monitors with details 3 googlealertsDocumentation; Release0:1:0 4 Chapter 1. Features CHAPTER 2 Code Documentation 2.1 Getting Started Install the library: pip install google-alerts or python setup.py install Save your configuration: google-alerts setup --email <[email protected]> --password 'password' Seed your session (driver download, http://chromedriver.chromium.org/downloads, do NOT use the pip pack- age 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' 2.1.1 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('[email protected]',' **password**') (continues on next page) 5 googlealertsDocumentation; Release0:1:0 (continued from previous page) # Authenticate your user ga.authenticate() # List configured monitors ga.list() # 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 ga.delete("89e517961a3148c7:c395b7d271b4eccc:com:en:US") 2.1.2 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":"https://google.com/alerts/feeds/09738342945634096720/ ,!9663349274289663466", "delivery":"RSS", "match_type":"BEST" }] 2.2 Code Documentation 2.2.1 GoogleAlerts Interface class google_alerts.GoogleAlerts(email=None, password=None) _config_bootstrap() Go through and establish the defaults on the file system. The approach here was stolen from the CLI tool provided with the module. Idea being that the user should not always need to provide a username and password in order to run the script. If the configuration file is already present with valid data, then lets use it. _logger() Create a logger to be used between processes. Returns Logging instance. _process_state() Process the application state configuration. 6 Chapter 2. Code Documentation googlealertsDocumentation; Release0:1:0 Google Alerts manages the account information and alert data through some custom state configuration. Not all values have been completely enumerated. _session_check() Attempt to authenticate the user through a session file. This process is done to avoid having to authenticate the user every single time. It uses a session file that is saved when a valid session is captured and then reused. Because sessions can expire, we need to test the session prior to calling the user authenticated. Right now that is done with a test string found in an unauthenticated session. This approach is not an ideal method, but it works. authenticate() Authenticate the user and setup our state. create(term, options) Create a monitor using passed configuration. delete(monitor_id) Delete a monitor by ID. delete_by_term(term) Delete an alert by term. list(term=None) List alerts configured for the account. At the time of processing, here are several state examples: • [‘062bc676ab9e9d9b:5a96b75728adb9d4:com:en:US’, [None, None, [‘email_aih_all’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 2, [[1, ‘[email protected]’, [], 1, ‘en-US’, 1, None, None, None, None, ‘7290377213681086747’, None, None, ‘AB2Xq4g1vxP5nJCT4SVMp8- 8CeYubB7G0yQdZnM’]]], ‘06449491676132715360’] • [‘062bc676ab9e9d9b:eb34fff1681232ae:com:en:US’, [None, None, [‘email_aih_best’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 3, [[1, ‘[email protected]’, [], 1, ‘en-US’, 1, None, None, None, None, ‘11048899972761343896’, None, None, ‘AB2Xq4ibeyRSs4e6CQEjGTYWRyQgHftJgjkGmdE’]]], ‘06449491676132715360’] • [‘062bc676ab9e9d9b:029a12ab092e4d48:com:en:US’, [None, None, [‘email_d_all’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 2, [[1, ‘[email protected]’, [None, 18], 2, ‘en-US’, 1, None, None, None, None, ‘13677540305540568185’, None, None, ‘AB2Xq4iqyPDNCX_G_ZahmtXr3Ev1Xxk71J3A9o8’]]], ‘06449491676132715360’] • [‘062bc676ab9e9d9b:be633f8e2d769ed1:com:en:US’, [None, None, [‘email_d_best’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 3, [[1, ‘[email protected]’, [None, 18], 2, ‘en- US’, 1, None, None, None, None, ‘3165773263851675895’, None, None, ‘AB2Xq4gAyl3SR- 5AKh3NstCHFf3I5tOCH_8Te98’]]], ‘06449491676132715360’] • [‘062bc676ab9e9d9b:4064fca73997bea1:com:en:US’, [None, None, [‘email_w_all’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 2, [[1, ‘[email protected]’, [None, 18, 0], 3, ‘en-US’, 1, None, None, None, None, ‘1277526588871069988’, None, None, ‘AB2Xq4jNqRCDJaqIvPfZTI6Sos2MMPb5q_6jS14’]]], ‘06449491676132715360’] • [‘062bc676ab9e9d9b:ed3adf6fd0968cb0:com:en:US’, [None, None, [‘email_w_best’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 3, [[1, ‘[email protected]’, [None, 18, 0], 3, ‘en-US’, 1, None, None, None, None, ‘11943490843312281977’, None, None, ‘AB2Xq4gvnjg6s07wCxTs4Ag8_6uOC0u9-7Aiu8E’]]], ‘06449491676132715360’] • [‘062bc676ab9e9d9b:a92eace4d0488209:com:en:US’, [None, None, [‘rss_aih_best’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 3, [[2, ‘’, [], 1, ‘en-US’, 1, None, None, None, None, 2.2. Code Documentation 7 googlealertsDocumentation; Release0:1:0 ‘10457927733922767031’, None, None, ‘AB2Xq4jZ1IPZLS44ZpaXYn8Fh46euu8_so_2k7k’]]], ‘06449491676132715360’] • [‘062bc676ab9e9d9b:ac4752c338e8c363:com:en:US’, [None, None, [‘rss_all’, ‘com’, [‘en’, ‘US’], None, None, None, False], None, 2, [[2, ‘’, [], 1, ‘en-US’, 1, None, None, None, None, ‘17387577876633356534’, None, None, ‘AB2Xq4h1wQcVxLfb0s835KmJWdw7bfUzzwpjUrg’]]], ‘06449491676132715360’] modify(monitor_id, options) Create a monitor using passed configuration. set_log_level(level) Override the default log level of the class 2.3 Exceptions class google_alerts.InvalidCredentials Exception for invalid credentials. class google_alerts.InvalidState Exception for invalid state. class google_alerts.MonitorNotFound Exception for missing monitors. class google_alerts.InvalidConfig Exception for invalid configurations. class google_alerts.ActionError Exception for generic failures on action. class google_alerts.AccountCaptcha Exception for account CAPTCHA. 2.4 Changelog 2.4.1 05-09-20 • Bugfix: Adjusted the seeding process to use Stackoverflow in order to handle initial Google authentication to bypass bot checks 2.4.2 11-20-19 • Change: Captured all results by default instead of best 2.4.3 07-15-19 • Bugfix: Handle issues in exception definition • Bugfix: Provide alert_frequency with a default option if not supplied 8 Chapter 2. Code Documentation googlealertsDocumentation; Release0:1:0 2.4.4 07-14-19 • Change: Wrap state parsing functions and have them raise exception on failures • Bugfix: Account for state changed pushed by Google, breaking all processing 2.4.5 05-23-19 • Feature: Add a new command line argument to allow a user to specify a seed timeout time 2.4.6 11-11-18 • 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 2.4.7 10-13-18 • Feature: Detect when user changes between Python versions during setup • Bugfix: Setup process appears to finally be bug-free, screw python2 support 2.4.8 07-10-18 • Feature: Added the ability to set the frequency when creating alerts • Bugfix: Fixed frequency settings when using the mail delivery method 2.4.9 05-30-18 • Change: Explicitly detect when a CAPTCHA is being thrown 2.4.10 05-28-18 • 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 2.4.11 05-25-18 • 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 2.4. Changelog 9 googlealertsDocumentation; Release0:1:0 2.4.12 04-29-18 • Feature: Allow users to setup exact match queries • Change: Added support for Python3 • Bugfix: Removed extra calls causing an error in the decrypt process 2.4.13 04-26-18 • Feature: Added a command line utility to the code for easy testing • Bugfix: Removed clobbering error inside of delete routine 10 Chapter 2. Code Documentation CHAPTER 3 License Copyright 2018 Brandon Dixon Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documen-