1.InfoTrie API Manual #

1.1.Getting Started #

  1. Get familiar with how to call an API
  2. Detailed explanations of general definitions of the sentiment data
  3. Have your first try on an API

1.2.Call An API #

Example:

curl -H "AppKey:<app-key>" -H "Accept: application/json" https://feed.finsents.com/idata/get_articles?class_nameid=c_1389

 

All Request Should follow the following:

  • All Request should have AppKey in Request Header

example AppKey : 480881f124a5427bb3324642fbc2f5bf

  • All Request should specify “Accept” Header as

Accept : application/json

  • All request should have correct API call and params as detailed in the doc

1.3.ID of Sentiment Data #

Since our system can analyse various types of sentiment data, we provider ID for the user to access details of a specific sentiment data through our APIs.

The general format for the ID is x_<id> where x represents the type of the sentiment data and id can specify the exact element. The symbol of different types is illustrated in the table.

Type nameid
sector s_<ID>
industry i_<ID>
subindustry si_<ID>
company c_<ID>
tag t_<ID>
source o_<ID>
index in_<ID>
place pl_<ID>
category ca_<ID>

1.3.1.Sector: s_<ID> #

Sector ID Sector Name
10  Energy
15  Materials
20  Industrials
30  Consumer Discretionary
40  Financials

1.3.2.Industry: i_<ID> #

Industry ID Industry Name
101020  Oil, Gas & Consumable Fuels
151010  Chemicals
151020  Construction Materials
201060  Machinery
203050  Transportation Infrastructure

1.3.3.Sub-industry: si_<ID> #

Sub-Industry ID Sub-Industry Name
15104010 Aluminum
20101010 Aerospace & Defense
20104010 Electrical Components & Equipment
20107010 Trading Companies & Distributors
20304010 Railroads

1.3.4.Company: c_<ID> #

Company ID Company Name
1 AAR CORP
2 AFP IMAGING CORP
84 APPLE INC
280 COCA-COLA BTLNG CONS
41815 ASIA UNITED BANK

1.3.5.Source: o_<ID> #

Source ID Source Name
58 Ticker Sense
72  Economix (NYT)
75  WSJ Blog
111  myweekendinvestment
134  forexcrunch

1.3.6.Index: in_<ID> #

Index ID Index Short Name Index Long Name
1 DAX30 DAX 30
2 CAC40 Cac 40
3 FTSE100 FTSE 100
4 STOXX50E Eurostoxx 50
5 DJ30 DJ 30
6 HSI40 Hang Seng Index
7 STI30 Straits Times Index (STI) 30
8 BSE30 BSE Sensex
9 SP500 S&P 500

1.3.7.Place: pl_<ID> #

Place ID Place Name
USA United States of America
GBR United Kingdom
CHN China
HKG Hong Kong
SGP Singapore

1.3.8.Category: ca_<ID> #

Category ID Category Name
1 Market News
5 Blogs
8 Oil and Gas
17 Forex
19  Financial Technology
 …

1.4.API Status Code #

API Status Code is used to present the status of the response after calling a specific API. It could help you quickly know/debug the exact problem.

All status codes in our APIs are standard HTTP status codes. Specifically, the five types of the status code are listed in the following.

Usually, codes in the 2xx range indicate success, codes in the 4xx range are for client-related failures, and 5xx codes are for server-related issues (these are rare).

  • 200 OK Successful request.
  • 201 Created New resource created.
  • 202 Accepted The request has been accepted for processing, but the processing has not been completed.
  • 400 Bad Request The request is malformed. Check the parameters or the syntax.
  • 401 Unauthorized Couldn’t authenticate the request.
  • 403 Forbidden The request is not allowed.
  • 404 Not Found No such resource.
  • 405 Not Allowed The method is not allowed.
  • 409 Conflict The resource already exists.
  • 412 Failed The precondition is invalid.
  • 413 Too Large Requests Too large requests entity hit the API too quickly.
  • 500 Internal Server Error Something went wrong on our end (these are rare).
  • 501 Not Implemented Something went wrong on our end (these are rare).
  • 503 Service Unavailable Something went wrong on our end (these are rare).

