Part of the Data Mining APIs

 

Returns feed engagements scores for a specified feed hash(es) over a span of time. Optionally it returns a summarized view of the data.

 

Feed Engagement is the sum of all engagement generated by any post in a feed - even from posts no longer int he physical RSS feed but found in the feed's archive.  So, if a post published months ago receives engagement today it will count towards today's feed engagement value.  Post engagement is the weighted sum of all social interactions by users across the web with that post.  See the Metrics API to get individual post level social interaciton counts.

 

The Feed Engagement API requires an initial call to the Feed Information API to get the Postrank feed id for the feed url.

 

 

GET/POST Parameters

 

appkey = [ string ]	Your Application Key
format = [ json | xml | rss]	The format of the returned data.
id = [ md5 ]	PostRank identifier of the feed. (only for GET). Lookup id using Feed Information API.
feed[] = [ [md5] ]	PostRank identifier of the feed. (only for POST) Lookup id using Feed Information API.
start_time = [ int ]	Start time (as unix timestamp) inclusive
end_time = [ int ]	End time (as unix timestamp) inclusive
summary = true	(Optional) Return data in summary view
mode = daily | hourly	(Optional) The time segment for engagement. Defaults to daily

 

Response Data

 

<feed_hash>	Postrank feed id key to map to multiple feeds in input. Always present even in the single feed case.
engagement = [ int, float ]	UNIX timestamp, engagement value pair
count = [ int ]	Number of time periods where engagement was found over the interval
average [ float ]	average engagement for each non-zero period in the time interval
min [ float ]	smallest non-zero engagement value found in the time interval
max [ float ]	largest engagement value found in the time interval
sum [ float ]	total engagement from each period for the time interval

 

 

Example: Daily Engagement for a feed

 

For a known feed, identified by PostRank Feed id, get the daily feed engagement between the time periods indicated by the start_time and end_time UNIX timestamps.

 

http://api.postrank.com/v2/feed/engagement?appkey=YOUR_APP_KEY&id=421df2d86ab95100de7dcc2e247a08ab&start_time=1233567890&end_time=1234567890&format=json

 

Response

{
   "421df2d86ab95100de7dcc2e247a08ab": 
   {
      "1233896400": "169.773",      
      "1233723600": "335.983",
      "1234069200": "186.95",
      "1233550800": "78.671",
      "1234414800": "85.563",
      "1234242000": "86.668",
      "1233637200": "148.615",
      "1234501200": "1151.73",
      "1234328400": "164.681",
      "1234155600": "120.774",
      "1233982800": "74.466",
      "1233810000": "449.037"
   }
}

 

Example: Hourly Feed Engagement

 

Add mode=hourly to set the period mode to hourly.  This buckets the engagement to a fine granularity.

 

http://api.postrank.com/v2/feed/engagement?appkey=YOUR_APP_KEY&id=421df2d86ab95100de7dcc2e247a08ab&start_time=1233567890&end_time=1233667890&mode=hourly&format=json

 

Response

{ 
   "421df2d86ab95100de7dcc2e247a08ab": 
   {
      "1233604800": "0.034",
      "1233619200": "2.022",
      "1233608400": "20.037",
      "1233590400": "0.031",
      "1233565200": "6.041",
      "1233550800": "0.025",
      "1233594000": "7.032",
      "1233583200": "2.032",
      "1233554400": "6.019",
      "1233612000": "4.032",
      "1233597600": "5.03",
      "1233579600": "0.02",
      "1233568800": "4.021",
      "1233637200": "2.017",
      "1233633600": "2.024",
      "1233626400": "2.024",
      "1233622800": "0.012",
      "1233558000": "8.027",
      "1233572400": "2.029",
      "1233601200": "0.034",
      "1233586800": "0.044",
      "1233615600": "0.023",
      "1233576000": "0.023",
      "1233561600": "4.035",
      "1233630000": "4.02"
   }
}

 

 

Example: Feed Engagement Summary

 

Add the summary=true parameter to just get a summary of engagement over the time period.  This style returns basic statistics of the data set instead of the data itself.  This is helpful especially in cases where there are many periods involved.

 

http://api.postrank.com/v2/feed/engagement?appkey=YOUR_APP_KEY&id=421df2d86ab95100de7dcc2e247a08ab&start_time=1233567890&end_time=1234567890&format=json&summary=true

 

Response

{ 
   "421df2d86ab95100de7dcc2e247a08ab":
   { 
      "count": 273, 
      "average": 92.750915750916,
      "min": 16.0, 
      "max": 1299.0, 
      "sum": 25321.0 
   }
}