Opinion Search API V2

Jodange Opinion Search API

API Endpoint

The Opinion Search API Version 2 endpoint is available at http://api.appinions.com/search/v2/opinions. Only HTTP GET requests are permitted. Each request functions as a search request against our index of opinions. Query constraints determine the types of results you get back and special navigation parameters allow you to filter and paginate through the results.

Query Syntax

The structure for the overall query as as follows

http://api.appinions.com/search/v2/opinions?appkey=<appkey>&fieldy=<query for fieldX>&fieldy=<query for field y>&start=<start>&rows=<row>&format=(xml|json)&filter=(field1,filter2,etc)&sort=<sortfield>

Authentication

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 http://developer.appinions.com and is provided via the appkey parameter with each request.

Quota and Usage Rate

Each user is allowed up to 5000 requests each month and up to 2 requests per second. An email will be sent to the account associated with the appkey if you approach your quota limit. Please consult the terms of service here for more information.  If you need to increase your quota limits please contact us. 

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
start The start position for the search results. See Pagination Info. false 0
rows The number of results to return.Max=1500. false 10
sort The field to sort on. Sortable fields={pub_date}. false N/A
filter The fields to show in the search results set. false N/A
format The response format. Formats = {json,xml}. false xml

 

The Query parameters

The query parameters define the search constraints. The field constraints take the form of a field name (see table below) followed by an equals sign and a query-expression expression, e.g. sent=(obama or bush). Fields are separated by ampersands sent=obama&author="Bob Smith". Within a field query you may use AND, OR, NOT operators. Phrase queries can be indicated with quotations. Dates can be specified in two range formats of the form 'X TO Y', where the date is a fully qualified UTC date-time in the format: YYYY-MM-DDTHH:MM:SSZ or simply with date as YYYY-MM-DD. Negative operators can be used with the minus sign, e.g sent=obama AND -bush.   The V2 API now supports the ability to filter out near-duplicate opinions via the dedup parameter.  With dedup set to false, all opinions are retrieved.  By default dedup is set to true, and will try to return only unique opinion results. 

Search Fields
Field Description Type
authors A keyword search across the author's name. string
author_id The ID associated with the author of the document from where the opinion was extracted.
string
dedup Whether to deduplicate opinions or retrieve all opinions whose representative opinion sentence is dedup value. Defaults to true. (true|false|sent_id)
doc_id The ID of the document. string
op_id The ID of the opinion. string
opholder A keyword search across the opinion holder's name. string
opholder_id The ID of the opinionholder. string
polarity The polarity of the opinion. (-1=negative,0=neutral,1=positive). int
publisher A keyword search across the publisher name for the document. string
publisher_id The ID of the publisher. string
publish_date The date range search between which the document was published, in the format [YYYY-MM-DD TO YYYY-MM-DD] or [YYYY-MM-DDThh:mm:ssZ to YYYY-MM-DDThh:mm:ssZ]
date
regions A keyword search across the region where the opinion document originated. string
sent The keyword search across the text of the opinion sentence. string
sent_id The ID of the sentence from where the opinion was extracted. string
type The type associated with the document from which the opinion was extracted [news,blog,transcript,tweet,comment]. string
topics A keyword search across the topics found in the opinion sentence. string
topic_id The ID of the opinion topic. string
doc_text A relevant-document query. Returns opinions from documents that are similar to the text provided in doc_text.  (deprecated as of 4/6/2012.   no longer supported.  use sent instead)
string
domain A special domain parameter that permits custom access to privileged data sources.   Not applicable for most users, but allows access to select data domains on a per-customer basis. string

 

Response

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
authors A list of the authors as a list of <author> elements with associated IDs.
doc_id The ID of the document
doc_link The URL of the original document.
doc_title The document title/headline.
payloads A list of extra non-searchable metadata fields associated with the opinion.  Varies betwen sources.
op_id The ID of the opinion.
opholder The name of the opinion holder and associated ID.
pre_sent The preceding sentence text.
post_sent The following sentence text.
polarity The polarity of the opinion (-1=negative, 0=neutral, 1=positive).
polarity_conf The confidence value associated with the polarity classification. 0=low, 1=high.
publisher The publisher's name and associated ID.
publish_date The date of publication in UTC format [e.g 2011-01-13T05:04Z]
regions A list of regions for the document as a list of <region> elements.
sent The text of the sentence.
sent_id The ID of the sentence from where the opinion was extracted.
type The type associated with the document from which the opinion was extracted [news,blog,transcript,tweet,comment]
topics The topics of the opinion as a list of <Topic> elements with associated IDs

 

Sorting

