awe.sm Stats API

Totals Endpoint

Retrieve all-time stats from links that were shared or created within a time period. Combined stats for a single subscription can be retrieved in a single call as well as for multiple projects (up to 50).

The endpoint behaves similarly to the stats/range endpoint, but differs in that the date range applies to the selection of links instead of the activity on the links. If you need interval data, use stats/range/intervals.

If service_postid_shared_at has been specified, this value is used instead of the link's creation date.

GETapi.awe.sm/stats/totals.json

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

Required Parameters

Parameter Type Description
key string or array API key(s) of the project(s) on which stats are being requested. Either a subscription or key parameter must be provided.
subscription string Key of the subscription on which stats are being requested. Either a subscription or key parameter must be provided.
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 The beginning of the period in which a link was created, rounded to previous hour. Requires value after 2011-09-01.
end_date date The end of the period in which a link was created, rounded to next 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. (Cannot be used as a group_by value.)
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 or array of strings A case-sensitive field capable of storing multiple values up to 255 characters. Only one value can be specified as a filter. Use a URL array in multiple value mode (tag_3[]=foo) or a key-value pair (tag_3=foo) in single value mode. See the Tag Overview for more information.
tag_2
tag_3
tag_4
tag_5
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, except domain. Tags have special handling. If key is an array or if subscription is used, project may be used to group by project API keys. shared_at_hour_of_day values range from 0 to 23, representing the hour of day. Hour 0 is midnight to 1 AM. shared_at_hour_of_week values range from 0 to 167, respresenting the hour of week. Monday is the start of the week by ISO 8601; Hour 0 is Monday midnight to 1 AM.
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_6_count, goal_6_value, goal_7_count, goal_7_value, goal_8_count, goal_8_value, goal_9_count, goal_9_value, goal_10_count, goal_10_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. Requires a valid group_by parameter. Cannot be a filtered or grouped parameter. Tags have special handling. If key is an array, project may be used to pivot by project API keys.
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_6_count, goal_6_value, goal_7_count, goal_7_value, goal_8_count, goal_8_value, goal_9_count, goal_9_value, goal_10_count, goal_10_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 on any links active within a period

Examples

Get the clicks and conversions stats from the month of August 2012.

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

{
    "start_date": "2012-08-01T00:00:00Z",
    "end_date": "2012-08-31T00:00:00Z",
    "with_metadata": false,
    "with_conversions": true,
    "filters": [],
    "group_by": null,
    "sort_type": null,
    "sort_order": null,
    "pivot": null,
    "with_zeros": false,
    "pivot_sort_type": null,
    "pivot_sort_order": null,
    "page": null,
    "per_page": 10,
    "total_results": 0,
    "offset": 0,
    "last_offset": 0,
    "totals": {
        "clicks": 2963,
        "shares": 1060,
        "clicks_per_share": 2.7953,
        "conversions": {
            "pageviews": 5096,
            "goal_1": {
                "count": 51,
                "value": 0,
                "label": "Signups"
            },
            "goal_2": {
                "count": 251,
                "value": 0,
                "label": "Attendances"
            },
            "goal_3": {
                "count": 53,
                "value": 0,
                "label": "Comments"
            },
            "goal_4": {
                "count": 119,
                "value": 0,
                "label": "Subscriptions"
            },
            "goal_5": {
                "count": 0,
                "value": 0,
                "label": ""
            },
            "goal_6": {
                "count": 0,
                "value": 0,
                "label": ""
            },
            "goal_7": {
                "count": 0,
                "value": 0,
                "label": ""
            },
            "goal_8": {
                "count": 0,
                "value": 0,
                "label": ""
            },
            "goal_9": {
                "count": 0,
                "value": 0,
                "label": ""
            },
            "goal_10": {
                "count": 0,
                "value": 0,
                "label": ""
            },
            "goal_total": {
                "count": 474,
                "value": 0
            }
        }
    },
    "groups": []
}

Last updated 2013-02-06