Guide

Rest API

The API's purpose is to retrieve raw data for indicators. When a request reaches an endpoint, no new data point is generated. Rather, existing data is retrieved.
Data can be obtained in JSON, CSV, and XLSX formats.
Each API query delivers data for Sentiment A and Sentiment B.
A single query solely provides data for a specific indicator configuration.
Single data points or time series can be requested.
GET HTTP request type
Referrer Policy in Headers are set to strict-origin-when-cross-origin. For info on more flexible access to MSA.IDX data check the Terms of use section. Same applies for potentially heavy users.

Request

Generally, the API URLs are analogous to the web interface URLs, but their suffixes and prefixes differ.

Comparison between URLs of web interface and API
URL web interface	https://msaidx.com/idx/javascript/reddit/popular/new/react/withcomments/feed
URL API for JSON request	https://msaidx.com/api/v0/idx/javascript/reddit/popular/new/react/withcomments/feed/n.json

API URL structure
API root	https://msaidx.com/api/v0
URL Segments	/<subreddit_filter>/<platform>/<subreddit_sort>/<postings_sort>/<postings_filter>/<comments>/<data_type>/<last_key>.<data_format>

Request props
property	description	options	remarks
<subreddit_filter>	filter Subreddits	string	latin letters in lower case; URI, replace whitespace with `%20`; forbidden: `_` and `#`; max length 30 characters
<platform>	online platform	`reddit`	currently only Reddit is supported
<subreddit_sort>	sort criteria subreddits	`relevance`, `popular`, `activity`	Subreddits sort options
<postings_sort>	sort criteria postings	`new`, `hot`, `rising`, `top`, `controversial`	Postings sort options
<postings_filter>	filter postings	string	latin letters in lower case; URI, replace whitespace with `%20`; forbidden: `_` and `#`; max length 30 characters
<comments>	comments inclusion	`commentsonly`, `withcomments`, `nocomments`
<data_type>	data type	`feed`, `point`	see table below
<last_key>	last evaluated key, time	`n`, string	last evaluated key from a previous query, formatted as base 32 of milliseconds since UNIX epoch; see table below
<data_format>	data format	`json`, `csv`, `xlsx`

There are two types of data: <data_type> for a single point in time point or a time series of the last 200 readings feed. For each of these two types, either the most recent values can be retrieved with the suffix /n or a specified time range starting from the last evaluated key /<last_key>.

Single data point or time series feed: <data_type>, <last_key>
query type	URL Fragments		description	example
Feed	/feed	/n	retrieve the 200 newest sentiment values	https://msaidx.com/api/v0/idx/javascript/reddit/popular/new/react/withcomments/feed/n.json
Feed	/feed	/<last_key>	retrieve 200 sentiment values, starting after a timestamp	https://msaidx.com/api/v0/idx/javascript/reddit/popular/new/react/withcomments/feed/1hd8p6can.json
Point	/point	/n	retrieve the latest sentiment values	https://msaidx.com/api/v0/idx/javascript/reddit/popular/new/react/withcomments/point/n.json
Point	/point	/<last_key>	retrieve values of a certain point of time	https://msaidx.com/api/v0/idx/javascript/reddit/popular/new/react/withcomments/point/1hd8p6can.json

Response

The <last_key> is included in response Headers as X-Last-Evaluated-Key
Data structure of different <data_type>s is identical

Resonse types
code	description
`200`	probably all ok
`204`	request ok, but no data for this query
`500`	Error

Response structure JSON
Variable		Key	Type
Time Retrieved		`time_retrieved`	ISO 8601 time string (UTC)
count		`count`	integer
`<last_key>`		`last_key`	string Limit not reached:`n`, otherwise: base 32 epoche timestring
Index ID		`index_id`	Identifier of a specific indicator configuration; analogous to the request URL, using first characters of sorting enums
Indicator data		`data`	array
`data`	Time sentiment was measured	`time`	ISO 8601 time string (UTC)
	Sentiment A score	`sa_v`	float
	Sentiment A standard deviation	`sa_d`	float
	Sentiment A median	`sa_m`	float
	Sentiment B score	`sb_v`	float
	Sentiment B standard deviation	`sb_d`	float
	Sentiment B median	`sb_m`	float
	Data points	`dp`	integer Number of Subreddits data were extracted from
	Is bot	`bot`	boolean `true` for bot request, `false` for human request

Example JSON response of `/point` request

URL: https://msaidx.com/api/v0/idx/javascript/reddit/popular/new/react/withcomments/point/1hd8p6can.json

{
  "time_retrieved": "2023-10-23T02:37:26.159Z",
  "count": 0,
  "last_key": "1hd8p6can",
  "index_id": "msaidx:javascript:r:p:n:react:w",
  "data": [
    {
      "time": "2023-10-21T09:31:22.839Z",
      "sa_v": 2.448264769196107,
      "sa_d": 5.815966592948507,
      "sa_m": 3.683261802575108,
      "sb_v": 2.1893821726872957,
      "sb_d": 1.8032012188732949,
      "sb_m": 7.729057017543861,
      "dp": 27,
      "bot": false
    }
  ]
}

Example JSON response of `/feed` request, latest results `/n`

URL: https://masaidx.com/api/v0/idx/javascript/reddit/activity/new/react/withcomments/feed/n.json

{
  "time_retrieved": "2023-10-23T05:00:51.081Z",
  "count": 3,
  "last_key": "n",
  "index_id": "msaidx:javascript:r:a:n:react:w",
  "data": [
    {
      "time": "2023-10-23T05:00:43.706Z",
      "sa_v": 1.6153406659263088,
      "sa_d": 5.404872204097089,
      "sa_m": 2.328805073431242,
      "sb_v": 1.9664262575303402,
      "sb_d": 1.918531502717251,
      "sb_m": 3.8814285714285717,
      "dp": 26,
      "bot": false
    },
    {
      "time": "2023-10-22T06:02:11.688Z",
      "sa_v": 2.251535697659823,
      "sa_d": 5.294023297711982,
      "sa_m": 2.800413613146791,
      "sb_v": 2.1386080623433665,
      "sb_d": 1.6666954670612415,
      "sb_m": 4.787234042553192,
      "dp": 26,
      "bot": false
    },
    {
      "time": "2023-10-22T00:45:48.928Z",
      "sa_v": 2.19792442009423,
      "sa_d": 5.274765931735789,
      "sa_m": 2.7745614035087725,
      "sb_v": 2.137344208353603,
      "sb_d": 1.6693694081932489,
      "sb_m": 4.931173143138219,
      "dp": 25,
      "bot": false
    }
  ]
}