comments.getComments REST

Skip to end of metadata
Go to start of metadata

Description

The method retrieves the comments in a specified comments stream. The comments that are retrieved are approved comments as well as ones that have approved replies.

Request URL

 

Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

Parameters

RequiredNameTypeDescription
categoryIDstringThe identifier of the comments category from which to retrieve the comments.
streamIDstringThe identifier of the comments stream from which to retrieve the comments.
dataFormatstringThe format of the response. The valid values are 'html' and 'json'.
includeNoteBooleanIndicates whether to add the note custom object to the response. Only moderators will be able to use this parameter to receive the note in the response.
includeUIDBooleanIndicates whether the UID of the commenter will be included in the returned object per comment. The default value is 'false'.
includeUserCommentsBooleanIndicates whether all the comments posted by the user to this stream will be included in the returned response. In reviews mode the default value of this parameter is true, in comments mode the default is false.
includeUserHighlightingBooleanIndicates whether the user highlighting groups of the logged-in user will be included in the returned response. The default value is 'false'.
includeUserOptionsBooleanThis parameter specifies whether to include a user options object in the response. The default is 'false'. When set to 'true' the response to the method will include the UserOptions object.
includeStreamInfoBooleanThis parameter specifies whether to include a stream information object in the response. The default is 'false . When set to 'true' the response to the method will include the StreamInfo object.
langstringThe language to which comment placeholder texts, such as "This comment has been deleted", should be translated. If this parameter is not passed, the language for translation is detected automatically based on the language in which the other comments are written.
markupTypestringThe 'markupType' parameter is only valid when 'dataFormat' is set to 'html'.
When dataFormat is set to HTML, the response is designed support microformat for web reviews.
Accepted values are:
  • 'microformat_haggregate' (default value) - a format to display aggregate review data for an item
  • 'microformat' - return both aggregate and singular review data

For more information go the the microformat section

pinnedCommentIDstringA comment ID from the stream specified by streamID. This parameter will assure that the comment thread will be included in the response, at the begining of the comments array, followed by the other comments in natural order. 
Note: the pinned comment thread is not counted by the threadLimit.
sortstringThe comments may be sorted in one of the following orders:
  • "dateDesc" - the first comment is the latest one. The comments are sorted by the timestamp of the root comment.
  • "dateAsc" - the first comment is the first created (oldest). The comments are sorted by the timestamp of the root comment.
  • "lastReply" - the first comment is the the comment with the latest reply. The comments are sorted by the timestamp of their latest reply.
  • "ratingDesc" - the comments are sorted by the overall rating value, the first comment is the one that gave highest rating.
  • "ratingAsc" - the comments are sorted by the overall rating value, the first comment is the one that gave lowest rating.
  • "votesDesc" - The first comment is the one that has the highest votes. The comments are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread.
  • "votesAsc" - The first comment is the one that has the lowest votes. The comments are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread.
startstringDefines the starting point of the comments to retrieve. The purpose of this parameter is pagination of the comments. Use the threadLimit parameter to define the number of comments returned per page. For the first page don't set the start parameter. The response includes a next field, which is a pointer to the starting point of the next page. Set the start parameter with the value of the next field received in the response of the previous getComments request.
tagsarrayThis parameter is a strings array representing a list of tags, e.g.: ["tag_a","tag_b"]. The tags are used to filter comments. Only comments that match the tags are retrieved.
threadDepthintegerThe maximum depth of replies per comments thread to retrieve.
Note: With  pinnedCommentID,  if the pinned  thread is bigger than the limit, it will not be returned even though pinned.
threadedBooleanIndicates whether the comments are threaded. The default value is true.
threadLimitintegerThe maximum number of comment threads to retrieve. If you don't give this parameter a value, the value will be taken from the comment category thread limit that is set in the Comments Settings page of Gigya's site (defaults to 25). You can change the comment category thread limit in the Comments Settings page or override it by using this parameter.
UIDstringA unique user ID. Including this parameter add the 'isSelf=true' indication to each of the comments posted by the user in the response.
format string Determines the format of the response. The options are:
  • json (default)
  • jsonp - if the format is jsonp then you are required to define a callback method (see parameter below).
