Getting Started with PetfindeR

Aaron Schlegel

About PetfindeR

The goal of the PetfindeR package is to provide a simple and straightforward interface for interacting with the Petfinder API through R. The Petfinder database contains approximately 300,000 adoptable pet records and 11,000 animal welfare organization records, which makes it a handy and valuable source of data for those in the animal welfare community. However, the outputs from the Petfinder API are in messy JSON format and thus it makes it more time-consuming and often frustrating to coerce the output data into a form that is workable with R. The PetfindeR package was developed to alleviate this difficulty and provide users with a streamlined interface for getting the data they want and using it for their specific purpose.

Introduction

This vignette introduces and walks through the methods available in PetfindeR and the Petfinder API for authenticating and extracting data from the database.

Obtaining an API Key from Petfinder

Before we can use the PetfindeR package, we need to obtain an API key from the Petfinder website to authenticate our requests. To acquire an API key, create an account on Petfinder’s developer page. A ‘secret’ key is also given from Petfinder for requests that require an additional layer of authentication; however, the current methods available do not need a secret key to be provided (this could potentially change in the future).

Getting Started with PetfindeR

library(PetfindeR)

After installing and loading the package, The first step in using the PetfindeR package is to initialize the API connection to Petfinder. To do this, we pass the API key received from Petfinder into the Petfinder function which calls a wrapped R6 class and creates the connection to the API.

It is best practice to obfuscate sensitive data such as API keys to avoid any potential malicious activity. To this effect, I load my API key by using the Sys.getenv() function to access an environment variable containing the key.

key <- Sys.getenv('PETFINDER_KEY')

The API key is securely loaded so that we can initialize the PetfindeR API!

pf <- Petfinder(key)

That’s all there is to it! The Petfinder API methods are now accessible through R.

Examples

The following section introduces the PetfindeR package and how to interact with the Petfinder API with some simple examples of extracting data from the database. The examples are split into pet and shelter methods, not due to any significant demarcation, but rather for organization.

Pet Methods

Method Petfinder API Method Description
breed.list() breed.list Returns the available breeds for the selected animal.
pet.find() pet.find Returns a collection of pet records matching input parameters.
pet.get() pet.get Returns a single record for a pet.
pet.getRandom() pet.getRandom Returns a randomly selected pet record. The possible result can be filtered with input parameters.

Finding the available breeds of an animal

The breed.list() method allows the user to pull a list of breeds associated with a particular type of animal. The currently available animals to search for are 'barnyard', 'bird', 'cat', 'dog', 'horse', 'reptile' and 'smallfurry'. Let’s say we are interested in finding the breeds of cats in the Petfinder database.

cats <- pf$breed.list('cat')
cats

breed.list() can also be set to return a data.frame object by setting the return_df parameter to TRUE.

cats <- pf$breed.list('cat', return_df = TRUE)
head(cats)

Finding pet records matching criteria

The pet.find() method enables one to return a data.frame of pet records that match the input parameters. The available parameters can be found using ?pet.find() or checking out the Petfinder API documentation directly.

Let’s say we want to find female cats in Washington. The default amount of records is 25 (assuming there are 25 to return), which can be overridden with the count parameter.

wa_cats <- pf$pet.find('WA', 'cat', sex='F')

The returned data can also be automatically parsed into a data.frame by setting the method parameter return_df to TRUE. Here, we make the same call to the Petfinder API but with return_df = TRUE and print the first six rows of the first ten columns to demonstrate the returned data.frame.

wa_cats <- pf$pet.find('WA', 'cat', sex='F', return_df = TRUE)
head(wa_cats[,1:10])

Returning random pet records

The pet.getRandom() method returns a random pet ID by default, but can return a full pet record with a description by setting output = 'full'.

pf$pet.getRandom(output = 'full')

We can also get a set of random results by setting the records parameter to the number of desired results to return. Note that each record counts as one call to the Petfinder API.

random_records <- pf$pet.getRandom(records = 3, output = 'full')

Similar to other methods available in the PetfindeR package, the pet.getRandom method can also be set to return a data.frame by setting the parameter return_df = TRUE. As an example, we get three random pet records again and output the result as a data.frame (note the returned records will likely not be the same as the earlier returned records due to the random nature of the output).

