clearspring - the widget network.

This documentation reflects the early-access version of the Clearspring Reporting API. As such, it is subject to change in the final release. Every effort will be made to ensure backwards compatibility, though there is a small chance that existing calls will need to be modified.

Contents

• Introduction
• Authentication
• API
  

Introduction

This document provides an overview of the Clearspring Reporting API. The Reporting API provides programmatic access to the analytics report data for your widgets. It may be used to create custom reports or to integrate widget analytics data with your own applications or reporting dashboards.

Authentication

In order to make use of the API, you'll need the API key provided with your Clearspring account. The API key must be sent with every request to authenticate the request with our servers and gain access to your analytics data. To get the API key for your account, click on "Settings" after you log in at www.clearspring.com, or click here to go directly to the Settings page. The API key is unique to your account, and provides access to analytics data for all the widgets in the account.

API

Overview

• Data is made available as feeds which are updated daily with new entries
• Data is requested via a simple HTTP GET with no message body so API data can be easily linked to and requests can be generated by hand without custom software.
• Data is available in JSON, XML, RSS and CSV formats for integration with your existing applications.

Request

A request to the API is made via the HTTP GET method with the URL in the following format:

http://services.clearspring.com/analytics/v1/csa[/<wid 1>/<wid 2>/.../<wid M>]?apikey=<key>[&<parameter 1>&<parameter 2>&...&<parameter N>]

Examples:

• Get today's Unique Visitors for widget 0000000000000000 :

http://services.clearspring.com/analytics/v1/csa/0000000000000000?apikey=<key>&met=U

• Get Views data for each of the top 5 domains in the last 31 days for widget 0000000000000000 :

http://services.clearspring.com/analytics/v1/csa/0000000000000000?apikey=<key>&met=V&dom=5&beg=1981-12-26

• Get the total number of Views, Unique Visitors, and Active Installs for each day in December in JSON format:

http://services.clearspring.com/analytics/v1/csa?apikey=<key>&beg=2007-12-01&end=2007-12-31&fmt=json

Widget Filtering

By default, data will be returned for all widgets accessible by your API key. To request data for specific widgets, add the widget ID's (WIDs) to the URL path.

Examples:

• Get data feed for widget 0000000000000000:

http://services.clearspring.com/analytics/v1/csa/0000000000000000?apikey=<key>

• Get data feed for widgets 0000000000000000 and 1111111111111111:

http://services.clearspring.com/analytics/v1/csa/0000000000000000/1111111111111111?apikey=<key>

• Get data feed for all widgets:

http://services.clearspring.com/analytics/v1/csa?apikey=<key>

Parameters

apikey
The API key is required to authenticate your request (see Authentication).

Example:

?apikey=xxxxxxxxxxxxxxxx

Authenticate request

beg
Set the begin date for the feed using YYYY-MM-DD format. If the value of beg is more than 31 days prior to the end date, the begin date is set at 31 days prior to the end date.

Example:

?beg=2007-11-18

Set the begin date to Nov. 18, 2007

end
Set the end date for the feed using YYYY-MM-DD format. If the value of end is a date in the future, the end date is set to the present day. If the value of end is prior to the begin date, a parm error will be returned.

Example:

?end=2007-12-26

Set the end date to Dec. 26, 2007

dom
Return data for each of the top dom domains for every metric and widget over the time span of the feed. The domains are returned in descending order (the top domain is returned first), along with other (the sum over all other domains) and total (the total across all domains without duplication).

Example:

?dom=3&met=U&beg=2007-05-01&end=2007-05-31

Get the Unique Visitors data for the three domains that produced the most Unique Visitors in the month of May.

fmt
Set the response format.

Note: The csv format has a 5MB file limit. Responses larger than 5MB are truncated. To ensure you receive all data, break your request into multiple smaller requests if your responses are near the file limit.

Examples:

?fmt=json

Return data in JSON format

?fmt=rss

Return data as an RSS 2.0 feed

met
Set the metrics to include in the response. The API currently supports the following metrics (for an explanation of each of the metrics, follow the link in the table below):

Use a string containing a combination of metric letter codes to include multiple metrics in a single request. When requesting data for multiple metrics broken down by domain (dom > 0), the domains returned are the top domains for the first metric specified over the entire time span requested. For example, the following request

http://services.clearspring.com/analytics/v1/csa/0000000000000000?apikey=<key>&met=VP&dom=5&beg=2008-05-24&end=2008-05-26