callback string This parameter is required only when the format parameter is set to jsonp (see above). In such cases this parameter should define the name of the callback method to be called in the response, along with the jsonp response data.
httpStatusCodes Boolean The default value of this parameter is false, which means that the HTTP status code in Gigya's response is always 200 (OK), even if an error occurs. The error code and message is given within the response data (see below). If this parameter is set to true, the HTTP status code in Gigya's response would reflect an error, if one occurred.

Authorization Parameters

Each REST API request must contain identification and authorization parameters.

Please refer to the Authorization Parameters section for details. 

 

Response Data

FieldTypeDescription
 
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
statusReason string A brief explanation of the status code.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
fullEventName string The full name of the event that triggered the response. This is an internally used parameter and not always returned.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or

 

 

commentsArray of
Comment objects
An array listing the comments. Each comment is represented by a JSON Comment object.
userCommentsArray of
Comment object s
When  includeUserComments is true, the response includes an array of all the comments posted by the user to this stream; each comment is represented by a JSON Comment object. In addition to the regular fields of the Comment object, the following fields are returned in the response of this method:
  • categoryID  - the category ID of the retrieved comment
  • streamID  -  the stream ID of the retrieved comment
commentCountintegerThe number of returned comments.
threadCountintegerThe number of returned comments threads.
hasMoreBooleanSpecifies whether there are more comments that were not returned within this response.
nextstringA pointer to the starting point of the next comments page. The purpose of this field is pagination of the comments. Use this field as the value of the 'start' parameter of the next getComments request, thus retrieving the next comments and avoid retrieving the same comments again.
streamInfoStreamInfo objectA JSON object containing meta information of the requested commenting stream. This object is available in the response only if the "includeStreamInfo" parameter is set to 'true' in the request.
userOptionsJSON object

A JSON object containing meta information of a comments user. This object is available in the response only if the " includeUserOptions"  parameter is set to  'true'  in the request.

The object includes the following fields: 

  • replyNotifications  - the value may be either "disabled" or "immediate". When "immediate" it means that the user receives notifications of replies to his comments, in this way "following" his comments.
  • notificationsEmail  - the email address to which the notifications are sent.

A field that does not contain data will not appear in the response.

 

Response Example

