Opinion Search API V2
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
