Accessing web services API using Python – Part 1

Before moving to use of API, I would rather like to discuss why APIs are necessary. When referring to context of use of web services like facebook, google maps, gmail, youtube, twitter, face plus plus,  users are often involved for using them manually or rather say physically. However, sometimes developers who are keen to code for different cross-platform apps or programs making life of people easier with their idea/application tends to access these services through their code and fetch considerable amount of data from them. Since such APIs has ability to output loads of important data once used appropriately. However, most of the web services like the ones mentioned above are also prone to robot attacks which often leads to servers crashes or DOS. The Web service providers are also, at the same time willing to let their services be used by different developers and third party applications ( This actually acts as a source of income for the service provider, I will further explain their criteria of usage). Hence it becomes necessary to sort robots from apps/programs developed by developers leading to channelizing and setting protocols to access their web services, which are often called as APIs.
Putting into technical terms
” The API itself is largely abstract in that it specifies an interface and controls the behavior of the objects specified in that interface. The software that provides the functionality described by an API is said to be an “implementation” of the API. An API is typically defined in terms of the programming language used to build an application.”

API are often backed by well documented manual for their usage across various platforms and criteria. For an instance, the most important list of criteria comes as:

1. The compute resources to run these APIs are not “free”
2. The data providers might limit the number of requests per day,
   demand an API “key”, or even charge for usage
3. They might change the rules as things progress

Take example of google maps api service which is free for upto 2500 requests per day. With number of requests exceeding to this threshold often leads to falling into API Business criteria and charges are deduced for use of service. So, for hobbyist or small scale developers who tend to need such services for adding features into their project can resort to use of API owing to small scale usage. Various APIs have been developed when citing hobbyist and makers point of view:

1. wit.ai service for Natural language processing, speech to text, home automations, etc
2. Faceplusplus service for face recognition and feature extraction
3. Google more than 50 API like Gmail, Google Maps, Voice recogntion, Calendar, etc. A simple google search will land you to their documentation
4. Twitter for notifications and tweeting
5. Facebook for notifications , posting, messaging

I have been through most of the API through python coding with good command over simple python libraries, which I will be explaining within this tutorials. Lets take an example to understand well the general procedure to access APIs

Google Maps APIs

As I have mentioned before use of documentation provided by service owners is highly important to know the protocols and features of the web service. Here, is the link to homepage of Google maps API. It can show various platforms with which API can be accessed. I am here going to explain the HTTP platform which is simplest and versatile owing to use of GET requests protocol well defined across various languages and OS. While referring to documentation of web service APIs for google maps, I came across 8 APIs, all having different feature output. Hence, it becomes necessary to get blueprint of your needs to select appropriate API. Once you are done with selection, sign in to become registered developer and get your access token or ACCESS_KEY which would let know service provider your frequency of requests and your identity whenever you will be using their service. You cannot fetch any data from any API until you have an ACCESS_KEY for which you always have to register yourself as developer at their developers site. I will assume through out the tutorial that access key is already provided to you.

Google maps direction API:

I will be explaining this API for generalizing the procedure. The API provides through point GPS co-ordinates, instructions to reach each through point, total time of travel, total distance of travel with steps to reach each through point. For those who are confused what through points are, it is set of GPS co-ordinates that must be covered to reach the destination for particular defined path.

1. Knowing inputs to service to return output

Go through the documentation and find out the inputs to he API. Generally, you can find it when documentation provides encoding of HTTP link for various attributes. Example:
Google maps directions documentation1. origin: defining the start place
2. destination: Defining the end point
3. mode: defining the mode of transport
4. key: access key of developer
I have not added other parameters, as they are optional.  However, it is encouraged to use them for increasing efficiency of accessing service.

2. Encoding format

This is nothing but the arrangement of parameters(inputs) within http link for api to work.
http://maps.googleapis.com/maps/api/directions/outputFormat?parameters

outputFormat can be wither JSON or XML. You have choice depending how efficiently you can use the parsing libraries for them. I prefer using XML over JSON owing to tree structure which is easy to understand as against JSON which is list nested dictionaries and lists. Parsing will be discussed in upcoming section
Parameters or inputs has to be arranged as shown below:
https://maps.googleapis.com/maps/api/directions/json?origin=Disneyland&destination=Universal+Studios+Hollywood4&key=YOUR_API_KEY
Parameters must be separated with ‘&’ and space must be replaces with ‘+’. BTW, this is universal url encoding which can be rather done with urllib library in python which is also used for GET request.