sysomos heartbeat api documentation - ccehub - home · heartbeat api documentation sysomos inc.,...

30
1 Sysomos API Documentation, Updated February 2014 Heartbeat API Documentation Sysomos Inc., Marketwired. Revised: February 2014

Upload: hoangtram

Post on 24-May-2018

243 views

Category:

Documents


4 download

TRANSCRIPT

Page 1: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

1 Sysomos API Documentation, Updated February 2014

Heartbeat API Documentation Sysomos Inc., Marketwired. Revised: February 2014

Page 2: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

2 Sysomos API Documentation, Updated February 2014

Preface

Heartbeat provides several REST based APIs through which collected information can be retrieved in XML

format. Data returned via XML can be used by clients to build customized dashboards, integrate Sysomos

heartbeat data within their CRM systems or design applications & dashboards that could work on the API data

from their respective heartbeat accounts. We currently do not provide development services for integrating our

API’s within client’s existing applications. All our major clients use their in-house or contracted development

teams for their development projects feeding data from their heartbeat accounts.

For most of your needs concerning heartbeat data and analytics on your heartbeat data, Measure API

and RSS Content API will suffice. Sysomos however does provide additional APIs to return data related to

Influencers, Content, Buzzgraph and Info. We also provide write API functionality to enable clients to interact

directly to their heartbeat data via API and Widget options for them to be able to use Sysomos’ analytics directly

as widgets as detailed in this document.

Volume of API calls to client heartbeats is administrated by a fair use policy of allowing 1500 API calls

per day. Each API call can provide up to 500 mention results; thus 1500 API calls can deliver up to a maximum of

720,000 social media mentions per day. This suffices most data needs given the average daily volume of new

data in all Sysomos heartbeats is significantly less than 100,000 mentions per day. For e.g. if your heartbeat gets

50,000 new mentions per day & known that every API call returns up to 500 results, you would only need 100

API calls (50000 / 500 = 100) to fetch all the 50,000 mentions including any social metadata (demographics,

sentiment, authority etc.) associated with the mentions via RSS Content API. For higher API call needs, please

reach sales for pricing.

API access comes at an additional API licensing cost, for details contact your Account Executive or Sales

at Sysomos. Sysomos provides demo access to API for a charge free period of 2 weeks, which is extendible at

Sysomos’ discretion if there is a genuine business need for extended trial. Sysomos Client Success Managers

and/or Social Media Specialists are the first point of contact for any API related inquiries. Feel free to reach them

for any questions or concerns about our API capabilities and how they can be best used to serve your business

needs.

Page 3: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

3 Sysomos API Documentation, Updated February 2014

Index

TITLE PAGE

1 HEARTBEAT MEASURE API 4

2 HEARTBEAT RSS CONTENT API 7

3 OTHER APIS

HEARTBEAT INFLUENCER API

11

HEARTBEAT CONTENT API 14

HEARTBEAT BUZZGRAPH API 16

HEARTBEAT WORDCLOUD API 19

HEARTBEAT INFO API 21

4 ENGAGEMENT APIS 23

5 WIDGETS 28

6 CONTACT US 30

Page 4: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

4 Sysomos API Documentation, Updated February 2014

Heartbeat Measure API

This API provides the raw numbers and counts as presented in the Measure tab of Heartbeat.

The format of the URL is:

(i) the API key (ii) the Heartbeat ID, (iii) the date range (iv) a list of filters, and optionally (v) a list of tags required in the output.

Important Note: The part of the URL with the date range and list of filters is exactly the same as in the web user interface for the Heartbeat’s Measure tab. The easiest way to produce this part of the url is to login to the web UI, navigate to the Measure tab, select the list of filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.

URL Parameter

Explanation

apiKey API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.

sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.

cTs Comma separated list of tags to be included in the output. The tag name is in the same format as in fTs and hence the web UI can be used to find the tag names. Simply use the tag as filter on the Measure tab and copy it from the fTs parameter of the URL.

Page 5: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

5 Sysomos API Documentation, Updated February 2014

Example 1:

http://api.sysomos.com/v1/heartbeat/measure?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&cTs=~SENTIMENT~pos,~SENTIMENT~neg,~SENTIMENT~none

