Analytics Report API

 

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.

Resource URI:

This URL applies to all documentation below and is only accessible by a GET request over HTTPS.

 https://data.simplereach.com/v1/analytics_reports 

Authentication:

The API is authenticated via header information. These values will be given to you by your Customer Success Manager, both are required.

Keys

SRTOKEN || Access token applies to an individual user.

SRAPPKEY || Application key applies to an organization.


Parameters:

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:

  • publisher
  • hour
  • day
  • month
  • year
  • content_id* 
  • article_id
  • publisher_article_id
  • author
  • tag
  • category
  • board_id
  • title
  • published_at
  • account_id

*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.

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.


Errors: 

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.

 

Codes 

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.

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.
 


Example Usage:

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:

https://data.simplereach.com/v1/analytics_reports
    ?board_id=
    &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:

 https://data.simplereach.com/v1/analytics_reports
    ?board_id=
    &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:

https://data.simplereach.com/v1/analytics_reports
    ?board_id=
    &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_idboard_id, or day. 

uniques is not included in any metric group and has to be requested individually.

 

Core Data

Metric group name: core_data

page_views
total_engaged_time
avg_engaged_time



Page View Breakouts

Metric group name: page_view_breakouts
 
direct_referrals
internal_referrals
other_referrals
search_referrals
social_referrals
desktop_referrals
mobile_referrals
tablet_referrals



Social Referral Breakouts

Metric group name: social_referral_breakouts
 
facebook_referrals
twitter_referrals
linkedin_referrals
pinterest_referrals
stumbleupon_referrals
reddit_referrals
googleplus_referrals
digg_referrals
delicious_referrals



Social Referral By Device

Metric group name: social_referral_by_device
 
desktop_facebook_referrals
mobile_facebook_referrals
tablet_facebook_referrals
desktop_twitter_referrals
mobile_twitter_referrals
tablet_twitter_referrals
desktop_linkedin_referrals
mobile_linkedin_referrals
tablet_linkedin_referrals
desktop_pinterest_referrals
mobile_pinterest_referrals
tablet_pinterest_referrals
desktop_stumbleupon_referrals
mobile_stumbleupon_referrals
tablet_stumbleupon_referrals
desktop_reddit_referrals
mobile_reddit_referrals
tablet_reddit_referrals
desktop_googleplus_referrals
mobile_googleplus_referrals
tablet_googleplus_referrals
desktop_digg_referrals
mobile_digg_referrals
tablet_digg_referrals
desktop_delicious_referrals
mobile_delicious_referrals
tablet_delicious_referrals



Social Actions

Metric group name: social_actions_by_network
 
twitter_followers
social_actions
facebook_actions
twitter_actions
linkedin_actions
pinterest_actions
stumbleupon_actions
googleplus_actions
delicious_actions



Paid Referrals

Metric group name: paid_referrals

paid_referrals
desktop_paid_referrals
mobile_paid_referrals
tablet_paid_referrals



Paid Social Referrals

Metric group name: paid_social_referrals

facebook_paid_referrals
twitter_paid_referrals
linkedin_paid_referrals
pinterest_paid_referrals
stumbleupon_paid_referrals
reddit_paid_referrals
digg_paid_referrals



Paid Social Referral By Device

Metric group name: paid_social_referrals_by_device

desktop_facebook_paid_referrals
mobile_facebook_paid_referrals
tablet_facebook_paid_referrals
desktop_twitter_paid_referrals
mobile_twitter_paid_referrals
tablet_twitter_paid_referrals
desktop_linkedin_paid_referrals
mobile_linkedin_paid_referrals
tablet_linkedin_paid_referrals
desktop_pinterest_paid_referrals
mobile_pinterest_paid_referrals
tablet_pinterest_paid_referrals
desktop_stumbleupon_paid_referrals
mobile_stumbleupon_paid_referrals
tablet_stumbleupon_paid_referrals
desktop_reddit_paid_referrals
mobile_reddit_paid_referrals
tablet_reddit_paid_referrals
desktop_digg_paid_referrals
mobile_digg_paid_referrals
tablet_digg_paid_referrals

 



Paid Content Recommendation Referrals

Metric group name: paid_content_recommendation_referrals
 
sr_outbrain_paid_referrals
outbrain_paid_referrals
taboola_paid_referrals
gemini_paid_referrals
gravity_paid_referrals

 


Paid Content Recommendation Referrals By Device

Metric group name: paid_content_recommendation_referrals_by_device
 
desktop_sr_outbrain_paid_referrals
mobile_sr_outbrain_paid_referrals
tablet_sr_outbrain_paid_referrals
desktop_outbrain_paid_referrals
mobile_outbrain_paid_referrals
tablet_outbrain_paid_referrals
desktop_taboola_paid_referrals
mobile_taboola_paid_referrals
tablet_taboola_paid_referrals
desktop_gemini_paid_referrals
mobile_gemini_paid_referrals
tablet_gemini_paid_referrals
desktop_gravity_paid_referrals
mobile_gravity_paid_referrals
tablet_gravity_paid_referrals



Paid Native Referrals

Metric group namepaid_native_referrals
 
nativo_paid_referrals
sharethrough_paid_referrals
polar_paid_referrals



Paid Native Referrals By Device

Metric group name: paid_native_referrals_by_device
 
desktop_nativo_paid_referrals
mobile_nativo_paid_referrals
tablet_nativo_paid_referrals
desktop_sharethrough_paid_referrals
mobile_sharethrough_paid_referrals
tablet_sharethrough_paid_referrals
desktop_polar_paid_referrals
mobile_polar_paid_referrals
tablet_polar_paid_referrals



Paid Other Referrals

Metric group namepaid_other_referrals
 
bing_display_paid_referrals
bing_search_paid_referrals
google_display_paid_referrals
google_search_paid_referrals
access_paid_referrals
amplify_paid_referrals



Paid Other Referrals By Device

Metric group namepaid_other_referrals_by_device
 
desktop_bing_display_paid_referrals
mobile_bing_display_paid_referrals
tablet_bing_display_paid_referrals
desktop_bing_search_paid_referrals
mobile_bing_search_paid_referrals
tablet_bing_search_paid_referrals
desktop_google_display_paid_referrals
mobile_google_display_paid_referrals
tablet_google_display_paid_referrals
desktop_google_search_paid_referrals
mobile_google_search_paid_referrals
tablet_google_search_paid_referrals
desktop_access_paid_referrals
mobile_access_paid_referrals
tablet_access_paid_referrals
desktop_amplify_paid_referrals
mobile_amplify_paid_referrals
tablet_amplify_paid_referrals


Versioning:

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.