gdata-python-api + Analytics with simple auth

Question

I'm working on converting a Python script using the Google gdata API client + user/pass authentication to something more suitable for production (an API key). I am pretty frustrated with the muddled state of their documentation on authentication. I admittedly don't have a great grasp of OAuth2, but it seems like it's way more complicated for my usage case, which is: Hit Google Analytics every 24 hours to get the X most popular articles on our site.

In this scenario, we're not dealing with modifying someone's personal data, and all activity is centered on one account. It doesn't seem like OAuth2 is worth the complexity for something so simple.

I see that on the Google API Console (https://code.google.com/apis/console/), I've registered there and notice that there's a "Simple API Access" section with one key beneath the "Client ID for web applications" (which appears to be OAuth2). There's also the Google domain update page, https://www.google.com/accounts/UpdateDomain, but that appears to be OAuth related.

Is there any way to use this Simple API Access key (not OAuth) for retrieving analytics data with the Python gdata client, and if so, does anyone have any authentication examples? I already have the data retrieval stuff working once authenticated, but I'm using the user/pass approach, which is not appropriate for production.

Answer 1

Greg,

If you are already using the library gdata-python-client, this is relatively easy to do if you are the only user that your application will be authorizing.

The general mechanisms were detailed in a blog post in September, 2011, but I'll describe them here for completeness.

Part 1: Go to the APIs console and start a new project.

Part 2: From the project, go to "Services" and enable "Analytics API"

Part 3: From the project, go to "API Access" and click "Create an OAuth 2.0 client ID..." (you'll need to provide a product name, though the value you provide won't matter). When asked for the application type, select "Installed Application" and then "Create client ID". Since you will be the only user, you will only need one refresh token, and you can get this by authorizing from a desktop application a single time.

Part 4: Get your client id and client secret from the APIs console and then create an empty token:

import gdata.gauth

CLIENT_ID = 'id-from-apis-console'
CLIENT_SECRET = 'secret-from-apis-console'
SCOPE = 'https://www.google.com/analytics/feeds/'  # Default scope for analytics

token = gdata.gauth.OAuth2Token(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET, 
    scope=SCOPE,
    user_agent='application-name-goes-here')

I got the scope from GData FAQ, though I'm not sure if it is correct.

Part 5: Use the token to create authorization URL for you to visit:

url = token.generate_authorize_url(redirect_uri='urn:ietf:wg:oauth:2.0:oob')

Since your application is an "Installed Application", your redirect URI is the default 'urn:ietf:wg:oauth:2.0:oob'. (Also note, the blog post had a typo and used the keyword argument redirect_url.)

Part 6: Visit the url and authorize your application to make requests on behalf of your account. After authorizing, you'll be redirected to a page with a code on it. This code will be used to exchange for an access token and a long-lived refresh token. The code has a life of 10 minutes and the access token has a life of an hour. The refresh token will allow you to get new access tokens for signing requests in perpetuity (or until you revoke the permission from your account).

Part 7: Use the code to get an access token:

code = 'random-string-from-redirected-page'
token.get_access_token(code)  # This returns the token, but also changes the state

This again differs slightly from the blog post, because we are using an installed application.

Part 8: With the token you can now make all requests you want to make to the analytics client:

import gdata.analytics.client

client = gdata.analytics.client.AnalyticsClient()
token.authorize(client)

This is the big money right here. When an access token expires, the API requests signed with that token are rejected. However, by authorizing the client as above, when the said requests fail, the token attempts to use the refresh token to obtain a new access token. If it successfully obtains a new access token, the client resends the original API request, signed with the new access token.

I don't know anything about the Analytics API so I won't provide any more details there.

Future Use Note 1: Saving information for future use. You can re-use this from different places and after this use very easily. There are methods called token_to_blob and token_from_blob provided by the library that allow turning a token into a string and converting out of a string:

saved_blob_string = gdata.gauth.token_to_blob(token)

Once you have done this, you can store the string in a file and kill your running Python process. When you'd like to use it again:

saved_blob_string = retrieve_string_from_file()  # You'll need to implement this
token = gdata.gauth.token_from_blob(saved_blob_string)

Future Use Note 2: This token will be able to be used to authorize a client and perform all your magic again and again, so long as you have the refresh token around. If for some reason you would like to get an access token again without calling token.generate_authorize_url, you'll need to manually set this on the object:

token.redirect_uri = 'urn:ietf:wg:oauth:2.0:oob'

Future Use Note 3: Also, if you lose your refresh token and would like to get another one without having to go to the browser to revoke the original, you can use the approval_prompt parameter to get a new refresh token by visiting the url generated by:

url = token.generate_authorize_url(
    redirect_uri='urn:ietf:wg:oauth:2.0:oob',
    approval_prompt='force')