SWI Server‎ > ‎

SWI Server API

SWI Server provides social media monitoring data through its REST API. The API makes integration of social media monitoring with existing enterprise software easy. For example, CRM and Collaboration software can use SWI Server API to automate the data flow from social media monitoring to enterprise platform.  Through API, SWI server automatically categorizes social contents and identifies leads, which are then automatically pulled into company's CRM or other enterprise software for timely actions.

API Calls

api-url = <swi server url>/api

Example: http://localhost/swiserver/api

api call url = <api-url>?appid=&method=[&params]

appid: client application id, issued by the swi server admin.

Method: getTopics

API method getTopics returns all topic lists or a selected list, each list containing all the topics defined for the list. The list and topic has a monitor url that links out to the corresponding monitoring page on the SWI server. This method gives enough information to make the simplest integration between social media monitoring and enterprise collaboration platform.

URL: <api-url>?method=getTopics&appid=[&listid=]

Parameters:
 listidTopic list id. It's optional.    
 If present, returns topics of the list. If not present, returns all topics for all lists.

XML response format:
  <web2express>
  <monitor listCount= monitorUrl=(link to monitor page on swi server)>
    <list id= name= topicCount= monitorUrl=(link to list page on swi server) >
      <topic id= name= sourceId=(external id) probeId=(probe id) monitorUrl=(link topic page on swi server)  />
      ...
    </list>
    ...
  </monitor>
  </web2express>
XML-encoded parameters: name, sourceId, monitorUrl

Example API calls:

To get all lists and topics:
http://localhost:8080/cis/api?method=gettopics&appid=abc
To get topics for one list: 
http://localhost:8080/cis/api?method=gettopics&listid=123&appid=abc
XML response:
<?xml version="1.0" encoding="UTF-8"?>
<web2express>
<monitor listCount="1" monitorUrl="http://localhost:8080/cis" >
<list id="1074" name="competition" topicCount="3" monitorUrl="http://localhost:8080/cis/listtopic?tlid=1074" >
<topic id="1076" name="google alert" sourceId="1" probeId="1075" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1076&amp;pid=1075" />
<topic id="1080" name="radian6" sourceId="2" probeId="1079" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1080&amp;pid=1079" />
<topic id="1082" name="web2express" sourceId="3" probeId="1081" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1082&amp;pid=1081" />
</list>
</monitor>
</web2express>

Method: getTopicStats

Method getTopicStats returns stats for topic lists or topics, including counts for contents, counts for positive sense or negative sense. 

URL: <api-url>?method=getTopicStats&appid=[&listid=&topicid=&days=]

Parameters:
 listidTopic list id. It's optional.    
 If present, returns list stats. If not present, returns stats for all lists.
 topicidTopic id. Requiring listid co-present.
 If present, return stats for the topic only.
 days          
Number of days starting from now.
 Range=1-30. Default=30.

XML response format for monitor stats:
<web2express>
<monitor listCount= monitorUrl= >
  <list id= name= topicCount= monitorUrl= docCount= pos= neg= >
    <!-- daystat in descending order of time -->
    <daystat day=(yyyy-mm-dd) count= pos= neg=/>
     ....

    <topic id= name= sourceId= probeId= monitorUrl= docCount= pos= neg= >
      <!-- daystat in descending order of time -->
      <daystat day= count= pos= neg=/>
       ....
    </topic>
   </list>
    ...
</monitor>
</web2express>
XML-encoded parameters: name, sourceId, monitorUrl

Example API calls:

To get stats for all lists:
http://localhost:8080/cis/api?method=gettopicstats&appid=abc

Xml response:
<web2express>
<monitor listCount="1" monitorUrl="http://localhost:8080/cis" >
  <list id="1074" name="competition" topicCount="3" monitorUrl="http://localhost:8080/cis/listtopic?tlid=1074" docCount="2430" pos="267" neg="12" >
    <daystat day="2010-07-27" count="255" pos="34" neg="2" />
    <daystat day="2010-07-26" count="306" pos="36" neg="3" />
    <daystat day="2010-07-25" count="149" pos="10" neg="1" />

    <topic id="1076" name="google alert" sourceId="1" probeId="1075" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1076&amp;pid=1075" docCount="1291" pos="85" neg="8" >
    </topic>
    <topic id="1080" name="radian6" sourceId="2" probeId="1079" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1080&amp;pid=1079" docCount="1052" pos="178" neg="4" >
    </topic>
    <topic id="1082" name="web2express" sourceId="3" probeId="1081" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1082&amp;pid=1081" docCount="87" pos="4" neg="0" >
    </topic>
  </list>