1.5.Choose Timezone #

By default, API returns data for Europe/Berlin timezone.

Some APIs have timezone parameter, please refer to each API description in API list for specific information. Users can choose from 3 timezones:
1/ America/New_York
2/ Asia/Singapore
3/ Europe/Berlin

For example, for choosing Asia/Singapore timezone, add ‘&timezone=Asia/Singapore‘ at the end of URL: https://feed.finsents.com/idata/get_articles?class_nameid=c_1389&timezone=Asia/Singapore

1.6.Categories of Sentiment Data #

InfoTrie offers up to 15 years of sentiment history as direct API access or through our data vendor partners. The tick by tick and/or daily time series can be provided for any index. Historical data can be downloaded on demand. Delivery can be made by mail / FTP / real-time feed (csv/json/xml).

InfoTrie is computing sentiment scores for:

 

1.6.1.Stocks #

Our system analyses more than 50,000 stocks and major global stock indices, which consists of

  • 15,000+ North American stocks
  • 8,000+ European stocks
  • 4,000+ Japanese stocks
  • 14,000+ Asian stocks excluding Japan
  • Chinese stocks: http://tushare.org/
  • 3,000+ Australia / New Zealand stocks
  • 1,000+ South American stocks

1.6.2.Commodities #

There are more than 181 kinds of Commodities monitored including

  • Base and Precious Metals
  • Soft
  • Energy

1.6.3.Forex #

Around 400 different kinds of forex and currencies are active in our system such as

  • AUD
  • EUR
  • GBP
  • HKD
  • INR
  • JPY
  • NOK
  • NZD
  • SEK
  • SGD
  • USD

1.7.Try Your First API #

Here is an example for you first try on calling our API.

You can call the API through Postman following the simple steps which are shown as below:

  1. Log in/Sign up Postman

 

  1. Input the URL and APPKEY

a. Type the URL to point a specific API: https://feed.finsents.com/idata/get_articles?class_nameid=c_1389

b. Type the your APPKEY in Headers:

key: APPKEY             value: 480881f124a5427bb3324642fbc2f5bf

 

  1. Send and get the response

The APPKEY is only used for testing your first API. Please contact us to get a stronger APPKEY with more permission!

 

Any comments, questions, suggestions or concerns please feel free to email: contact@infotrie.com.

 

2.API List #

2.1.Get Articles #

Get the articles for sector, industry, sub-industry and companies.

Timezone parameter

By default, this API returns data for Europe/Berlin timezone. Users can choose from 3 timezones:

1/ America/New_York
2/ Asia/Singapore
3/ Europe/Berlin

Request

Method URL           
GET idata/get_articles/

 

 

Params Values  
class_nameid string “nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    in : index

●    pl: place

●    c: company

●    o:source

●    bl:blog (use bl_all for all blogs)

●    cm: commodity

●    top: topic

subclass_nameid string This is an optional field.

“nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    s : sector

●    i: industry

●    si : subindustry

●    c: company

●    t: tag

●    o:source

offset number Default value is 0
count number default value is 15
start_date number This is the maximum value. The format is “YYYY-MM-DD”
end_date number This is the minimum value. The format is “YYYY-MM-DD

If start_date is given, then the default end_date is 24 hours past start_date.

last_update number values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

 

 

Note: for retrieving news just for a day, provide values just for the start_date.

 

The table shows the possible values of subclass_nameid for a given class_nameid

 

class nameid subclass_nameid
in : index ●    s : sector

●    i: industry

●    si : subindustry

●    c: company

●    t: tag

●    o:source

pl: place ●    s : sector

●    i: industry

●    si : subindustry

●    c: company

●    t: tag

●    o:source

c: company ●    t: tag

●    o:source

●    tp:static tag

o:source

 

Response

Status Response
200 Response will have the JSON structure as below

