The Cownt.us Webservice API is designed to give website programmatic access to data about their sites. It provides a simple Rest XML interface to page statistics for the Cownter and Cowrate application.

The Cownt.us webservice API is very simple to use. You query the webservice with a URL and parameters described below and get XML back. This can be done manually with any browser or programmatically from any programming language with libraries like curl, lwp and many others. All you need is your username and the token that you were given when you signed up. If you have implementation questions, drop us a note and we will help you out.

We cannot anticipate all the ways that this data can be used. However, here are some examples to give you an idea of the possibilities:

- You run a news site. The Giants game just ended and hundreds of readers flock to the sports article to read the play-by-play. Using the Cownt.us API, your site notices this trend and floats the article all the way to the front page. When the surge subsides, the site automatically adjusts and pushes the article back into the sports pages.

- You run an online shopping site specializing in shoes. Using the Cownt.us API you highlight the shoes which have the most shoppers looking at them. The natural want to see what everyone else is looking at draws more customers in. You can also drop a price and see the immediate effect on traffic flow.

- You run a social networking site. Instead of showing the newest members, threads with the most posts or any other similar statistic, you can show real "buzz". With the Cownt.us API you can see what the people in your community are doing right now and change pages to dynamically adapt.

- You do not like how our bubbles look. You decide to implement your own cownter number on the side of all your pages. You simply call the API with the url and show the number on the page.

We cannot anticipate all the ways that this data can be used. However, here are some examples to give you an idea of the possibilities:

- You want to gauge popularity of pages on your site. You use this data behind the scenes to improve pages that are not well received by your visitors.

- You run a news or blog site and want to know which stories or posts are most popular. You want the front page to list the stories in order of popularity like Digg.com. You also need to separate the stories by subject or type. Using the Cownt.us API you gain full control of how to display those ranked pages and even which rank to use.

- You run a social networking site. Each page is a user profile. You can have people rate each other and then show the most popular people in categories like male/female, age groups and other segments.

- You simply would like more control over rank display than what our widgets offer.

Name	Value	Default	Description
token	Integer		This is the token that you were given when you signed up. If you forgot your token, you can retrieve it from my account
username	String		This is the username that you made when you signed up for the Cownt.us account. If you forgot your username please use the feedback form and we will send it to you.
v	Decimal	1	Version of the API. Currently we are at version 1.
app	"cowrate" "cownter"	cownter	This is the application for which you would like data.
type	"url" "list"	list	This is the type of query that you are sending. The two available types for Cownter are list and url: - list returns a sorted list of pages and their counts for a particualar token. - url returns one page for a particular url. The parameters specific to those types are described below.
maxsize	Integer	10	The maximum amount of results you would like sent to you. Ex. If you have 1000 pages you may only want the top 20.
rank	String	visitors	This defines how you want the results ranked or ordered. Currenly there are only 2 available ranks; visitors and lastvisited. Visitors would put the pages that have the most people on them at the top, while lastvisited would put the sites that were most recently visited at the top.
url	Encoded URL		The url for which you would like to retrieve information. This url should be escaped (URLEncoded). Here is an example: http://cownt.us/ -> http%3A%2F%2Fcownt.us%2F .

Get a list of pages sorted by amount of current visitors:

http://ws.cownt.us/ws?v=1&app=cownter&token=7&username=alex&type=list&rank=visitors&maxsize=3

Result:

<reply version="1" application="cownter" token="7" username="alex">
  <params>
    <type>list</type>
    <maxsize>3</maxsize>
    <rank>visitors</rank>
    <usage>
       <tokenHits>52</tokenHits>
       <totalHits>74</totalHits>
    </usage>
  </params>
  <page>
    <title>BestSellers Lists - All Top Sellers In One Place</title>
    <url>http://www.bslists.com/</url>
    <visitors>0</visitors>
    <lastvisit>2008-08-09 19:56:02</lastvisit>
  </page>
  <page>
    <title>BestSellers Lists - amazon Musical Instruments Top Sellers</title>
    <url>http://www.bslists.com/bestsellers.fcgi?src=amazon&cat=51575011&i=on</url>
    <visitors>0</visitors>
    <lastvisit>2008-08-02 22:42:33</lastvisit>
  </page>
  <page>
    <title>BestSellers Lists - amazon Toys Top Sellers</title>
    <url>http://www.bslists.com/bestsellers.fcgi?src=amazon&cat=219221011&i=on</url>
    <visitors>0</visitors>
    <lastvisit>2008-08-02 22:43:40</lastvisit>
  </page>
</reply>