</monitor>
</web2express>


To get stats for one list and its topics:
http://localhost:8080/cis/api?method=gettopicstats&appid=abc&listid=1074

XML response:
<web2express>
<monitor listCount="1" monitorUrl="http://localhost:8080/cis" >
  <list id="1074" name="competition" topicCount="3" monitorUrl="http://localhost:8080/cis/listtopic?tlid=1074" docCount="2430" pos="267" neg="12" >
    <daystat day="2010-07-27" count="255" pos="34" neg="2" />
    <daystat day="2010-07-26" count="306" pos="36" neg="3" />
    <daystat day="2010-07-25" count="149" pos="10" neg="1" />
   
    <topic id="1076" name="google alert" sourceId="1" probeId="1075" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1076&amp;pid=1075" docCount="1291" pos="85" neg="8" >
    <daystat day="2010-07-27" count="153" pos="13" neg="1" />
    <daystat day="2010-07-26" count="178" pos="12" neg="1" />
    <daystat day="2010-07-25" count="127" pos="7" neg="0" />
    </topic>
    <topic id="1080" name="radian6" sourceId="2" probeId="1079" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1080&amp;pid=1079" docCount="1052" pos="178" neg="4" >
    <daystat day="2010-07-27" count="96" pos="21" neg="1" />
    <daystat day="2010-07-26" count="126" pos="24" neg="2" />
    <daystat day="2010-07-25" count="22" pos="3" neg="1" />
    </topic>
    <topic id="1082" name="web2express" sourceId="3" probeId="1081" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1082&amp;pid=1081" docCount="87" pos="4" neg="0" >
    <daystat day="2010-07-27" count="6" pos="0" neg="0" />
    <daystat day="2010-07-26" count="2" pos="0" neg="0" />
    <daystat day="2010-07-25" count="0" pos="0" neg="0" />
    </topic>
  </list>
</monitor>
</web2express>


To get stats for one topic:
http://localhost:8080/cis/api?method=gettopicstats&appid=abc&listid=1074&topicid=1080

XML response:
<web2express>
<monitor listCount="1" monitorUrl="http://localhost:8080/cis" >
  <list id="1074" monitorUrl="http://localhost:8080/cis/listtopic?tlid=1074" >
    <topic id="1080" name="radian6" sourceId="2" probeId="1079" monitorUrl="http://localhost:8080/cis/topic?listid=1074&amp;tid=1080&amp;pid=1079" docCount="1052" pos="178" neg="4" >
    <daystat day="2010-07-27" count="96" pos="21" neg="1" />
    <daystat day="2010-07-26" count="126" pos="24" neg="2" />
    <daystat day="2010-07-25" count="22" pos="3" neg="1" />

    </topic>
  </list>
</monitor>
</web2express>

Method: getTopicContents

Method getTopicContents provides filtered contents for a topic list or a topic. Data type can be specified to get public updates, blogs or news.

URL: <api-url>?method=getTopicContents&appid=&listid=[&topicid=&=datatype=&sense=&start=&max=]

Parameters:
listidTopic list id. It's required.    
Returns contents for all topics in the list.
topicidTopic id. Optional. Requiring listid co-present.
If present, return contents for the topic only.
datatype         
Content data type. Optional. 1=tweet, 2=blog, 3=news.   Default=1. Not applied when sense is present.
sense
 Sense of the context. Optional.
 pos=positive, neg=negative. default is none. Applied to topic only.
 start Start index for returned contents. Optional.
 0-based. Default=0. Results are sorted by time in descending order.
 max Max number of contents to return. Optional.
 Range=1-100. Default=20.

XML response format for content:
<web2express>
 <monitor monitorUrl= >
  <list id= name= monitorUrl= >
   <topic id= name= sourceId= probeId=/ monitorUrl=   >
    <contents count= more=(true|false) total=>
      <content datatype=(1|2|3) id= title= link=(to original source) author= publisher= source= time=(yyyy/MM/dd HH:mm z) >
        <text> (context found in content) </text>
        <authorUrl> (link to author page) </authorUrl>
        <engageUrl> (link to engagement page on swi server) </engageUrl>
      </content>
    </contents>
   </topic>
  </list>
 </monitor>
</web2express>
XML-encoded parameters: name, sourceId, monitorUrl, title, link, author, publisher, source, text, authorUrl, engageUrl
Tweet has authorUrl linked to twitter user page.
Tweet and blog have engageUrl linked to SWI Server for engagement.

Example uses:

To get contents for topic list:
http://localhost:8080/cis/api?method=gettopiccontents&appid=abc&listid=1074