[

{

“last_update”: <integer timestamp> value ‘0’ will return current data

“data”:

{

title: <article title>,

hms: <hour:min:sec>

teaser: <teaser>,

image_name: <image name>

url:<url>

date: <string in dd-mm-yyyy format>

domain: <domain name>

domain_id: <name id for the domain>

sentiment: <between 1 to 10>

relevance: <high,medium,low>

},

{ … }

]

}

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

2.2.Get Treemap #

Get Treemap data.

Request

Method URL           
GET idata/get_treemap/

 

Params Values  
asset

 

string

 

This shows which asset class data has to be returned.

values :

●    equities

place string values : values : refer to Appendix B
sector string values : [not supported]
market string values : [not supported]
index string values : refer the Appendix A
exchange string values:  name OR name_id for the exchange

Values for supported exchanges can be retrieved using the get_data method

companies string values: company_id’s in csv format
last_update number values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

view_all boolean  [not supported]

values : 0 and 1

default: 0

If set to 1, then the return data will contain all companies which includes companies with zero buzz score and sentiment score

count number Return one batch of result by default. Parameter “count” can return several batches of result in reverse time order

 

Response

Status Response
200 Response will have following default

structure.

 

“nameid” will be concatenation of class type and id. eg: x_<id>

where x is:

●    s : sector

●    i: industry

●    si : subindustry

●    c: company

 

 

{

“last_update”: <integer timestamp> value ‘0’ will return current data

“data”:

[

{

“name”: <sector name>,

“nameid”: <sector name id>,

“buzz”: <score in range of 0 -10>

“sentiment”: <score in range of 0 -10>

“change”: <change in %>

“children”: [

{

“name”: <industry name>,

“nameid”: <industry name id>,

“buzz”: <score in range of 0 -10>

“sentiment”: <score in range of 0 -10>

“change”: <change in %>

“children”: [

{

“name”: <subindustry name>,

“nameid”: <subindustry name id>,

“buzz”: <score in range of 0 -10>

“sentiment”: <score in range of 0 -10>

“change”: <change in %>

“children”: [

{

“name”: <company name>,

“ticker”: <ticker>,

“price”: <current stock price>,

“nameid”: <company name id>,

“buzz”: <score in range of 0 -10>

“raw_buzz”: <not normalized value>

“sentiment”: <score in range of 0 -10>

“raw_sentiment”: <not normalized value>

“change”: <change in %>

},

{ … }

]

},

{ … }

]

},

{ …}

]

},

{…}

]

}

400 {“error”:”Invalid param.”}
401 {“error”:”Invalid API token.”}
500 {“error”:”Something went wrong. Please try again later.”}

2.3.Get Tags #

Request

Method URL           
GET idata/get_tags/

 

 

Params Values  
class_nameid string “class_nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    in : index

●    pl: place

●    gen:general (gen_0)

 

subclass_nameid string “subclass_nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    s : sector

●    i: industry

●    si : subindustry

●    c: company

 

 

last_update number values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

count number Return one batch of result by default. Parameter “count” can return several batches of result in reverse time order

 

For values of id : Refer the infotrie classification document of id’s of each of class members

Response

Status Response
200 Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

name: <tagname>

weight: <number in range of  0- 10>

},

{ … }

]

}

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

2.4.Get Sentiment History #

Timezone parameter

By default, this API returns data for Europe/Berlin timezone. Users can choose from 3 timezones:

1/ America/New_York
2/ Asia/Singapore
3/ Europe/Berlin

Request

Method URL           
GET idata/get_sentiment_history/

 

 

Params Values  
nameid string “nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    c: company (in case of company, the result would be single company data)

●    in:index

●    pl:place

●    cm: <commodity> eg: cm_51

●    top : topic

multiple nameid’s can be specified in csv format

 

start_date (not supported) string The start date

In format YYYY-MM-DD

Default  is  “today”

end_date (not supported) string In format YYYY-MM-DD

Default is  90 days from start date