The URL above uses a 7 day period (dRg) with the filter tag (fTs) equal to “me”. The same set of filters is used on the following web UI page:

http://hb.sysomos.com/hb2/?hid=<YOUR-HEARTBEAT-ID>&tab=statistics&dRg=7&fTs=me

The list of tags included in the output are ~SENTIMENT~pos , ~SENTIMENT~neg, and ~SENTIMENT~none which are for Positive, Negative and No sentiment. This will produce output similar to:

Page 6: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

6 Sysomos API Documentation, Updated February 2014

Example 2:

http://api.sysomos.com/v1/heartbeat/measure?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&sDy=2010-10-07&eDy=2010-10-08&fTs=dunkin-coffee,promotion,~COUNTRY~US,~SOURCE~t&cTs=dunkin-coffee,promotion

The URL above uses the period between October 7th 2010 (sDy) and October 8th 2010 (eDy) with the filter tag (fTs) equal to dunkin-coffee, promotion, ~COUNTRY~US and ~SOURCE~t. The same set of filters is used on the following web UI page:

http://hb.sysomos.com/hb2/?hid=<YOUR-HEARTBEAT-ID>&tab=statistics&fTs=dunkin-coffee,promotion,~COUNTRY~US,~SOURCE~t&sDy=2010-10-07&eDy=2010-10-08

The tags included in the output are dunkin-coffee and promotion which are defined as custom tags in this Heartbeat. This will produce output similar to:

Page 7: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

7 Sysomos API Documentation, Updated February 2014

Heartbeat RSS Content API

As with the Content API, this API returns content information for the mentions collected by Heartbeat.

The format of the URL is:

(i) the API key,

(ii) the Heartbeat ID,

(iii) the date range,

(iv) a list of filters, and optionally

(v) a list of tags required in the output.

The part of the URL with the date range and list of filters is exactly the same as in the web user interface for the Heartbeat’s Measure tab. The easiest way to produce this part of the url is to login to the web UI, navigate to the Measure tab, select the list of filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.

URL Parameter

Explanation

apiKey

API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.

sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the

Page 8: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

8 Sysomos API Documentation, Updated February 2014

URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.

cTs Comma separated list of tags to be included in the output. The tag name is in the same format as in fTs and hence the web UI can be used to find the tag names. Simply use the tag as filter on the Measure tab and copy it from the fTs parameter of the URL.

startid A 0-based integer index specifying the initial record to retrieve in the result set. In conjunction with the max parameter, can be used to batch results for a given query.

max The maximum number of records to retrieve.

Example:

http://api.sysomos.com/v1/heartbeat/rsscontent?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&cTs=~SENTIMENT~pos,~SENTIMENT~neg,~SENTIMENT~none&startid=0&max=10

Output:

NOTE: For Twitter no data is provided in the Title and Content XML Tags i.e. the raw text for the tweet. Tweet ID,

Tweet Web URL and Twitter API URL are provided that can be used to fetch that data directly from twitter.

<beatApi xmlns="http://www.blogscope.net/api/namespace/schema/SearchResponse">

<beatRequest>

<heatbeatID>3692</heatbeatID>

<key>YOUR API KEY</key>

<size>1</size>

<offset>0</offset>

</beatRequest>

<beatResponse>

<totalResults>91542</totalResults>

<beat>

<docid>3692:10532076</docid>

<mediaType>TWITTER</mediaType>

<time>2012-08-16T12:04:07-04:00</time>

<title>tweet</title>

<content>http://hb.sysomos.com/hb2/sidebar/?hid=3692&bid=10532076</content>

Page 9: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

9 Sysomos API Documentation, Updated February 2014

<link>http://hb.sysomos.com/hb2/sidebar/?hid=3692&bid=10532076</link>

<location>

<country>th</country>

<locationString>chiangrai-;thailand-?</locationString>

</location>

<influenceLevel>6</influenceLevel>

<sentiment>NONE</sentiment>

<tag>

<value>t</value>

<displayName>TWITTER</displayName>

<systemType>SOURCE</systemType>

</tag>

<tag>

<value>-1</value>

<displayName>-1</displayName>

<systemType>AGE</systemType>

</tag>

<tag>

<value>none+</value>

<displayName>Not Assigned</displayName>

