Update Endpoint No Longer Requires Tool Key

2013-05-13

Tool is no longer a required parameter for the update endpoint.

Examples

Update an existing link with a new tag value with full JSON response

POST http://api.awe.sm/url/update/demo.awe.sm_ELZ.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&tag=foobar

{
    "awesm_url": "http://demo.awe.sm/ELZ",
    "awesm_id": "demo.awe.sm_ELZ",
    "domain": "demo.awe.sm",
    "path": "ELZ",
    "created_at": "2011-08-19T23:39:15Z",
    "redirect_url": "http://plancast.com/p/6xfs/silicon-valley-tweetup-summer-2011?utm_campaign=&utm_medium=demo.awe.sm-copypaste&utm_source=direct-demo.awe.sm&utm_content=test-main",
    "original_url": "http://plancast.com/p/6xfs/silicon-valley-tweetup-summer-2011",
    "channel": "copypaste",
    "service": "copypaste",
    "tool": "test-main",
    "application": "test",
    "parent": null,
    "sharer_id": null,
    "username":null,
    "service_userid": null,
    "service_postid": null,
    "service_postid_metadata": {
        "reach": null,
        "shared_at": null
    },
    "campaign": null,
    "campaign_metadata": {
        "description": null,
        "name": null
    },
    "user_id": "23291",
    "user_id_metadata": {
        "icon_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-snc4/41657_627286_9900_n.jpg",
        "username": "jstrauss",
        "profile_url": "http://plancast.com/user/23291"
    },
    "tag": "foobar",
    "notes": null,
    "updated_at":"2011-08-19T23:52:55Z"
}

Group by shared_at_hour_of_day and shared_at_hour_of_week for Stats API queries

2013-02-06

Group by shared_at_hour_of_week and shared_at_hour_of_day to retrieve click performance by share creation time

Example Stats API call to retrieve clicks data and group them by shared_at_hour_of_day

GET http://api.awe.sm/stats/range.json?v=3&key=bb9a7e96e7f43bec1daf9e3944d5cf9b3290e180a89bc746b7d1f38a4ee508ca&group_by=shared_at_hour_of_day&start_date=2012-12-10&end_date=2012-12-15

Stats API endpoints updated:

Group, Pivot by project on multiple project Stats API queries

2013-01-16

When specifying multiple API keys on Stats APIs, you can now group and pivot by project. This complements the multiple project Stats API queries feature introduced on October 12, 2012.

Stats API endpoints updated:

Options Details Stats API queries

2013-01-03

Retrieve available group by options in a project via this call

Example Stats API call to retrieve available group by options with metadata in a project

GET http://api.awe.sm/stats/range/options.json?v=3&key=bb9a7e96e7f43bec1daf9e3944d5cf9b3290e180a89bc746b7d1f38a4ee508ca&group_by=channel&start_date=2012-12-10&end_date=2012-12-15

Stats API endpoints updated:

stats/range/options

Conversion Details Stats API queries

2012-12-17

Conversion data for awesm link(s) is available via stats call

Example Stats API call to retrieve conversion data for a single awesm link

GET http://api.awe.sm/stats/demo.awe.sm_1Cg/conversions.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9

Example Stats API call to retrieve conversion data for multiple awesm links

GET http://api.awe.sm/stats/awesm_ids/conversions.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&awesm_ids=demo.awe.sm_1Bf,demo.awe.sm_1Cg

Stats API endpoints updated:

Multiple project Stats API queries

2012-10-12

You can now retrieve combined stats for multiple projects in a single API call. To use, pass an array of project API keys to the endpoints instead of a single API key string.

Example Stats API call with a single project specified:

GET https://api.awe.sm/stats/totals.json?v=3&start_date=2012-09-01&end_date=2012-10-01&with_conversions=true&key=AAAaaaAAAaaaAAA

Example Stats API call with multiple projects specified:

GET https://api.awe.sm/stats/totals.json?v=3&start_date=2012-09-01&end_date=2012-10-01&with_conversions=true&key[]=AAAaaaAAAaaaAAA&key[]=BBBbbbBBBbbbBBB

Stats API endpoints updated:

Conversions via images, cross-domain support, new examples

2012-09-05

You can now register conversion goals via HTML images. This allows conversion tracking in places where JavaScript is prohibited or undesirable. More

