assignments/Ind_Assignment_4_Using_an_API.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Individual Assignment 4 - Using an API\n",
    "In this assignment, students will explore public Application Programming Interfaces (APIs) learn how to make a connection to a public API to query for data and use the data that is returned.  \n",
    "\n",
    "## Goal\n",
    "The goal of this lesson is to help students learn how to connect to public APIs and as a function of researching these APIs get an understanding of the common patterns and practices of setting up an API end point.\n",
    "\n",
    "## Deliverables\n",
    "1. A PDF of a completed notebook OR a link to the repository where the final version of the notebook is store.\n",
    "\n",
    "## Background\n",
    "As a data analyst, data is the fuel that drives the engine of discovery.  Often times this means using data we have collected with web forms, using external systems or via some business process.  Occassionally, we'll be given the data directly or we can download some data from a webpage that meets our needs.  Being able to gather data from sources on the web is a skill that is often very useful.  Wouldn't it be great if you could download [weather data predictions](https://www.abstractapi.com/api/weather#:~:text=What%20does%20the%20Weather%20API%20do%3F%20Abstract%27s%20Weather,and%20forecasted%20weather%20data%20for%20millions%20of%20locations.) as part of your morning routine, or grab [movies reviews](https://www.rottentomatoes.com/) to make plans for the weekend or even get data from the [James Webb Telescope](https://www.nasa.gov/mission_pages/webb/about/index.html) so you can process your own images from outer space!\n",
    "\n",
    "Web APIs are a powerful tool for developers to access data and functionality from other applications. They allow developers to query data from a remote server and receive a response in a structured format, such as JSON or XML.\n",
    "\n",
    "There are literally millions of web APIs available on the internet, some are private and only available to known and trusted business partners, many are available at a cost to the consumer and others are free.  Some have utilization caps for free use and expose more utilization and premium features to paying customers.  Here are just a very few commonly used, public APIs.\n",
    "\n",
    "### Common third-party APIs\n",
    "\n",
    "- The [Twitter API](https://developer.twitter.com/en/docs), which allows you to do things like displaying your latest tweets on your website.\n",
    "- Map APIs, like [Mapquest](https://developer.mapquest.com/) and the [Google Maps API](https://developers.google.com/maps/), which allow you to do all sorts of things with maps on your web pages.\n",
    "- The [Facebook](https://developers.facebook.com/docs/) suite of APIs, which enables you to use various parts of the Facebook ecosystem to benefit your app, such as by providing app login using Facebook login, accepting in-app payments, rolling out targeted ad campaigns, etc.\n",
    "- The [Telegram APIs](https://core.telegram.org/api), which allows you to embed content from Telegram channels on your website, in addition to providing support for bots.\n",
    "- The [YouTube API](https://developers.google.com/youtube/), which allows you to embed YouTube videos on your site, search YouTube, build playlists, and more.\n",
    "- The [Pinterest API](https://developers.pinterest.com/), which provides tools to manage Pinterest boards and pins to include them in your website.\n",
    "- The [Twilio API](https://www.twilio.com/), which provides a framework for building voice and video call functionality into your app, sending SMS/MMS from your apps, and more.\n",
    "\n",
    "## Instructions\n",
    "For this assignment, you should work through this notebook.  Executing all the cells and writing code in the various YOUR TURN cells in this notebook.\n",
    "\n",
    "You have a choice of either submitting a PDF of the notebook output, or a link to the repository where the completed notebook is stored.\n",
    "\n",
    "**You should not be using ChatGPT or similar AI for this assignment.**  Your work should be your own.  You may use the internet to search for answers to questions, but you should not be using AI to generate the answers for you.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part 1 - Investigating APIs\n",
    "Before we start writing code and connecting to various APIs, it is helpful to look into what kind of APIs are available and how to use them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Your Turn #1 - Investigating APIs\n",
    "Open up your favorite search engine and find a few APIs.  Investigate them a bit and then answer the following questions.\n",
    "\n",
    "- For each of the 3 APIs that you looked at (name and URL).\n",
    "    - What data format did they primarily use for communication? (XML, JSON, CSV, something else)\n",
    "    - Did any of the APIs require some credentials in order to use them?\n",
    "    - Review the documentation.  Did one or more of the documentation include examples of how to use the service?  \n",
    "    - What else in the documentation was helpful to understand how to leverage the API?\n",
    "    - How could you use the API to build something useful?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part 2 - Using a public API\n",
    "It's not easy to find public APIs that don't require some kind of credentials.  The reason for is that when you provide credentials (usually an API \"key\"), the developer of the API can limit the number of requests your program makes and can determine which API calls are being used by a particular end-point.  There is cost to running an API, the cost of the compute resources, disk space and network traffic - all which can add up, so charging a little bit of money can help defray these costs and ensure that the endpoints requesting data are serious enough to spend a little money to make their application go.\n",
    "\n",
    "While every API interaction is different (most APIs have documentation showing examples of how to call it), there are some basic principals/tools/patterns we can employ.  Here we'll look at an example that is very useful and gives a sense of the Python tools used to navigate the endpoint when you see something similar.\n",
    "\n",
    "## Using the requests library\n",
    "The [`requests`](https://requests.readthedocs.io/en/latest/) library is a very common library for automating the interaction with webpages.  There are lots and lots of features, we'll focus on just a few.  For more information, you can see the excellent documentation [here](https://requests.readthedocs.io/en/latest/).\n",
    "\n",
    "There are several different request types that can be sent to a webpage (GET, PUT, DELETE, HEAD, et al). GET is used to navigate a static website, sometimes using query parameters as we have seen already.  PUT and POST are used to submit data on a form.  We'll leave the others for a more advanced treatise.  For our purposes, we'll just take a look at GET.  \n",
    "\n",
    "Let's take a new example.  What if we want get the current price of bitcoin?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "# Create a variable to hold the end point of the API\n",
    "url = 'https://api.coindesk.com/v1/bpi/currentprice.json'\n",
    "# Using the requests library to make a GET request to the API, and store the response in a variable called response\n",
    "response = requests.get(url)\n",
    "\n",
    "# Print the response (as text)\n",
    "print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well that is interesting, but clearly the response is JSON, so maybe we should try getting the response as JSON instead of text.  (There is no JSON type, JSON is stored as a dictionary so keep this in mind as we take a look at the next steps)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pprint\n",
    "\n",
    "json_response = response.json()\n",
    "print(f\"The type of the json_response is {type(json_response)}\\n\\n\")\n",
    "\n",
    "# Print the response (as json), actually as a dictionary\n",
    "pprint.pprint(response.json())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course we know how to do interesting things with dictionaries and then use the keys to get the data we want, so let's go ahead and get the current price of bitcoin in USD.\n",
    "\n",
    "A side note here.  What we really have is a dictionary of dictionaries which also have dictionaries as their values.  This can be hard to conceptualize but let's try to break it down a bit.\n",
    "\n",
    "We know we have a dictionary because it is surrounded in `{}`.  Let's take a look at the keys in the dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the keys in the dictionary\n",
    "print(f\"\\nThe keys in the dictionary are: {json_response.keys()}\\n\\n\")\n",
    "\n",
    "# Get the value associate with the bpi key\n",
    "print(f\"The value associated with the bpi key is: {json_response['bpi']}\\n\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Okay so now we can see that the value associated with the `bpi` key is another dictionary.  Notice how the value starts with an `{`.  Let's repeat and get the keys in the new dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the value associated with the value associated with the bpi key\n",
    "bpi_dictionary = json_response['bpi']\n",
    "# Get all the keys in the bpi dictionary\n",
    "print(f\"The keys in the bpi dictionary are: {bpi_dictionary.keys()}\\n\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Perfect!  So we have gotten the VALUE associated with the bpi KEY and see it's a dictionary with three more keys 'USD', 'GBP', 'EUR'. This means we can get the values for each of these from the bpi_dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the value of the bpi_dictionary associated with the USD key\n",
    "usd_value = bpi_dictionary['USD']\n",
    "print(f\"The value of the bpi_dictionary associated with the USD key is: {usd_value}\\n\\n\")   \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again we see that the VALUE associated to the USD key of the bpi dictionary is itself another dictionary.  Let's get the keys for this new dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the USD as a dictionary\n",
    "usd_dictionary = bpi_dictionary['USD']\n",
    "\n",
    "# Print the keys in the usd_dictionary\n",
    "print(f\"The keys in the usd_dictionary are: {usd_dictionary.keys()}\\n\\n\")\n",
    "\n",
    "# For each key in the usd_dictionary, print the key and the value   \n",
    "for key in usd_dictionary.keys():\n",
    "    print(f\"The value associated with the {key} key is: {usd_dictionary[key]}\")\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we can see the values for each of the keys in the USD dictionary are string and numbers. No more dictionaries.  So now we get to the value we want."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Print the rate_float value associated with the USD dictionary\n",
    "print(f\"\\nThe `rate_float` value associated with the USD dictionary is: {usd_dictionary['rate_float']}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we'll put it all together into a single cell, and show you how to shortcut this into a single line of Python"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import pprint # import pretty print\n",
    "\n",
    "# Create a variable to hold the end point of the API\n",
    "url = 'https://api.coindesk.com/v1/bpi/currentprice.json'\n",
    "# Using the requests library to make a GET request to the API, and store the response in a variable called response\n",
    "response = requests.get(url)\n",
    "\n",
    "# Get the response as json (as a dictionary)\n",
    "json_response = response.json()\n",
    "# Print the response as json just as a checkpoint\n",
    "pprint.pprint(json_response)\n",
    "\n",
    "# Get the bpi dictionary from the json_response\n",
    "bpi_dictionary = json_response['bpi']\n",
    "# Get the USD dictionary from the bpi dictionary\n",
    "usd_dictionary = bpi_dictionary['USD']\n",
    "# Get the rate_float value from the usd_dictionary\n",
    "rate_float = usd_dictionary['rate_float']\n",
    "\n",
    "# NOTE: \\n is a special character that means \"new line\"\n",
    "print(f\"\\nThe current price of Bitcoin in USD is {rate_float}\\n\")\n",
    "\n",
    "# Here we are going to do the same thing as above, but in one line of code\n",
    "bitcoin_in_usd = json_response['bpi']['USD']['rate_float']\n",
    "print(f\"\\nThe current price of Bitcoin in USD is {bitcoin_in_usd}\\n\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## YOUR TURN - Query a public API (Part 1)\n",
    "\n",
    "Now it's your turn.  Starting from the top.  Make the request, but since you'll be running at a different time than the example, let's make sure to include the example.  I'd like to see the US, Euro, and British Pound exchange rate for bitcoin and the time in which you made the query.  Your result should look like:\n",
    "\n",
    "\n",
    "```\n",
    "The exchange rate for bitcoin at Sep 14, 2023 18:41:00 UTC:\n",
    " in GBP is 22326.7304\n",
    " in EUR is 26028.8456\n",
    " in USD is 26719.65\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import pprint # import pretty print\n",
    "\n",
    "# Create a variable to hold the end point of the API\n",
    "url = 'https://api.coindesk.com/v1/bpi/currentprice.json'\n",
    "# Using the requests library to make a GET request to the API, and store the response in a variable called response\n",
    "response = requests.get(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## YOUR TURN - Query a public API (Part 2)\n",
    "One of the easiest ways to figure out what you are going to get back is to just post the query into a web browser and see what the result is.  You can try that with this next URL\n",
    "```https://production.api.coindesk.com/v2/tb/price/ticker?assets=ETH,XRP,BTC```\n",
    "\n",
    "Once you see what kind of data is returned from this query, repeat similar steps to the ones above, but this time give us the breakdown of the open and close values of each of the three coins (XRP, ETH and BTC).  \n",
    "\n",
    "*HINT: the dictionary key `ohlc` represents (open, high, low, close), from here I presume you can figure out which sub-key applies to open and close*\n",
    "\n",
    "Loop through each of the currencies so you don't need to have repetitive code in your solution.  Your output should look something like\n",
    "\n",
    "```\n",
    "The open price for ETH is: 46.23\n",
    "The close price for ETC is: 46.24\n",
    "The open price for XRP is: 46.23\n",
    "The close price for XRP is: 46.24\n",
    "The open price for BTC is: 46.23\n",
    "The close price for BTC is: 46.24\n",
    "```\n",
    "**HINT 2 (optional):** to limit the decimal points in your print statements use the `:.2f` format like so ```print(f'{currency_value:.2f}')```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Start by writing out the algorithm in plain english first"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## YOUR TURN - Query a public API (Part 3)\n",
    "On [Zippopotam.us](https://www.zippopotam.us/), we can get useful information for zipcodes across the world.  To get information from different zipcodes, we just change the URL to have the zipcode we need in the URL.  For instance, \n",
    "\n",
    "`https://api.zippopotam.us/us/72712` gives us information for Bentonville, AR.  And if we change the last bit of the string we get another zip code `https://api.zippopotam.us/us/90210`.\n",
    "\n",
    "This is super handy, so let's develop a little app that asks the user for the zip code we should be querying and then return them information about the zip code.  Here's what the end result should look like if we type 72712\n",
    "\n",
    "```\n",
    "Zipcode: 72712\n",
    "Bentonville, AR US\n",
    "```\n",
    "\n",
    "**HINTS**\n",
    "- I suggest trying to build your code to work with a fixed URL first.  In other words, pick one of the URLS above (or another) and use this as a starting point to build your program. Once you have got it working, then replace the fixed zip code with your user request.  This will save you from having to type in the zip code everytime you run the app while you are developing it\n",
    "- You can use the `input()` function to get input from the user at runtime\n",
    "- Remember that JSON can return dictionaries of dictionaries like we've seen above, but the elements may also be lists, which could be lists of dictionaries or lists of lists.  The best idea is to break it down one step at a time, like we did above until you get to the exact item you are looking for before trying to put it all into a single line of Python code\n",
    "- It may be helpful to build your code in VS Code as a python file instead of a Jupyter notebook so that you can use the debugger.  Build it there and paste into the notebook when you are finished if you like.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Start by writing out the algorithm in plain english first"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "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.11.3"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}