Gimpsy - help

Showing Gimpsy Search Results - 3^rd party interface

Content

Preface
Implementation overview
Step 1 - obtaining CATEGORY information
Step 2 - Obtaining SITE information
Step 3 - Directing the user to a site.
Example of a redirecting script

Preface

Gimpsy is a unique directory, which provides extremely accurate search results related to sites with online activity. This document describes the technical details required to design and implement an interface from a 3^rd party site (hereafter referred to as Partner) to Gimpsy. Using the interface is currently free of charge, but prior approval by Gimpsy must be obtained. Gimpsy reserves the full rights to accept or refuse any such requests.

Implementation overview

Getting search results from Gimpsy is a two step process. In the first step, Gimpsy provides a list of categories that are deemed to be most relevant to the search query. In the second step, Gimpsy shows the sites in a chosen category.

Within the first step results, Gimpsy provides a numerical 'relevancy index' for each category. Using that information, the Partner then chooses to display sites from some of the categories, just one category or none at all.

It is also quite possible, and user friendly, to show 'related categories' to the user, so that if the automated process has not matched the user's expectations, another Gimpsy category may be selected. In effect, that means showing the results obtained from the first step. Here, too, the Partner should decide on the cut-off point for showing those categories. It could be by an arbitrary number (say 5) or up to and including a specific relevance indicator.

Step 1 - obtaining CATEGORY information

In all the calls to the Gimpsy interface, a Partner-specific code must be present. It is vital that this code will not be visible to, nor accessible by, any user! Showing the code to the users or making it available to another 3^rd party will be considered as a violation of the Terms and Conditions governing the agreement between Gimpsy and the Partner, and will result in its termination.

The general format of the call for the first step (categories) is:

http://www.gimpsy.com/gimpsy/partner/?sign=CALLER_SIGNATURE
&type=ctg&max=MAXIMUM_RESULT_ITEMS&phrase=SEARCH_PHRASE

where:

CALLER_SIGNATURE - signature for authenticating a caller. As an example, the following signature is used: "a2baac2322227d473a437e3c93e717a5".
IMPORTANT NOTE: To prevent misuse of the this facility by unauthorized sites, the 'caller signature' published here will NOT work.
Should you wish to test the system, you must obtain a valid signature from Gimpsy.
TYPE - must be the string 'ctg' to obtain CATEGORIES
MAXIMUM_RESULT_ITEMS = maximum number of categories to be shown. If omitted or equal zero, all categories are shown.
SEARCH_PHRASE - url encoded phrase to search, such as "buy+book"

The results are returned as an XML data file, with the following format:

for the very first and last row. If there is nothing in between - there is no new data.
- a record of a Gimpsy category
- The text used for that category
- the link to the Gimpsy category, to be used by the searcher to go to that category from the Partner site. This URL should be shown on the Partner's site together with the category information, if the Partner decides to show Gimpsy CATEGORIES.
- the percentage (or the row number) of the category matching algorithm (score is between 0 and 100 - inclusive)
- each category has a score, based on the number of matches found in the sites' description, URL and Title of the searcher's keyword.
- part of the URL to the Gimpsy script that will return a list of sites with of a given category with appropriative location and properties. This is internal information, which should not be made available to the Partner users.

Example:

http://www.gimpsy.com/gimpsy/partner/?sign=a2baac2322227d473a437e3c93e717a5
&type=ctg&max=2&phrase=buy+linux+in+USA+Utah

The results would be:

<data>
  <gcat>
    <catdescr>Buy > computer > software</catdescr> 
   <catlink>http://www.gimpsy.com/dir/Buy/computer/software/?country=1
     &state=45&properties=19</catlink> 
    <catscore>100</catscore> 
    <sitescore>1586</sitescore> 
    <sitelistreq>cid=1297&country=1&state=45&properties=19
    </sitelistreq> 
  </gcat>
  
  <gcat>
    <catdescr>Host > web site</catdescr> 
   <catlink>http://www.gimpsy.com/dir/Host/web_site/?country=1&state=45
      &properties=99</catlink> 
    <catscore>75</catscore> 
    <sitescore>1781</sitescore> 
    <sitelistreq>cid=668&country=1&state=45&properties=99
    </sitelistreq> 
  </gcat>
</data>

Step 2 - Obtaining SITE information

Assuming that the Partner decides that the 'catscore' of one of the categories obtained in the first step is high enough and it wants to display the sites from that category.

The general format of the call in the second step (sites) is:

http://www.gimpsy.com/gimpsy/partner/?sign=CALLER_SIGNATURE&type=site
  &max=MAXIMUM_RESULT_ITEMS&SITELISTREQ