awe.sm conversion tracking now works across domains. If you use multiple domains on your website (e.g. http://mysite.com and http://mystore.com), conversions will now be tracked on both domains regardless of which domain the awe.sm share originally linked to.

Advanced conversion examples were added:

Faster stats, multi value fields, new endpoints

2012-08-20

awe.sm Stats API values are now available within seconds instead of several minutes.

Four new tag fields have been added and the existing tag field has been upgraded. Tag fields are a new way to store multiple values in a single field. For example, you could store tags used in a WordPress blog post in every share of the blog post. Then, you could retrieve share stats filtered on one of the values. Full Details

The new stats/totals endpoint allows the retrieval of all-time stats based on when an awe.sm link was shared or created.

Interval requests for an awe.sm share are now available explicitly:

Additional Conversion Goals

2012-05-14

Conversion tracking allows you to understand what happens after someone clicks an awe.sm link. Projects now support ten conversion goals, so you can track twice as many types of actions that happen as a result of sharing.

To use, pass goal_6 through goal_10 to the Conversions API. Conversion goal labels can be set in your project settings.

CORS support and crossdomain.xml

2012-02-22

To improve access to the awe.sm Create API and Stats API, we now support the Cross-Origin Resource Sharing mechanism. This emerging W3 specification allows XMLHttpRequests across domains. It has significant advantages over JSON-P, such as POST method support and error handling. More than 85% of internet users can take advantage of CORS today.¹

We've also added a crossdomain.xml policy file for Flash applications.

According to latest browser usage in February 2012.

Faster, asynchronously loaded Share Buttons

2012-02-16

The awe.sm-powered Facebook and Twitter share buttons can now be loaded after the initial rendering of a page by the browser. Asynchronously loading the share buttons decreases the perceived load time of your pages and is now the recommended embedding method. Review the documentation for updated examples of how to take advantage of this feature.

HTTPS support for awe.sm APIs & tools

2012-01-23

The awe.sm-powered Facebook and Twitter sharing buttons, Administration API, Create API, Conversions API and JavaScript library, and Stats API are available now via HTTPS.

To use, simply replace http:// with https:// on these resources. Optionally, you can specify a scheme-relative request by replacing http:// with //.

awe.sm tracking links support HTTPS redirections on the awe.sm domain. SSL on custom domains is not yet supported. https://awe.sm/ should only be used when redirecting to an SSL-encrypted destination to avoid insecure content warnings in some browsers.

Conversions added to Administration API

2011-12-29

Conversion Tracking can now be managed via the Administration API using the projects/new and projects/{api_key}/update endpoints.

V3 APIs Released

2011-12-05

awe.sm now has more ways to share, track, retrieve stats, and manage your projects. They're easier and faster to use than ever before.

New Features

New Administration Endpoints

Ten new endpoints to manage domains, projects, and users.

New Create API Endpoint

api.awe.sm/url/update/{awesm_id}.{format}

Modify an awe.sm link's metadata after it's been created. Useful for adding a service's post id, time of sharing, and server user's friend count to an awe.sm link.

New Stats API Endpoint

api.awe.sm/stats/active.json

Retrieve all-time stats for all clicked (active) links in a project between a specified date and the present. Useful if your application needs to update stats totals periodically.

Redirection Patterns

Redirection Patterns can automatically and dynamically alter where an awe.sm link points. They allow for metadata stored with an awe.sm link to be passed to your application at the time it’s clicked.

Improved Features

Conversions metadata can now be specified in the awe.sm settings interface and be returned in stats requests.

awe.sm-powered Share Buttons now use the V3 APIs.

Pivots allow for secondary grouping within stats. For example, you could group stats by campaign and pivot by service to see how each service performed in several campaigns.

Sorting and pagination is now allowed on group and pivot results on any performance column, ascending or descending.

Expanded Metadata

Channels can now be collectively filtered and retrieved by their associated service.

Tools can now be collectively filtered and retrieved by their associated application.

Campaigns are now stubified, while preserving human-readable names in campaign_name. When a campaign is first used, campaign_description can be specify a human-readable description of a campaign.

Users of your application can be associated with awe.sm links by user_id. The user's username, profile URL, and icon URL can also be specified when a user_id is first used.

User identities on services can be associated with awe.sm links by service_userid. The user's username, profile URL, and icon URL on the service it is sharing on can also be specified when a service_userid is first used.

Service shares can be associated with awe.sm links by service_postid. On a per awe.sm link basis, the service user's fan/follower/friend count can be stored in service_postid_reach. The time an awe.sm link is shared on a service can be stored in service_postid_shared_at.

V2 to V3 Migration Notes

awe.sm's V3 APIs are JSON only, except where noted. XML is no longer supported.

Date time values now returned as ISO 8601 formatted.

V2 Parameter Name Changes

V2 Parameter	V3 Parameter	Notes
api_key	key
awesm_id	path
awesm_url	awesm_id
clicked_after	start_date
clicked_before	end_date
notes	tag	Existing `notes` were migrated to the `tag` field. The notes field is now an arbitrary, open-ended field retrievable only on individual awe.sm links.
parent_awesm	parent
user_id	service_userid	id of the user on the channel
version	v

Create API

api.awe.sm/url/share

The destination parameter value is no longer implied based on the channel and must be specified.

api.awe.sm/url/retweet

The make_parent parameter was added to disable automatic parent-child relationship creation when an awe.sm link is passed in the text parameter, if desired.

The destination parameter value is no longer implied based on the channel and must be specified.

The AWESM_TARGET placeholder in the destination parameter is now AWESM_TEXT.