will return Views and Active Installs for the 5 domains with the most Views over Memorial Day weekend 2008.

Note: The met parameter is case sensitive, so make sure to use 'U' and not 'u' to specify Unique Visitors.

Examples:

?met=V

Return data for Views only

?met=UP

Return data for Unique Visitors and Active Installs

q
Return data for each of the domains requested for every metric and widget over the time span of the feed. The domains must be specified as a comma delimited list with no white space.

Note: When the q parameter is specified, the dom parameter is ignored.

Example:

?met=N&q=google.com,facebook.com,myspace.com

Get the New Installs created today on each of the three domains requested.

Rate Limit

Every API key is rate limited to 10 requests per minute.

Response

A response consists of an ordered sequence of entries. Each entry corresponds to data collected during a single day.

Dates

Data is returned at a time resolution of one day. Specifically, if the entry date is 2007-12-26, then the data in the entry was collected between 2007-12-26T00:00:00-05:00 and 2007-12-26T23:59:59-05:00 (note the use of EST). The only exception to this is the current day's entry which contains all the data collected up to the present time.

Format

The response data can be formatted as XML, JSON, RSS or CSV using the fmt parameter. Example responses in both XML and JSON format are included below.

XML
Example:

<?xml version="1.0" ?>
<feed uri="http://services.clearspring.com/analytics/v1/csa/0000000000000000?beg=2007-11-18&end=2007-12-26&dom=3&fmt=xml">
   <entry date="2007-12-26">
      <wdata wid="0000000000000000">
            <metric name="Unique Visitors">
               <datum src="total">3573</datum>
               <datum src="www.facebook.com">1001</datum>
               <datum src="www.myspace.com">305</datum>
               <datum src="www.xanga.com">192</datum>
            </metric>
            <metric name="Views">
               <datum src="total">22256</datum>
               <datum src="www.myspace.com">5982</datum>
               <datum src="www.facebook.com">3489</datum>
               <datum src="www.google.com/ig">2391</datum>
               <datum src="other">10394</datum>
            </metric>
            <metric name="Active Installs">
               <datum src="total">1132</datum>
               <datum src="www.myspace.com">345</datum>
               <datum src="www.facebook.com">132</datum>
               <datum src="www.myyearbook.com">73</datum>
               <datum src="other">582</datum>
            </metric>
      </wdata>
   </entry>
   <entry date="2007-12-25">
      [...]
   </entry>
      .
      .
      .
   <entry date="2007-11-18">
      [...]
   </entry>
</feed>

JSON
Example:

http://services.clearspring.com/analytics/v1/csa/0000000000000000?beg=2007-11-18&end=2007-12-26&dom=3&fmt=json
{"feed" : "http://services.clearspring.com/analytics/v1/csa/0000000000000000?beg=2007-11-18&end=2007-12-26&dom=3&fmt=json",
 "entries" : [{
    "date"  : "2007-12-26",
    "wdata" : {
       "0000000000000000" : {
          "Unique Visitors" : [
             ["total", 3573],
             ["www.facebook.com", 1001],
             ["www.myspace.com", 305],
             ["www.xanga.com", 192]
          ],
          "Views" : [
             ["total", 22256],
             ["www.myspace.com", 5982],
             ["www.facebook.com", 3489],
             ["www.google.com/ig", 2391],
             ["other", 10394]
          ],
          "Active Installs" : [
               ["total", 1132],
               ["www.myspace.com", 345],
               ["www.facebook.com", 132],
               ["www.myyearbook.com", 73],
               ["other", 582]
          ]
       }
     } 
   },
   {"date"  : "2007-12-25",
     ...
   },
   .
   .
   .
   {"date"  : "2007-11-18",
     ...
   }]
}

Length

The maximum response length is 31 entries. If a request for more than 31 entries is received, the response will contain the most recent 31 entries (starting from the end parameter value and going back in time). To retrieve more than 31 entries, break your request into multiple contiguous requests.

Errors

If there is an error with your request, you will receive one of the following error messages in lieu of a normal response. The error will be provided in the format specified by the fmt parameter.

<data>
   <message>Internal server error</message>
   <status>1</status>
</data>

<data>
   <message>Authentication failed</message>
   <status>12</status>
</data>

<data>
   <message>Rate-limit exceeded</message>
   <status>14</status>
</data>

<data>
   <message>Not a supported format (fmt=morseCode)</message>
   <status>21</status>
</data>

For information on how to request access to the Reporting API please read our FAQ.