ndays number Default is  90 days from date
last_update number values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

 

Response

status nameid Response
200 c_<company_id> Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

name:<company name>

ticker:<company ticker>

start_date: <YYYY/MM/DD>

end_date: <YYYY/MM/DD>

sentiment: [

{

high: <score in range 0 – 10>

low : <score in range 0 – 10>

sentiment : <score in range 0 – 10>

buzz : <score in range 0 – 10>

date : <DD/MM/YYYY>

}

… , …

]

},

{

name:<company name>

ticker:<company ticker>

}

]

}

where ;

sentiment data is in ascending date format

●    First element is the max date (start date)

●    last element  is the min date (end date)

sentiment = “0” means no data found for the date

200 cm_<commodity_id> Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

name:<commodity name>

class:

type:

subtype:

start_date: <YYYY/MM/DD>

end_date: <YYYY/MM/DD>

sentiment: [

{

high: <score in range 0 – 10>

low : <score in range 0 – 10>

sentiment : <score in range 0 – 10>

buzz : <score in range 0 – 10>

date : <DD/MM/YYYY>

}

… , …

]

},

{

name:<commodity name>

class:

}

]

}

where ;

sentiment data is in ascending date format

●    First element is the max date (start date)

●    last element  is the min date (end date)

sentiment = “0” means no data found for the date

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

2.5.Get News Buzz #

Request

Method URL           
GET idata/get_news_buzz/

 

 

Params Values  
type

 

string

 

Type

values :

●    “gen_0”

●    “twitter”

 

last_update number last_update

values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

 

Response

Status Type Response
200 “gen_0” Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

title: <title>,

url: <url>,

weight: <weight of article in range 0-10>,

teaser: <teaser>,

image_name: <image name>

},

{…}

]

}

“twitter” Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

tweet: <text>,

id: <tweetid>

},

{…}

]

}

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

2.6.Get Data #

Request

Method URL           
GET idata/get_data/

 

 

Params Values  
type string Type

Data type. Valid values are :

●     “company_list”,

●    “company_list_all”

●    ”sources”

●    “source_categories”

●    “indexes”

●    “exchanges”

version number Version

Current version of the data.

Server will return the data only if the version reported is older than currently available at server.

 

last_update number last_update

values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

 

Response

Status Response
200 Data structure for the response will depend on the data type. Refer the table below for each data type
400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

 

 

 

Data Type Response Data Structure
company_list

company_list_all

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

version:<version>,

data: [

{

    name:<company name>

nameid:  i_<company_id>

ticker:<company ticker>

place:<place name>

    exchange:<exchange name>

  },

{ … }

]

}

}

commodity_list {

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

version:<version>,

data: [

{

    name:<commodity name>

nameid:  cm_<commodity_id>

class:<commodity class Symbol>

type:<commodity class Type>

subtype:<commodity class SubType>

  },

{ … }

]

}

}

 

sources {

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

version:<version>,

data:[

{

name: <source name>,

nameid: o_<source_id>,

category: <comma separated category id’s (ca_)>

},

{…}

]

}

}

NOTE:  Refer to the get_data   source_categories for the supported categories

source_categories NOTE:

●      Maximum support of 3 levels. Means “parent category”, “child category” and “child of child category”.

●      The priority can be used to decide the order of  listing

 

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

version:<version>,

data:[

{

name: <category name>,

name_id: ca_<category id>,

priority: <number in 0 -10>

children : [

name:  ,

priority: ,

children: [ … ]

]

},

{…}

]

}

}

indexes {

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

version:<version>,

data:[

{

name: <index name>,

nameid: in_<index_id>,

place_name:<place_name>,

placeid:pl_<place_id>

regionid: pl_<region_id>

region_name:<region name>

scoreid:sc_<score_id>

},

{…}

]

}

}

exchanges {

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

version:<version>,

data:[

{

name: <exchange name>,

name_id: <exchange id>

},

{…}

]

}

}