where:

CALLER_SIGNATURE - signature for authenticating a caller. As an example, the following signature is used: "a2baac2322227d473a437e3c93e717a5".
TYPE - must be 'site' to obtain SITES' information
MAXIMUM_RESULT_ITEMS = maximum number of sites to be shown. If omitted or equal zero, 10 sites are shown.
SITELISTREQ - the string obtained from the 'sitelistreq' tag from the first step

In returning results, the following pairs of XML will be used:

for the very first and last row. If there is nothing in between - there is no data.
start and end the details of a particular site
- Can be 'w' (winner), 'p' (promoted) and 'r' (regular)
- site's title
- site's description
- the site's URL
- the URL for tracking the clicks from the Partner

The results obtained are:

<data>
<gsite>
  <type>p</type> 
  <title>ValueSnap!</title> 
  <descr>Large selection of software for networking, business, education, 
  games, graphics, handheld, personal interest, Internet, finance, utilities,
  operating systems, Linux and voice recognition.</descr> 
  <surl>http://www.valuesnap.com</surl> 
  <turl>msc=86218&country=1&state=45&pos=1</turl> 
  </gsite>
- <gsite>
  <type>r</type> 
  <title>BuyCheapSoftware</title> 
  <descr>Product inventory of over 600 name brand titles, including: Adobe,
   Corel, Filemaker, Lotus/IBM, Microsoft and PowerQuest. With a range of business
   packages such as Windows, Exchange and SQL Servers and 
   Developer Tools.</descr> 
  <surl>http://www.buycheapsoftware.com</surl> 
  <turl>msc=48588&country=1&state=45&pos=2</turl> 
</gsite>
</data>

Step 3 - Directing the user to a site

Part of the agreement of using Gimpsy data on the Partner's site is that any user clicking on a search result shown there will be redirected to the site's destination via Gimpsy. To achieve that, the site information shown on the Partner's site may NOT have a direct link to the site's URL. Instead, the URL will point to an internal script, which will get all the parameters and then call the Gimpsy site redirection routine.

The reason for NOT allowing a direct call to the Gimpsy script from the user viewable information is that it should also contain the Partner-specific CALLER_SIGNATURE.

The general format of the call in the second step (sites) is:

http://www.gimpsy.com/gimpsy//partner/cgi_partner_stat.php?sign=CALLER_SIGNATURE&TURL

where:

CALLER_SIGNATURE - signature for authenticating a caller. As an example, the following signature is used: "a2baac2322227d473a437e3c93e717a5".
TURL - the string obtained from the 'turl' tag from the second step

For example, the call to go to the first site in the example sites obtained of the second step above would be:

http://www.gimpsy.com/gimpsy/partner/cgi_partner_stat.php?
sign=a2baac2322227d473a437e3c93e717a5&msc=86218&country=1&state=45&pos=1

The simplest way to achieve it would be to create a small script within the Partner's site, that will obtain the TURL as a parameter, inserting the CALLER_SIGNATURE in the right place.

For example, the URL that the user will SEE may look like:

http://www.partner.com/cgi/gsite.php?msc=86218&country=1&state=45&pos=1

That script will, in turn, call the script from Gimpsy to direct the user to its desired site.

Example of a redirecting script

<?php
//=================================================================
//  Redirects a link to user's site via Gimpsy.
//  Copyright (c) 2003 by Gimpsy
//  Written by Sergey Ogarkov
//=================================================================
// Input:
// turl  - the url-encoded parameter for tracking 
//          the clicks from the Partner
//
// For example, if  tag from Gimpsy interface 
// is the folloing:
//   msc=48588&country=1&state=45&pos=2
// the URL for calling this script should be:
// http://www.yoursite.com/this_script.php?turl=msc%3D48588%26country%3D1
   %26state%3D45%26pos%3D2
//=================================================================

// Partner's signature for authentication
$sign='a2baac2322227d473a437e3c93e717a5';  // should be replaced by the real one!!!

$Gimpsy_script='http://www.Gimpsy.com/Gimpsy/Partner/cgi_Partner_stat.php';

$url=$Gimpsy_script.'?sign='.$sign.'&'.$turl;

header("Location: ".$url);

?>

Showing Gimpsy Search Results - 3rd party interface

Content

Preface

Implementation overview

Step 1 - obtaining CATEGORY information

Step 2 - Obtaining SITE information

Step 3 - Directing the user to a site

Example of a redirecting script

Showing Gimpsy Search Results - 3^rd party interface