The Analytics Report endpoint returns content data for a given board. This is the underlying API that we use to construct our reports in our app. Using the API, data can be rolled up in more complex combinations, using more fields and groupings to meet your specific needs.
This URL applies to all documentation below and is only accessible by a GET request over HTTPS.
The API is authenticated via header information. These values will be given to you by your Customer Success Manager, both are required.
SRTOKEN || Access token applies to an individual user.
SRAPPKEY || Application key applies to an organization.
board_id || Required. The 24 character id of the board.
day[gte] || Restricts the results to data collected after or during the day specified. Defaults to the board start date. Format: yyyy-mm-dd
day[lte] || Restricts the results to data collected before or during the day specified. Defaults to the dashboard’s end date. Format: yyyy-mm-dd
fields || A comma-separated list of which fields to return. All fields are listed further down the page in their metric groups, with the exception of uniques, which is not included in any metric group and must be requested specifically. Be aware that there is a large performance impact to requesting uniques, especially when grouping by multiple fields, and requests can time out.
metric_groups || Each metric group represents a set of related fields. A metric group can be defined instead of listing all the individual fields. More than one can be specified. A list of the available metric groups is further down on the page.
sort || Required. Indicates which requested metric to sort results by, e.g. page_views will sort by page views and -page_views will sort descending. It is recommended to sort by something that will preserve a consistent sort order when paginating results. The sort field must be one of the fields included in the fields or metric_groups parameter. uniques is not a sortable metric.
group_by || Comma-separated list of which values to use to group results. Multiple values can be included. For example, grouping by content_id returns the metrics for each content item and grouping by content_id and day will roll up the performance of each content_id for each day in the report range. Below is the list of available options:
*Grouping by content_id automatically returns content-level metadata like the title and URL.
tags || A comma-separated list of values, of which only one has to be matched.
authors || A comma-separated list of values, of which only one has to be matched.
categories || A comma-separated list of values, of which only one has to be matched.
limit || Number of results per page. Default is 30, maximum is 1000. We recommend keeping limits below 100 whenever possible.
page || Used to paginate through results.
utc_offset || UTC offset for which timezone is being specified. Defaults to the user’s timezone settings in the application based on the SRTOKEN used to authenticate. Supported values are integers between -11 and 13.
SimpleReach uses conventional HTTP response codes to indicate success and failure of the API call. In general codes in the 200’s are successful, codes in the 400’s represent an error in how the API was called, and codes in the 500’s represent internal failures with SimpleReach systems.
200 || Worked as expected.
401 || Unauthorized request. There was a problem authenticating or you are requesting information from a dashboard that you do not have access to. Check that your SRAPPKEY and SRTOKEN are correct, provided as header attributes, and that you can access the same board on the application front end.
422 || Invalid values were passed to the API. For example, a group_by or sort for a field that is unsupported, does not exist, or a required field was not provided.
429 || Rate limit exceeded. API users are limited to one concurrent request at a time. Please wait for a response to complete before starting a new request. If you have multiple processes running in parallel you may be exceeding your limit.
500 || Internal server error with SimpleReach systems. We would appreciate reporting any 500 errors to your Customer Success Manager. Include the time(s) the request was made, exact URL or request including all parameters, HTTP response code, error message (if available), and the SRTOKEN and SRAPPKEY used when you report the problem.
504 || The request has timed out. In most cases if you retry the request will be successful. It is recommended to build retry logic into any automated API interactions.
Errors can happen for many reasons. It is recommended that you write code that gracefully handles error conditions and retries on common traffic and network-related errors such as timeouts.
Report any errors that you cannot recover from via retry to your SimpleReach Customer Success Manager. Please be sure to include the following when reporting any problems: time(s) the request was made, exact URL or request including all parameters, HTTP response code, error message (if available), and the SRTOKEN and SRAPPKEY used.
The following examples highlight some common use cases for the API. These are not full usage examples, they only include the full resource URI and examples of parameter usage.
A high level report showing a few key metrics for a set of content:
&day[gte]=2017-03-15 &day[lte]=2017-03-22 &content_item.tags[in]= &content_item.authors[in]= &group_by=board_id &metric_groups=core_data &sort=-page_views
A report showing the same key metrics, but presented by content item:
&day[gte]=2017-03-15 &day[lte]=2017-03-22 &content_item.tags[in]= &content_item.authors[in]= &group_by=content_id &limit=30 &metric_groups=core_data &page=1 &sort=-social_referrals
A report showing page views and uniques for all content items on a board, broken down by day:
&day[gte]=2017-03-15 &day[lte]=2017-03-22 &fields=page_views,uniques &group_by=content_id,day &sort=-page_views
Full List of Fields and Metric Groups:
Fields listed below are organized by metric group. Each field can be requested individually or the whole set can be requested by metric group, which will return all listed fields in the group.
Most fields return a count. Time-related fields are returned in seconds. uniques currently can be returned when grouping by content_id, board_id, or day.
uniques is not included in any metric group and has to be requested individually.
Metric group name: core_data
Page View Breakouts
Metric group name: page_view_breakouts
Social Referral Breakouts
Metric group name: social_referral_breakouts
Social Referral By Device
Metric group name: social_referral_by_device
Metric group name: social_actions_by_network
Metric group name: paid_referrals
Paid Social Referrals
Metric group name: paid_social_referrals
Paid Social Referral By Device
Metric group name: paid_social_referrals_by_device
Paid Content Recommendation Referrals
Metric group name: paid_content_recommendation_referrals
Paid Content Recommendation Referrals By Device
Metric group name: paid_content_recommendation_referrals_by_device
Paid Native Referrals
Metric group name: paid_native_referrals
Paid Native Referrals By Device
Metric group name: paid_native_referrals_by_device
Paid Other Referrals
Metric group name: paid_other_referrals
Paid Other Referrals By Device
Metric group name: paid_other_referrals_by_device
Any destructive changes to APIs will be versioned, followed by a deprecation period of the previous version. Structural changes, including removing fields, will be considered destructive. Adding a new field will not be considered a destructive change.