Get the amount of visitors currently on a particular page:

http://ws.cownt.us/ws?v=1&app=cownter&token=7&username=alex&type=url&url=http%3A%2F%2Fwww.bslists.com/

Reply:

<reply version="1" application="cownter" token="7" username="alex">
  <params>
    <type>url</type>
    <url>http://www.bslists.com/</url>
    <usage>
      <tokenHits>59</tokenHits>
      <totalHits>81</totalHits>
    </usage>
  </params>
  <page>
    <visitors>0</visitors>
    <lastvisit>2008-08-09 19:56:02</lastvisit>
    <url>http://www.bslists.com/</url>
  </page>
</reply>

Query with an error URL:

http://ws.cownt.us/ws

Reply:

<reply version="1" application="cownter" token="" username="">
  <error>"token" is required</error>
  <error>"username" is required</error>
  <error>username () is not the owner of token ()</error>
  <params>
    <type>list</type>
    <maxsize>10</maxsize>
    <rank>visitors</rank>
    <usage>
      <tokenHits>0</tokenHits>
      <totalHits>0</totalHits>
    </usage>
  </params>
</reply>
    

#!/usr/bin/perl

use strict;
use LWP::Simple;
use XML::Simple;

# replace XXX with your username and YYY with your token
my $url = "http://ws.cownt.us/ws?v=1&app=cownter&token=YYY&"
         ."username=XXX&type=list&rank=visitors&maxsize=10";

my $content = get($url);

print "Content-type: text/html\n\n";

my $ref = XMLin(\$content);

print "<html><head></head><body><table border=\"1\">\n";
print "<tr><th>URL</th><th>Visitors</th><th>Last Visited</th></tr>\n";
foreach my $page (@{$ref->{page}}) {
    printf("<tr><td><a href=\"%s\" target=\"_new\">%s</a></td><td>%s</td><td>%s</td></tr>\n",
            $page->{url}, $page->{url}, $page->{visitors}, $page->{lastvisit});
}
print "</table></body></html>\n";

<?php
    // replace XXX with your username and YYY with your token
    $url = "http://ws.cownt.us/ws?v=1&app=cownter&"
         . "token=YYY&username=XXX&type=list&rank=visitors&maxsize=10";
    $contents = file_get_contents($url);
    $xml = new SimpleXMLElement($contents);
?>
<html><head></head><body><table border="1">
<tr><th>URL</th><th>Visitors</th><th>Last Visited</th></tr>
<?php foreach ($xml->page as $page) { ?>
<tr>
<td><a href="<?php echo $page->url ?>"><?php echo $page->url ?></a></td>
<td><?php echo $page->visitors ?></td>
<td><?php echo $page->lastvisit ?></td>
</tr>
<?php } ?>
</table></body></html>

Name	Value	Default	Description
token	Integer		This is the token that you were given when you signed up. If you forgot your token, you can retrieve it from my account
username	String		This is the username that you made when you signed up for the Cownt.us account. If you forgot your username please use the feedback form and we will send it to you.
v	Decimal	1	Version of the API. Currently we are at version 1.
app	"cowrate" "cownter"	cownter	This is the application for which you would like data. The two supported ones are "cowrate" and "cownter"
type	"url" "list"	list	This is the type of query that you are sending. The two available types for Cownter are list and url: - list returns a sorted list of pages and their ranks for a particualar category. - url returns page statistics for a particular url within all categories where it appears. The parameters specific to those types are described below.
maxsize	Integer	10	The maximum amount of results you would like sent to you. Ex. If you have 1000 pages you may only want the top 20.
rank	"simplerank" "-simplerank"		This defines how you want the results ranked or ordered. Currenly there are only 2 available ranks; simplerank and -simplerank. Simplerank ranks pages with: (thumbs up)-(thumbs down), putting the highest ranked pages at the top. While -slimplerank puts the lowest ranking pages at the top.
cat	String		This is the category of the pages that you want to list.
url	Encoded URL		The url for which you would like to retrieve information. This url should be escaped (URLEncoded). Here is an example: http://cownt.us/ -> http%3A%2F%2Fcownt.us%2F .

Get a list of pages sorted by (thumbs up)-(thumbs down):

http://ws.cownt.us/ws?v=1&app=cowrate&token=7&username=alex&type=list&maxsize=3&cat=news&rank=simplerank

Result:

