TheCatAPI

Introduction to the Cat API

The Cat API website focuses on providing information about thousands of cats. This service gives developers access to a large collection of cat images and detailed breed information through API requests. Users can retrieve images or filter results based on specific breeds and categories. I will be using this API to create a function that complies the returned data into a structured data frame for further analysis and exploration.

Obtaining the API Key

To begin gathering information from The Cat API, you first need to set up an individual API key. Start by opening your web browser and navigating to the official Cat API website: https://thecatapi.com. From there, click the “Get Your API Key” button, which will take you to the registration page.

You will see two plan options, including a free one that allows up to 10,000 requests per month and provides access to images and breed information. For this project, select the “Get Free Access” option. You will then be prompted to enter your email, a brief description of your application, and the type of project you are working on. After submitting this information, your API key will be sent to your email. Make sure to check your spam or junk folder if it doesn’t appear within a few minutes of submitting the request.

Accessing the API in R

The first step in working with The Cat API in R is loading the necessary packages. These libraries allow us to send API requests, handle JSON data, and organize the results into a usable format.

library(tidyverse) # All the tidy things

── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.1.4     ✔ readr     2.1.6
✔ forcats   1.0.1     ✔ stringr   1.6.0
✔ ggplot2   4.0.1     ✔ tibble    3.3.1
✔ lubridate 1.9.4     ✔ tidyr     1.3.2
✔ purrr     1.2.1     
── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors

library(jsonlite)  # Converting json data into data frames

Attaching package: 'jsonlite'

The following object is masked from 'package:purrr':

    flatten

library(magrittr)  # Extracting items from list objects using piping grammar

Attaching package: 'magrittr'

The following object is masked from 'package:purrr':

    set_names

The following object is masked from 'package:tidyr':

    extract

library(httr)      # Interacting with HTTP verbs

The next step is creating a function that builds the API request URL. This function allows you to customize parameters such as the number of images returned, page number, and specific filters, which makes the API call more flexible and reusable for different analyses.

api_key <- "api_key=live_VdM2x6adWQZDHad6tKJ7QD7BgCvoRJswTtsgPq2PNDmACYRKDDwz90nk8GgdQR3Z"

cat_url <-
  function(api_key, limit, page, order, has_breeds, breed_ids, category_ids) {
    
    # Define the endpoint
    cat_endpoint <- "https://api.thecatapi.com/v1/images/search"
    
    # Define your API key query parameter
    api_key <- paste("?api_key=",api_key, sep = "")
    
    # Apply the filtering criteria
    limit <- paste("&limit=",limit, sep = "")
    page <- paste("&page=",page, sep = "")
    order <- paste("&order=",order, sep = "")
    has_breeds <- paste("&has_breeds=",has_breeds, sep = "")
    breed_ids <- paste("&breed_ids=",breed_ids, sep = "")
    category_ids <- paste("&category_ids=",category_ids, sep = "")
    
    # Creating your final API call URL #
    cat_api_GET <- 
      paste(cat_endpoint,api_key, limit, page, order, has_breeds, breed_ids, category_ids, sep = "")
    
     return(cat_api_GET)
}

In this step, you use the previously created function to generate the final API request URL. By specifying parameters, you are able to customize data that will be retrieved from The Cat API.

final_cat_url <-
  cat_url(api_key = "live_VdM2x6adWQZDHad6tKJ7QD7BgCvoRJswTtsgPq2PNDmACYRKDDwz90nk8GgdQR3Z",
          limit = 100,
          page = 0,
          order = "DESC",
          has_breeds = 1,
          breed_ids = "",
          category_ids = "")

The following code creates a function that takes the API URL and sends a request to retrieve the data. The returned JSON data is then converted into a data frame, which makes it easier to view and analyze R.

cat_df <- data.frame()
  
cat_api_GET_df <-
  function(final_cat_url) {
    cat_df <-
      final_cat_url %>%
      GET(add_headers("x-api-key" = api_key)) %>% 
      content(as = "text",
              encoding = "UTF-8") %>% 
      fromJSON()
    return(cat_df)
  }

The loop goes through each API URL and calls the function to retrieve the data from The Cat API. It then combines each result into one single data frame so all of the information is stored together.

for (i in seq_along(final_cat_url)) {
  cat_df <-
    cat_api_GET_df(final_cat_url[i]) %>%
    bind_rows(cat_df)
}

This example retrieves data specifically for the Siamese cat breed using the API function with a breed filter. The resulting data is then stored in a data frame so it can be viewed and analyzed in R.

siamese_url <- 
    cat_url(
      api_key = "live_VdM2x6adWQZDHad6tKJ7QD7BgCvoRJswTtsgPq2PNDmACYRKDDwz90nk8GgdQR3Z",
      limit = 10,
      page = 0,
      order = "DESC",
      has_breeds = 1,
      breed_ids = "siam",
      category_ids = ""
    ) 

siamese <-
  cat_api_GET_df(siamese_url)