:cat2: :dog2: :rooster: :rabbit2: :racehorse:
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
is best installed with devtools
to get the most recent production version.
install.packages('devtools') # if devtools is not already installed
::install_github('aschleg/PetfindeR') devtools
PetfindeR
can also be installed from CRAN using
install.packages()
:
install.packages('PetfindeR')
Please note the version on CRAN may be behind the most recent version on GitHub. I apologize for any confusion or inconvenience; however, submitting the package to CRAN can often be delayed due to reviews and other submission steps.
An account must first be created with Petfinder to receive an
API and secret key. The API and secret key will be used to grant access
to the Petfinder API, which lasts for 3600 seconds, or one hour. After
the authentication period ends, you must re-authenticate with the
Petfinder API. The following are some quick examples for using
PetfindeR
to get started. More in-depth tutorials for
PetfindeR
and some examples of what can be done with the
library, please see the More Examples and Tutorials section below.
Authenticating the connection with the Petfinder API is done at the
same time the Petfinder
class is initialized.
= Petfinder(key=key, secret=secret) pf
# All animal types and their relevant data.
= pf$animal_types()
all_types
# Returning data for a single animal type
= pf$animal_types('dog')
dogs
# Getting multiple animal types at once
= pf$animal_types(c('cat', 'dog', 'rabbit')) cat_dog_rabbit_types
= pf$breeds('cat')
cat_breeds = pf$breeds('dog')
dog_breeds
# All available breeds or multiple breeds can also be returned.
= pf$breeds()
all_breeds = pf$breeds(types=c('cat', 'dog', 'rabbit')) cat_dog_rabbit
The animals()
method returns animals based on specified
criteria that are listed in the Petfinder database. Specific animals can
be searched using the animal_id
parameter, or a search of
the database can be performed by entering the desired search
criteria.
# Getting first 20 results without any search criteria
= pf$animals()
animals
= pf$animals(animal_type = 'cat', gender = 'female', status = 'adoptable',
cats location = 'Seattle, WA', distance = 10, results_per_page = 50, pages = 2)
Similar to the animals()
method described above, the
organizations()
method returns data on animal welfare
organizations listed in the Petfinder database based on specific
criteria, if any. In addition to a general search of animal welfare
organizations, specific organizational data can be extracted by
supplying the organizations()
method with organization
IDs.
# Return the first 1,000 animal welfare organizations
= pf$organizations(results_per_page = 100, pages = 10)
organizations
# Get organizations in the state of Washington
= pf$organizations(state='WA') wa_organizations
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.