Longitude on Latitude
---------------------

Longitude is a data export tool for Google Latitude personal location
information.

Longitude is a simple Python program which serves two purposes, first, to
provide a simple, unix-y way to export your Latitude data, and second, to
serve as an example of how to fetch data from Latitude using the oauth2
module.

Requirements
------------

Python >= 2.6 (may work on earlier versions with require modules installed)
Python sqlite3
Python oauth2
Python argparse

How to use
----------

Longitude is built as a simple tool to fetch your data from Latitude and place
it in a database for later manipulation, nothing more, and nothing less. As a
result, setup has been made as simple as possible, beyond the requirements for
safe authentication via oauth.

1) First, follow these steps to get your oauth authorization keys from Google:

    a) Visit https://www.google.com/accounts/ManageDomains
    b) Add a domain you control via "Add a New Domain"
    c) Under "Manage registration", click the domain you just added
    d) Follow the steps to verify your domain.
    e) Get your oauth consumer secret.

2) Now that your domain is set up to authenticate with Google, edit the
   'longitude.cfg' file accordingly. Set the auth domain to your domain name,
   and the secret to your oauth consumer secret.

3) Now you are ready to run Longitude. Execute longitude.py and follow the
   directions. A usage example with supported options is provided below in the
   Usage section. The first time you run the program you will have to
   authenticate to the Google account you wish to export data for. Simply
   open the URL which you are prompted to open and authorize your domain.
   The oauth authentication keys (and *not* your password) will now be stored
   in the specified keys file (the default is 'keys'), allowing Longitude to
   silently authenticate in the future.

4) At this point, Longitude is able to access your data and will retrieve
   as much location data as it can (currently the previous 1000 data points).
   These will be stored in the sqlite database you specified (default is
   'loc_db' in the current path).

5) If you wish to automatically import new data, at this point you can set up
   a simple cron job which executes Longitude. Because Longitude has stored
   your authorization keys in the keys file, authorization will be silent and
   require no user intervention from this point forward. Further, Longitude
   will automatically skip data points which have already been imported and
   simply import the new points which it finds.

Usage
-----

Longitude tries to be modular and Unix-like. Longitude supports the following
options:

longitude.py [-h] [--config [file]] [--keys [file]] [--db [file]] [-v]
   
optional arguments:
  -h, --help            show this help message and exit
  --config [file], -c [file]
                        longitude configuration file, defaults to
                        'longitude.cfg' in the current path
  --keys [file], -k [file]
                        oauth key storage file, defaults to 'keys' in the
                        current path
  --db [file], -d [file]
                        sqlite storage DB for storing waypoints, defaults to
                        'loc_db' in the current path
  -v                    be verbose

Troubleshooting
---------------

-Ack! After trying to authenticate I still get an authorization error!

   I've recieved reports that Google's oauth API can sometimes lag, causing it
   to deny requests for Latitude information for a short time after initial
   authentication. Try again after a few minutes by re-running Longitude (your
   credentials have already been stored and will automagically be re-used to
   attempt authentication again).

   If the problem continues, ensure your domain has been properly verified
   with Google, and that you have correctly entered your configuration
   information in the Longitude configuration file. Then delete your keys file
   and try to authenticate again.

License
-------

Longitude is licensed under the GNU GPL version 3. The full license is
included with this source in the LICENSE file.

Copyright
---------

Copyright (c) 2010 Eric Harmon

Based on examples from oauth2:

Copyright (c) 2007 Leah Culver