Developer Documentation

Topics have one of 4 styles: Question, Idea, Problem, and "Talk". They form the basis of all communication that takes place in Get Satisfaction. In the Get Satisfaction API, topics are represented as an Atom feed, with at least 1 entry. This first entry of a topic feed is the content for the topic itself. Every entry after the first is a reply to the original topic. For detailed information, please refer to the annotated sample feed below:

<feed xmlns="https://www.w3.org/2005/Atom" xmlns:sfn="https://api.getsatisfaction.com/schema/0.1" xmlns:opensearch="https://a9.com/-/spec/opensearch/1.1/" xmlns:thr="https://purl.org/syndication/thread/1.0">  
    
    
  <id>https://localhost:3000/topics/27521</id>  
  <title>how can i delete my company or hide it from the public?</title>  
  <updated>2008-02-12T20:25:40Z</updated>  
  <published>2007-10-19T16:16:20Z</published>  
    
    
  <!--   
    Paging links:  
      
    Use these links to page through the data set:  self, first, last, next, prev  
      
    next or prev will only appear if the page actually exists.   
   -->  
  <link rel="self" href="https://localhost:3000/topics/27521?page=1" type="application/atom+xml">  
  <link rel="first" href="https://localhost:3000/topics/27521?page=1" type="application/atom+xml">  
  <link rel="last" href="https://localhost:3000/topics/27521?page=1" type="application/atom+xml">  
    
    
  <!--   
    Navigation links:  
      
    rel=company :  The company in which this topic is posted  
    rel=replies :  The sub-feed that represents all replies to this topic.  POST here to create replies  
  -->  
  <link rel="company" href="https://localhost:3000/companies/4" type="text/html">  
  <link rel="replies" href="https://localhost:3000/topics/27521/replies" type="application/atom+xml">  
    
  <!-- Satisfaction specific ID -->  
  <sfn:id>27521</sfn:id>  
    
    
  <entry>  
    <id>https://localhost:3000/topics/27521</id>  
      
    <link rel="topic" href="https://localhost:3000/topics/27521" type="application/atom+xml">  
      
    <!-- topic_at_sfn is a link back into the main GetSatisfaction application. -->  
    <link rel="topic_at_sfn" href="https://getsatisfaction.com/satisfaction/topics/how_can_i_delete_my_company_or_hide_it_from_the_public" type="text/html">  
      
    <link rel="company" href="https://localhost:3000/companies/4" type="text/html">  
    <link rel="replies" href="https://localhost:3000/topics/27521/replies" type="application/atom+xml">  
      
    <sfn:id>27521</sfn:id>  
    <title type="html">how can i delete my company or hide it from the public?</title>  
    <updated>2008-02-12T20:25:40Z</updated>  
    <published>2007-10-19T16:16:20Z</published>  
      
    <author>  
      <name>hipperweb</name>  
      <uri>https://localhost:3000/people/23891</uri>  
    </author>  
    <content type="html">  
      
    </content>  
      
    <!-- Topic style:  question, idea, problem, or talk -->  
    <sfn:topic_style>question</sfn:topic_style>  
  
    <!--   
      Additional statistics   
        
      flag_count:  The number of Abuse/Spam flags that have been applied to this topic  
      reply_count:  The number of replies posted to this topic  
      follower_count:  The number of people actively following the topic  
    -->  
    <sfn:flag_count>0</sfn:flag_count>  
    <sfn:reply_count>10</sfn:reply_count>  
    <sfn:follower_count>9</sfn:follower_count>  
      
    <!-- Tags applied to this topic -->  
    <sfn:tags>remove company, privacy, public</sfn:tags>  
  </entry>  
    
  <!-- All of the following entry elements would be replies to this topic -->  
  <entry>...</entry>  
  <entry>...</entry>  
  <entry>...</entry>  
  <entry>...</entry>  
</feed>  

Posting Topics

To create a topic on Get Satisfaction, you will post to https://api.getsatisfaction.com/topics with a series of required and optional parameters that will be form-encoded. You can look at https://api.getsatisfaction.com/topics/new to see a mock HTML form that describes the parameters that are available.

The required parameters include:

topic[company_id]

The Get Satisfaction specific record ID of the company that you are posting this topic to. The is the <span class="id" /> tag in a company hcard. Use either this option or topic[company_domain] to set the company, but not both.

topic[company_domain]

An alternative to using topic[company_id], company_domain allows you to specify the owning company of topic using its name. The companies domain is the first element of the URL path in the main Get Satisfaction API: For example, twitter's address on Get satisfaction is https://getsatisfaction.com/twitter, and its domain is 'twitter', whereas I want sandy's domain is 'iwantsandy'

topic[style]

Specifies the topic's style: either question, idea, problem, or answer.

topic[subject]

The single-sentence summary of a topic that shows up in topic listings.

topic[additional_detail]

A full description of the topic.

The optional parameters include:

topic[keywords]

A comma-separated list of tags that are to be associated with topic

topic[products]

A comma-separated list of product names that should be associated with this topic

topic[emotitag][face]

A value that describes the emoticon face to attach to this topic: one of happy, sad, indifferent, or silly.

topic[emotitag][feeling]

A word or two describing in more detail how you are feeling. Examples include anxious, thankful, or frustrated.

topic[emotitag][intensity]

A rating of 0-3 that describes the intensity of how you are feeling, 3 being the most intense, 0 being the baseline.

Topic lists

As with other resources in satisfaction, there are many ways to slice, dice, filter, sort, and page topic data. In general, the API uses different resources to segment the data, such as /companies/satisfaction/topics which represents all of the topics posted to getsatisfaction. Additionally, you can pass any number of query parameters to additionally filter or sort a given list of topics.

