Goo.gl client class and API configuration

UPD: repository is now on github .

Hello colleagues!

I remember at one time I was very pleased with the news that the Google URL shortener had official APIs. At that time, I was just developing an application that often needed to shorten feed links. I just screwed bit.ly, but was tempted to try a new service from Google. Using the documentation, in a few hours I sketched the basic functionality and built the script into the project.

Over time, changes were made to the script, and finally, I decided to add comments to the code, write simple documentation and put everything in Google code .

Main features and features of the class from competitors:

• Small size (150 lines), all in one module, no need to connect a heavy official python client ;
• Full API coverage, unlike a similar project ;
• Comments and documentation in code;
• Authorization support through ClientLogin + function for receiving it;
• Additional initialization parameters if your API has restrictions on referer or IP;

For more than three months, I managed to reduce about 12,000 unique links and in general I am very pleased with the service. Below I want to give code examples and talk about how to tune the API for maximum performance.

To use the class, you first need to get the API key. In general, you can use the abbreviation without a key, but then your limits are extremely small. We go to the API console page , click "Add project" and in the list of available services include the URL Shortener API (the last in the list).



Your key will be written on the “Project home” tab in the “API access” sub-item:



For now, let's skip the description of authentication and query restrictions, let's see the class in action:

import googl
client = googl.Googl("MyAPIAccessKey")
result = client.shorten("http://code.google.com/p/python-googl-client/")
print result
>>> {u'kind': u'urlshortener#url', u'id': u'http://goo.gl/67TaW', u'longUrl': u'http://code.google.com/p/python-googl-client/'}
print client.expand(result["id"])
>>> {u'status': u'OK', u'kind': u'urlshortener#url', u'id': u'http://goo.gl/67TaW', u'longUrl': u'http://code.google.com/p/python-googl-client/'}

We performed the simplest actions: from a long link we got a short one and vice versa: we extracted information about the original by a short one.

To get additional statistics on clicks and time periods, we pass an additional parameter projection to the expand () method, its value can be one of the constants with the PROJ_ prefix:

info = client.expand('http://goo.gl/67TaW', projection=googl.PROJ_FULL)

This will return to us something like this:

{
	u'status': u'OK',
	u'kind': u'urlshortener#url',
	u'created': u'2011-05-19T05:47:13.058+00:00',
	u'analytics': {
		u'week': {
			u'shortUrlClicks': u'0',
			u'longUrlClicks': u'1'
		},
		u'allTime': {
			u'shortUrlClicks': u'0',
			u'longUrlClicks': u'1'
		},
		u'twoHours': {
			u'shortUrlClicks': u'0',
			u'longUrlClicks': u'1'
		},
		u'day': {
			u'shortUrlClicks': u'0',
			u'longUrlClicks': u'1'
		},
		u'month': {
			u'shortUrlClicks': u'0',
			u'longUrlClicks': u'1'
		}
	},
	u'longUrl': u'http://code.google.com/p/python-googl-client/',
	u'id': u'http://goo.gl/67TaW'
}

The semantic values ​​of each field are described in the documentation .

Now consider authorization. Authorization is needed in order for Google to make sure that the request was fulfilled by Pupkin, not Sumkin. Firstly, it gives access to statistics, and secondly, it significantly raises the limits. Authorization can be performed in two ways: OAuth and ClientLogin . So far I have implemented the second method, as it is simpler (I will fasten OAuth later). To request a token, you need to install the gdata-python-client library and call the get_client_login () function, passing it the username and password from your account. Set the received token in the class initialization, after which each request will become authorized:

import googl
client_login = googl.get_client_login("login", "pass")
client = googl.Googl("MyAPIAccessKey", client_login=client_login)

Important: the token's lifetime is approximately one week, after which it needs to be updated. In my project, I set the token update function to crowns once a day.

If you will shorten links in batches, sooner or later catch the “rate limits” exception. This is because by default your console has a limit of 1.0 requests / second / user:



Increase this value to an acceptable, say 1000 requests.

Finally, consider query filtering. All API requests can be filtered in two ways: by IP and domain. On the “Traffic Controls” tab, you can specify one of the types:



If you selected the item “Browser-embedded scripts”, then in the text field specify the address mask from which the requests will come, for example, “* .example.com / *”. When initializing the class, you need to specify the referer parameter that satisfies this mask:

import googl
client = googl.Googl("MyAPIAccessKey", referer="http://www.example.com")

IP restriction works as follows. You specify the mask of the IP address. Each request searches for the userip parameter (from the address bar). If it is not found, then it is assigned the real IP address of the machine from which the call was made. The userip thus obtained is compared with the specified mask. The userip parameter can be set when the class is initialized:

import googl
client = googl.Googl("MyAPIAccessKey", userip="127.0.0.1")

References:

• Project page on Github;
• Official documentation
• Official google-api-python-client with urlshorter support, example .