You may sort by Publish Date with most recent first, by specifying 'sort=pub_date.' Otherwise, sorting will be performed according to an internally-defined relevancy ranking formula based on the other query parameters defined in your search request. Additional fields may be provided for sorting in the future.

Filtering

By default, all response fields will be provided in the response. Optionally, users can specify to filter on specific fields, and ignore all others, by specifying a comma separated list of fields for for the filter param. E.g. 'filter=field1,field2'. This usage can be helpful for clients that prefer low-bandwidth responses. Note, the filter param will not effect the ordering of the fields.

Pagination

The result sets are navigated through pagination, using the start and row parameters. The query parameter, start , determines the position in the result sets to start from, and rows determines the numbers results to return. The default value for start is 0, and the default for rows=10. The maximum value for rows is 1500.

Response Codes

Each request will return an HTTP response with corresponding HTTP code. Below is a table summarizing the common HTTP codes you can expect to receive. Note, because this is a search application you will receive a '200' response even for requests that return zero results.

Response Codes
HTTP Code Name Description
200 Success A normal search request result.
400 Bad Request Your request is malformed.
403 Forbidden You are have reached your quota limit or attempting to access an unauthorized resource.
404 Not Found The resource you are requesting does not exist.
500 Server Error An internal server error.
503 Server Unavailable The API service is done for maintance.

 

Example Output

The following is a sample response for the query q=sent=carbon tax&rows=1

<?xml version='1.0' encoding='UTF-8'?>
 <opinions totalNumFound="2421" start="0" numReturned="1">
   <opinion index="0">
      <op_id>16f30a2f-a8e8-3fba-a48c-ac083fc37782</op_id>
      <dedup>0</dedup>
      <sent_id>b2b65c65-146f-31d8-b2f3-f375093bb04c</sent_id>
      <doc_id>25a9c6b8-6bc0-349c-8900-bd01b7403bfa</doc_id>
      <doc_link>http://ct.moreover.com/ct?haid=b7f289771</doc_link>
      <doc_title>Demented thinking: Copenhagen didn't work</doc_title>
      <publish_date>2011-01-06T12:33Z</publish_date>
      <type>blog</type>
      <pre_sent>One further impetus for climate-tax......</pre_sent>
      <sent>A carbon tax is the closest thing to an...... </sent>
      <post_sent>The international community should..... </post_sent>
      <topics>
        <topic id="f3532d62-3916-48d5-a4a8-684a5c16fbcf">Climate Change</topic>
        <topic id="2443ab22-ab8n-4sad-443b-8a84234qpaz4">Carbon Tax</topic> 
      </topics>
      <publisher id="3ade49c0-52d6-3f7d-8f99-63b302887aa7">Watts Up</publisher>
      <authors>
        <author id="534asd-2434-23ad-aadd-232aeppq">Anthony Watts</author>
      </authors>
      <opholder id="f3532d62-3916-48d5-a4a8-684a5c16fbcf">Robert Ball</opholder>
      <polarity>1</polarity>
      <polarity_conf>0.73413336</polarity_conf>
      <payloads />
   </opinion>
 </opinions>

 

Example Queries

The following are some example queries a description of the results they return.

Examples
Query Description
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent=France AND Paris&polarity=-1 Search for opinions in sentences with text containing France and have Negative Polarity
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent=PARIS NOT Hilton Search for opinions about Paris, but not Hilton
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent=obama&topics=mideast Search for opinions in sentences with text containing obama and topic mideast
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent=obama&topics=mideast AND Israel Search for opinions in sentences with text containing obama and topic mideast and Israel
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent=Fighter+AND+(Oscar OR Movie) Search for opinions the movie "The Fighter.  Opinions with text that has Fighter and either Oscar or movie.
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent="New York"&publish_date=[2010-3-1 TO 2010-3-31] Search for opinions in sentences with text containing 'New York' which are published in March 2010
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent="New York"&publish_date=[2010-3-1T23:30:00Z TO 2010-3-1T23:59:59Z] Search for opinions in sentences with text containing "New York" which are published in the last half hour of March 1st, 2010
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent=obama OR bush&filter=sent,author Search for opinions in sentences with text containing Obama or Bush and only return sent and author fields
http://api.appinions.com/search/v2/opinions?appkey=<appkey>&sent=obama OR bush&filter=sent,author&sort=publish_date Search for opinions in sentences with text containing Obama or Bush and only return sent and author fields and sort by publish date

Differences with Opinion Search API V1

  • Support for multiple authors.  Authors field becomes a list of Author elements.
  • Support for opinion deduplication via dedup parameter.
  • Support for payload metadata
  • Improved ID naming scheme
  • Improved data quantity and quality