An-introduction-to-using-APIs.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# An introduction to using APIs\n",
    "\n",
    "This is a 10 minute tutorial for non-programmers to learn how developers use APIs - where you will actually <font color=blue>access real APIs</font> from inside your web browser.\n",
    "\n",
    "<font color=blue>Get inside your programmer's head</font> Usually you have to rely on a programmer to do some magic to build an application that uses APIs. Here we attempt to look inside the programmers head, so you learn what that 'magic' is (the computer programs that they write). At times it might feel like you are having to learn maths again, but there's <font color=blue>no test at the end</font> so you don't have to understand it, just get the general idea of what is going on.\n",
    "\n",
    "<font color=blue>All the tools you need are here on this page</font> We have created a 'sandbox' where you can read and run real computer programs below without having to download and install software to your device. If you are brave, you can <font color=blue>even change the programs</font> below to try different ways of using the APIs.\n",
    "\n",
    "**You can *not* break it!** When you opened this web page it created <font color=blue>a whole new copy just for you to play with</font>, the original version is not touched. \n",
    "* If things go badly, you can easily refresh the web page and start over again.\n",
    "* If things go well, who knows, you might decide to save your program and start learning how to download the software for yourself...\n",
    "\n",
    "## What is an API?\n",
    "\n",
    "As humans we use websites to get and give information. APIs (Application Programming Interface) are for computer systems to get and give that same information. \n",
    "\n",
    "Computer systems are quite intelligent but also quite simple, so they don't understand huge blocks of words and images on web pages, that's why APIs break the information down into <font color=blue>small and structured pieces of data</font>.\n",
    "\n",
    "You can read more in [Wikipedia's API entry](https://en.wikipedia.org/wiki/Application_programming_interface) or watch this [3 minute video on APIs](https://www.youtube.com/watch?v=s7wmiS2mSXY).\n",
    "\n",
    "## How to play this tutorial\n",
    "\n",
    "To read computer programs, it's best to <font color=blue>think of a computer program as a recipe</font> - they usually start with a few ingredients, then the method explains the step-by-step how use those ingredients to make something. The difference is that instead of using fancy words that only cooks understand, programs use fancy words that only computers understand.\n",
    "\n",
    "This tutorial has one long computer program (written in the [Python](https://www.python.org/) programming language), but we are going to read and run (operate/execute) one section at a time.\n",
    "\n",
    "1. Read each section's text (on a white background)\n",
    "2. See if you can <font color=blue>understand the program code</font> in the following grey box (with \"In[]\" next to it)\n",
    "3. Click on that grey box\n",
    "4. <font color=blue>Run that section of the program</font> (by clicking on the \"Run\" button at the top of this web page)\n",
    "5. Look at the output it shows\n",
    "6. Rinse and repeat (start at step (1) again)\n",
    "\n",
    "Let's begin..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Ingredients\n",
    "\n",
    "The top of the program lists the things we will need:\n",
    "* `import` specifies special program functions (pots and pans) that we will need\n",
    "* `name = value` means <font color=blue>define a simple name (alias/variable)</font> for a value so we can use that name again later instead of the value (which makes it easier to read the program)\n",
    "* `print` isn't an ingredient, it's part of the method - to display something so you can read it\n",
    "* A `#` (hash character) at the start of a line means the line is a comment (meant for the programmer not the computer), like that tip your aunt scribbled for you (the cook) on your recipe\n",
    "\n",
    "In this tutorial we are going to use <font color=blue>MusicBrainz API</font>. You can read more about the [MusicBrainsz Web Service API](https://wiki.musicbrainz.org/Development).\n",
    "\n",
    "Our programmer read through MusicBrainz's API documentation and discovered that the API can be queried by the name of music artists. Our programmer loves to dance so decided to build an app about bands who have 'disco' in their name.\n",
    "\n",
    "ACTIONS: \n",
    "* Look through the lines of code in the next grey box to see what we will ask the computer to do\n",
    "* Click on the grey box and press the RUN button at the top of this web page. You will see a message appear directly after the grey box."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# here we are at the top of our program!\n",
    "\n",
    "# firstly we tell the computer any special program functions (pots and pans) that we will need\n",
    "import requests\n",
    "import folium\n",
    "\n",
    "# next we list the inputs (ingredients)\n",
    "# we give each input its own short name (so we can talk about it later), then add '=' (equals sign), and then add the input value\n",
    "\n",
    "# the band name to search on\n",
    "band_name = 'disco'\n",
    "\n",
    "# the URL (web address) of the main API's search endpoint - let's call it 'api_endpoint'\n",
    "# we insert the band_name above into the endpoint query\n",
    "api_endpoint = 'http://musicbrainz.org/ws/2/artist/?query=name:' + band_name + ' AND area:*&limit=5&fmt=json'\n",
    "\n",
    "# display a fun message showing that the computer has read to the end of our ingredients list\n",
    "print('OK, got the ingredients, time to cook')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Retrieve data from the main API\n",
    "\n",
    "Now we start the <font color=blue>method part of the recipe</font>. We write a list of commands that we want the computer to run one-by-one.\n",
    "\n",
    "However, we are going to use a special trick where we still keep adding in new ingredients (new names/variables/aliases) within the method. It's ok because we do this in cooking too, for example:\n",
    "* `butter_sugar_mixture = mix_together(butter, sugar)`\n",
    "* `pour_into(bowl, butter_sugar_mixture)`\n",
    "\n",
    "We want to start by getting some data from the main API.\n",
    "\n",
    "You are already used to telling your web browser to go to a web address (e.g. google.com) to show you the web page response. We are now going to tell the computer program to <font color=blue>get the data response</font> from the API's address (also known as the 'API endpoint').\n",
    "\n",
    "ACTIONS: \n",
    "* Look through the lines of code in the next grey box to see what we will ask the computer to do\n",
    "* Click on the grey box and press the RUN button at the top of this web page. You will see a message appear directly after the grey box."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# make a request to our API endpoint, name the response with the alias 'response'\n",
    "response = requests.get(api_endpoint)\n",
    "\n",
    "# find the the json data inside the response, name it 'data'\n",
    "data     = response.json()\n",
    "\n",
    "# show the response data\n",
    "print(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Display data from the main API\n",
    "\n",
    "Yikes, that data is complicated! \n",
    "\n",
    "The data is wrapped in <font color=blue>special codes called JSON</font> - which is a bit like HTML (if you've seen how a web page is made).\n",
    "\n",
    "Here's a sample reformatted so it is slightly easier to read. The data is arranged like files inside folders.\n",
    "* First we have a top folder for the complete response, between the `{...}` braces\n",
    "* The top folder has a file named `count` and a folder named `artists`\n",
    "* The `artists` folder has a list of sub-folders, between the `[...]` square brackets\n",
    "* These sub-folders aren't named, they just have 3-4 fields (id/type/name/country) between the `{...}` braces\n",
    "\n",
    "```JSON\n",
    "{\n",
    "  count: 1442,\n",
    "  artists: \n",
    "    [\n",
    "      {\n",
    "        id: \"c131bca1-79d1-4c2f-8985-c9bc700d5c77\",\n",
    "        type: \"Group\",\n",
    "        name: \"Disco\",\n",
    "        country: \"FI\",\n",
    "      },\n",
    "      {\n",
    "        id: \"ac856099-3614-420d-ae65-11979fa25373\",\n",
    "        name: \"Disco\",\n",
    "        country: \"US\",\n",
    "      }\n",
    "    ]\n",
    "}\n",
    "```\n",
    "\n",
    "Because we are inside our programmer's head we understand those JSON codes, but our programmer wants to make it <font color=blue>easier for our app users to read</font>.  So we will work our way through each record and show only the bits we want. Let's start with the artist name and country - they look useful to users.\n",
    "\n",
    "In the next section of our program, we are going to use a special looping `for` command that <font color=blue>automatically works its way through a list</font> and runs the same sub-command for each item it finds in that list.\n",
    "* `data['artists']` tells it the list (find the 'artists' folder in the response we have already named 'data')\n",
    "* for each item, give it the name `record`\n",
    "* the sub-commands are indented - here we have chosen to show the name and country from each item (that we have just named 'record')\n",
    "\n",
    "It's a bit complicated, but it should make more sense when you run it.\n",
    "\n",
    "ACTIONS: \n",
    "* Look through the lines of code\n",
    "* Click on the grey box an press the RUN button\n",
    "* Look at the output - a nicely formatted list of the bands found"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# a special 'for' loop - for each item in the list (the artists part of the response data), name it 'record' and do something with it\n",
    "for record in data['artists']:\n",
    "    # show only the name and country from each record\n",
    "    print(record['name'] + ' from ' + record['area']['name'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Congratulations! You have made a call to an API and formatted the response data.\n",
    "\n",
    "BUT...\n",
    "\n",
    "Can't we make it a bit more interesting? We could show where the bands are on a map, except the MusicBrainz API doesn't give us the GPS co-ordinates.\n",
    "\n",
    "Luckily our programmer knows that there are other APIs out there we can also use..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Lookup extra (geocoding) data from another API\n",
    "\n",
    "The [Geocode XYZ API](https://geocode.xyz/api) does 'geocoding' - it converts the name of a place into GPS latitude/longitude co-ordinates. Then we can plot where each band comes from on a map.\n",
    "\n",
    "ACTIONS:\n",
    "* Look through the lines of code\n",
    "* Click on the grey box an press the RUN button\n",
    "* Now we have a map!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set up a 'folium' map (folium is a special function for drawing maps)\n",
    "map = folium.Map()\n",
    "\n",
    "# define the geocoding API endpoint\n",
    "# note that we will need to call it with a different place name each time, so use a placeholder {{place}} for now\n",
    "lookup_api_endpoint = 'https://geocode.xyz/{{place}}?json=1'\n",
    "\n",
    "# loop through the bands (again)\n",
    "for record in data['artists']:\n",
    "    \n",
    "    # get this band's country's name, and put it into the API endpoint (using 'replace')\n",
    "    artist_name = record['name']\n",
    "    country_name = record['area']['name']\n",
    "    api_search_url = lookup_api_endpoint.replace('{{place}}', country_name)\n",
    "\n",
    "    # call the API \n",
    "    response = requests.get(api_search_url)\n",
    "    \n",
    "    # pull out the latitude and longitude from the response\n",
    "    lookup_data = response.json()\n",
    "    lat = lookup_data['latt']\n",
    "    lon = lookup_data['longt']\n",
    "    \n",
    "    # add a marker to our map with the GPS co-ordinates and the name of the band\n",
    "    print(artist_name + ' from ' + country_name + ': ' + lat + ',' + lon)\n",
    "    folium.Marker([float(lat), float(lon)], popup=artist_name).add_to(map)\n",
    "\n",
    "# draw the map\n",
    "map"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Next steps\n",
    "\n",
    "Congratulations! Let's review what you did, you:\n",
    "* Called an API\n",
    "* Pulled out some data from the response\n",
    "* Used that data to call another API to add in extra data\n",
    "* Displayed it all so it is useful to a user\n",
    "\n",
    "Now it's play time:\n",
    "* Change the name of the bands we are looking for (then run each step again)\n",
    "* Look at the API documentation, maybe there are different fields you could display\n",
    "\n",
    "### About\n",
    "Source code for this tutorial: [GitHub repository using-apis](https://github.com/staplegun/using-apis)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}