cat_api.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The Cat API\n",
    "# docs: https://thecatapi.com/docs.html\n",
    "\n",
    "# An API used to request images of cats on tumblr.\n",
    "# In this example, we'll dig into what is available through the api and then request a cat picture or two."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests    # the best Python library for making HTTP requests \n",
    "from IPython.display import Image # this will allow us to display images in the jupyter notebook\n",
    "import xml.dom.minidom\n",
    "\n",
    "base_url = \"http://thecatapi.com/\"   # This is the base url for the api.  Each endpoint we call will be built\n",
    "                                     # upon this URL. (you'll see exactly what I mean in the next example)\n",
    "base_url"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The main end point: `/api/images/get`\n",
    "# docs: https://thecatapi.com/docs.html#get\n",
    "#\n",
    "# This endpoint is where you'll request the actual images\n",
    "endpoint = \"api/images/get\"\n",
    "request_url = base_url + endpoint  # the full url where we request cat images\n",
    "\n",
    "request_url"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If we make a request with this url by itself we will get a random cat image.  Let's try it!\n",
    "\n",
    "# First we send a GET request to the `request_url` 'http://thecatapi.com/api/images/get'\n",
    "r = requests.get(request_url)  \n",
    "r"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This request returned a `Response` object.  We can do a lot with these as you'll see in this and other examples.\n",
    "# In this case, the endpoint we requested returns an image file.  Because of this we want to access the `content`\n",
    "# field of the response.  (in most cases, when dealing with data, you'll want to use the `text` field)\n",
    "r.content"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is what a jpg looks like if you convert it's data into a string of hexidecimal numbers.\n",
    "# It's not very useful, so lets display it as an image.\n",
    "Image(data=r.content)     # this will take the jpg data and make a viewable image with it"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This endpoint generates a different image each time, so if we make the request again, we'll get a different image\n",
    "r = requests.get(request_url)  \n",
    "Image(data=r.content)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Getting random images of cats is great, but sometimes you want to specify what type of cat image you want.\n",
    "# This is where we can use paramaters.\n",
    "# You've probably seen GET request paramaters before at the end of urls.\n",
    "# They appear at the end of a url after a '?'.\n",
    "\n",
    "# Let's look at the catAPI documentation to see what paramters we can send to our endpoint\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[/api/images/get docs](https://thecatapi.com/docs.html#get)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The paramater `category` allows you to provide categories to filter the types of cat pictures that are returned\n",
    "# The list is really long and changes, so the api provides a `/api/category/list` endpoint.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[/api/category/list docs](http://thecatapi.com/api/categories/list)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If we call that endpoint, we can see what categories we can use.\n",
    "category_endpoint = 'api/categories/list'\n",
    "category_url = base_url + category_endpoint\n",
    "category_url"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make a new request to get the list\n",
    "r = requests.get(category_url)\n",
    "\n",
    "# Since this will be text data, we can use the `text` field to see what the API returned\n",
    "print(r.text)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# \"Space\" sounds awesome!  Let's use that.\n",
    "# Per the `/api/images/get` documentation, we'll need to provide that as the `category` paramater.\n",
    "# In requests, you can do that by providing your paramaters and a python dict to request's `params` argument.\n",
    "\n",
    "our_params = {'category': 'hats',   # request cats in space\n",
    "              'size': 'large', 'format': 'xml'}      # and large images\n",
    "request_url  # the url we used to request cat images earlier\n",
    "r = requests.get(request_url, params=our_params)\n",
    "print(r.text)\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
}