'Petfinder' API Wrapper

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.


Build Status Build status codecov

ūüźą ūüźē ūüźď ūüźá ūüźé

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.

Installation

The 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 installed
devtools::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.

Examples and Usage

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.

Authenticating

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.

Get animal breeds currently listed on Petfinder

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 breed.list method.

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)

Finding pets listed on Petfinder

The 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)

Locating animal shelters in a given location

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 data.frame.

wa.shelters <- pf$shelter.find(location = 'Seattle', count = 500, return_df = TRUE)

Available Methods

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

Documentation

About Petfinder.com

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.

News

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("PetfindeR")

2.0.0 by Aaron Schlegel, 25 days ago


https://github.com/aschleg/PetfindeR


Browse source code at https://github.com/cran/PetfindeR


Authors: Aaron Schlegel


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports R6, httr, jsonlite

Suggests testthat, knitr, rmarkdown, dplyr


See at CRAN