Client class goo.gl and API setup

UPD: The repository is now on Github .

Hello colleagues!

I remember that in my time I was very pleased with the news that the Google API shortening URLs had official APIs. At that time, I was just developing an application that often needed to shorten news feed links. I just screwed bit.ly, but was tempted to try a new service from Google. Using the documentation, I in a few hours sketched out the basic functionality and embedded the script in 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 on the Google code .

The 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 the code;
• Support authorization through ClientLogin + function to get it;
• Additional initialization parameters, if your API has restrictions on the 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 examples of code and tell you how to configure the API for maximum performance.

To use a class, you must first obtain an API key. In general, you can use the shortcut without a key, but then your limits are extremely small. Go to the API console page, click “Add project” and turn on the URL Shortener API (the last one in the list) in the list of available services.



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



For now, let's skip the description of authentication and restriction of requests, 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: we got a short link from a long link and vice versa: we extracted information about the original from a short link.

To get additional statistics on clicks and time periods, 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 meaning of each field is described in the documentation .

Now consider the authorization. Authorization is necessary for Google to make sure that Pupkin fulfilled the request, not Sumkin. Firstly, it gives access to statistics, and secondly, it significantly raises the limits. Authorization can be done in two ways: OAuth and ClientLogin . So far I have implemented the second method, since it is simpler (I will screw OAuth later). To request a token, you must install the gdata-python-client library and call the get_client_login () function, passing it the login 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 life of the token is approximately one week, after it needs to be updated. In my project, I put the token update function on kroner once a day.

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



Increase this value to an acceptable, say, 1000 queries.

Finally, consider filtering requests. All API requests can be filtered in two ways: by IP and domain. On the tab "Traffic Controls" 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 requests will come, for example, "* .example.com / *". When initializing a 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 an IP address mask. Each request searches for the userip parameter (from the address bar). If it is not found, then the real IP address of the machine with which the call was made is assigned to it. The userip obtained in this way is compared with the specified mask. The userip parameter can be set during class initialization:

 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 .