awe.sm Stats API

Range Intervals Endpoint

Retrieve graph-ready stats for a given time period.

GETapi.awe.sm/stats/range/intervals.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.
start_date	date	The beginning of the period for which you want data, rounded to previous hour.
end_date	date	The end of the period for which you want data, rounded to next hour.
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.
interval	string	Period of time between stats: `hour`, `day`, or `week`. Limited to 500 intervals. Requires `start_date` after 2010-06-04. Default is `day`.
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`.
with_zeros	boolean	Flag to include intervals with no activity. 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`.

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 total values similar to this API without interval values

Example

Get the daily activity totals from the first week of September 2011, including days where there was no activity.

GET http://api.awe.sm/stats/range/intervals.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&start_date=2011-09-01&end_date=2011-09-08&with_zeros=true

{
    "end_date": "2011-09-08T00:00:00Z",
    "filters": [],
    "group_by": null,
    "groups": [],
    "interval": "day",
    "last_offset": 0,
    "offset": 0,
    "page": null,
    "per_page": 10,
    "sort_order": null,
    "sort_type": null,
    "start_date": "2011-09-01T00:00:00Z",
    "total_results": 0,
    "totals": {
        "intervals": [
            {
                "clicks": 4,
                "clicks_per_share": 2,
                "day": "2011-09-01T00:00:00Z",
                "shares": 2
            },
            {
                "clicks": 1,
                "clicks_per_share": 1,
                "day": "2011-09-02T00:00:00Z",
                "shares": 1
            },
            {
                "clicks": 0,
                "clicks_per_share": 0,
                "day": "2011-09-03T00:00:00Z",
                "shares": 0
            },
            {
                "clicks": 3,
                "clicks_per_share": 1,
                "day": "2011-09-04T00:00:00Z",
                "shares": 3
            },
            {
                "clicks": 2,
                "clicks_per_share": 1,
                "day": "2011-09-05T00:00:00Z",
                "shares": 2
            },
            {
                "clicks": 9,
                "clicks_per_share": 1,
                "day": "2011-09-06T00:00:00Z",
                "shares": 9
            },
            {
                "clicks": 0,
                "clicks_per_share": 0,
                "day": "2011-09-07T00:00:00Z",
                "shares": 0
            }
        ]
    },
    "with_conversions": false,
    "with_metadata": false,
    "with_zeros": true
}

Last updated 2012-01-23

Have questions? Talk to us.