places {

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

version:<version>,

data:[

{

place: <place name>,

nameid: pl_<place_id>,

},

{…}

]

}

}

 

 

2.7.Get Articles Tag #

Get the articles for sector, industry, sub-industry and companies

Timezone parameter

By default, this API returns data for Europe/Berlin timezone. Users can choose from 3 timezones:

1/ America/New_York
2/ Asia/Singapore
3/ Europe/Berlin

Request

Method URL           
GET idata/get_articles_tag/

 

Params Values  
class_nameid string “nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    in : index

●    pl: place

●    gen:general (use gen_0 )

last_update number values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

count number Return one batch of result by default. Parameter “count” can return several batches of result in reverse time order
tag name of the tag return top articles for one single tag only

Response

Status Response
200 Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

name: <tag name>

articles:

[

{

title: <article title>,

teaser: <teaser>,

image_name: <image name>

url:<url>

time: string in dd:mm:yyyy format

domain: <domain name>

},

]

},

{ … }

]

}

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

2.8.Get Article Ids #

Get big list of article ids for time range for an asset

Request

Method URL           
GET idata/get_articles_ids/

 

 

Params Values  
nameid number “nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    cm: <commodity> eg: cm_51

●    c: <company>

●    fx: <forex>

 

 

Response

Status Response
200 Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

date:<DD-MM-YYYY>

id:<document id>

}

]

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

2.9.Get Articles for Ids #

Get article details for ids

Request

Method URL           
GET idata/get_articles_for_ids/

 

 

Params Values  
nameid number “nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    cm: <commodity> eg: cm_51

●    c: <company>

●    fx: <forex>

 

ids string article ids in csv format

 

Response

Status Response
200 Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

[

{

title:

url:

relevance: <score in range 1 to 10; where 1 is lowest and 10 is highest>

sentiment:<score in range 1 to 10; where 1 is lowest and 10 is highest>

}

]

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

2.10.Get Leaders Laggers #

Timezone parameter

By default, this API returns data for Europe/Berlin timezone. Users can choose from 3 timezones:

1/ America/New_York
2/ Asia/Singapore
3/ Europe/Berlin

Request

Method URL           
GET idata/get_leaders_laggers/

 

Example : /get_leaders_laggers?nameid=in_9&count=3

 

 

Params Values  
nameid

 

string

 

Type

values :

●    <index_id>

 

count number Max number of companies in each of leader/lagger

Default is 5

last_update number last_update

values:

●    0 means, there is no valid last updated data

●    In case of any non zero value, the response will have valid “data” only if the current data at server is newer than the last updated version reported by the client

 

Response

Status Response
200 Response will have the JSON structure as below

{

last_update: <integer timestamp> value ‘0’ will return current data

data:

{

leaders :

[

{

nameid: <company id>,

sentiment : <sentiment score>

ticker : <news volume>

name :<company name>

},

]

laggers :

[

{

nameid: <company ticker>,

sentiment : <sentiment score>

ticker : <news volume>

name :<company name>

},

]

}

400 {“error”:”Invalid params”}
401 {“error”:”Invalid Auth key.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

 

 

2.12.Get Company ID #

Get Company id.

*Note:

This API works based on query. User can give ticker for a company also as part of query. This API will return companies that are satisfying the query condition. Ie, if you give ‘FB’, it will return ‘FaceBook’ company detail and company(s) that have FB in their names. For query with ticker, it will result only one company.

Request

Method URL           
GET https://feed.finsents.com/search_company?query=company name

 

Params Values  
nameid string “nameid” will be concat of class type and id. eg: x_<id>

where x is:

●    c: <company>

 

Response

Status Response
200 Response will have following default

structure.

 

{

“country”:

“name”: ”

“nameid”:

“is_active”:

“default_ticker”:

“ticker”:

}

]

}

400 {“error”:”Invalid param.”}
401 {“error”:”Invalid API token.”}
500 {“error”:”Something went wrong. Please try again later.”}

 

Help Guide Powered by Documentor
Suggest Edit