{
       "comments": [{
            "ID": "7b25a80da16d44f18f50f5bb992c544b",
            "threadID": "",
            "commentText": "hello",
            "sender": {
                "photoURL": "http://a323.yahoofs.com/coreid/4a0fd68fi13fczul6re4/WrKu8nMwaLUGTjWSmmCcsa4-/1/t192.jpg?ciAAgGPBvUEtodfm",
                "profileURL": "http://pulse.yahoo.com/_DBFQRQ3CMDPI5LQYAAMCLDNXZQ",
                "loginProvider": "Yahoo",
                "name": "assafesh1",
                "isSelf":true
            },
            "vote":"none",
            "flagCount": 0,
            "timestamp": 1308579064686,
            "threadTimestamp": 1308579064686},
        {
            "ID": "agpyZWFkLXdyaXRlcgwLEgNNc2cYp_DrCQw",
            "threadID": "",
            "commentText": "I love it!",
            "sender": {
                "photoURL": "http://profile.ak.fbcdn.net/hprofile-ak-snc4/186209_100002136853114_7099987_q.jpg",
                "profileURL": "http://www.facebook.com/profile.php?id=100002136853114",
                "loginProvider": "Facebook",
                "name": "Rodney Adkins",
                "isSelf" : false
            },
            "vote":"none",
            "providerPostIDs": "{ "twitter" : "210415333096431617", "facebook" : "100000812394836_392407840796292" }",
            "flagCount": 0,
            "timestamp": 1302081658927,
            "threadTimestamp": 1302081788650,
            "replies": [{
                "ID": "agpyZWFkLXdyaXRlcgwLEgNNc2cYu-jrCQw",
                "parentID": "agpyZWFkLXdyaXRlcgwLEgNNc2cYp_DrCQw",
                "threadID": "agpyZWFkLXdyaXRlcgwLEgNNc2cYp_DrCQw",
                "commentText": "test 10",
                "sender": {
                    "photoURL": "http://profile.ak.fbcdn.net/hprofile-ak-snc4/186209_100002136853114_7099987_q.jpg",
                    "profileURL": "http://www.facebook.com/profile.php?id=100002136853114",
                    "loginProvider": "Facebook",
                    "name": "Rodney Adkins",
                    "isSelf" : false
                },
                "vote":"none",
                "providerPostIDs": "{"facebook" : "100002136853114_111739068907321" }",
                "flagCount": 0,
                "timestamp": 1302081788650,
                "threadTimestamp": 1302081788650}]},
        {
            "ID": "agpyZWFkLXdyaXRlcgwLEgNNc2cYvPGFCgw",
            "threadID": "",
            "commentText": "my comment",
            "sender": {
                "name": "bsdsa",
                "isSelf" : false
            },
            "vote":"none",
            "flagCount": 0,
            "timestamp": 1302685252965,
            "threadTimestamp": 1302685252965}],
        "commentCount": 4,
        "threadCount": 3,
        "hasMore": false,
        "next": "1297586956259",
        "streamInfo": {
             "commentCount": 6,
             "threadCount": 3,
             "rssURL": "http://comments.gigya.com/comments/rss/1069621/17235654/foo1",
             "streamTitle": "My page",
             "streamURL": "http://wildfiresocial.com/qa/site/assaf/GS2/GS2API/GSAPI.htm",
             "status": "enabled"
        },
        "statusCode": 200,
        "errorCode": 0,
        "statusReason": "OK",
        "callId": "21c5ef00019446f2928f7b5427141f70",
        "time": "2015-03-22T11:42:25.943Z"
    }

Microformat Response

The microformats are a standardized way to display data on the web. Specifically, hreview is a microformat to display review data.
For more on hreview visit the microformats hreview page.

When calling comments.getComments with dataFormat set to "html", the response returned is according to hreview standards.
The following markup illustrates the 'microformat_haggregate' and the 'microformat' response structure.

 

<!-- microformat_haggregate returns the 'hreview-aggregate' div -->
<div class="hreview-aggregate">

    <span class="item">
        <span class="fn">Gigya Example</span>
    </span>
    
    <span class="rating">
        <span class="average">4.5</span> out of 
        <span class="best">5</span> 
    </span>based on 

    <span class="votes"><%=NUM_OF_RATINGS%></span> ratings.

    <span class="count"> <%NUM_OF_REVIEWS%></span> reviews.

</div>

<!-- microformat returns the 'hreview' divs in addition to the 'hreview-aggregate' div -->
<div class="hreview">
    
    <span class="item">
        <span class="fn">Product number 1</span>
    </span>

    <span class="description">Product description 1</span>

    <span class="rating">

    <span class="value">5</span> out of 
    <span class="best">5</span>stars

    </span>
</div>

<div class="hreview">

    <span class="item">
        <span class="fn">Product number 2</span>
    </span>

    <span class="description">Product description 2</span>

    <span class="rating">
        <span class="value">4</span> out of 
        <span class="best">5</span>stars
    </span>
</div>

<div class="hreview">
    
    <span class="item">
        <span class="fn">Product number 3</span>
    </span>

    <span class="description">Product description 3</span>

    <span class="rating">
        <span class="value">4</span> out of 
        <span class="best">5</span>stars
    </span>
</div>

Unable to render {include} The included page could not be found.