Grouping API V2

The Grouping API provides a mechanism to obtain aggregated information of a select set of fields in the Opinion Search Index.  For a given query, one can get frequency counts over the grouped field.  The available fields for grouping are: 

  • Author 
  • Topic 
  • Publish Date
  • Opinion Holders
  • Polarity

A grouping query is identical to the Opinion Search V2 API, with the addition of single parameter,  'group'


API Endpoint

The Opinion Search API Version 2 endpoint is available at

Query Syntax

The structure for the overall query as as follows<appkey>&fieldy=<query for fieldX>&fieldy=<query for field y>&format=(xml|json)&group=<groupfield>&group_start=<start position>&group_rows=<number of rows to return>


The API requires that each user obtain an application key. This key is used to track API usage. A key can be obtained by registering at and is provided via the appkey parameter with each request.  If you already have an Opinion Search API key, you will still need to request a new key for the Grouping API. 

Search Parameters

There are a set of basic HTTP query parameters that can be be provided with each request. The application key, appkey is required with each request.

Overall Parameters
Name Description Required Default Value
appkey The application key true N/A
format The response format. Formats = {json,xml}. false xml
group A comma separated list of groups from the set  {author_id, topic_id, opholder_id,polarity,publish_date} true N/A
group_start The start position for the search results.  See pagination Info. false 0
group_rows The number of results to return. Max=30 false 10


The Query parameters

Search Fields
Field Description Type
<Opinion Search API Query Parameters>
See Opinion Search API V2 Search Fields N/A



You can paginate through the grouped fields using the group_start and group_rows parameters, as you can with the Opinion Search API.   This permits you to page through the lists from most frequent(in the case of topic, opinion holder, publisher, and author) or most recent (in the case of publish_date).  The group_start and group_rows parameters apply to all the groups in the request.  There is no way to use different start/row parameters for each group field within a request.   In order to paginate over publish date for periods longer than 30 days use the group_start parameter, not the publish_date constraints that you would normally use to constrain the results in the opinion search API.  For example, to get the opinion counts between 30 and 40 days ago use group_start =30 and group_rows=10.



The API allows the query responses to be provided in XML or JSON formats. The default is XML. Use format=json, as a query parameter to return JSON. The following table shows the fields that are returned with each result.

Response Fields
Field Description
groupfield A list of groupfield blocks with id
group An ID/Name with frequency value for each groupfield

Example Output

The following is a sample response for the query q=sent=carbon tax&rows=1&group=topic_id (ie. return the most common topics associated with opinions that have carbon tax in their sentence)

<opinions totalNumFound="28407">

 <groupfield id="topic_id">
   <value name="Barack Obama" id="b97f7b3e-66ea-4322afe2e40">7975</value>
   <value name="State of the Union" id="5bce1ae1-725-782e570c43aa">1267</value>
   <value name="Obama administration" id="e76ec9eb-93be602e80f12fde">895</value>
   <value name="Congress" id="6fc2821c-61df-47a3-8044">836</value>
   <value name="Michelle Obama" id="018f8273-a8e5-48790474cf8f1">769</value>
   <value name="White House" id="e8b129b6-03f0-44f5-a15f-46a19a7d4f9b">640</value>
   <value name="Stimulus Package" id="67aa7bf7-6249-488-77fef7081e55">310</value>
   <value name="United States" id="25567c8e-87e4-42c7-b579-ff46543f4">222</value>
   <value name="Washington" id="bc64715d-f471-46e6-8717-9be24253b3e2">220</value>
   <value name="Senate" id="ef47ed53-3d8e-42c6-9a8b-ed163a17d57e">211</value>
   <value name="Paul Ryan" id="508803d8-c8d8d8-c9576cd892f0">203</value>