API stands for Application Programming Interface, and web APIs allow you to programmatically interface with a web resource using the HTTP protocol (the same as you use in your web browser).

1. Let’s explain that geek-speak with an example from weather underground.

A standard web browser HTTP request to a web server might look like this:

Request: http://www.wunderground.com

Response: an html file, which your browser knows how to format nicely so you can see the weather and some graphics.

An API request looks like this: http://api.wunderground.com/api/YOUR_KEY/forecast/q/France/Paris.json

You can enter that in your web browser, but its designed to be sent from a program you designed, e.g. python using the requests module. YOUR_KEY is like a password. Most API’s require some kind of key as a password, especially if the information is more than just weather, but your private account data. You can see the API request includes some other parameters – here is its the forecast request for a city. The exact nature of how to form this URI differs between API’s, but most of them have excellent documentation.

import requests
r = requests.get('http://api.wunderground.com/api/YOUR_KEY/forecast/q/France/Paris.json')

The API response is now stored in the variable r, and rather than being a bunch of html, it is (usually) encoded in JSON, which is much easier to work with in programming languages, as it is similar to a python dictionary that we can easily look up something we need. Here’s a partial example from weather underground, if we print the r variable:

{
  "response": {
  "version":"0.1",
  "termsofService":"http://www.wunderground.com/weather/api/d/terms.html",
  "features": {
  "forecast": 1
  }
	}
		,
	"forecast":{
		"txt_forecast": {
		"date":"4:39 AM CET",
		"forecastday": [
		{
		"period":0,
		"icon":"snow",
		"icon_url":"https://icons.wxug.com/i/c/k/snow.gif",
		"title":"Thursday",
		"fcttext":"Cloudy with rain and snow this morning. Remaining cloudy this afternoon. High around 45F. Winds WSW at 5 to 10 mph. Chance of rain 40%.",
		"fcttext_metric":"Rain and snow this morning. Overcast for the afternoon. High 7C. Winds WSW at 10 to 15 km/h. Chance of rain 40%.",
		"pop":"40"
		}
		,
		{
		"period":1,
		"icon":"nt_partlycloudy",
		"icon_url":"https://icons.wxug.com/i/c/k/nt_partlycloudy.gif",
		"title":"Thursday Night",
		"fcttext":"Mostly cloudy early, then clearing overnight. Scattered frost possible. Low 32F. Winds WNW at 5 to 10 mph.",
		"fcttext_metric":"Evening clouds will give way to clearing overnight. Scattered frost possible. Low around 0C. Winds WNW at 10 to 15 km/h.",
		"pop":"20"
		}

That becomes really useful when we use python to grab the data we want, for example:

forecast_data = r.json()

for day in forecast_data ['forecast']['simpleforecast']['forecastday']:
    print day['date']['weekday'] + ":"
    print "Temperature (High): ", day['high']['celsius'] + "C"

Now that information is in python, you can obviously manipulate it however you like. The reason why web API’s are so useful is that the data is available on the web, so can be accessed through pretty much any programming language or platform – you can get the same data in a python script, an iOS app or anything else – all through this one method.

2. Some useful web APIs

There are thousands of web APIs, and many of the most popular websites have them. Gmail, Twitter, Facebook, Dropbox, IMDB, eBay etc. So a bit a of python hacking and you could have a Raspberry Pi tweet when the weather goes above a certain temperature, upload a picture to dropbox, send your mum and email and your dad a text of a random movie, or whatever you want! So there’s the trivial bus also some excellent back-end services have web APIs that can integrate with you web application, such as payment gateways like PayPal or Stripe, or messaging services like Twillio or Send Grid. So if you have a web app that people pay for you can receive money and get a text message when a new customer signs up, all through interfacing with these third party APIs that do the hard work for you.

3. Python wrappers

Even better is that many of the API’s already have a python wrapper library for them. By that I mean someone has written a python library that makes it much easier than directly calling an HTTP using the ‘requests’ library. For example, in python we can use the python library python-twitter (you’d need to set up the various API keys from your account first):

import twitter
twitterapi = twitter.Api(consumer_key='consumer_key',consumer_secret='consumer_secret', access_token_key='access_token', access_token_secret='access_token_secret')
status = twitterapi.PostUpdate('I love python-twitter!')

and that tweets “I love python twitter”! You only need to set up the twitter.Api obejct once per session too. There is a tutorial on a simple use of the Twitter API in the Raspberry Pi Education Manual page 115.

For the next post I’ll show you how to use a web API to put live traffic updates on an AndyPi or compatible HD44780 LCD!