petkey™ API - Partners Basic Integration

The basic integration method is the simplest way to add petkey™ functionality to your existing website. All it takes is a few references to our javascript library and css stylesheets at the top of your html pages. This page provides an overview of what features are available and how to integrate them into your site.

Prerequisites:

You have an existing website - Obvioulsy in order to integrate our features, you need to have an existing website. Many of our partners utilized hosted website services such as Weebly or WordPress. Petkey does not provide a website for you.
Obtain Your Kennel Management API Key - All API functions require an API key. This is a unique 36-character key provided to you when you sign up for API access. Please contact us at 734-600-3463 or info@petkey.org to obtain your key.
Basic Understanding of HTML and Javascript - Basic integration is relatively simple, however, it requires that you know the basics of html and javascript in order to copy and paste the code to the approprate places inside your page. You should know how to access your page <head> to reference the scripts and stylesheets. And you should know how to add a <div id="petkey"> to a spot within the body of your page. Please contact us if none of this makes sense.

What Features are Available?

The following features are available through the current basic integration method.

Pet Results - This provides a page on your website where you can search and display pets that are listed in your Kennel Management system. The results dipslay in a grid containing the pets photo, breed and gender. There are several options for choose what and how to display the results. For example, you can choose to only display pets with photos. Only pets of a certain pet type, breed, gender, etc. These options are explained in the documentation listed below.
Pet Detail - This goes hand in hand with the available pet results. When your users click on a particular pet within the results, they are taken to a separate page that displays the detailed profile for that pet. The detail page includes additional photos, breed info, age, coloring, etc, etc.
Perfect Breed Match - Our perfect breed match tool consists of a 13 question survey that matches user preferences to breed characteristics. Partners can choose to limit the results to breeds they have available in their kennel, or they can allow it to select from all available breeds.

Pet Results

Pet results is a page on your website where you can search and display pets that are listed in your Kennel Management system. Follow the steps below to create the pet results page.

Create New Page or Use Existing Page - The first step is to select the page on your site where the results will be displayed. Most sites have a dedicated page separate from the site home page for this. So if the home page of your site is http://www.mycompany.com/, then your pet results page could be something like http://www.mycompany.com/available-pets/ or http://www.mycompany.com/available-pets.html .

Add Javascript and CSS references to <head> - Copy and paste the following code to the <head> section of your page.

Notes about JQuery:

On Line #3 above, there is a script reference to JQuery version 3.1.1. JQuery is a popular javascript framework that is required for petkey integration. However, many popular web hosting providers already include JQuery as part of their site templates. If your site already includes a version of JQuery, you can remove Line #3 from the above code to avoid conflicts. The minimum version is JQuery 1.8.3.

Add the petkey div to the <body> - Pick a location within the body of the html page where you would like the results to appear and place the following html:
<div id="petkey"></div>

This div can be anywhere based on your page layout. The results will fill the maximum area allowed by it's container. For best results, it is recommended that you pick a location that is at least 800px wide. Try to avoid putting the results into smaller areas like a 2 or 3 column layout. The body html should look something similar to the folowing:
```
                <body>
                    <div style="width: 800px; margin: auto;">
                        <h1>Available Pets</h1>
                        <div id="petkey"></div>
                    </div>
                </body>
            
```

Full Page Example:

                <html>
                    <head>
                        <link type="text/css" rel="stylesheet" href="https://api.petkey.org/v4/partners.css" />
                        <script type="text/javascript" src="https://api.petkey.org/js/jquery-3.1.1.min.js"></script>
                        <script type="text/javascript" src="https://api.petkey.org/v4/partners.js"></script>
                        <script type="text/javascript">
                            $(document).ready(function () {
                                PetkeyApi.Keys = "[ENTER YOUR API KEY]";            
                                PetkeyApi.PetDetailPage = "/pet-detail.html";       

                                PetkeyApi.ShowFilter = true;                        
                                PetkeyApi.SearchOptions.Status = "available";       
                                PetkeyApi.SearchOptions.HasPhoto = true;            
                                PetkeyApi.SearchOptions.PetType = "dog";            
                                PetkeyApi.SearchOptions.BreedId = "";               
                                PetkeyApi.SearchOptions.Gender = "";                

                                PetkeyApi.initSearch();

                            });
                        </script>
                    </head>
                    <body>
                        <div div style="width: 800px; margin: auto;">
                            <h1>Available Pets</h1>
                            <div id="petkey"></div>
                        </div>
                    </body>
                </html>

Pet Detail

The pet detail page is where your users will go when they click on one of the pets in the pet results page. It shows additional photos, breed info, and has links to submit customer inquiries to your kennel management system. Follow the steps below to create the pet detail page.

