Jun. 27, 2013

How to access various Web Services in Python

Overview

A very good way of learning Python is trying to work with various Web Services
API's.

How do I access web services such as Youtube, Vimeo, Twitter?

In order to answer that, we will first have to get some knowledge about API's,
JSON, Data structures etc.

Getting Started

For those of you that have followed us, you have hopefully gained some basic
Python knowledge. And for you who hasn't, I'd suggest that you start reading
our pages at the very top of the site or click on the link below that you want
to read more about.
Basics (Overview)

Dictionary

Functions

Lists

Loops

Modules

Strings

API : Application Programming Interface

An API is a protocol intended to be used as an interface by software components
to communicate with each other. An API is a set of  programming instructions and
standards for accessing web based software applications (such as above).

With API's applications talk to each other without any user knowledge or
intervention.
Often, companies like Google, Vimeo and Twitter releases it's API to the public
so that developers can develop products that are powered by its service.

It is important to know that an API is a software-to-software interface,
not a user interface.

API Key

Many services on the Internet (such as Twitter, Facebook..) requires that you
have an "API Key".  

An application programming interface key (API key) is a code passed in by
computer programs calling an API to identify the calling program, its developer,
or its user to the Web site. 

API keys are used to track and control how the API is being used, for example
to prevent malicious use or abuse of the API. 

The API key often acts as both a unique identifier and a secret token for
authentication, and will generally have a set of access rights on the API
associated with it.
When we interact with an API we often get the responses in a form called JSON.

Json

Let's very quickly and without going too much in-dept see what JSON is.
JSON (JavaScript Object Notation) is a compact, text based format for computers
to exchange data.

It's built on two structures: 
	- A collection of name/value pairs

	- An ordered list of values.
JSON take these forms: objects, array, value, string, number
Object
	- Unordered set of name/value pairs. 
	- Begins with { and ends with }. 
	- Each name is followed by : (colon) 
	- The name/value pairs are separated by , (comma).
Array
	- Ordered collection of values. 
	- Begins with [ and ends with ]. 
	- Values are separated by , (comma).
Value
	- Can be a string in double quotes, number, or true or false or null,
	  or an object or an array.
String
	- A sequence of zero or more Unicode characters, wrapped in double
	  quotes, using backslash escapes.
Number
		- Integer, long, float

Accessing Web Services

Python provides us with the json and simplejson modules to interact with JSON.
At this time, we should know what an API is and what it does. Additional, we now
know the basics of JSON. 

To get started with accessing web services, we first need to find an URL to
call the API. 

Before we get the URL, I'd really recommend that you read the documentation
provided (if any).

The documentation describes how to use the API and contains important information
on how we can interact with it.
The URL that we need can often be found on the company's website,
at the same place where the API documentation is. 

As an example:

YouTube
http://gdata.youtube.com/feeds/api/standardfeeds/most_popular?v=2&alt=json

Vimeo
http://vimeo.com/api/v2/video/video_id.output

Reddit
http://www.reddit.com/user/spilcm/comments/.json

Please not that these can be outdated, hence, verify that you have the latest
version. 

When you have an URL and you have read the documentation provided, we start with
importing the modules we need.

What modules do I need?

The modules I usually use when working with JSON are:
	- requests
	- json (or simplejson)
	- pprint

I used to use the urllib2 module to open the URL's, but ever since Kenneth Reitz
gave us the Requests module, I'm letting that module do most of my HTTP tasks. 

 urllib2 vs requests 

Working with the data

Once you know which URL you need and have imported the necessary modules,
we can use the request module to get the JSON feed. 

r = requests.get("http://www.reddit.com/user/spilcm/about/.json")
r.text

You can copy and paste the output into a JSON editor to get an easier overview
over the data.

I use http://jsoneditoronline.org/ but any JSON editor should do the work. 

The next step would be to convert the JSON output into a Python dictionary.

Converting the data

This will take the JSON string and make it a dictionary:
json.loads(r.text)	

Note: You can also take a python object and serialize it to JSON, by using
json.dumps(). 

However, that is not what we want to do now.

Looping through the result

We know have a python dictionary and we can start using it to get the results
we want.

A common way of doing that is to loop through the result and get the data that
you are interested in.

This can sometimes be the tricky part and you need to look carefully how the
structure is presented.
Again, using a Json editor will make it easier.
json

Using the YouTube API

At this point, we should have enough knowledge and information to create a program

This program will show the most popular videos on YouTube.

#Import the modules
import requests
import json

# Get the feed
r = requests.get("http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?v=2&alt=jsonc")
r.text

# Convert it to a Python dictionary
data = json.loads(r.text)

# Loop through the result.
for item in data['data']['items']:

    print "Video Title: %s" % (item['title'])

    print "Video Category: %s" % (item['category'])

    print "Video ID: %s" % (item['id'])

    print "Video Rating: %f" % (item['rating'])

    print "Embed URL: %s" % (item['player']['default'])

    print
See how we loop through the result to get the keys and values that we want.

YouTube, Vimeo and Twitter Examples

How to use the YouTube API in Python

How to use the Vimeo API in Python

How to use the Twitter API in Python

Parsing JSON

API Documentation for various Web Services

YouTube
https://developers.google.com/youtube/2.0/developers_guide_json

Vimeo
http://developer.vimeo.com/apis/

Twitter
https://dev.twitter.com/docs/api/1.1/overview

Reddit
http://www.reddit.com/dev/api


Read more about: