Content Endpoints

 
/score/current.json?url=http://www.example.com/article/title
 

These are the available content routes for the API. Please note: All query string parameter values should be URL encoded.

CAVEATS

Where a URL parameter is required: some pieces of content are shared under a common canonical URL. If SimpleReach is passed a variant of the canonical URL, we will return the canonical url in the url field of the response object. The original_url field will be passed back as part of the JSON object is a canonical URL is found to not be the same as the passed in URL.

/V1/SCORE/TOP.{JSON,RSS} 

For a given account, return in RSS/Atom or JSON format the top 10 articles sorted by score. The number of articles returned can be modified using the count query string parameter. A maximum of 100 content items can be retrieved.

Example:

/score/top.rss?account_id=000000000000000000000000
 


  … removed for brevity …

 

 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
… removed for brevity …
</feed>

This call can also be done in a more granular fashion. Tags, authors, or categories can be used in the field query string parameter and then the value query string parameter is used for the search term. The value parameter should be url encoded if there are any characters (such a colon) that may not be properly passed in URL query strings.

Example:

/score/top.rss?account_id=000000000000000000000000&field=tag&value=sports
 


  … removed for brevity …

 

/V1/SOCIAL/COUNTS.JSON 

Get the social counts and the current SimpleReach score for a given URL.

Example:

/social/counts.json?url=http%3A%2F%2Fwww.example.com%2Farticle%2Ftitle
 
{
  "url": "http://www.example.com/article/title/",
  "counts": { "actions": 160,
  "facebook": { "likes": 18 },
  "twitter": {"tweets": 142} },
  "score": { "current": 18.284 }
}
 

/V2/CONTENT/REPORT.JSON 

Board Report is a variant of the content report (above) that similar results that are specific to a single board. The results returned will show count data for content items for the time period supplied. If a period greater than one hour is specified, the data returned will be an aggregate of every hour returned.

board_id: 24 character id of the board the export is to be run for

start_date: start date for report query eg: "1377006303000"

end_date: end date for report query eg: "1377468060000"

page: page to return from results

count: items per page AND items to return (if not paging) max items = 50

extra_fields: extra fields can now be requested in the response, the possible fields are below

Paging is implemented using the "page" an "count" querystring parameters as well as the "total_records" value returned in the response object. The count querystring is limited to a maximum of "50".

Extra fields (optional) is a comma separated list of fields that will be returned when specified in the request using the 'extra_fields' query string parameter. The default fields are: title, url, hour, published_at, pageviews_total, social_actions, social_referrals the possible optional fields are as follows and can be specified in any order: 'tags', 'authors', facebook_actions', 'twitter_actions', 'linkedin_actions', 'stumbleupon_actions', 'delicious_actions', 'pinterest_actions', 'googleplus_actions', 'uniques', 'facebook_referrals', 'twitter_referrals', 'linkedin_referrals', 'digg_referrals', 'stumbleupon_referrals', 'reddit_referrals', 'delicious_referrals', 'pinterest_referrals', 'googleplus_referrals', 'search_referrals', 'direct_referrals', 'internal_referrals', 'other_referrals'

Example

/V2/content/report.json?board_id=000000000000000000000000&start_date=1377006303000&end_date=1377468060000[&extra_fields=facebook_referrals%2Cfacebook_actions]
 
{
  "items": [{
    "referrer_social": 0,
    "hour": "2013-08-25 22:00:00",
    "title": "Article 392204",
    "url": "http://www.example.com/article/392204",
    "pageviews_total": 5430,
    "published_at": "2014-09-20 18:00:00",
    "social_actions": 86
    [,"facebook_referrals": "45",
    "facebook_actions": "52"]
  }],
  "updated": "2013-10-18 16:35:10.293417",
  "subtitle": "Powered By SimpleReach",
  "feed_url": "http://api.simplereach.com/v2/content/report.json?board_id=000000000000000000000000&start_date=1377006303000&end_date=1377468060000",
  "title": "Content Report for 000000000000000000000000, between 1377006303000 and 1377468060000",
  "total_records": 500
}

 

/V2/CONTENT/EXPORT.JSON 

The content export end point provides a user with the ability to request a CSV export be run via the API. The end point requires the following parameters:

board_id: 24 character id of the board the export is to be run for

email: the email address to receive notification of export completion