<systemType>ASSIGNED</systemType>

</tag>

<tag>

<value>none</value>

<displayName>none</displayName>

<systemType>SENTIMENT</systemType>

</tag>

<tag>

<value>blackberry</value>

<displayName>blackberry</displayName>

</tag>

Page 10: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

10 Sysomos API Documentation, Updated February 2014

<tag>

<value>TH</value>

<displayName>Thai</displayName>

<systemType>LANGUAGE</systemType>

</tag>

<tag>

<value>unknown</value>

<displayName>Unknown Gender</displayName>

<systemType>GENDER</systemType>

</tag>

<tag>

<value>1204</value>

<displayName>1204</displayName>

<systemType>T</systemType>

</tag>

<tweetid>236131231568367616</tweetid>

<tweetJsonLink>http://api.twitter.com/1/statuses/show.json?id=236131231568367616

&include_entities=true</tweetJsonLink>

<tweetHbLink>http://hb.sysomos.com/hb2/sidebar/?hid=3692&bid=10532076

</tweetHbLink>

<twitterFollowers>1160</twitterFollowers>

<twitterFollowing>129</twitterFollowing>

</beat>

<count>1</count>

</beatResponse>

</beatApi>

Other APIs Heartbeat Influencer API This API returns the list of influencers as shown in Heartbeat’s Top Influencers tool.

Page 11: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

11 Sysomos API Documentation, Updated February 2014

The URL must contain

(i) the API key (ii) the Heartbeat ID (iii) the date range (iv) a list of filters (v) the social media type (vi) and optionally the number of influencers to return (vii) and optionally the number of mentions to return for each influencer

As with the Measure API, the easiest way to produce this part of the URL is to login to the web UI, navigate to the Top Influencer tool, select the source and filters as required, and copy the values of the parameters fTs, dRg, tTb, sDy and eDy as present in the URL.

URL Parameter

Explanation

apiKey API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.

sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.

tTb Type of social media to retrieve top influencers for. The value of this can be ‘blogposts’, ‘twitter’, ‘forums’, or ‘news’. Defaults to ‘twitter’ when not specified.

maxInfluencers The maximum number of influencers to return. The default value is 10.

maxMentions The number of mentions returned for each influencer. A mention contains data for a tweet/post/article produced by the influencer. Default value of 25.

Example 1:

http://api.sysomos.com/dev/v1/heartbeat/influencer?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&tTb=twitter&dRg=7&fTs=me,~SENTIMENT~neg

Page 12: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

12 Sysomos API Documentation, Updated February 2014

This URL returns the top influencers for Twitter (tTb) over the last 7 days (dRg) who made comments with negative sentiment regarding the keywords defined in ‘me’ (fTs). It is equivalent the UI page:

http://hb.sysomos.com/hb2/?hid=YOUR-HEARTBEAT-ID&tab=statistics&sTb=influencers&tTb=twitter&dRg=7&fTs=me,~SENTIMENT~neg

The XML response would be similar to the following:

Example 2:

http://api.sysomos.com/dev/v1/heartbeat/influencer?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&tTb=blogposts&sDy=15615&eDy=15617&fTs=me&scO=Recency&maxSample=3000&maxInfluencers=4

This URL returns the top influencers for Blogs (tTb) between October 1st’2012 (sDy) and October 3rd’2012 (eDy) who mentioned the filter ‘tim-hortons’(fTs). It only returns the top four influencers (maxInfluencers). Other than the number of influencers it is equivalent to the UI page:

http://hb.sysomos.com/hb2/?hid=YOUR_HB_ID&startid=0&maxC=6&max=20&tab=statistics&sTb=influencers&tTb=blogposts&sDy=15615&eDy=15617&fTs=me&scO=Recency&maxSample=3000&maxToShow=4

Page 13: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

13 Sysomos API Documentation, Updated February 2014

The XML response (tags minimized to show all four influencers):

Page 14: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

14 Sysomos API Documentation, Updated February 2014

Heartbeat Content API

In addition to the RSS Content API which allows use of filters, Heartbeat also offers a more low-level content API for mirroring the entire database of social mentions locally. Content API is a legacy version of RSS Content API, it is recommended to use RSS Content API over this API if you are a new client.

The URL requires

