Wrapper of the 'Petfinder API' < https://www.petfinder.com/developers/v2/docs/> that implements methods for interacting with and extracting data from the 'Petfinder' database. The 'Petfinder REST API' allows access to the 'Petfinder' database, one of the largest online databases of adoptable animals and animal welfare organizations across North America.
🐈 🐕 🐓 🐇 🐎
PetfindeR wraps the Petfinder API in an easy-to-use, conveninent R package. The
PetfindeR library also provides handy methods for coercing the returned JSON from the API into usable
data.frame objects to facilitate data analysis and other tasks.
PetfindeR library has been submitted to CRAN for review, but in the meantime, the library can be installed using devtools.
install.packages('devtools') # if devtools is not already installeddevtools::install_github('aschleg/PetfindeR')
The latest development version can always be installed using
devtools rather than waiting for new releases to become live on CRAN.
After receiving an API key from Petfinder, usage of
PetfindeR to extract data from the Petfinder database is straightforward. Below, we demonstrate some examples on authenticating with the Petfinder API and extracting data using the available API methods.
PetfindeR is built using
R6 Classes, therefore authenticating with the Petfinder API only requires creating an object to store the authentication with a given API key as in the example below.
library(PetfindeR)pf <- Petfinder(key) # Initialize the connection with the Petfinder API.
With the authenticated object
pf created above, we can use it to extract data from the Petfinder API. To see the available breeds of a particular animal, we can use the
cats <- pf$breed.list('cat')
Most methods in the
PetfindeR package can also be set to return a
data.frame instead of the raw JSON from the API by setting the parameter
return_df = TRUE.
cats.df <- pf$breed.list('cat', return_df = TRUE)
pet.find method returns data on the currently available animals at animal shelters in the specified location. The method requires a location to be passed, which can be as granular as a zip code or as broad as a country in North America. The default amount of records returned is 25, which can be increased up to 1,000 by adjusting the
count parameter. Here we find 100 available female cats listed on the Petfinder website within the Seattle area.
sea.female.cats <- pf$pet.find(location = 'Seattle',animal = 'cat', sex = 'female', count = 100)# The `pet.find` method can also be set to return a `data.frame` for easier analysis.sea.female.cats <- pf$pet.find(location = 'Seattle',animal = 'cat', sex = 'female', count = 100, return_df = TRUE)
Similar to the
pet.find method described above, we can use the
shelter.find method to locate animal shelters in a given location. Let's say we are interested in finding 500 animal shelters in Washington State starting in Seattle. The Petfinder API will automatically expand its search for shelters in a given location once it finds all the shelters in the provided location. Therefore, specifying the search to begin in Seattle with a count of 500 will also return shelters outside of the Seattle area (as there are not 500 animal shelters in Seattle alone). The
shelter.find method, as with other methods provided by
PetfindeR, has a
return_df parameter which will automatically coerce the returned JSON results from the API into a
wa.shelters <- pf$shelter.find(location = 'Seattle', count = 500, return_df = TRUE)
The following table lists the methods for interacting with the Petfinder API.
|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.|
|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.|
Further information on the methods available in the Petfinder API can be found by checking out Petfinder's API method documentation
Petfinder.com is one of the largest online, searchable databases for finding a new pet online. The database contains information on over 14,000 animal shelters and adoption organizations across North America with nearly 300,000 animals available for adoption. Not only does this make it a great resource for those looking to adopt their new best friend, but the data and information provided in Petfinder's database makes it ideal for analysis.