export_type: the type of report - content, day, author, channel, tag OR custom_tag

params: is a URL encoded JSON document describing the content report

order: sort order for report eg: referrer_social desc

start_date: start date for report query eg: "Fri, 01 Aug 2014 00:00:00 EDT -04:00"

end_date: end date for report query eg: "Fri, 08 Aug 2014 23:59:59 EDT -04:00"

tags: an array of tags to be queried eg: ["George Michael"]

authors: an array of tags to be queried eg: ["Gary The Goat", "Wendel Sailor"]

channels: an array of tags to be queried eg: ["Editorial", "Blog"]

The API will return a JSON document containing the export id and a status. Once the content report is created, an email will be sent to the email address provided in the request. This email will contain a link to the content report which can then be downloaded.

Params example:

%7B%22order%22%3A%5B%22referrer_social%20desc%22%5D%2C%22start_date%22%3A%20%22Fri%2C%2001%20Aug%202014%2000%3A00%3A00%20EDT%20-04%3A00%22%2C%22end_date%22%3A%20%22Fri%2C%2008%20Aug%202014%2023%3A59%3A59%20EDT%20-04%3A00%22%2C%22tags%22%3A%20%5B%22George%20Michael%22%5D%7D
 
{
"order": ["referrer_social desc"],
"start_date": "Fri, 01 Aug 2014 00:00:00 EDT -04:00",
"end_date": "Fri, 08 Aug 2014 23:59:59 EDT -04:00",
"tags": ["George Michael"]
}

Example:

/V2/content/export.json?board_id=000000000000000000000000&email=wylecyote@simplereach.com&export_type=content¶ms=%7B%22order%22%3A%5B%22referrer_social%20desc%22%5D%2C%22start_date%22%3A%20%22Fri%2C%2001%20Aug%202014%2000%3A00%3A00%20EDT%20-04%3A00%22%2C%22end_date%22%3A%20%22Fri%2C%2008%20Aug%202014%2023%3A59%3A59%20EDT%20-04%3A00%22%2C%22tags%22%3A%20%5B%22George%20Michael%22%5D%7D
 
{
"status": "In Progress",
"request": {
"board_id": "000000000000000000000000",
"export_type": "content",
"params": {
"order": "referrer_social desc",
"end_date": "2014-09-19 15:00:00-04:00",
"start_date": "2014-09-19 14:00:00-04:00"
},
"email": "wylecyote@simplereach.com"
}
}

/V2/CONTENT/BY_DAY.JSON 

Retrieves daily social action metrics for each content item on a board.

board_id: 24 character id of the board the export is to be run for

start_date: start date for the report query in milliseconds since the epoch

end_date: end date for the report query in milliseconds since the epoch

page: page number for the purposes of paging * optional, defaults to 1

count: number of records to return * optional, defaults to 100

Each report may span a maximum of 7 days and 100 records. Use the "total_records" field in the response object to allow paging. The 'count' and 'page' parameters can be specified independently.

Example:

/v2/content/by_day.json?board_id=000000000000000000000000&start_date=1412692813095&end_date=1412865613095[&page=1&count=100]
 
{
"title": "Content Report for board 000000000000000000000000, between 1412692813095 and 1412865613095",
"subtitle": "Powered by SimpleReach",
"feed_url": "http://api.simplereach.com/v2/content/by_day.json?board_id=000000000000000000000000&start_date=1412692813095&end_date=1412865613095",
"updated": "2014-10-07 10:50:48.033444",
"items": {
"total_records": 5000,
"2014-10-07": {
"00000000000000000000000000000000": {
"googleplus_referrers": 0,
"twitter_actions": 0,
"referrer_none": 2,
"stumbleupon_actions": 0,
"delicious_referrers": 0,
"referrer_search": 0,
"reddit_referrers": 0,
"referrer_other": 0,
"delicious_actions": 0,
"facebook_referrers": 0,
"linkedin_actions": 0,
"digg_referrers": 0,
"referrer_social": 0,
"pinterest_referrers": 0,
"pinterest_actions": 0,
"googleplus_actions": 0,
"linkedin_referrers": 0,
"facebook_actions": 0,
"social_actions": 0,
"referrer_internal": 0,
"twitter_referrers": 0,
"pageviews_total": 2,
"stumbleupon_referrers": 0
},
...,
}
...,
}
}