random_records_df <- pf$pet.getRandom(records = 3, output = 'full', return_df = TRUE)
random_records_df[,1:10]

Getting pet records associated with a petId

Given a petId, an ID associated with information on a pet in the Petfinder database, the pet.get() method will return the pet record as a JSON object represented as an R list. The method also accepts a vector or list of IDs for returning multiple records. For example, we can take the petIds given in our previous call to pet.getRandom() and pass those to pet.get(). Note since we are using the same petIds from before, the returned records will be the same. We also set the return_df parameter to TRUE to demonstrate the functionality to convert the returned JSON result into a data.frame as in other methods seen previously.

pet_get_df <- pf$pet.get(petId = random_records_df$id, return_df = TRUE)
pet_get_df[,1:10]

Shelter Methods

Method Petfinder API Method Description
shelter.find() shelter.find Returns a collection of shelter records matching input parameters.
shelter.get() shelter.get Returns a single shelter record.
shelter.getPets() shelter.getPets Returns a collection of pet records for an individual shelter.
shelter.listByBreed() shelter.listByBreed Returns a list of shelter IDs listing animals matching the input animal breed.

Shelter methods are somewhat similar to the Pet methods we explored previously, but return information on animal shelters and other animal welfare organizations.

Finding animal welfare organizations in an area

Using the shelter.find() method, one can locate shelters and their available attributes matching the input parameters. For example, say we wanted to find shelters in a ZIP code in Seattle (my old zip code).

wa_shelters <- pf$shelter.find('98115')
head(wa_shelters$petfinder$shelters$shelter)

As with other methods in PetfindeR, the shelter.find method also has a return_df parameter that coerces and outputs the returned JSON into a workable data.frame.

wa_shelters_df <- pf$shelter.find('98115', return_df = TRUE)
head(wa_shelters_df)

Returning information on specific animal welfare organizations

Similar to pet.get(), the shelter.get() method takes a shelterId and returns the available information on the shelter from the Petfinder database.

One shelter that’s very dear to me is Seattle Area Feline Rescue, the shelterId of which is ‘WA40’. Let’s return the information available on the rescue.

safr <- pf$shelter.get('WA40')
safr

This data can also be transformed into a one-row data.frame by setting return_df = TRUE.

safr_df <- pf$shelter.get('WA40', return_df = TRUE)
safr_df

Getting pet records from a shelter

Let’s say we are interested in finding the available pets at a particular shelter; we could use the shelter.getPets() method to quickly find this information. Here, we return the pets currently available at the Seattle Area Feline Rescue and print the first ten columns of the returned data.

safr.pets <- pf$shelter.getPets('WA40')
head(safr.pets$petfinder$pets$pet)[,1:10]

The shelter.getPets() method also has a return_df parameter that can be set to TRUE to return a clean, workable data.frame for analysis.

safr.pets_df <- pf$shelter.getPets('WA40', return_df = TRUE)
head(safr.pets_df)[,1:10]

Finding shelters that have a particular animal breed

The shelter.listByBreed() method allows one to find shelters that have a particular breed of animal, which may be useful for users interested in finding rarer breeds of animal. The breed argument must match a breed listed in the Petfinder database, which can be easily extracted by using the breed.list() method. We already pulled the available cat breeds earlier in the vignette, so we can use that to select a breed of cat to search.

The Abyssinian is a beautiful and wonderfully friendly breed of cat, so let’s search for some shelters that have Abyssinians listed on Petfinder.

aby_shelters <- pf$shelter.listByBreed('cat', 'Abyssinian')

Note: There currently seems to be an issue (as of 5/9/2018) with the Petfinder API and the shelter.listByBreed method. The API will return an object successfully, but the data is empty. Hopefully, Petfinder will be able to fix this issue soon, but in the meantime, I leave this note here just in case.

Conclusion

In this vignette, we introduced the core functionality of the PetfindeR library for interacting and extracting data from the Petfinder API. In future vignettes, we will further explore working with the PetfindeR library as well some potential uses of the package for data extraction and analysis.