<reply version="1" application="cowrate" token="7" username="alex">
  <params>
    <type>list</type>
    <maxsize>3</maxsize>
    <rank>simplerank</rank>
    <category>news</category>
    <usage>
      <tokenHits>70</tokenHits>
      <totalHits>92</totalHits>
    </usage>
  </params>
  <page>
    <title>Test Page</title>
    <url>http://cownt.us/testing.html</url>
    <category>news</category>
    <thumbsup>10</thumbsup>
    <thumbsdown>0</thumbsdown>
    <addedtocat>2008-07-25 00:38:08</addedtocat>
    <lastrated>2008-08-05 21:02:10</lastrated>
    <pagevisitors>155</pagevisitors>
    <added>2008-07-25 00:38:08</added>
    <lastvisited>2008-08-05 21:02:10</lastvisited>
    <ranks>
      <simplerank>10</simplerank>
    </ranks>
  </page>
  <page>
    <title>Testing Scripts</title>
    <url>http://cownt.us/testing2.html</url>
    <category>news</category>
    <thumbsup>5</thumbsup>
    <thumbsdown>0</thumbsdown>
    <addedtocat>2008-07-25 00:41:41</addedtocat>
    <lastrated>2008-08-04 12:15:13</lastrated>
    <pagevisitors>28</pagevisitors>
    <added>2008-07-25 00:41:41</added>
    <lastvisited>2008-08-04 12:15:13</lastvisited>
    <ranks>
      <simplerank>5</simplerank>
    </ranks>
  </page>
</reply>

Get the rating of a particular page:

http://ws.cownt.us/ws?v=1&app=cowrate&token=7&username=alex&type=url&url=http%3A%2F%2Fcownt.us%2Ftesting2.html

Reply:

<reply version="1" application="cowrate" token="7" username="alex">
  <params>
    <type>url</type>
    <url>http://cownt.us/testing2.html</url>
    <usage>
      <tokenHits>75</tokenHits>
      <totalHits>97</totalHits>
    </usage>
  </params>
  <page>
    <visitors>28</visitors>
    <lastvisit>2008-08-04 12:15:13</lastvisit>
    <firstvisit>2008-07-25 00:41:41</firstvisit>
    <title>Testing Scripts</title>
    <url>http://cownt.us/testing2.html</url>
    <categorymember>
      <category>news</category>
      <thumbsup>5</thumbsup>
      <thumbsdown>0</thumbsdown>
      <addedtocat>2008-07-25 00:50:34</addedtocat>
      <lastrated>2008-08-04 12:15:13</lastrated>
      <ranks>
        <simplerank>5</simplerank>
      </ranks>
    </categorymember>
  </page>
</reply>

Query with an error URL:

http://ws.cownt.us/ws

Reply:

<reply version="1" application="cownter" token="" username="">
  <error>"token" is required</error>
  <error>"username" is required</error>
  <error>username () is not the owner of token ()</error>
  <params>
    <type>list</type>
    <maxsize>10</maxsize>
    <rank>visitors</rank>
    <usage>
      <tokenHits>0</tokenHits>
      <totalHits>0</totalHits>
    </usage>
  </params>
</reply>
    

#!/usr/bin/perl

use strict;
use LWP::Simple;
use XML::Simple;

# replace XXX with your username and YYY with your token
my $url = "http://ws.cownt.us/ws?v=1&app=cowrate&token=YYY&"
         ."username=XXX&type=list&rank=simplerank&cat=XXX&maxsize=10";

my $content = get($url);

print "Content-type: text/html\n\n";

my $ref = XMLin(\$content);

print "<html><head></head><body><table border=\"1\">\n";
print "<tr><th>URL</th><th>Title</th><th>Rating</th></tr>\n";
foreach my $page (@{$ref->{page}}) {
    printf("<tr><td><a href=\"%s\" target=\"_new\">%s</a></td><td>%s</td><td>%s</td></tr>\n",
            $page->{url}, $page->{url}, $page->{title}, $page->{ranks}->{simplerank});
}
print "</table></body></html>\n";

<?php
    // replace XXX with your username and YYY with your token
    $url = "http://ws.cownt.us/ws?v=1&app=cowrate&"
         . "token=YYY&username=XXX&type=list&rank=simplerank&cat=XXX&maxsize=10";
    $contents = file_get_contents($url);
    $xml = new SimpleXMLElement($contents);
?>
<html><head></head><body><table border="1">
<tr><th>URL</th><th>Title</th><th>Rating</th></tr>
<?php foreach ($xml->page as $page) { ?>
<tr>
<td><a href="<?php echo $page->url ?>"><?php echo $page->url ?></a></td>
<td><?php echo $page->title ?></td>
<td><?php echo $page->ranks->simplerank ?></td>
</tr>
<?php } ?>
</table></body></html>