(i) the API key and (ii) the Heartbeat ID, and optionally (iii) the start date (iv) the end date (v) the number of mentions to return and (vi) a starting offset

URL Parameter

Explanation

apiKey API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

addedAfter The GMT start date - only content added after this date will be returned. The format of this parameter is yyyy-mm-ddThh:mm:ssZ (e.g. 2010-05-22T16:30:00Z).

addedBefore The GMT end date - only content added before this date will be returned. The format of this parameter is yyyy-mm-ddThh:mm:ssZ (e.g. 2010-05-22T16:30:00Z).

size The number of mentions to return, with 100 being the default. Mentions are returned in chronological order starting with the earliest.

offset The number of mentions to skip in the return. An offset of 10 would mean that the first mention returned is the 11th mention for the specified time period.

Example:

http://api.sysomos.com/dev/v1/heartbeat/content?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&offset=0&size=10&addedAfter=2010-10-15T13:00:00Z&addedBefore=2010-10-18T13:00:00Z

This URL returns content for the period between 1pm GMT, October 15th 2010 (addedAfter) and 1pm GMT, October 18th (addedBefore). The response has 10 mentions (size), starts at the first mention (offset), and looks similar to the below:

Page 15: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

15 Sysomos API Documentation, Updated February 2014

Page 16: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

16 Sysomos API Documentation, Updated February 2014

Heartbeat Buzzgraph API

This API returns the word-pair metrics associated with Heartbeat’s Buzzgraph tool. If you are primarily interested in the image, we provide a Buzzgraph widget for webpage integration (see Heartbeat Widgets documentation), so you do not need to go through the API and code your own graph.

Similar to the Measure API, the URL must contain

(i) the API key, (ii) the Heartbeat ID, (iii) the date range, (iv) a list of filters, and optionally (v) the number of word pairs to return.

The easiest way to produce this part of the URL is to login to the web UI, navigate to the Buzzgraph tool, select the filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.

URL Parameter

Explanation

apiKey API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.

sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.

size The number of word-pairs to return. The default is 30.

Example:

Page 17: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

17 Sysomos API Documentation, Updated February 2014

http://api.sysomos.com/v1/heartbeat/buzzgraph?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=2&fTs=me,~SOURCE~n

This URL returns the Buzzgraph word-pairs for content collected during the last 2 days (dRg) filtered for the tag “me” in news sources (fTs). It is equivalent to the information in the UI page:

http://hb.sysomos.com/hb2/?hid=YOUR-HEARTBEAT-ID&tab=statistics&sTb=analytics&dRg=2&fTs=me,~SOURCE~n

Each word-pair in the XML response includes a number signifying the relative strength of association between those words:

Page 18: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

18 Sysomos API Documentation, Updated February 2014

Page 19: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

19 Sysomos API Documentation, Updated February 2014

Heartbeat Wordcloud API

This API returns the wordcloud metrics associated with Heartbeat’s wordcloud tool. If you are primarily interested in the image, we provide a wordcloud widget for webpage integration as a link at the bottom of the API returned results, this is a dynamic widget that changes based on the filters.

Similar to the Measure API, the URL must contain

(i) the API key, (ii) the Heartbeat ID, (iii) the date range, (iv) a list of filters, and optionally

The easiest way to produce this part of the URL is to login to the web UI, navigate to the Wordcloud tool, select the filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.

URL Parameter

Explanation

apiKey API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.

sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.

fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.

Example:

Page 20: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

20 Sysomos API Documentation, Updated February 2014

http://api.sysomos.com/v1/heartbeat/wordcloud?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=2&fTs=me,~SOURCE~n

This URL returns the wordcloud words for content collected during the last 2 days (dRg) filtered for the tag “me” in news sources (fTs). It is equivalent to the information in the UI page:

http://hb.sysomos.com/hb2/?hid=YOUR-HEARTBEAT-

ID&tab=statistics&sTb=analytics&dRg=2&fTs=me,~SOURCE~n

Page 21: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

21 Sysomos API Documentation, Updated February 2014

Heartbeat Info API

This API returns a Heartbeat's settings, including general settings, queries and tagging rules, user

details (including twitter setup) and configured Facebook pages.

The URL must contain

(I) the API key, and

