Wrapper for the Petfinder API
Project description
Petpy - Python Wrapper for the Petfinder API
:cat2: :dog2: :rooster: :rabbit2: :racehorse:
Petpy is an easy-to-use and convenient Python wrapper for the Petfinder API.
Installation
petpy
is easily installed through pip
.
pip install petpy
The library can also be cloned or downloaded into a location of your choosing and then installed using the setup.py
file per the following:
git clone git@github.com:aschleg/petpy.git
cd petpy
python setup.py install
Examples and usage
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 petpy
to get started. More in-depth tutorials for petpy
and some examples of what
can be done with the library, please see the More Examples and Tutorials section below.
Authenticating with the Petfinder API
Authenticating the connection with the Petfinder API is done at the same time the Petfinder
class is initialized.
pf = Petfinder(key=key, secret=secret)
Finding animal types
# All animal types and their relevant data.
all_types = pf.animal_types()
# Returning data for a single animal type
dogs = pf.animal_types('dog')
# Getting multiple animal types at once
cat_dog_rabbit_types = pf.animal_types(['cat', 'dog', 'rabbit'])
Getting animal breeds for available animal types
cat_breeds = pf.breeds('cat')
dog_breeds = pf.breeds('dog')
# All available breeds or multiple breeds can also be returned.
all_breeds = pf.breeds()
cat_dog_rabbit = pf.breeds(types=['cat', 'dog', 'rabbit'])
The breeds
method can also be set to coerce the returned JSON results into a pandas DataFrame by setting
the parameter return_df = True
.
cat_breeds_df = pf.breeds('cat', return_df = True)
all_breeds_df = pf.breeds(return_df = True)
Finding available animals on Petfinder
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
animals = pf.animals()
# Extracting data on specific animals with animal_ids
animal_ids = []
for i in animals['animals'][0:3]:
animal_ids.append(i['id'])
animal_data = pf.animals(animal_id=animal_ids)
# Returning a pandas DataFrame of the first 150 animal results
animals = pf.animals(results_per_page=50, pages=3, return_df=True)
Getting animal welfare organizations in the Petfinder database
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 as a pandas DataFrame
organizations = pf.organizations(results_per_page=100, pages=10, return_df=True)
# Get organizations in the state of Washington
wa_organizations = pf.organizations(state='WA')
More Examples and Tutorials
A series of IPython notebooks that introduce and explore some of the functionality and possible uses of the
petpy
library. The notebooks can also be launched interactively with binder by clicking the
"launch binder" badge.
Please note the following notebook is still based on the legacy version of Petfinder and thus are not fully
representative of the functionality and methods of the most recent version of petpy
and the Petfinder API. These
are currently being updated to reflect the new version of petpy
.
Documentation
Requirements
- Python >= 3.4
- requests >= 2.18.4
- Although not strictly required to use
petpy
, the pandas library is needed for returning the results as a DataFrame.
License
MIT
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for petpy-2.0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5f4a22ac0c3f12179f7251ff156dfe334330a291574cb31dc2c6d7d5bd6ddf68 |
|
MD5 | 5db14ad3c70d2d979f395ed067f5a857 |
|
BLAKE2b-256 | ee959cca34345445d8db4de07ac110813ab5421e1a92dc1004fdf04fe8c1977a |