Table of Contents
- What is the Knowsis API?
- API Endpoints
- Insights Endpoints
- Asset Identifiers
- Errors
The Knowsis API allows developers to add Knowsis analytics to their website and applications. Knowsis sentiment data is derived from 1000s of online sources and is generated through our own proprietary machine learning algorithms.
We make the sentiment of 100s of publicly traded assets (equities, commodities, indices, forex pairs) and non tradable assets (macro drivers, pre IPO companies etc) available.
Our API is accessible via HTTPS, is RESTful, and offers JSON response formats (find the schema below). All data responses are UTF-8 encoded.
We presently offer sentiment data for the current day.
Times and dates are provided in UTC timezone and are in ISO 8601 format.
We use OAuth for authentication. As all resources are protected, you must sign every request you make using your API consumer key and secret, as per the OAuth Consumer Request 1.0 Draft 1 specification. We strongly recommend using an existing OAuth library. The oauth.net website lists suggested libraries by language.
The following parameters MUST appear in every request:
- oauth_consumer_key - The consumer key provided to you by Knowsis
- oauth_nonce - A random string of characters that differs from call to call (this helps to prevent replay attacks) be sure to make these characters legal (percent-encoded)
- oauth_timestamp - The number of seconds elapsed since midnight, 1 January 1970. Be sure this is within ten minutes of the real time
- oauth_signature_method - The method used to generate the signature. We currently only support HMAC-SHA1
- oauth_signature - You generate the signature by passing into a cryptographic function your consumer key, your shared secret, and an encoded version of the "base string"
The oauth_version parameter is optional; the value will be assumed to be 1.0 if it is not provided.
We can render responses for you using JSON.
The default format is JSON
In order to specify your choice of response format use a standard HTTP Accept header.
Accept: application/json, text/javascript
We currently offer a python API Client (pyknowsis) which is available from pypi.
pip install pyknowsis
You can also get the latest version of the source code from our github repository.
Documentation is also available on the github repository
Access to the Knowsis API is available through a RESTful interface
The Knowsis API is available for registered users at https://api.knowsis.com/. To register an account contact [email protected]
The list assets endpoint will return an asset list resource containing all asset resources available to your account. Asset lists can be paged to return upto 100 assets at a time
GET /assets/
There are also four asset list filter endpoints which will only return assets of the requested type:
| Endpoint | Type | Description |
|---|---|---|
| equities | list of asset resources | A list of equities |
| commodities | list of asset resources | A list of commodities |
| indices | list of asset resources | A list of indices |
| forex | list of asset resources | A list of forex pairs |
GET /equities/
GET /commodities/
GET /indices/
GET /forex/
JSON Response
GET https://api.knows.is/assets/
Accept: application/json, text/javascript
{
"meta":{
"page":1,
"pagesize": 100,
"items": 2,
"total_items": 2
},
"assets": [
{
"name": "Anglo American PLC",
"type": "Equity"
"identifiers": [
{
"identifier": "AAL:LN",
"type": "Bloomberg"
},
{
"identifier": "AAL.L",
"type": "Reuters"
},
{
"identifier": "GB00B1XZS820",
"type": "ISIN"
}
]
},
{
"name": "ARM Holdings PLC",
"type": "Equity",
"identifiers": [
{
"identifier": "ARM:LN",
"type": "Bloomberg"
},
{
"identifier": "ARMH:US",
"type": "Bloomberg"
}
]
}
]
}
###Asset List Resource
The asset list resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| meta | metadata resource | paging metadata |
| assets | list of asset resources | available assets |
The metadata resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| page | int | requested/current page |
| pagesize | int | requested page size |
| items | int | number of items in the current page |
| total_items | int | total items available |
The asset endpoint will return a single asset based on the specified {identifier} value.
GET /assets/{identifier}/
JSON Response
GET https://api.knows.is/assets/ARM.L/
Accept: application/json, text/javascript
{
"name": "ARM Holdings PLC",
"identifiers": [
{
"identifier": "ARM:LN",
"type": "Bloomberg"
},
{
"identifier": "ARMH:US",
"type": "Bloomberg"
}
]
}
The asset resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| name | string | display name for this asset |
| identifiers | list of asset identifier resource | list of asset identifier resource |
Accept: application/json, text/javascript
{
"identifier": "$MMM",
"type": "Cashtag"
}
The asset identifier resource is up of the following fields:
| Field | Type | Description |
|---|---|---|
| identifier | string | identifier value |
| type | list of asset identifier resource | type of identifier |
The asset sentiment endpoint will return a list of sentiment resources. The default view is the current day’s sentiment data for a single asset based on the specified {identifier} value. The date which the data refers to is also returned in the request
GET /assets/{identifier}/sentiment/
For API consumers that have licensed our historical sentiment data there are optional parameters to get sentiment for a specified date range
| Parameter | Format | Description |
|---|---|---|
| startdate | date - (YYYYMMDD) | the first day in the requested range |
| enddate | date - (YYYYMMDD) | the last day in the requested range |
The asset sentiment endpoint will adhere to the following behaviour:
- If no start date or end date is provided the data will be for the current day only.
- If there is no start date, the data will be returned for the end date only.
- If there is no end date, the data range will span from the start date provided up until the current day.
- If the start date is after the end date, the start date will be ignored and the API will adhere to the step 3.
JSON Response
GET https://api.knows.is/assets/$ARMH/sentiment/?startdate=20121231&enddate=20130101
Accept: application/json, text/javascript
{
"name": "ARM Holdings PLC",
"identifier": "$ARMH",
"startdate": "2012-12-31T00:00:00Z",
"enddate": "2013-01-02T00:00:00Z",
"datapoints": [
{
"date": "2013-01-01T00:00:00Z",
"sentiment": {
"current": -19,
"previous": -4,
"change": -15
},
"volume": {
"change": 6
}
},
{
"date": "2012-12-31T00:00:00Z",
"sentiment": {
"current": -4,
"previous": -40,
"change": 36
},
"volume": {
"change": 456
}
}
]
}
The asset sentiment resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| name | string | name for the asset |
| identifier | string | identifier used in the request |
| startdate | datetime | the start date of the datapoint range returned |
| enddate | datetime | the end date of the datapoint range returned |
| datapoints | list of datapoint resources | datapoint |
{
"date": "2013-01-01T00:00:00Z",
"sentiment": {
"current": -19,
"previous": -4,
"change": -15
},
"volume": {
"change": 6
}
}
The datapoint resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| date | datetime | date which datapoint relates to |
| sentiment | sentiment resource | sentiment value |
| volume | volume resource | volume value |
"sentiment": {
"current": 64,
"previous": 58,
"change": -6
}
The sentiment resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| current | integer | sentiment for the current period |
| previous | integer | sentiment for the previous period |
| change | integer | absolute change between current and previous sentiment values |
"volume":{
"change": -36
}
The volume resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| change | integer | change from normal social conversation volume level |
The asset themes endpoint will return a list of themes for the asset based on the specified {identifier} value.
GET /assets/{identifier}/themes/
JSON Response
GET https://api.knows.is/assets/$ARMH/themes/
Accept: application/json, text/javascript
{
"name": "ARM Holdings PLC",
"identifier": "$ARMH",
"startdate": "2013-01-01T00:00:00Z",
"enddate": "2013-01-01T00:00:00Z",
"dailythemes": [
{
"date": "2013-01-01T00:00:00Z",
"themes": [
{
"title": "The title of the theme"
}
]
},
{
"date": "2013-01-02T00:00:00Z",
"themes": [
{
"title": "The title of the first theme"
},
{
"title": "The title of the next theme"
}
]
}
]
}
The theme list resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| themes | list of theme resources | list of themes for the requested asset |
The theme resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| title | string | Theme title |
Access to the Insights endpoints is via the same oAuth credentials as the Knowsis data API above. This API is responsible for rendering more visual elements such as widgets and graphs.
This endpoint will return a widget containing the most recent tweets for a particular {identifier}, and will auto-update via javascript as new tweets become available. High-level analytics such as sentiment & volume will also be visible depending on subscription level.
GET /assets/w/{identifier}/
The following are optional query string parameters
| Field | Type | Description |
|---|---|---|
| css | encoded url | the https url to a stylesheet be injected into the of the response for client styling |
GET https://insights.knows.is/assets/w/$ARM/?css=https://www.client.com/style.css
Accept: text/html
The html will be styled as follows and any of the CSS classes can be styled:
<html>
<body>
<div class="container">
<div class=" app-container">
<div id="ARMH " class="tweets-view-container ">
<ul class="tweets-list ">
<li class="tweet-container">
<div class="tweet-title-container">
<a href="https://twitter.com/intent/user?screen_name=HalftimeReport">
<div class="tweet-profile-icon"><img
src="https://testinsights.knows.is/external/twitter_profile/?url=https://pbs.twimg.com/profile_images/590580807753986049/fhYEXRiC_normal.png"
width="15px" height="15px" alt="User Image"></div>
<div class="tweet-profile">CNBC Halftime Report</div>
<div class="tweet-username">@HalftimeReport</div>
</a>
<a class="tweet-date-link" href="https://twitter.com/HalftimeReport/status/738400580079517697"
target="_blank">
<div class="tweet-date" data-created="2016-06-02T16:03:11"
title="Thu, 2 Jun 2016 16:03:11 +0100">2 minutes
</div>
</a>
</div>
<div class="tweet-content">
Best days behind for Apple? $AAPL
<a href="http://twitter.com/HalftimeReport/status/738400580079517697/photo/1"
class="link-primary media-url" target="_blank">pic.twitter.com/7a00FrhTaK</a>
<div class="tweet-media">
<a href="http://twitter.com/HalftimeReport/status/738400580079517697/photo/1"
target="_blank">
<img class="img-responsive"
src="https://testinsights.knows.is/external/image/?url=https://pbs.twimg.com/media/Cj9TaZsWgAAKCIM.jpg"
alt="Image attached to this tweet">
</a>
</div>
</div>
</li>
</ul>
</div>
<div id="powered-by-knowsis ">
Powered by <a href="http://knowsis.com " target="_blank " title="Knowsis | Actionable Web Intelligence ">Knowsis</a>
</div>
</div>
</div>
</body>
</html>The "Powered By Knowsis" section must not be styled, moved or hidden without prior agreement.
By default images attached to a tweet are shown and links to these images are hidden.
If you want to hide images and display links instead, add the following css to your stylesheet:
.media-url {
display: inline;
}
.tweet-media {
display: none;
}We support several publicly available identifiers for retrieving details of the assets that we track. A full list of available identifiers can be found using the /assets/ endpoint to fetch a list of all assets.
The following common ticker symbol formats are currently supported in requests for individual assets:
AAPL:US
AAPL.0
NASDAQ:AAPL
APPL
we also support the most common social media format, the Twitter cashtag:
$GOOG
and International Securities Identification Numbers (ISIN):
US0378331005
Macro and asset driver topics do not have a ticker symbol or ISIN code so you will need to refer to these by the Knowsis proprietary identifiers which can be found by calling the /assets/ endpoint.
As identifiers may contain reserved characters, you should ensure that the identifier has been url encoded before being sent to the API.
In the event of a problem with your request you will receive an error response
As much as possible, Knowsis attempts to use the appropriate HTTP status codes to indicate the general class of problem. We will also provide a body to the request in the requested format with more details on the problem where available. You should handle errors in your application and present your end users with a more friendly response than the error messages provided here.
| Error Message | Description |
|---|---|
| 400 (Bad Request) | Any case where a parameter is invalid, or a required parameter is missing. This includes the case where OAuth parameters are not provided. |
| 401 (Unauthorized) | The OAuth signature was provided but was invalid. |
| 403 (Forbidden) | Access to the requested resource was refused by the server. Your api account does not have permissions to access the request resource. |
| 404 (Not Found) | The requested resource does not exist. |
| 405 (Method Not Allowed) | Attempting to use POST with a GET-only endpoint, or vice-versa. |
| 409 (Conflict) | The request could not be completed as it is. Use the information included in the response to modify the request and retry. |
| 500 (Internal Server Error) | Our servers are having problems. The request is probably valid but needs to be retried later. |
Example error response body
{
"error": {
"errorCode": "400",
"errorMessages": [
"Missing parameter OAuth Consumer",
"Missing parameter OAuth Nonce",
"Missing parameter OAuth Signature"
]
}
}
The error resource is made up of the following fields:
| Field | Type | Description |
|---|---|---|
| errorCode | integer | The relevant HTTP error code |
| errorMessages | list of strings | List of human readable error messages |
Additional details are provided in the errorMessages part of the error resource. It should be one of the following types of errors.
| Error Message | Description |
|---|---|
| Missing OAuth parameter | The case where any of the required OAuth parameters are not provided. we will also specify the name of parameter that is missing. |
| Invalid OAuth Consumer | The provided OAuth Consumer key was not valid |
| Signature verification failed | The provided OAuth signature did not match that generated by the server. |