(II) the Heartbeat ID. The service is located at http://api.sysomos.com/v1/heartbeat/info?

URL Parameter

Explanation

apiKey

API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

Example 1:

http://api.sysomos.com/v1/heartbeat/info?hid=YOUR-HEARTBEAT-ID&apikey=YOUR-APIKEY

Page 22: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

22 Sysomos API Documentation, Updated February 2014

Page 23: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

23 Sysomos API Documentation, Updated February 2014

Engagement APIs

In addition to the standard read-only REST API, Heartbeat provides a write-access REST-API to affect changes in Heartbeat from an external application.

Currently Heartbeat provides API to:

1. add workflow comments to individual beats 2. to post to walls of Facebook fan pages configured within Heartbeat 3. and to post and reply to status updates of Twitter users configured within Heartbeat

Access to Heartbeat Write APIs must be configured enabled separately from read-only API access. If you receive an “API Access disabled” error message, contact your account manager.

Heartbeat Update Workflow API

This API allows an external application to 1) add a workflow comment to and/or update the workflow status of an existing Beat within a Heartbeat account.

For comments, the user posting the comment is implied by the per-user apiKey parameter.

If status is specified, a comment will automatically be added to the workflow identifying the user to which the post was assigned.

URL Parameter Explanation

apiKey

API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

bid Integer beat id, identifies the post within each Heartbeat account whose workflow you with to update.

status String userid, assigns the post to a user within the Heartbeat workflow. The user must be a valid user in the Heartbeat account identified by hid. The special strings none+ and closed+ may also be specified. These strings set the workflow's assigned status to “Assigned to none” and “Case closed”, respectively.

Page 24: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

24 Sysomos API Documentation, Updated February 2014

comment String containing the text of the 'workflow update' comment to add to the Beat.

Example 1:

http://api.sysomos.com/v1/heartbeat/workflow?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&bid=BEAT-ID&comment=this%20is%20a%20comment

Beat ID can be found by hovering over the respective beat when testing this API as shown in red circle below, these are also returned as an XML field of the docID tag in the RSS Content API as:

<docid>YOUR-HEARTBEAT-ID:BEAT-ID</docid>

E.g. <docid>1234:567890</docid>

This URL returns a minimal response echoing the request parameters, with and an Errors element if the operation fails.

The XML response is as follows:

<hbWorkflowApi>

<request>

<hid>YOUR-HEARTBEAT-ID</hid>

<bid>YOUR-BEAT-ID</bid>

<status>[email protected]</status>

</request>

</hbWorkflowApi>

In case of error the response will contain an error TAG defining the error, contact your account manager in that case.

Example 2:

Page 25: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

25 Sysomos API Documentation, Updated February 2014

http://api.sysomos.com/v1/heartbeat/workflow?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&bid=YOUR-BEAT-ID&comment=this%20is%20a%20comment

The following XML indicates a failure, in this instance; the bid parameter does not refer to a Beat in the Heartbeat account. The error element will be set to true if an internal error has occurred – the element is false in this case since the error is due to invalid input. Is a comment

Example 3:

http://api.sysomos.com/v1/heartbeat/workflow?apiKey=APIKEY&hid=496&bid=YOUR-BEAT-ID&[email protected]

This request assigns a post within Heartbeat to the user ‘[email protected]’. As with manual workflow assignment in Heartbeat, the user being assigned the post will receive a workflow email if the user’s email address is configured within Heartbeat.

Heartbeat Post to Twitter/Facebook API

This API allows an external application the ability to post messages to external platforms. We currently support Twitter status updates and Facebook wall posts.

Facebook

For Facebook wall posts, the Facebook page must be configured within Heartbeat for the Heartbeat account specified by the hid parameter.

If the bid(beat ID) parameter is provided, and refers to a Facebook wall post, the message is posted as a comment to an existing wall post specified by the bid. Posting a reply to a non-public wall will result in an error response from the API.

If no bid parameter is defined, a new wall post referenced by the pageId parameter. Upon successful posting, the post identified by bid will be updated with a workflow comment stating ‘Replied via facebook’.

Twitter

Twitter accounts must be configured within Heartbeat for the user specified by the apiKey parameter.

Page 26: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

26 Sysomos API Documentation, Updated February 2014

