notebooks/01-Introduction to petpy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following post introduces the `petpy` package and its methods for interacting with the Petfinder API. The goal of the `petpy` library is to enable other users to interact with the rich data available in the Petfinder database with an easy-to-use and straightforward Python interface. Methods for coercing the resulting JSON data into [pandas DataFrame](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html) are also available to help facilitate users who are more interested in using the API for data analysis. More information on the Petfinder API itself can be found on the [API documentation page](https://www.petfinder.com/developers/v2/docs/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Table of Contents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Obtaining an API and Secret key](#api_key)\n",
    "* [Installation](#installation)\n",
    "    - [Animal Types](#types)\n",
    "    - [Extracting breeds of animals available in the Petfinder database](#breeds)\n",
    "    - [Finding animals](#animals)\n",
    "    - [Finding shelters matching search criteria](#organizations)\n",
    "* [Conclusion](#conclusion)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Obtaining an API and Secret Key <a id='api_key'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we can begin extracting data from the API, we first require an API and secret key to authenticate access. To receive an API and secret key, [create a free account with Petfinder](https://www.petfinder.com/developers/) on their developer page and request an API key.\n",
    "\n",
    "The API and secret key received from Petfinder are what we will use to authenticate our connection to the Petfinder API with `petpy`. Note authenication has a timeout of 3600 seconds, or one hour, after which the authentication to the API will need to be made again. For more information on how the Petfinder API authenication works, [visit the API documentation on the Petfinder developer page](https://www.petfinder.com/developers/v2/docs/#using-the-api).\n",
    "\n",
    "Storing your keys received from APIs and other sensitive information in a secure file or as an environment variable is considered best practice to avoid any potential malicious activity. Therefore, we save the API and secret keys we received from Petfinder as environment variables to keep our credentials safe. For Mac users, here is a good [StackOverflow question](https://apple.stackexchange.com/questions/329865/add-environment-variable-to-path) on how to set up environment variables. For Windows users, this appears to be a good website on how to [add environment variables](https://www.computerhope.com/issues/ch000549.htm) for different versions of windows. We can then access these environment variables using the `os` library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "key = os.getenv('PETFINDER_KEY')\n",
    "secret = os.getenv('PETFINDER_SECRET_KEY')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installation <a id='installation'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If not already installed, install `petpy` using `pip`:\n",
    "\n",
    "``pip install petpy``\n",
    "\n",
    "Then, import the package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import petpy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that `petpy` is imported, we can authenticate our connection to the API and begin extracting data! The authentication to the Petfinder API occurs when the `Petfinder` class is initialized, which requires the API and secret keys we received in the previous step as parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "pf = petpy.Petfinder(key=key, secret=secret)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `pf` variable is the initialized Petfinder class with our given API and secret key. We can now use this instance to interact with and extract data from the Petfinder API."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Animal Types <a id='types'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `animal_types` method allows one to get information on all or specific animal types in the Petfinder database. Animal type data includes the type's species, color, coat and gender. Leaving the `types` parameter of the method empty will return all available animal types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "animal_types = pf.animal_types()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For brevity, let's print out the names of the animal types and their coat types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Dog \n",
      " ['Hairless', 'Short', 'Medium', 'Long', 'Wire', 'Curly']\n",
      "Cat \n",
      " ['Hairless', 'Short', 'Medium', 'Long']\n",
      "Rabbit \n",
      " ['Short', 'Long']\n",
      "Small & Furry \n",
      " ['Hairless', 'Short', 'Long']\n",
      "Horse \n",
      " []\n",
      "Bird \n",
      " []\n",
      "Scales, Fins & Other \n",
      " []\n",
      "Barnyard \n",
      " ['Short', 'Long']\n"
     ]
    }
   ],
   "source": [
    "for animal in animal_types['types']:\n",
    "    print(animal['name'], '\\n', animal['coats'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `animal_types` method also accepts a single or multiple animal types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "cats = pf.animal_types('cat')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, we print the returned cat coat and colors listed in the Petfinder database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['Hairless', 'Short', 'Medium', 'Long']\n",
      "['Black', 'Black & White / Tuxedo', 'Blue Cream', 'Blue Point', 'Brown / Chocolate', 'Buff & White', 'Buff / Tan / Fawn', 'Calico', 'Chocolate Point', 'Cream / Ivory', 'Cream Point', 'Dilute Calico', 'Dilute Tortoiseshell', 'Flame Point', 'Gray & White', 'Gray / Blue / Silver', 'Lilac Point', 'Orange & White', 'Orange / Red', 'Seal Point', 'Smoke', 'Tabby (Brown / Chocolate)', 'Tabby (Buff / Tan / Fawn)', 'Tabby (Gray / Blue / Silver)', 'Tabby (Leopard / Spotted)', 'Tabby (Orange / Red)', 'Tabby (Tiger Striped)', 'Torbie', 'Tortoiseshell', 'White']\n"
     ]
    }
   ],
   "source": [
    "print(cats['type']['coats'])\n",
    "print(cats['type']['colors'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "cat_dog = pf.animal_types(['cat', 'dog'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cat \n",
      " ['Black', 'Black & White / Tuxedo', 'Blue Cream', 'Blue Point', 'Brown / Chocolate', 'Buff & White', 'Buff / Tan / Fawn', 'Calico', 'Chocolate Point', 'Cream / Ivory', 'Cream Point', 'Dilute Calico', 'Dilute Tortoiseshell', 'Flame Point', 'Gray & White', 'Gray / Blue / Silver', 'Lilac Point', 'Orange & White', 'Orange / Red', 'Seal Point', 'Smoke', 'Tabby (Brown / Chocolate)', 'Tabby (Buff / Tan / Fawn)', 'Tabby (Gray / Blue / Silver)', 'Tabby (Leopard / Spotted)', 'Tabby (Orange / Red)', 'Tabby (Tiger Striped)', 'Torbie', 'Tortoiseshell', 'White']\n",
      "Dog \n",
      " ['Apricot / Beige', 'Bicolor', 'Black', 'Brindle', 'Brown / Chocolate', 'Golden', 'Gray / Blue / Silver', 'Harlequin', 'Merle (Blue)', 'Merle (Red)', 'Red / Chestnut / Orange', 'Sable', 'Tricolor (Brown, Black, & White)', 'White / Cream', 'Yellow / Tan / Blond / Fawn']\n"
     ]
    }
   ],
   "source": [
    "for animal in cat_dog['types']:\n",
    "    print(animal['name'], '\\n', animal['colors'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Finding Available Breeds of Animal Types <a id='breeds'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Listed breeds for each animal type can be extracted using the `breeds()` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "animal_breeds = pf.breeds()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The resulting JSON (dict) object is rather long due to the amount of types, so let's print out the first three breeds of each animal type."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dog\n",
      "['Affenpinscher', 'Afghan Hound', 'Airedale Terrier']\n",
      "cat\n",
      "['Abyssinian', 'American Bobtail', 'American Curl']\n",
      "rabbit\n",
      "['American', 'American Fuzzy Lop', 'American Sable']\n",
      "small-furry\n",
      "['Abyssinian', 'Chinchilla', 'Degu']\n",
      "horse\n",
      "['Appaloosa', 'Arabian', 'Belgian']\n",
      "bird\n",
      "['African Grey', 'Amazon', 'Brotogeris']\n",
      "scales-fins-other\n",
      "['Asian Box', 'Ball Python', 'Bearded Dragon']\n",
      "barnyard\n",
      "['Alpaca', 'Alpine', 'Angora']\n"
     ]
    }
   ],
   "source": [
    "for breed in animal_breeds['breeds']:\n",
    "    print(breed)\n",
    "    print(animal_breeds['breeds'][breed][0:3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For those who prefer a tabular output, setting the `return_df` parameter to `True` will return a pandas DataFrame instead of a dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>breed</th>\n",
       "      <th>name</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Dog</td>\n",
       "      <td>Affenpinscher</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Dog</td>\n",
       "      <td>Afghan Hound</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Dog</td>\n",
       "      <td>Airedale Terrier</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Cat</td>\n",
       "      <td>Abyssinian</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Cat</td>\n",
       "      <td>American Bobtail</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Cat</td>\n",
       "      <td>American Curl</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Rabbit</td>\n",
       "      <td>American</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Rabbit</td>\n",
       "      <td>American Fuzzy Lop</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Rabbit</td>\n",
       "      <td>American Sable</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Small-furry</td>\n",
       "      <td>Abyssinian</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Small-furry</td>\n",
       "      <td>Chinchilla</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Small-furry</td>\n",
       "      <td>Degu</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Horse</td>\n",
       "      <td>Appaloosa</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Horse</td>\n",
       "      <td>Arabian</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Horse</td>\n",
       "      <td>Belgian</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Bird</td>\n",
       "      <td>African Grey</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Bird</td>\n",
       "      <td>Amazon</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Bird</td>\n",
       "      <td>Brotogeris</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Scales-fins-other</td>\n",
       "      <td>Asian Box</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Scales-fins-other</td>\n",
       "      <td>Ball Python</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Scales-fins-other</td>\n",
       "      <td>Bearded Dragon</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Barnyard</td>\n",
       "      <td>Alpaca</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Barnyard</td>\n",
       "      <td>Alpine</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Barnyard</td>\n",
       "      <td>Angora</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "               breed                name\n",
       "0                Dog       Affenpinscher\n",
       "1                Dog        Afghan Hound\n",
       "2                Dog    Airedale Terrier\n",
       "0                Cat          Abyssinian\n",
       "1                Cat    American Bobtail\n",
       "2                Cat       American Curl\n",
       "0             Rabbit            American\n",
       "1             Rabbit  American Fuzzy Lop\n",
       "2             Rabbit      American Sable\n",
       "0        Small-furry          Abyssinian\n",
       "1        Small-furry          Chinchilla\n",
       "2        Small-furry                Degu\n",
       "0              Horse           Appaloosa\n",
       "1              Horse             Arabian\n",
       "2              Horse             Belgian\n",
       "0               Bird        African Grey\n",
       "1               Bird              Amazon\n",
       "2               Bird          Brotogeris\n",
       "0  Scales-fins-other           Asian Box\n",
       "1  Scales-fins-other         Ball Python\n",
       "2  Scales-fins-other      Bearded Dragon\n",
       "0           Barnyard              Alpaca\n",
       "1           Barnyard              Alpine\n",
       "2           Barnyard              Angora"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "animal_breeds_df = pf.breeds(return_df=True)\n",
    "animal_breeds_df.groupby('breed').head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to the `animal_types` method described above, the `breeds()` method can accept a single or multiple animal types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "ename": "KeyError",
     "evalue": "'types'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mKeyError\u001b[0m                                  Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-13-5ba120c07ab5>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mcat_breeds\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mpf\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mbreeds\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'cat'\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mreturn_df\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mTrue\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      2\u001b[0m \u001b[0mcat_breeds\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mhead\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m/anaconda3/lib/python3.7/site-packages/petpy/api.py\u001b[0m in \u001b[0;36mbreeds\u001b[0;34m(self, types, return_df, raw_results)\u001b[0m\n\u001b[1;32m    248\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    249\u001b[0m             \u001b[0mresult\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mr\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mjson\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 250\u001b[0;31m             \u001b[0mresult\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m'type'\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mresult\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mpop\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'types'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    251\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    252\u001b[0m         \u001b[0;32melse\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mKeyError\u001b[0m: 'types'"
     ]
    }
   ],
   "source": [
    "cat_breeds = pf.breeds('cat', return_df=True)\n",
    "cat_breeds.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cat_rabbit = pf.breeds(['cat', 'rabbit'], return_df=True)\n",
    "cat_rabbit.groupby('breed').head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Search for animals in the Petfinder database <a id='animals'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `animals` method can be used to perform a general search for animals based on specified criteria or returning data on specific animals based on their respective IDs. For example, let's say we want to get 100 adoptable female cats within a 10 mile distance of Seattle, WA. For all possible search query parameters, please see the [petpy documentation for the `animals()` method](https://petpy.readthedocs.io/en/latest/api.html#find-listed-animals-on-petfinder)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cats = pf.animals(animal_type='cat', gender='female', status='adoptable', location='Seattle, WA', distance=10,\n",
    "                  results_per_page=50, pages=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `animals()` method can also return a pandas DataFrame if the parameter `return_df` is set to `True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cats_df = pf.animals(animal_type='cat', gender='female', status='adoptable', location='Seattle, WA', distance=10, \n",
    "                     results_per_page=50, pages=2, return_df=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the `pages` parameter is set to `None`, all matching results from the Petfinder database will be extracted. The `pages` parameter defaults to `1`, therefore it must be explictly set to `None`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "cats_df_all_results = pf.animals(animal_type='cat', gender='female', status='adoptable', \n",
    "                                 location='Seattle, WA', distance=10, pages=None, return_df=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(432, 41)"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cats_df_all_results.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Specific animal data can also be extracted by supplying the `animal_id` parameter in the `animals()` method. As the search by ID is a direct search, the general search queries such as `gender`, `age`, and the others are overridden. As an example, we can use some of the `animal_ids` returned from the `animals()` method. Although Petfinder `animal_ids` are integers, they can be supplied as strings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "cat_ids = pf.animals(animal_id=[45325908, '45325906'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Finding animal welfare organizations <a id='organizations'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `organizations()` method is similar to the `animals()` method described above but is used to perform general or specific searches by ID on animal welfare organizations listed in the Petfinder database. Again, similar to the first example above, we can find animal welfare organizations in a 50 mile radius of Seattle, WA. To see all of the possible search parameters, please see the [petpy documentation for the `organizations()` method](https://petpy.readthedocs.io/en/latest/api.html#get-animal-welfare-organization-data)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(126, 29)"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "wa_orgs = pf.organizations(location='Seattle, WA', distance=50, sort='distance', pages=None, return_df=True)\n",
    "wa_orgs.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also extract specific animal welfare organization data by supplying the `organizations()` method with Petfinder organization IDs. Fortunately, we have some we can use from the previous call to the `organizations()` method! Since we are directly searching for organizations, the general search parameters in the method are overridden and do not need to be supplied."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>organization_id</th>\n",
       "      <th>address.address1</th>\n",
       "      <th>address.address2</th>\n",
       "      <th>address.city</th>\n",
       "      <th>address.country</th>\n",
       "      <th>address.postcode</th>\n",
       "      <th>address.state</th>\n",
       "      <th>adoption.policy</th>\n",
       "      <th>adoption.url</th>\n",
       "      <th>email</th>\n",
       "      <th>...</th>\n",
       "      <th>name</th>\n",
       "      <th>phone</th>\n",
       "      <th>photos</th>\n",
       "      <th>social_media.facebook</th>\n",
       "      <th>social_media.instagram</th>\n",
       "      <th>social_media.pinterest</th>\n",
       "      <th>social_media.twitter</th>\n",
       "      <th>social_media.youtube</th>\n",
       "      <th>url</th>\n",
       "      <th>website</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>wa575</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>Seattle</td>\n",
       "      <td>US</td>\n",
       "      <td>98104</td>\n",
       "      <td>WA</td>\n",
       "      <td>1.  Visit http://www.royalhounds.org\\r\\n\\r\\n2....</td>\n",
       "      <td>http://www.royalhounds.org/adoption-applicatio...</td>\n",
       "      <td>info@royalhounds.org</td>\n",
       "      <td>...</td>\n",
       "      <td>Royal Hounds Greyhound Adoption</td>\n",
       "      <td>None</td>\n",
       "      <td>[{'small': 'https://s3.amazonaws.com/petfinder...</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>https://www.petfinder.com/member/us/wa/seattle...</td>\n",
       "      <td>http://royalhounds.org/</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>wa500</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>Seattle</td>\n",
       "      <td>US</td>\n",
       "      <td>98121</td>\n",
       "      <td>WA</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>alleycatproject206@gmail.com</td>\n",
       "      <td>...</td>\n",
       "      <td>Alley Cat Project</td>\n",
       "      <td>(206) 745-0243</td>\n",
       "      <td>[]</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>https://www.petfinder.com/member/us/wa/seattle...</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>wa266</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>Seattle</td>\n",
       "      <td>US</td>\n",
       "      <td>98122</td>\n",
       "      <td>WA</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>info@bullseyerescue.org</td>\n",
       "      <td>...</td>\n",
       "      <td>BullsEye Dog Rescue</td>\n",
       "      <td></td>\n",
       "      <td>[]</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>None</td>\n",
       "      <td>https://www.petfinder.com/member/us/wa/seattle...</td>\n",
       "      <td>None</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>3 rows × 29 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "  organization_id address.address1 address.address2 address.city  \\\n",
       "0           wa575             None             None      Seattle   \n",
       "1           wa500             None             None      Seattle   \n",
       "2           wa266             None             None      Seattle   \n",
       "\n",
       "  address.country address.postcode address.state  \\\n",
       "0              US            98104            WA   \n",
       "1              US            98121            WA   \n",
       "2              US            98122            WA   \n",
       "\n",
       "                                     adoption.policy  \\\n",
       "0  1.  Visit http://www.royalhounds.org\\r\\n\\r\\n2....   \n",
       "1                                               None   \n",
       "2                                               None   \n",
       "\n",
       "                                        adoption.url  \\\n",
       "0  http://www.royalhounds.org/adoption-applicatio...   \n",
       "1                                               None   \n",
       "2                                               None   \n",
       "\n",
       "                          email  ...                             name  \\\n",
       "0          info@royalhounds.org  ...  Royal Hounds Greyhound Adoption   \n",
       "1  alleycatproject206@gmail.com  ...                Alley Cat Project   \n",
       "2       info@bullseyerescue.org  ...              BullsEye Dog Rescue   \n",
       "\n",
       "            phone                                             photos  \\\n",
       "0            None  [{'small': 'https://s3.amazonaws.com/petfinder...   \n",
       "1  (206) 745-0243                                                 []   \n",
       "2                                                                 []   \n",
       "\n",
       "  social_media.facebook social_media.instagram social_media.pinterest  \\\n",
       "0                  None                   None                   None   \n",
       "1                  None                   None                   None   \n",
       "2                  None                   None                   None   \n",
       "\n",
       "  social_media.twitter social_media.youtube  \\\n",
       "0                 None                 None   \n",
       "1                 None                 None   \n",
       "2                 None                 None   \n",
       "\n",
       "                                                 url                  website  \n",
       "0  https://www.petfinder.com/member/us/wa/seattle...  http://royalhounds.org/  \n",
       "1  https://www.petfinder.com/member/us/wa/seattle...                     None  \n",
       "2  https://www.petfinder.com/member/us/wa/seattle...                     None  \n",
       "\n",
       "[3 rows x 29 columns]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "wa_some_orgs = pf.organizations(organization_id=wa_orgs['organization_id'][0:3].tolist(), return_df=True)\n",
    "wa_some_orgs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Conclusion <a id='conclusion'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Hopefully this served as a useful introduction to the basic functionality of `petpy` and some short examples to get started. The Petfinder database contains a wealth of adoptable animal information that is updated constantly so it is the goal of the `petpy` wrapper library to make extracting and interacting with this data even easier whether you're building a web app or want to scrape the database for data analysis."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}