Available topic list resources

/topics

All of the topics in satisfaction

/flagged/topics

Every topic with atleast 1 abuse or spam flag, sorted by most flagged topics first

/companies/XXXXX/topics

All of the topics posted to a company Example call that represents all of the topics in iwantsandy: https://api.getsatisfaction.com/companies/iwantsandy/topics

/people/XXXXX/topics

All of the topics posted by a person Example call that represents all of the topics that I have created: https://api.getsatisfaction.com/people/scott/topics

/people/XXXXX/followed/topics

All of the topics followed by a person Example call that represents all of the topics that I am currently following: https://api.getsatisfaction.com/people/scott/followed/topics/topics

/products/XXXXX/topics

All of the topics that are about a product Example call that represents all of the topics are about an apple iBook: https://api.getsatisfaction.com/products/apple_ibook/topics

/tags/XXXXX/topics

All of the topics tagged with a given tag Example call that represents all of the topics tagged with 'bug': https://api.getsatisfaction.com/tags/bug/topics

Available query parameters for topic lists

limit

used to specify the number of items that will appear within a single page of results for the feed. 30 is the max

page

Scroll the page X of the topic list. Pair it with limit. Example call to show items 30-45 of the topics in the twitter community: https://api.getsatisfaction.com/companies/twitter/topics?limit=15&page;=3

query

q

full text search for topics using query. please note that this disabled other options besides page and limit Example call searching for "My twitter stream is missing updates": https://api.getsatisfaction.com/topics?q=My+twitter+stream+is+missing+updates

sort

Sorts the list of topics returned. Go figure. Available options include:

recently_created

Sorts by the topics most recently created first

recently_active

Sorts by the topics most recently posted to or marked by someone who also has the problem/question/idea first.

most_flagged

Topics with the most spam or abuse flags are first

most_me_toos

Topics with the most people who also have the problem/question/idea first

unanswered

Only show topics with no replies

Example call to show the most popular topics first in the twitter community: https://api.getsatisfaction.com/companies/twitter/topics?sort=most_me_toos

style

Filter topics by style: options are question, idea, problem, and talk, Example call to show only questions: https://api.getsatisfaction.com/topics?style=question

Sample atom response for a topic feed

<feed xmlns="https://www.w3.org/2005/Atom" xmlns:sfn="https://api.getsatisfaction.com/schema/0.1" xmlns:opensearch="https://a9.com/-/spec/opensearch/1.1/" xmlns:thr="https://purl.org/syndication/thread/1.0">  
    
   <id>https://localhost:3000/companies/twitter/topics?page=1</id>  
   <title>Topics in Twitter</title>  
   <updated>1969-12-31T18:00:00Z</updated>  
   <link rel="self" href="https://localhost:3000/topics?page=1" type="application/atom+xml">  
   <link rel="first" href="https://localhost:3000/topics?page=1" type="application/atom+xml">  
   <link rel="next" href="https://localhost:3000/topics?page=2" type="application/atom+xml">  
   <link rel="last" href="https://localhost:3000/topics?page=58" type="application/atom+xml">  
       
     
   
   <opensearch:totalresults>858</opensearch:totalresults>  
   <sfn:question_count>349</sfn:question_count>  
   <sfn:idea_count>75</sfn:idea_count>  
   <sfn:problem_count>417</sfn:problem_count>  
   <sfn:talk_count>17</sfn:talk_count>  
   <sfn:unanswered_count>196</sfn:unanswered_count>  
  
   <entry>  
     <id>https://localhost:3000/topics/40981</id>  
     <link rel="topic" href="https://localhost:3000/topics/40981" type="application/atom+xml">  
     <link rel="topic_at_sfn" href="https://localhost:3000/twitter/topics/can_twitter_update_my_myspace_status_bar" type="text/html">  
     <link rel="company" href="https://localhost:3000/companies/55" type="text/html">  
     <link rel="replies" href="https://localhost:3000/topics/40981/replies" type="application/atom+xml">  
     <sfn:id>40981</sfn:id>  
       
     <title type="html">Can Twitter update my Myspace status bar?</title>  
     <updated>2008-03-03T22:44:25Z</updated>  
     <published>2007-11-15T05:52:49Z</published>  
   
     <author>  
       <name>crazygurlbritt</name>  
       <uri>https://localhost:3000/people/40081</uri>  
     </author>  
     <content type="html">  
       If I add a gadget to my Myspace will Twitter update my myspace status just as if I were doing it on myspace without Twitter?  I want to be able to post on Twitter and then my myspace friends will be able to see my update when they log in.  I want it to show up where all my myspace status updates are.  I guess you can do this on facebook or is the facebook app kind of like a gadget?  I hope this isnt confusing.  I want something it's just hard to explain.  My Twitter dream is to be able to call Jott It! to update Twitter and then Twitter updates my Myspace and Facebook status so that I don't have to log in at all.  I wonder if this is possible?  
     </content>  
   
     <sfn:topic_style>question</sfn:topic_style>  
     <sfn:reply_count>2</sfn:reply_count>  
     <sfn:follower_count>12</sfn:follower_count>  
     <sfn:flag_count>0</sfn:flag_count>  
     
     <sfn:tags></sfn:tags>  
   </entry>  
  
   <entry>...</entry>  
   <entry>...</entry>  
   <entry>...</entry>  
  
</feed>
  

• Follow us on Twitter
• Visit us on Facebook
• Read our Blog
• Get Satisfaction.tv