awe.sm Stats API

Totals Endpoint

Retrieve all-time stats from links that were shared or created within a time period.

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.
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, `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

Have questions? Talk to us.