Authentication Flows

Overview

This library is unofficial and does not use any formal Google APIs to access alerts. As such, in order to authenticate, we need to go through the normal user login flow. Doing this will sometimes trigger Google to show a CAPTCHA which breaks the standard authentication built into this library.

Setup

Follow these steps to ensure you have setup the library successfully.

Begin by running the setup on the command line:

google-alerts setup --email <[email protected]> --password 'password'

Setup will take your credentials and encode them within a local configuration file. The configuration file is located at ~/.config/google_alerts/.

You can test your authentication by performing a `list` operation on the command line:

google-alerts list

If successful, you will get back a response with an empty array or with listings you have already configured in your account. If you're not successful, it could be that your username and password are incorrect or a CAPTCHA is being thrown; the error message will tell you where the issue exists.

If a CAPTCHA is being thrown, you need to use the seed option on the command line. In order to run this command successfully, you must download the Chrome driver and have it on your local file system. You can download the driver for your given platform here: http://chromedriver.chromium.org/downloads.

Once downloaded, run the seed command:

google-alerts seed -d <driver location>

This process will spawn a Chrome window that navigates to the login screen and makes use of your existing saved credentials from your configuration file. These will be automatically filled in and progressed on the form without the need for user interaction. If the CAPTCHA is required, it will display and you will need to fill it in within a timely manner (15 seconds). Once successfully authenticated, a new session file will be created in ~/.config/google_alerts/ that will act as your authentication session.

Note: The authentication process, seed or otherwise, will authenticate against StackOverflow. The reason for this is that Google treats partner applications differently than a direct login; security is more relaxed and so it's easier to successfully authenticate. If this concerns you, please propose a proper solution through a pull request or use another library.