To get contents for a topic:
http://localhost:8080/cis/api?method=gettopiccontents&appid=abc&listid=1074&topicid=1076&datatype=1

To get contents for a topic that have positive sense:
http://localhost:8080/cis/api?method=gettopiccontents&appid=abc&listid=1074&topicid=1076&datatype=1&sense=1

Sample XML responses:
<web2express>
<monitor monitorUrl="http://localhost:8080/cis" >
  <list id="1074" name="competition" monitorUrl="http://localhost:8080/cis/listtopic?tlid=1074" >
  <contents count="21" more="true" total="3443" >
  <content id="88d610e1-9845-11df-b6ca-00188ba32fb8" title="New Blog Post: Google Alert - workout routine http://ow.ly/18hWkp" link="" datatype="1" author="daddontsk8" publisher="twitter" source="twitter" time="2010/07/25 16:25 PDT" >
   <text>New Blog Post: &lt;b&gt;Google Alert&lt;/b&gt; - workout routine &lt;a href=&quot;http://ow.ly/18hWkp&quot;&gt;http://ow.ly/18hWkp&lt;/a&gt;&lt;br&gt;</text>
   <authorUrl>http://twitter.com/daddontsk8</authorUrl>
   <engageUrl>http://localhost:8080/cis/engagelead?aid=7ffa0692-9208-11df-9780-00188ba32fb8</engageUrl>
  </content>
  <content id="88d39fe3-9845-11df-b6ca-00188ba32fb8" title="Yes, doesn&apos;t everybody? RT @FXAlgo: @johnpneedham you google alert your name?" link="" datatype="1" author="johnpneedham" publisher="twitter" source="twitter" time="2010/07/25 15:37 PDT" >
   <text>Yes, doesn&apos;t everybody? RT &lt;a href=&quot;http://twitter.com/FXAlgo&quot;&gt;@FXAlgo&lt;/a&gt;: &lt;a href=&quot;http://twitter.com/johnpneedham&quot;&gt;@johnpneedham&lt;/a&gt; you &lt;b&gt;google alert&lt;/b&gt; your name?&lt;br&gt;</text>
   <authorUrl>http://twitter.com/johnpneedham</authorUrl>
   <engageUrl>http://localhost:8080/cis/engagelead?aid=88d610e0-9845-11df-b6ca-00188ba32fb8</engageUrl>
  </content>
    ...
  </contents>
  </list>
</monitor>
</web2express>

Method: getAuthors

Method getAuthors provides authors of filtered social contents or social leads.

URL: <api-url>?method=getAuthors&appid=[&lead=&sort=&start=&max=]

Parameters:
 lead Author is selected as lead or not. Optional.
true or false (default)
 sort
 Authors are sorted by time or content count. Optional.
 1=by count, 2=by time (default)
 start Start index for returned contents. Optional.
 0-based. Default=0.
 max Max number of contents to return. Optional.
 Range=1-1000. Default=100.

XML response format:
<web2express>
 <monitor monitorUrl=>
  <authors count= more= total= monitorUrl=  >
    <author id= userId= name= publisher= docCount= lead= categories= monitor_url=   />
  </authors>
 </monitor>
</web2express>
XML-encoded parameters: userId, name, publisher, categories, monitorUrl

Example uses:

To get latest authors of social contents:
http://localhost:8080/cis/api?method=getauthors&appid=abc

To get latest social leads:
http://localhost:8080/cis/api?method=getauthors&appid=abc&lead=true

Sample XML response:
<web2express>
<monitor monitorUrl="http://localhost:8080/cis" >
 <authors count="101" more="true" total="368" monitorUrl="http://localhost:8080/cis/leads" >
  <author id="cee995a2-9d0b-11df-b2a6-00188ba32fb8" userId="" name="gregoryBurrus" publisher="Success Is Mandatory Today" docCount="1" lead="true" categories="Research, " monitorUrl="http://localhost:8080/cis/engagelead?aid=cee995a2-9d0b-11df-b2a6-00188ba32fb8" />
  <author id="ceddaec0-9d0b-11df-b2a6-00188ba32fb8" userId="" name="admin" publisher="translecent stone candle holder" docCount="1" lead="true" categories="Research, " monitorUrl="http://localhost:8080/cis/engagelead?aid=ceddaec0-9d0b-11df-b2a6-00188ba32fb8" />
 </authors>
</monitor>
</web2express>

Error Response

Example:
<web2express>
<error code="400" msg="failed to get topics"/>
</web2express>

Please let us know if you need more API support.


Comments