Create The Pet Detail Page - Pet detail should be a new page that is separate from your pet results page. This is where the user will navigate to when they click on a particular pet in your pet results. A pet id parameter will be appended to the url which will tell the detail page which particular pet to load. By seperating the detail page from the results, it allows us to create a unique url for each pet. For example, if your company url is http://www.mycompany.com, the pet detail page could be http://www.mycompany.com/pet-detail or http://www.mycompany.com/pet-detail.html. When the pet id parameter is added from the pet results page, the url to the specific pet would become http://www.mycompany.com/pet-detail.html?pid=xxxx where xxx = the petkey™ pet id assigned in kennel management.
Add Javascript and CSS references to <head> - Copy and paste the following code to the <head> section of your page.
```
                

                

                
                
                
            
```
Notes about JQuery:

On Line #3 above, there is a script reference to JQuery version 3.1.1. JQuery is a popular javascript framework that is required for petkey integration. However, many popular web hosting providers already include JQuery as part of their site templates. If your site already includes a version of JQuery, you can remove Line #3 from the above code to avoid conflicts. The minimum version is JQuery 1.8.3.
Add the petkey div to the <body> - Pick a location within the body of the html page where you would like the pet details to appear and place the following html:
<div id="petkey"></div>

This div can be anywhere based on your page layout. The pet detail will fill the maximum area allowed by it's container. For best results, it is recommended that you pick a location that is at least 500px wide. The body html should look something similar to the folowing:
```
                <body>
                    <div style="width: 500px; margin: auto;">
                        <h1>Pet Detail</h1>
                        <div id="petkey"></div>
                    </div>
                </body>
            
```

Full Page Example:

                <html>
                    <head>
                        <link type="text/css" rel="stylesheet" href="https://api.petkey.org/v4/partners.css" />
                        <script type="text/javascript" src="https://api.petkey.org/js/jquery-3.1.1.min.js"></script>
                        <script type="text/javascript" src="https://api.petkey.org/v4/partners.js"></script>
                        <script type="text/javascript">
                            $(document).ready(function () {
                                PetkeyApi.Keys = "[ENTER YOUR API KEY]";            
                                PetkeyApi.PetResultsPage = "/available-pets.html";  
                                PetkeyApi.initPetDetail();
                            });
                        </script>
                    </head>
                    <body>
                        <div div style="width: 800px; margin: auto;">
                            <h1>Pet Detail</h1>
                            <div id="petkey"></div>
                        </div>
                    </body>
                </html>

Perfect Breed Match

Perfect breed match is a tool consists of a 13 question survey that matches user preferences to breed characteristics. Each resulting breed is given a breed score. The lower the score, the closer the breed matches the user preferences. By default, all breeds within petkey will be compared and the top 5 scores will be returned. However, this behaviour can be modified. By setting the KennelOnly input parameter, only the breeds that are available within your kennel management system are considered for comparison. This ensures the resulting top breeds are actually pets you have available to adopt. Follow the steps below to integrate the perfect breed match tool on your website.

Create The Perfect Breed Match Page - Create a new page on your website. The name of the page is not important here since the breed match tool is completely seperate from the pet results and the pet details page. For this example, we'll assume it's called http://www.mycompany.com/perfect-breed-match.html

Add Javascript and CSS references to <head> - Copy and paste the following code to the <head> section of your page.

Notes about JQuery:

Add the petkey div to the <body> - Pick a location within the body of the html page where you would like the breed match quiz to appear and place the following html:
<div id="petkey"></div>

This div can be anywhere based on your page layout. The pet detail will fill the maximum area allowed by it's container. For best results, it is recommended that you pick a location that is at least 800px wide. The body html should look something similar to the folowing:
```
                <body>
                    <div style="width: 500px; margin: auto;">
                        <h1>Find Your Perfect Breed</h1>
                        <div id="petkey"></div>
                    </div>
                </body>
            
```

Full Page Example:

                <html>
                    <head>
                        <link type="text/css" rel="stylesheet" href="https://api.petkey.org/v4/partners.css" />
                        <script type="text/javascript" src="https://api.petkey.org/js/jquery-3.1.1.min.js"></script>
                        <script type="text/javascript" src="https://api.petkey.org/v4/partners.js"></script>
                        <script type="text/javascript">
                            $(document).ready(function () {
                                PetkeyApi.Keys = "[ENTER YOUR API KEY]";
                                PetkeyApi.BreedMatchOptions.MaxResults = 5;         
                                PetkeyApi.BreedMatchOptions.IncludeHybrids = true;  
                                PetkeyApi.BreedMatchOptions.KennelOnly = true;      
                                PetkeyApi.initBreedMatch();
                            });
                        </script>
                    </head>
                    <body>
                        <div div style="width: 800px; margin: auto;">
                            <h1>Find Your Perfect Bree</h1>
                            <div id="petkey"></div>
                        </div>
                    </body>
                </html>