awe.sm Aggregate Data API

This API allows you to retrieve anonymized aggregate data for the share actions through awe.sm for a given long URL.

It is based on our Lookup API, full details of which can be found in the awe.sm developers group.

Retrieve a set of awe.sm URLs based on some criteria

GET create.awe.sm/url.:format

Retrieves aggregate data for a set of awesm_urls based on some combination of querying by share_type, create_type, original_url, created_at_start, and created_at_end. Additionally, results can be bounded by dates.

Parameters

• format (optional, default "json", this parameter is a part of url used for the API call)
  • json, xml
• version (required)
  • the version of the API the consumer expects, e.g. 1
• original_url (required)
  • URL that was originally awe.sm encoded
• start_date (optional, default is created_at_start)
  • constrain aggregate stats to after the starting date provided (unix epoch time)
  • if a created_at_start and/or created_at_end is specified, they will act as search criteria limiting the set of awesm_urls for which aggregate stats are returned
• end_date (optional, default is created_at_end)
  • constrain aggregate stats to before the ending date provided (unix epoch time)
  • if a created_at_start and/or created_at_end is specified, they will act as search criteria limiting the set of awesm_urls for which aggregate stats are returned
• share_type (optional)
  • filter by service identifier, e.g. twitter, email, newsletter, facebook-post, twitter, linkedin, other
• create_type (optional)
  • filter by originating action, e.g. api, bookmarklet, sociable-wordpress, twitterfeed, etc.
• created_at_start (optional, default is beginning of unix epoch time)
  • limit the awe.sm URLs returned to having a created_at after the starting value provided (unix epoch time)
• created_at_end (optional, default is last day statistics are available)
  • limit the awe.sm URLs returned to having a created_at before the ending value provided (unix epoch time)

Response

A valid query will return a response with the following fields:

 search_criteria (element is parameter name)
 total_shares (in period specified by start_date/end_date, if present)
 total_clicks (in period specified by start_date/end_date, if present)

Examples

Get aggregate data for all awe.sm-powered URLs that redirect to http://totally.awe.sm:

 $ curl -i "http://create.awe.sm/url.xml?version=1&original_url=http://totally.awe.sm"
 <urls>
   <original_url>http://totally.awe.sm</original_url>
   <total_shares>7</total_shares>
   <total_clicks>34</total_clicks>
 </urls>

Get aggregate data for awe.sm-powered URLs that redirect to http://totally.awe.sm and were shared to the Facebook wall (vs status update, which is share_type=facebook-status):

 $ curl -i "http://create.awe.sm/url.xml?version=1&original_url=http://totally.awe.sm&share_type=facebook-post"
 <urls>
   <original_url>http://totally.awe.sm</original_url>
   <total_shares>1</total_shares>
   <share_type>facebook-post</share_type>
   <total_clicks>1</total_clicks>
 </urls>

Get aggregate data for awe.sm-powered URLs that redirect to http://totally.awe.sm and were created since June 16, 2006 @ 20:28:23 GMT:

 $ curl -i "http://create.awe.sm/url.xml?version=1&original_url=http://totally.awe.sm&created_at_start=1245184103"
 <urls>
   <original_url>http://totally.awe.sm</original_url>
   <created_at_end>2009-09-21T16:23:36Z</created_at_end>
   <total_shares>0</total_shares>
   <total_clicks>0</total_clicks>
   <created_at_start>2009-06-16T20:28:23Z</created_at_start>
 </urls>

Get aggregate data since June 16, 2006 @ 20:28:23 GMT for all awe.sm-powered URLs that redirect to http://totally.awe.sm:

 $ curl -i "http://create.awe.sm/url.xml?version=1&original_url=http://totally.awe.sm&start_date=1245184103"
 <urls>
   <original_url>http://totally.awe.sm</original_url>
   <total_shares>0</total_shares>
   <start_date>2009-06-16T20:28:23Z</start_date>
   <total_clicks>7</total_clicks>
   <end_date>2009-09-21T16:23:36Z</end_date>
 </urls>