Petfinder Listings

Description

Petfinder is a free site where shelters and rescues can post pets for adoption. The Petfinder Listings plugin takes advantage of the Petfinder API and can be integrated into your site without coding. All you need is your Petfinder shelter id and free Petfinder API v2.0 API key and secret.

The Petfinder Listings plugin allows you to:

  1. Display all pets listed with your shelter on Petfinder
  2. Display a featured or random pet in a widget

Sign up to be notified when the Petfinder plugin is updated

You can sign up to receive notices when this plugin is updated or other important changes here: (https://unboxinteractive.com/petfinder-plugin-email-list/)

Demos

Midwest Italian Greyhound Rescue lists available pets from different shelters on one site.

Shortcode

[shelter_list] displays a list of pets from your shelter. You must enter your shelter ID, Petfinder v2.0 API key and secret on the Petfinder Listings’ settings page for this shortcode to work. You may also need to edit your Petfinder settings to enable sharing your data with third parties. See Petfinder settings under Frequently Asked Questions below.
Optional attributes for shortcode are:

  • shelter_id – Allows you to list adoptable pets from a shelter different from the shelter id defined in your Petfinder Listings Settings.

  • animal – Type of animal. Value should be one of the following or blank/don’t set to get all: Dog, Cat, Rabbit, Small & Furry, Horse, Bird, Scales, Fins & Other, Barnyard.

  • breed – If you wish to list only one breed on a page, leave blank/don’t set to get all. Note: adding ! before breed to exclude breeds was removed when updated plugin to support Petfinder API v2.0 in plugin version 1.0.13.

Example:
[shelter_list breed=”Italian Greyhound”] – other breeds are not matched

  • count – The maximum number of pets to return. Defaults to 75 and must be a number. Petfinder API v2.0 added ability to filter before retrieving results so you can set the count to the real number you want to list on the page now.

  • include_info – Value should be set to “yes” or “no”; default is “yes”. If set to “yes”, Breeds, Spayed/Neutered, Up-to-date with routine shots, Housebroken, kid safe, cat safe, dog safe, special needs are displayed in list below photo thumbnails. Each list item has a different CSS class so you can hide any you do not want to show.

  • css_class – Set your own class name on div containing all pets. The default value is ‘pets’. This allows you to control the styles separately on different pages.

  • contact – For Petfinder API v1.0 ONLY: Default is blank. If set to a value, will only list animals with this contact. Contact should be set to first and last name of Contact Person in the Petfinder Contact/Location box for each animal. Does not work with plugin after version 1.0.13 when updated to support Petfinder API v2.0.

  • status – Values can be: A=adoptable, H=hold, P=pending, X=adopted/removed. For Petfinder API v2.0 ONLY (when Petfinder API Key and Secret v2.0 are set): New status of ‘found’ was added. A, H, P = adoptable. X = adopted. (H=hold and P=pending were removed as options. Use v1.0 values: A,H,P,X for backwards compatibility, and can add ‘found’ if using v2.0.

  • sort_by – Value can be: newest, last_updated or name. Value can also be set globally in Petfinder Settings.

  • petfinder_down_message – For Petfinder API v1.0 ONLY: Set a message that displays when Petfinder is down. Example: petfinder_down_message=’Petfinder is down at the moment. Please try to view our pets on our Petfinder page Here‘ NOTE: you can’t use the same type of quote marks to quote the value and any HTML in the string.

Example using all attributes: [shelter_list shelter_id=”WI185″ breed=”Italian Greyhound” count=75 animal=”Dog” include_info=”no” css_class=”igs” status=”A” sort_by=”newest” petfinder_down_message=”Please check on Petfinder” contact=”Barb Smith”]

You can also list a single pet with the following shortcode
[get_pet pet_id=”numeric value”]

  • pet_id – Required. You can get this id from the pet’s Petfinder URL. URL will look like the following: https://www.petfinder.com/dog/nanook-45732995/mo/kansas-city/missouri-kansas-ig-rescue-mo306/?referrer_id=cca97ef9-e23d-4d0b-b29d-52afa8f7d70e – 45732995 is the pet id.

  • css_class – Set your own class name on div containing single pet. The default value is ‘pets’. This allows you to control the styles separately on different pages.

  • include_info – Value should be set to “yes” or “no”; default is “yes”. If set to “yes”, Breeds, Spayed/Neutered, Up-to-date with routine shots, Housebroken, kid safe, cat safe, dog safe, special needs are displayed in list below photo thumbnails. Each list item has a different CSS class so you can hide any you do not want to show.

Example using all attributes: [get_pet pet_id=”23367571″ include_info=”no” css_class=”igs”]

Widget

Add the Petfinder Listings Featured Pet widget under Appearance -> Widgets. After adding the widget to a sidebar you can set a featured pet id to display a featured pet, or leave blank to display a random pet from your shelter.
Featured Pet Widget Settings:

Featured Pet ID – You can get this id from the pet’s Petfinder URL. URL will look like the following: https://www.petfinder.com/dog/nanook-45732995/mo/kansas-city/missouri-kansas-ig-rescue-mo306/?referrer_id=cca97ef9-e23d-4d0b-b29d-52afa8f7d70e – 45732995 is the pet id.

Your Listing Page URL – The page where your shortcode [shelter_list] can be found. If this is set, your featured pet will link directly to this pet on your shelter list page. (Optional)

Featured Pet Image Size – The size of the Featured Pet image. (Required)

Featured Pet Copy Size – For Petfinder API v1.0 ONLY: How many characters from the Pet’s description you want to display. You can also enter 0 to display full description or -1 for none. (Required). Petfinder API v2.0 can use -1 for none. Otherwise description excerpt will display that is returned from the Petfinder API. The Petfinder API no longer returns the full pet description.

Featured Pet PDF Link – If you would like to create a PDF with more information about your Featured Pet, link to the PDF uploaded separately through WordPress’ Media here.

Screenshots

  • Settings Page
  • Widget Settings
  • Page with shortcode [shelter_list]
  • Widget display

Installation

  1. Upload expanded petfinder-listings folder to the /wp-content/plugins/ directory
  2. Activate the plugin through the “Plugins” menu in WordPress
  3. Set your Petfinder v2.0 API Key and Secret, Shelter Id, Thumbnail and Large image size under WordPress Settings -> Petfinder Listings. You will need to generate a free Petfinder API key on Petfinder here: http://www.petfinder.com/developers/api-key. You’ll need to create an account on Petfinder first if you don’t have one. You do not have to use your shelter’s Petfinder account to generate these keys. Your shelter ID is your Shelter’s Petfinder username, usually your state abbreviation plus a number.
  4. Place the shortcode [shelter_list] in a Page or Post content to display your pet list on a page. The lists includes all pets’ name, description and photos uploaded to Petfinder.
  5. If the list is not working after correctly entering all your Petfinder Listings Settings, make sure your Petfinder account is set up to share data through Petfinder’s API. To do this, log into your Petfinder account and click on the Organization Info tab. Look for the box labeled ‘Share Pet List’ and make sure all checkboxes within this box are selected: Please share my pet list with all third parties, Partner sites & Petfinder API users. (As of 12/1/2019, I do not know if these instructions need to be changed after Petfinder updated its interface. I do not have a shelter Petfinder account to view this information. If these instructions need to be changed, please contact me so I can update them. )
  6. Add the Petfinder Listings Featured Pet widget (Appearance -> Widgets) if desired.

FAQ

How do you get a Petfinder API key?

You will need to generate a free Petfinder API key on Petfinder here: http://www.petfinder.com/developers/api-key.

What to do if your page doesn’t list any pets and says ‘shelter opt-out’

If the list is not working after correctly entering all your Petfinder Listings Settings and the page displays a status of ‘shelter opt-out’, make sure your Petfinder account is set up to share data through Petfinder’s API. To do this, log into your Petfinder account and click on the Organization Info tab. Look for the box labeled ‘Share Pet List’ and make sure all checkboxes within this box are selected: Please share my pet list with all third parties, Partner sites & Petfinder API users. (Please let me know if these instructions need to be updated after Petfinder changed its interface.)

How do you change the Petfinder list styles?

This plugin generates generic HTML and includes a stylesheet to position the elements. To style, override CSS in your theme’s stylesheet. You might need to add !important to each style.

I have a video in petfinder but it isn’t showing on my site.

Petfinder does not return video information through their API, however if you have a video on YouTube you can paste the video embed code in your pet’s description to display the video through the Petfinder plugin.

Reviews

September 19, 2017
I appreciate the author's contribution that has helped many shelters and rescue organizations. However it no longer works and I would love to see this updated... It really was a beautiful plugin
Read all 6 reviews

Contributors & Developers

“Petfinder Listings” is open source software. The following people have contributed to this plugin.

Contributors

Translate “Petfinder Listings” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

1.0.13

  • 12/2/2019
  • Converted to use Petfinder API Version 2
  • In order to use the Petfinder API Version 2 (), you will need to get a new API Key and Secret from https://www.petfinder.com/developers/api-key. Note, Petfinder API no longer returns the full pet description so instead, I included a link to view the pet on Petfinder. You can keep using Petfinder API v1.0 until it stops working if you want to display your pets’ full description. Petfinder API v1.0 is supposed to stop working Jan 2020.

1.0.12

  • Added namespace prefixes to new functions.

1.0.11

  • Fixed so large images display.
  • Added sorting pets on newest, last_updated and name
  • Added ability to set message in shortcode for when petfinder is down. Can link to own petfinder page using shortcode attribute petfinder_down_message.

1.0.10

  • Fixed so if no pets listed returns “No results found for this pet. Please check back soon!” instead of Petfinder is down message.

1.0.9

  • Switched to using WordPress call to get data from petfinder which should work on more web hosts.
  • Added type of pet to outer div around pet details.

1.0.8

  • Added shortcode get_pet to list a single pet by petfider ID.
  • Added shelter_list attribute status.

1.0.7

  • Added shortcode attribute contact. This allows you to list dogs attributed to different contacts on different pages. Contacts can be added in the Petfinder Admin Contacts page. The contact value should match your contact’s first and last name. For example, contact=”Bill Smith”. When adding an animal you can set the contact person in the Contact/Location box. The location information is not available through Petfinder’s API but the Contact name is. Also added “Powered by Petfinder.com” option at request of Petfinder.

1.0.5

  • Added shortcode attribute include_info
  • Removed Setting Include Cat or Kid Safe and switched to shortcode attribute include_info
  • Added different css classes to each info list item.
  • Added a shortcode attribute css_class to set css class on div containing all pets.

1.0.4

  • Added shortcode attributes animal and count
  • Added note on how to display video within description
  • Switched mixed breed dogs to not display when breed is set.

1.0.3

  • Bug Fixes with repository set up

1.0

  • This is the first version