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 post 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
At the time of this writing, PetfindeR has been submitted to CRAN but
and is currently in the review process. In the meantime, the package can
be easily installed through the devtools package function install_github().
devtools::install_github('aschleg/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
## $`@encoding`
## [1] "iso-8859-1"
##
## $`@version`
## [1] "1.0"
##
## $petfinder
## $petfinder$`@xmlns:xsi`
## [1] "http://www.w3.org/2001/XMLSchema-instance"
##
## $petfinder$breeds
## $petfinder$breeds$breed
## $t
## 1 Abyssinian
## 2 American Curl
## 3 American Shorthair
## 4 American Wirehair
## 5 Applehead Siamese
## 6 Balinese
## 7 Bengal
## 8 Birman
## 9 Bobtail
## 10 Bombay
## 11 British Shorthair
## 12 Burmese
## 13 Burmilla
## 14 Calico
## 15 Canadian Hairless
## 16 Chartreux
## 17 Chausie
## 18 Chinchilla
## 19 Cornish Rex
## 20 Cymric
## 21 Devon Rex
## 22 Dilute Calico
## 23 Dilute Tortoiseshell
## 24 Domestic Long Hair
## 25 Domestic Medium Hair
## 26 Domestic Short Hair
## 27 Egyptian Mau
## 28 Exotic Shorthair
## 29 Extra-Toes Cat / Hemingway Polydactyl
## 30 Havana
## 31 Himalayan
## 32 Japanese Bobtail
## 33 Javanese
## 34 Korat
## 35 LaPerm
## 36 Maine Coon
## 37 Manx
## 38 Munchkin
## 39 Nebelung
## 40 Norwegian Forest Cat
## 41 Ocicat
## 42 Oriental Long Hair
## 43 Oriental Short Hair
## 44 Oriental Tabby
## 45 Persian
## 46 Pixie-Bob
## 47 Ragamuffin
## 48 Ragdoll
## 49 Russian Blue
## 50 Scottish Fold
## 51 Selkirk Rex
## 52 Siamese
## 53 Siberian
## 54 Silver
## 55 Singapura
## 56 Snowshoe
## 57 Somali
## 58 Sphynx / Hairless Cat
## 59 Tabby
## 60 Tiger
## 61 Tonkinese
## 62 Torbie
## 63 Tortoiseshell
## 64 Turkish Angora
## 65 Turkish Van
## 66 Tuxedo
##
## $petfinder$breeds$`@animal`
## [1] "cat"
##
##
## $petfinder$header
## $petfinder$header$timestamp
## $petfinder$header$timestamp$`$t`
## [1] "2018-05-13T21:53:18Z"
##
##
## $petfinder$header$status
## $petfinder$header$status$message
## named list()
##
## $petfinder$header$status$code
## $petfinder$header$status$code$`$t`
## [1] "100"
##
##
##
## $petfinder$header$version
## $petfinder$header$version$`$t`
## [1] "0.1"
##
##
##
## $petfinder$`@xsi:noNamespaceSchemaLocation`
## [1] "http://api.petfinder.com/schemas/0.9/petfinder.xsd"
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)
## cat.breeds
## 1 Abyssinian
## 2 American Curl
## 3 American Shorthair
## 4 American Wirehair
## 5 Applehead Siamese
## 6 Balinese
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])
## status contact.phone contact.state contact.email
## 1 A 206-296-7387 WA adoptapet@kingcounty.gov
## 2 A 206-296-7387 WA adoptapet@kingcounty.gov
## 3 A 425-576-5548 WA info@thewhole-cat.com
## 4 A 425-576-5548 WA info@thewhole-cat.com
## 5 A <NA> WA rescuinganimals@gmail.com
## 6 A (253) 856-1771 WA anotherchancecats2007@gmail.com
## contact.city contact.zip contact.address1 age size id
## 1 Kent 98032 21615 64th Ave S Senior M 39921493
## 2 Kent 98032 21615 64th Ave S Adult L 37949653
## 3 Redmond 98052 8103 161st Ave NE Senior L 40688475
## 4 Redmond 98052 8103 161st Ave NE Senior M 41470264
## 5 Federal Way 98023 <NA> Adult M 41589923
## 6 Des Moines 98198 PO Box 13244 Young M 39650811
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')
## $`@encoding`
## [1] "iso-8859-1"
##
## $`@version`
## [1] "1.0"
##
## $petfinder
## $petfinder$pet
## $petfinder$pet$options
## $petfinder$pet$options$option
## $t
## 1 altered
## 2 hasShots
## 3 housetrained
## 4 noDogs
## 5 noCats
## 6 noKids
##
##
## $petfinder$pet$status
## $petfinder$pet$status$`$t`
## [1] "A"
##
##
## $petfinder$pet$contact
## $petfinder$pet$contact$phone
## $petfinder$pet$contact$phone$`$t`
## [1] "717-831-5010"
##
##
## $petfinder$pet$contact$state
## $petfinder$pet$contact$state$`$t`
## [1] "PA"
##
##
## $petfinder$pet$contact$address2
## named list()
##
## $petfinder$pet$contact$email
## $petfinder$pet$contact$email$`$t`
## [1] "info@castawaycritters.org"
##
##
## $petfinder$pet$contact$city
## $petfinder$pet$contact$city$`$t`
## [1] "Harrisburg"
##
##
## $petfinder$pet$contact$zip
## $petfinder$pet$contact$zip$`$t`
## [1] "17105"
##
##
## $petfinder$pet$contact$fax
## named list()
##
## $petfinder$pet$contact$address1
## $petfinder$pet$contact$address1$`$t`
## [1] "P.O. Box 1421"
##
##
##
## $petfinder$pet$age
## $petfinder$pet$age$`$t`
## [1] "Adult"
##
##
## $petfinder$pet$size
## $petfinder$pet$size$`$t`
## [1] "M"
##
##
## $petfinder$pet$media
## $petfinder$pet$media$photos
## $petfinder$pet$media$photos$photo
## @size
## 1 pnt
## 2 fpm
## 3 x
## 4 pn
## 5 t
## 6 pnt
## 7 fpm
## 8 x
## 9 pn
## 10 t
## 11 pnt
## 12 fpm
## 13 x
## 14 pn
## 15 t
## $t
## 1 http://photos.petfinder.com/photos/pets/35679386/1/?bust=1488734507&width=60&-pnt.jpg
## 2 http://photos.petfinder.com/photos/pets/35679386/1/?bust=1488734507&width=95&-fpm.jpg
## 3 http://photos.petfinder.com/photos/pets/35679386/1/?bust=1488734507&width=500&-x.jpg
## 4 http://photos.petfinder.com/photos/pets/35679386/1/?bust=1488734507&width=300&-pn.jpg
## 5 http://photos.petfinder.com/photos/pets/35679386/1/?bust=1488734507&width=50&-t.jpg
## 6 http://photos.petfinder.com/photos/pets/35679386/2/?bust=1488734507&width=60&-pnt.jpg
## 7 http://photos.petfinder.com/photos/pets/35679386/2/?bust=1488734507&width=95&-fpm.jpg
## 8 http://photos.petfinder.com/photos/pets/35679386/2/?bust=1488734507&width=500&-x.jpg
## 9 http://photos.petfinder.com/photos/pets/35679386/2/?bust=1488734507&width=300&-pn.jpg
## 10 http://photos.petfinder.com/photos/pets/35679386/2/?bust=1488734507&width=50&-t.jpg
## 11 http://photos.petfinder.com/photos/pets/35679386/3/?bust=1477877892&width=60&-pnt.jpg
## 12 http://photos.petfinder.com/photos/pets/35679386/3/?bust=1477877892&width=95&-fpm.jpg
## 13 http://photos.petfinder.com/photos/pets/35679386/3/?bust=1477877892&width=500&-x.jpg
## 14 http://photos.petfinder.com/photos/pets/35679386/3/?bust=1477877892&width=300&-pn.jpg
## 15 http://photos.petfinder.com/photos/pets/35679386/3/?bust=1477877892&width=50&-t.jpg
## @id
## 1 1
## 2 1
## 3 1
## 4 1
## 5 1
## 6 2
## 7 2
## 8 2
## 9 2
## 10 2
## 11 3
## 12 3
## 13 3
## 14 3
## 15 3
##
##
##
## $petfinder$pet$id
## $petfinder$pet$id$`$t`
## [1] "35679386"
##
##
## $petfinder$pet$shelterPetId
## $petfinder$pet$shelterPetId$`$t`
## [1] "1732589-CC-11179"
##
##
## $petfinder$pet$breeds
## $petfinder$pet$breeds$breed
## $t
## 1 Beagle
## 2 Jack Russell Terrier
##
##
## $petfinder$pet$name
## $petfinder$pet$name$`$t`
## [1] "Duke- *ADOPTION SPECIAL*"
##
##
## $petfinder$pet$sex
## $petfinder$pet$sex$`$t`
## [1] "M"
##
##
## $petfinder$pet$description
## $petfinder$pet$description$`$t`
## [1] "You can fill out an adoption application online on our official website.Please contact Jamie (ccjamieballa@gmail.com) for more information about this pet.Hello my name is Duke! I really would love a forever home. I love to run and play so a fenced yard would be so fun! I do well on walks and don't pull on my leash.I really love being the center of attention so I prefer to live without other animals. We are still trying out how well I do with children.I am potty trained, well mannered, crate trained. A super loving pup who is quiet, timid with loud noises and knows sit and stay. I travel great in the car.I would make a great running companion or might even do pretty well in Agility training. I would love to be a part of my very own family. Could that be you??Duke is in foster care so please complete an application before meeting him. Completing an application does not obligate you to adopt; however, it is required. Applications are processed in the order received in an effort to find the best match possible for both the dog and the adopter.*Duke has an adoption special right now. His adoption fee is only $150. If you feel you are the right home for Duke please fill out an app! 5/12/18 5:11 PM"
##
##
## $petfinder$pet$mix
## $petfinder$pet$mix$`$t`
## [1] "yes"
##
##
## $petfinder$pet$shelterId
## $petfinder$pet$shelterId$`$t`
## [1] "PA224"
##
##
## $petfinder$pet$lastUpdate
## $petfinder$pet$lastUpdate$`$t`
## [1] "2016-07-15T21:28:15Z"
##
##
## $petfinder$pet$animal
## $petfinder$pet$animal$`$t`
## [1] "Dog"
##
##
##
## $petfinder$`@xmlns:xsi`
## [1] "http://www.w3.org/2001/XMLSchema-instance"
##
## $petfinder$header
## $petfinder$header$timestamp
## $petfinder$header$timestamp$`$t`
## [1] "2018-05-13T21:53:20Z"
##
##
## $petfinder$header$status
## $petfinder$header$status$message
## named list()
##
## $petfinder$header$status$code
## $petfinder$header$status$code$`$t`
## [1] "100"
##
##
##
## $petfinder$header$version
## $petfinder$header$version$`$t`
## [1] "0.1"
##
##
##
## $petfinder$`@xsi:noNamespaceSchemaLocation`
## [1] "http://api.petfinder.com/schemas/0.9/petfinder.xsd"
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]
## status.1 status.2 status.3 status address1.state
## 1 altered hasShots housetrained A MA
## 2 <NA> <NA> <NA> A TX
## 3 altered hasShots housetrained A MI
## address1.email address1.city address1.zip age
## 1 Info@AhimsaHaven.org Templeton 01468 Adult
## 2 animal.customerservice@austintexas.gov Austin 78702 Adult
## 3 kelcruiser@aol.com Macomb 48042 Adult
## size
## 1 L
## 2 XL
## 3 M
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]
## status.1 status.2 status.3 status address1.state
## 1 altered hasShots housetrained A MA
## 2 <NA> <NA> <NA> A TX
## 3 altered hasShots housetrained A MI
## address1.email address1.city address1.zip age
## 1 Info@AhimsaHaven.org Templeton 01468 Adult
## 2 animal.customerservice@austintexas.gov Austin 78702 Adult
## 3 kelcruiser@aol.com Macomb 48042 Adult
## size
## 1 L
## 2 XL
## 3 M
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)
## country.$t longitude.$t name.$t
## 1 US -122.2939 Forgotten Dogs Rescue
## 2 US -122.2939 Fox Terrier Fanciers of Puget Sound Rescue
## 3 US -122.2939 Little Blessings Rescue
## 4 US -122.3004 Dog Gone Seattle
## 5 US -122.3005 Friends of the Animals Foundation
## 6 US -122.3005 Pacific Northwest KUVASZ Rescue
## phone.$t state.$t email.$t
## 1 <NA> WA forgotten.dogs.rescue@gmail.com
## 2 360-733-5735 WA kmartin44@earthlink.net
## 3 206473-1111 WA adoptions@littleblessingsrescue.vpweb.com
## 4 <NA> WA adopt@doggoneseattle.org
## 5 (206) 719-4864 WA info@fafseattle.org
## 6 <NA> WA vicki@AnimalsReign.com
## city.$t zip.$t latitude.$t id.$t address1.$t
## 1 Seattle 98115 47.6831 WA368 <NA>
## 2 Seattle 98115 47.6831 WA58 <NA>
## 3 Seattle 98115 47.6831 WA620 <NA>
## 4 Seattle 98165 47.7161 WA650 <NA>
## 5 Seattle 98125 47.7165 WA77 P.O. Box 16308
## 6 Seattle 98125 47.7165 WA90 <NA>
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)
## country longitude name
## 1 US -122.2939 Forgotten Dogs Rescue
## 2 US -122.2939 Fox Terrier Fanciers of Puget Sound Rescue
## 3 US -122.2939 Little Blessings Rescue
## 4 US -122.3004 Dog Gone Seattle
## 5 US -122.3005 Friends of the Animals Foundation
## 6 US -122.3005 Pacific Northwest KUVASZ Rescue
## phone shelterate email
## 1 <NA> WA forgotten.dogs.rescue@gmail.com
## 2 360-733-5735 WA kmartin44@earthlink.net
## 3 206473-1111 WA adoptions@littleblessingsrescue.vpweb.com
## 4 <NA> WA adopt@doggoneseattle.org
## 5 (206) 719-4864 WA info@fafseattle.org
## 6 <NA> WA vicki@AnimalsReign.com
## city zip latitude id address1
## 1 Seattle 98115 47.6831 WA368 <NA>
## 2 Seattle 98115 47.6831 WA58 <NA>
## 3 Seattle 98115 47.6831 WA620 <NA>
## 4 Seattle 98165 47.7161 WA650 <NA>
## 5 Seattle 98125 47.7165 WA77 P.O. Box 16308
## 6 Seattle 98125 47.7165 WA90 <NA>
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
## $`@encoding`
## [1] "iso-8859-1"
##
## $`@version`
## [1] "1.0"
##
## $petfinder
## $petfinder$`@xmlns:xsi`
## [1] "http://www.w3.org/2001/XMLSchema-instance"
##
## $petfinder$shelter
## $petfinder$shelter$country
## $petfinder$shelter$country$`$t`
## [1] "US"
##
##
## $petfinder$shelter$longitude
## $petfinder$shelter$longitude$`$t`
## [1] "-122.3428"
##
##
## $petfinder$shelter$name
## $petfinder$shelter$name$`$t`
## [1] "Seattle Area Feline Rescue"
##
##
## $petfinder$shelter$phone
## $petfinder$shelter$phone$`$t`
## [1] "206-659-6220 "
##
##
## $petfinder$shelter$state
## $petfinder$shelter$state$`$t`
## [1] "WA"
##
##
## $petfinder$shelter$address2
## named list()
##
## $petfinder$shelter$email
## $petfinder$shelter$email$`$t`
## [1] "adoptions@seattleareafelinerescue.org"
##
##
## $petfinder$shelter$city
## $petfinder$shelter$city$`$t`
## [1] "Shoreline"
##
##
## $petfinder$shelter$zip
## $petfinder$shelter$zip$`$t`
## [1] "98133"
##
##
## $petfinder$shelter$fax
## named list()
##
## $petfinder$shelter$latitude
## $petfinder$shelter$latitude$`$t`
## [1] "47.7382"
##
##
## $petfinder$shelter$id
## $petfinder$shelter$id$`$t`
## [1] "WA40"
##
##
## $petfinder$shelter$address1
## $petfinder$shelter$address1$`$t`
## [1] "14717 Aurora Ave N"
##
##
##
## $petfinder$header
## $petfinder$header$timestamp
## $petfinder$header$timestamp$`$t`
## [1] "2018-05-13T21:53:24Z"
##
##
## $petfinder$header$status
## $petfinder$header$status$message
## named list()
##
## $petfinder$header$status$code
## $petfinder$header$status$code$`$t`
## [1] "100"
##
##
##
## $petfinder$header$version
## $petfinder$header$version$`$t`
## [1] "0.1"
##
##
##
## $petfinder$`@xsi:noNamespaceSchemaLocation`
## [1] "http://api.petfinder.com/schemas/0.9/petfinder.xsd"
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
## country longitude name phone state
## 1 US -122.3428 Seattle Area Feline Rescue 206-659-6220 WA
## address2 email city zip fax
## 1 NA adoptions@seattleareafelinerescue.org Shoreline 98133 NA
## latitude id address1
## 1 47.7382 WA40 14717 Aurora Ave N
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]
## options.option status.$t contact.phone.$t
## 1 altered, hasShots, housetrained A 206-659-6220
## 2 NULL A 206-659-6220
## 3 altered, housetrained A 206-659-6220
## 4 altered, housetrained, noKids A 206-659-6220
## 5 altered, housetrained, noCats, noKids A 206-659-6220
## 6 altered, housetrained, noKids A 206-659-6220
## contact.state.$t contact.email.$t contact.city.$t
## 1 WA adoptions@seattleareafelinerescue.org Shoreline
## 2 WA adoptions@seattleareafelinerescue.org Shoreline
## 3 WA adoptions@seattleareafelinerescue.org Shoreline
## 4 WA adoptions@seattleareafelinerescue.org Shoreline
## 5 WA adoptions@seattleareafelinerescue.org Shoreline
## 6 WA adoptions@seattleareafelinerescue.org Shoreline
## contact.zip.$t contact.address1.$t age.$t size.$t
## 1 98133 14717 Aurora Ave N Adult L
## 2 98133 14717 Aurora Ave N Baby M
## 3 98133 14717 Aurora Ave N Senior L
## 4 98133 14717 Aurora Ave N Senior L
## 5 98133 14717 Aurora Ave N Adult M
## 6 98133 14717 Aurora Ave N Adult M
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]
## status contact.phone contact.state contact.email
## 1 A 206-659-6220 WA adoptions@seattleareafelinerescue.org
## 2 A 206-659-6220 WA adoptions@seattleareafelinerescue.org
## 3 A 206-659-6220 WA adoptions@seattleareafelinerescue.org
## 4 A 206-659-6220 WA adoptions@seattleareafelinerescue.org
## 5 A 206-659-6220 WA adoptions@seattleareafelinerescue.org
## 6 A 206-659-6220 WA adoptions@seattleareafelinerescue.org
## contact.city contact.zip contact.address1 age size id
## 1 Shoreline 98133 14717 Aurora Ave N Adult L 6481751
## 2 Shoreline 98133 14717 Aurora Ave N Baby M 6497950
## 3 Shoreline 98133 14717 Aurora Ave N Senior L 38016564
## 4 Shoreline 98133 14717 Aurora Ave N Senior L 40493265
## 5 Shoreline 98133 14717 Aurora Ave N Adult M 40674254
## 6 Shoreline 98133 14717 Aurora Ave N Adult M 40977444
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.