awe.sm Stats API

Active Endpoint

Retrieve all-time stats for all clicked (active) links in a project between a specified date and the present.

GETapi.awe.sm/stats/active.json

The POST method is also supported. HTTPS is supported on this endpoint.

Required Parameters

Parameter	Type	Description
key	string	API key of the project on which stats are being requested.
v	integer	API version: `3` for this endpoint.

Optional Parameters

Parameter	Type	Description
callback	string	Returns a JSON-P response named with this parameter's value.
start_date	date	How recently an awe.sm link has been active, rounded to previous hour.
with_conversions	boolean	Flag to include conversion values in response. Default is `FALSE`.
with_metadata	boolean	Flag to include metadata objects in response. Default is `FALSE`.

Filter Parameters

Parameter	Type	Description
application	string	The key representing the group of tools used to create awe.sm links. See the Link Creation Overview for more information.
awesm_id	string	The unique id of a given awe.sm link in the form `%domain%_%path%`. For example: if the `awesm_url` is `http://planca.st/d6H2`, the `awesm_id` is `planca.st_d6H2`.
campaign	string	A project-specific label. See the Link Creation Overview for more information.
channel	string	Where the created awe.sm links were shared within a `service`. See Services and Channels for list of common values.
domain	string	The hostname on which the awe.sm links were created.
original_url	string	The address of the shared page, subject to canonicalization if redirection patterns were enabled.
parent	string	The awesm_id that drove the visit that led to awe.sm links being created. Format of `%domain%_%path%`.
service	string	Where the created awe.sm links were shared. See Services and Channels for list of common values.
service_postid	string	The message id containing the awe.sm link shared. Value must be formatted `service:post_id`, e.g. `twitter:130039394869583873`.
service_userid	string	The user id of the sharer on the service shared to. Value must be formatted `service:user_id`, where "service" corresponds to the service of the specified `channel`. Example: `twitter:13263` for tweets made by @jhstrauss.
sharer_id	string	awe.sm's internal id of the sharer captured from the awe.sm Publisher and unauthenticated use of the Share Endpoint or Share Buttons.
tag	string	A case-sensitive project-specific label. See the Link Creation Overview for more information.
tool	string	The key representing the creation method of awe.sm links. See the Link Creation Overview for more information. The tool name is also accepted, but tool names are not guaranteed to be unique.
user_id	string	Your application's unique identifier for a user initiating a share. Case-sensitive.
username	string	The username corresponding to a `sharer_id` if the user has registered with awe.sm (e.g. members of your project).

Group Parameters

Parameter	Type	Description
group_by	string	Options are any of the Filter Parameters, `shared_at_hour_of_day`, `shared_at_hour_of_week`, and `shared_at_day_of_week`
sort_type	string	Default `clicks`; options are `clicks`, `shares`, `clicks_per_share`, `pageviews`, `goal_1_count`, `goal_1_value`, `goal_2_count`, `goal_2_value`, `goal_3_count`, `goal_3_value`, `goal_4_count`, `goal_4_value`, `goal_5_count`, `goal_5_value`, `goal_total_count`, `goal_total_value`, `alpha`, `shared_at`; `with_conversions` must be TRUE for conversion fields to be available
sort_order	string	Ascending or descending sorting on values: `asc` and `desc`. Default is `desc`.

Pivot Parameters

Parameter	Type	Description
pivot	string	Options are any of the Filter Parameters, `shared_at_hour_of_day`, `shared_at_hour_of_week`, and `shared_at_day_of_week`. Requires a valid `group_by` parameter. Cannot be a filtered or grouped parameter.
with_zeros	boolean	Flag to include pivots with no activity. Default is `FALSE`.
pivot_sort_type	string	Options are `clicks`, `shares`, `clicks_per_share`, `pageviews`, `goal_1_count`, `goal_1_value`, `goal_2_count`, `goal_2_value`, `goal_3_count`, `goal_3_value`, `goal_4_count`, `goal_4_value`, `goal_5_count`, `goal_5_value`, `goal_total_count`, `goal_total_value`, `alpha`, `shared_at`. Default is `clicks`. `with_conversions` parameter must be `TRUE` for conversion fields to be available.
pivot_sort_order	string	Ascending or descending sorting on values: `asc` or `desc`. Default is `desc`.

Pagination Parameters

Parameter	Type	Description
per_page	integer	The maximum number of results returned per request. Default is `10`.
page	integer	The group of results to be returned if the number of results is greater than the `per_page` value. Page numbers start at and default to `1`.
offset	integer	The position of the first result to be returned. Overrides `page` if specified. Should be set to `last_offset` value returned in the previous page.

Related APIs

Range: returns stats from a period
Range Intervals: returns periodic values similar to this API for use with graphs

Examples

If an application wanted to track performance of specific shares, it could call stats/active periodically with grouping by awesm_id specified.

GET http://api.awe.sm/stats/active.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&start_date=2011-11-01&group_by=awesm_id

{
    "start_date": "2011-11-01T00:00:00Z",
    "end_date": null,
    "with_metadata": false,
    "with_conversions": false,
    "filters": [],
    "group_by": "awesm_id",
    "sort_type": "clicks",
    "sort_order": "desc",
    "pivot": null,
    "with_zeros": false,
    "pivot_sort_type": null,
    "pivot_sort_order": null,
    "page": 1,
    "per_page": 10,
    "total_results": 40,
    "offset": 0,
    "last_offset": 10,
    "totals": {
        "clicks": 3547,
        "shares": 40,
        "clicks_per_share": 88.675
    },
    "groups": [
        {
            "clicks": 2202,
            "shares": 1,
            "clicks_per_share": 2202,
            "awesm_id": "awe.sm_17"
        },
        {
            "clicks": 1262,
            "shares": 1,
            "clicks_per_share": 1262,
            "awesm_id": "awe.sm_5"
        },
        {
            "clicks": 12,
            "shares": 1,
            "clicks_per_share": 12,
            "awesm_id": "tc.gd_e6"
        },
        {
            "clicks": 9,
            "shares": 1,
            "clicks_per_share": 9,
            "awesm_id": "awe.sm_5Xaqx"
        },
        {
            "clicks": 8,
            "shares": 1,
            "clicks_per_share": 8,
            "awesm_id": "demo.awe.sm_PCI"
        },
        {
            "clicks": 6,
            "shares": 1,
            "clicks_per_share": 6,
            "awesm_id": "demo.awe.sm_K7e"
        },
        {
            "clicks": 4,
            "shares": 1,
            "clicks_per_share": 4,
            "awesm_id": "demo.awe.sm_K8E"
        },
        {
            "clicks": 4,
            "shares": 1,
            "clicks_per_share": 4,
            "awesm_id": "demo.awe.sm_OX0"
        },
        {
            "clicks": 3,
            "shares": 1,
            "clicks_per_share": 3,
            "awesm_id": "demo.awe.sm_KLX"
        },
        {
            "clicks": 3,
            "shares": 1,
            "clicks_per_share": 3,
            "awesm_id": "demo.awe.sm_OxY"
        }
    ]
}

Last updated 2012-01-23

Have questions? Talk to us.