The following vignette introduces the
PetfindeR package and its methods for interacting with the Petfinder API. The goal of the
PetfindeR library is to enable other users to interact with the rich data available in the Petfinder database. More information on the Petfinder API itself can be found on the API documentation page.
Before we can begin extracting data from the API, we first require an API and secret key to authenticate access. To receive an API and secret key, create a free account with Petfinder on their developer page and request an API key.
The API and secret key received from Petfinder are what we will use to authenticate our connection to the Petfinder API with
PetfindeR. Note authenication has a timeout of 3600 seconds, or one hour, after which the authentication to the API will need to be made again. For more information on how the Petfinder API authenication works, visit the API documentation on the Petfinder developer page.
Storing your keys received from APIs and other sensitive information in a secure file or as an environment variable is considered best practice to avoid any potential malicious activity. Therefore, we save the API and secret keys we received from Petfinder as environment variables in a specific R file named
.Renviron. If you do not have an
.Renviron file on your system, here is handy and short guide for creating one and adding environment variables for both Linux and Windows. If on a Mac, you can add the
.Renviron file in your home directory. After saving the variables and restarting R/RStudio, we can access the environment variables with the
If not already installed,
PetfindeR can be installed through the usual means:
The package can also be installed with
devtools for those wanting the most recent development version.
Once installed, we can load the library as usual:
PetfindeR is loaded, we can authenticate our connection to the API and begin extracting data! The authentication to the Petfinder API occurs when the
PetfindeR class is initialized, which requires the API and secret keys we received in the previous step as parameters.
pf variable is the initialized Petfinder class with our given API and secret key. We can now use this instance to interact with and extract data from the Petfinder API.
animal_types method allows one to get information on all or specific animal types in the Petfinder database. Animal type data includes the type’s species, color, coat and gender. Leaving the
types parameter of the method empty will return all available animal types.
We can get the names of all the animal types available in the Petfinder API by using the
Specific information for a given type can be accessed as usual:
animal_types method also accepts a single or multiple animal types.
We can access the type’s data as we did before:
Multiple specific animal types can also be passed.
Listed breeds for each animal type can be extracted using the
For brevity, let’s print the animal types and the first three breeds of each type.
Similar to the
animal_types() method, the
breeds() mehtod can accept a single or multiple animal types.
animals method can be used to perform a general search for animals based on specified criteria or returning data on specific animals based on their respective IDs. For example, let’s say we want to get 100 adoptable female cats within a 10 mile distance of Seattle, WA.
Specific animal data can also be extracted by supplying the
animal_id parameter in the
animals() method. As the search by ID is a direct search, the general search queries such as
age, and the others are overridden. As an example, we can use some of the
animal_ids returned from the
animals() method. Although Petfinder
animal_ids are integers, they can be supplied as strings.
organizations() method is similar to the
animals() method described above but is used to perform general or specific searches by ID on animal welfare organizations listed in the Petfinder database. Again, similar to the first example above, we can find animal welfare organizations in a 50 mile radius of Seattle, WA. To see all of the possible search parameters, please see the petpy documentation for the
We can also extract specific animal welfare organization data by supplying the
organizations() method with Petfinder organization IDs. When performing a direct search for organizations, the general search parameters in the method are overridden and do not need to be supplied.
Hopefully this served as a useful introduction to the basic functionality of
PetfindeR and some short examples to get started. The Petfinder database contains a wealth of adoptable animal information that is updated constantly so it is the goal of the
PetfindeR wrapper library to make extracting and interacting with this data even easier whether you’re building a web app or want to scrape the database for data analysis.