As with posting to facebook, if a bid parameter is provided, and refers to a tweet, the message will be posted as a public reply to that tweet. Replies will be prefixed by a @screenname preamble indicating the Twitter user being replied to, if not already in the reply text.

A workflow comment will be added to the post identified by bid stating ‘Replied via twitter as @screenname’. If the bid parameter is omitted, a new tweet is posted.

Twitter direct (private) messaging is supported via the ‘d’ notation: d screenname message. See http://support.twitter.com/entries/14606-what-is-a-direct-message-dm for more details. Note that you can only send direct messages to users that are following the user specified by the screenName parameter.

URL Parameter

Explanation

apiKey

API Key

hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.

Bid Integer beat id, identifies the post within the Heartbeat account to reply to. If not provided, a new wall post (Facebook) or status update (Twitter) is created.

Platform The social media platform on which to post. Supported values are twitter and facebook. If Bid is provided, the platform parameter is optional – if not provided it will be inferred from the type of post referred to by bid.

screenName The screen name of the Twitter user whose status should be updated. Do not include the leading @. This twitter user must be configured in Heartbeat by the user specified by the apiKey parameter.

pageId The pageId of the facebook page to post to. The parameter is only relevant if the platform element is set to facebook. The page referenced by this pageId must be configured within Heartbeat.

message String containing the message text to post. If platform is set to twitter, this field is limited to 140 characters.

Example 1 (Facebook):

http://api.sysomos.com/dev/v1/heartbeat/post?apiKey=<YOUR-APIKEY>&hid=<YOUR-HEARTBEAT-ID>&platform=facebook&message=I'm%20on%20facebook&pageId=<YOUR-FACEBOOK-PAGE-ID>

Page 27: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

27 Sysomos API Documentation, Updated February 2014

Example 2 (Twitter):

http://api.sysomos.com/dev/v1/heartbeat/post?apiKey=<YOUR-APIKEY>&hid=<YOUR-HEARTBEAT-ID>&platform=twitter&message=%23winning&screenName=sysomos

Page 28: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

28 Sysomos API Documentation, Updated February 2014

Heartbeat Widgets

Heartbeat provides several ways of integrating it with other business applications:

Password-less logins: Users can navigate from any web app to Heartbeat with a single click requiring no

passwords or additional authentication steps.

Data Exports: All content monitored by Heartbeat can be periodically exported as either RSS XML or CSV

Widgets: Heartbeat charts and data can be embedded in another web app within minutes by including it

as an iframe or image. All widgets provide password-less click through for detailed data drill down.

REST Based Measure API: For a tighter integration, XML-based REST APIs are available.

Example Widget 1: Latest Activity

Page 29: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

29 Sysomos API Documentation, Updated February 2014

The activity chart in your Heartbeat can be integrated as an iframe in your web application by using the following URL. Note the APIKEY needs to be substituted with the correct value.

http://hb.sysomos.com/hb2/widgets/measure.jsp?hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&scO=date&authStr=YOUR-APIKEY

Example Widget 2: BuzzGraph

The BuzzGraph shows a visual summary of conversations by listing relevant keywords.

The BuzzGraph can be included as an image by using the URL below. Note the APIKEY needs to be substituted with correct value. This widget is not an iframe but an img.

http://hb.sysomos.com/hb2/dimg/buzzgraphhbimg.jsp?hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&width=450&sisi=30&kt=1&authStr=YOUR-APIKEY

Page 30: Sysomos Heartbeat API Documentation - cceHUB - Home · Heartbeat API Documentation Sysomos Inc., ... API access comes at an additional API licensing cost, ... 1160

30 Sysomos API Documentation, Updated February 2014

Contact Us To have any more questions concerning Sysomos, feel free to reach your respective Account Manager or Sales representative. Call: 1 866 483 3338 Email: [email protected]

Technical Support [email protected]

Sysomos Inc. 25 York Street, Suite 900, P.O. Box 403 Toronto, ON, M5J 2V5, Canada See on Google maps 1 416 479 0629 (Phone) 1 866 961 4978 (Fax)

Media Inquiries [email protected] blog.sysomos.com twitter.com/sysomos

Privacy Inquiries [email protected]

Sales/General Inquiries [email protected]