Assignment 6: Learning a New API

Tutorial: Creating and Using The Cat API

Author

Roe Breckenridge

The Cat API Introduction

The Cat API is a free web service that provides access to thousands of cat images, gifs and breed information. Cat images can be retrieved using simple URL (web) requests. This document will instruct you on how to generate your personal Cat API Key on TheCatAPI.com website and show you ways to utilize it to gather information about and/or analyze various cat breeds.

The API can be used to:

Practice working with APIs
Learn and practice retrieving JSON data
Creating visualizations that use images
Creating data sets for projects

### Setting Up the API

# Step 1: Create an account

# Go to https://thecatapi.com
# Create a free account
# Get your API key
# Keep your API key private

### Step 2: Load the required packages - Install them first if needed

# Load the following packages in R
library(tidyverse) # All the tidy things
library(jsonlite)  # Converting json data into data frames
library(httr)      # Interacting with HTTP verbs
library(rsconnect) # Enables Publishing of Quarto docs
library(magrittr)  # Extracting items from list objects using piping grammar

Understanding API Requests

With the Cat API, data is retrieved by sending a request to a URL endpoint. The base URL example we used in our supplemental R script is:

https://api.thecatapi.com/v1/images/search

This request can be customized using the following parameters

Parameter: Purpose:

limit number of images returned

breed_ids filter by breed

category_ids filter image categories

API results are returned in JSON format which can then be converted to a dataframe in R.

Example 1: Random Cat Images

This first example retrieves 10 random cat images using an API request.

The data was collected using a supplemental R script I created and saved as a CSV file.

### Step 3: API results may change over time. This is why we use a supplemental R script to collect the data.
#| label: Load the dataset
random_cats <- read_csv("random_cats.csv", show_col_types = FALSE)

### Step 4: Display an image
#| label: Using the knitr command we can now display the first image

knitr::include_graphics(random_cats$url[1])

Example 2: Filter by Breed (Bengal Cats)

Additionally, we can retrieve data from a specific breed using the breed_ids parameter.

Here is an example of a customized endpoint to retrieve 5 Bengal cat breed specific images:

https://api.thecatapi.com/v1/images/search?limit=5&breed_ids=beng

### Step 3 (AGAIN) 
#| label: Load the dataset
bengal_cats <- read_csv("bengal_cats.csv", show_col_types = FALSE)

### Step 4 (AGAIN): 
#| label: Display Benga cat images

knitr::include_graphics(bengal_cats$url[1])

knitr::include_graphics(random_cats$url[2])

The Results

Each API request returns structured information:

id: unique identifier for each image
url: a link to the cat image
width: image width
height: image height

The JSON output is converted into tabular format for analysis.

Filtering allows you to retrieve targeted data instead of random results.

Conclusion

The Cat API shows how APIs allow automated data collection. They are widely used in the data science industry to gather real-time data for analysis.

--- title: "Assignment 6: Learning a New API" subtitle: "Tutorial: Creating and Using The Cat API" author: "Roe Breckenridge" toc: true format: html: toc: true code-tools: true embed-resources: true execute: warning: false message: false echo: true editor: visual --- ## The Cat API Introduction The Cat API is a free web service that provides access to thousands of cat images, gifs and breed information. Cat images can be retrieved using simple URL (web) requests. This document will instruct you on how to generate your personal Cat API Key on TheCatAPI.com website and show you ways to utilize it to gather information about and/or analyze various cat breeds. The API can be used to: 1. Practice working with APIs 2. Learn and practice retrieving JSON data 3. Creating visualizations that use images 4. Creating data sets for projects ```{r} ### Setting Up the API # Step 1: Create an account # Go to https://thecatapi.com # Create a free account # Get your API key # Keep your API key private ``` ```{r} ### Step 2: Load the required packages - Install them first if needed # Load the following packages in R library(tidyverse) # All the tidy things library(jsonlite) # Converting json data into data frames library(httr) # Interacting with HTTP verbs library(rsconnect) # Enables Publishing of Quarto docs library(magrittr) # Extracting items from list objects using piping grammar ``` ## Understanding API Requests With the Cat API, data is retrieved by sending a request to a URL endpoint. The base URL example we used in our supplemental R script is: https://api.thecatapi.com/v1/images/search This request can be customized using the following parameters Parameter: Purpose: limit number of images returned breed_ids filter by breed category_ids filter image categories **API results are returned in JSON format which can then be converted to a dataframe in R.** ## Example 1: Random Cat Images This first example retrieves 10 random cat images using an API request. The data was collected using a supplemental R script I created and saved as a CSV file. ```{r} ### Step 3: API results may change over time. This is why we use a supplemental R script to collect the data. #| label: Load the dataset random_cats <- read_csv("random_cats.csv", show_col_types = FALSE) ``` ```{r} ### Step 4: Display an image #| label: Using the knitr command we can now display the first image knitr::include_graphics(random_cats$url[1]) ``` ## Example 2: Filter by Breed (Bengal Cats) Additionally, we can retrieve data from a specific breed using the **breed_ids** parameter. Here is an example of a customized endpoint to retrieve 5 Bengal cat breed specific images: https://api.thecatapi.com/v1/images/search?limit=5&breed_ids=beng ```{r} ### Step 3 (AGAIN) #| label: Load the dataset bengal_cats <- read_csv("bengal_cats.csv", show_col_types = FALSE) ``` ```{r} ### Step 4 (AGAIN): #| label: Display Benga cat images knitr::include_graphics(bengal_cats$url[1]) knitr::include_graphics(random_cats$url[2]) ``` ## The Results Each API request returns structured information: 1. id: unique identifier for each image 2. url: a link to the cat image 3. width: image width 4. height: image height The JSON output is converted into tabular format for analysis. Filtering allows you to retrieve targeted data instead of random results. ## Conclusion The Cat API shows how APIs allow automated data collection. They are widely used in the data science industry to gather real-time data for analysis.