NAV
shell python

Introduction

Welcome to the StockGeist REST API documentation page. If you really liked our StockGeist dashboard and feel like going to the next level by integrating our data into your own project, then you are in the right place.

Here you will find all the information about the features and possibilities of our API as well as code samples illustrating usage of all the available endpoints. By querying these endpoints, you will get exactly the same data that is used to power the StockGeist dashboard itself.

For those eager to learn everything about our API from A to Z, - just keep scrolling this page down. Otherwise, you can use the navigation panel on the left and jump straight to the endpoint that you need.

Query structure

The base URL for all API calls is https://api.stockgeist.ai/ and the general query structure is <base_url>/<endpoint_group>/<endpoint_name> All endpoints can be divided into two groups:

Additional parameters to the query can be passed as <endpoint_name>?param1=value1,value2&param2=value3,value4. Here param1 and param2 are query parameters whose values value1, ... specify what exactly is returned by the endpoint. Thus, the endpoint route is separated from the query parameters by the question mark symbol ?, multiple parameters are joined by symbol &, their values assigned with equality sign = and multiple values are specified using a comma ,.

Response structure

General structure of the response:

    {
      "metadata":
        {
          "status": 200,
          "message": "OK",
          "credits": 500000,
          "server_timestamp": "2021-02-11 09:58:39.637552+00:00"
        },
      "body": 
        ...
    }

The returned result for all endpoints is always a JSON object. The metadata key refers to the response JSON section common for all endpoints and the body key data depends on the endpoint. Inside the metadata section, status key denotes the HTTP status code (see all Status codes) of the response, message gives the specifics behind the status code, credits denotes the number of credits available for making API queries and server_timestamp holds the timestamp of the moment when the server finished processing the query. If status is not equal to 200, the value under the body key is an empty list.

Authentication and querying

Use this code for authentication and querying:

import requests

token = "qwerty1234"

# create a session and pass correct headers containing the token to it
session = requests.Session()
session.headers = {
        "Content-Type": "application/json",
        "Authorization" : f"Bearer {token}"
}

res = session.get("<base_url>/<endpoint_group>/<endpoint_name>")

# or create a default session and pass the token with the query
session = requests.Session()

res = session.get("<base_url>/<endpoint_group>/<endpoint_name>?token=qwerty1324")
# with shell, you can just pass the correct header with each request
curl -X "<base_url>/<endpoint_group>/<endpoint_name>" \ 
-H 'Content-Type: application/json' -H "Authorization: qwerty1234"

# or pass the token with the query
curl -X "<base_url>/<endpoint_group>/<endpoint_name>?token=qwerty1234"

StockGeist uses API tokens to allow access to the API. You can obtain your API token by creating a StockGeist account and navigating to the API token section of your user profile.

StockGeist API server expects the API token to be included in all API requests to the server in a header

Authorization: "Bearer qwerty1234

or in the query itself, e.g.,

https://api.stockgeist.ai/time-series/message-metrics?token=qwerty1234

Request limits

For any endpoint, we enforce the maximum limit of 10 requests per 1 second per 1 IP address.

Query costs

Each query made to StockGeist API costs a certain number of credits depending on the endpoint, granularity of requested data and number of returned data points. Thus, the total cost of a query is given by the formula: total_cost = basic_endpoint_cost * timeframe_factor * number_of_datapoints. Here basic_endpoint_cost varies for each endpoint and is given under corresponding menu entries of this documentation. timeframe_factor depends on the selected data granularity and is given by the following relations: 5m - 1; 1h - 5; 1d - 50. Finally, number_of_datapoints depends on the specified time range.

Status codes

The StockGeist API uses the following error codes:

Error Code Meaning
200 [OK] -- Everything is fine.
400 [Bad Request] -- Query parameters are wrong.
401 [Unauthorized] -- API token is wrong or not authorized to access the specified endpoint.
403 [Forbidden] -- Not enough credits to access requested data.
404 [Not Found] -- Specified endpoint not found.
429 [Too Many Requests] -- Request limit exceeded.
500 [Internal Server Error] -- Problem with our server. Try again later.

Time series endpoints

General structure of response body of a time series endpoint:

    {
      ...
      "body":
        [
          {
            "timestamp": "2021-02-11 15:05:00+00:00",
            "symbol": "AAPL",
            ...
          },
          {
            "timestamp": "2021-02-11 15:10:00+00:00",
            "symbol": "AAPL",
            ...
          },
          ...
        ]
    }

This group of endpoints returns time-ordered data points. Depending on the query parameters, the data list returned in a JSON object can have one or more elements. Each data point is constructed from the information gathered during a time interval the beginning of which is specified by the timestamp value in the response body and duration of this interval - by the timeframe query parameter.

Query parameters

Parameter Default Description
symbol None (required) Company ticker. Only one ticker is allowed.
timeframe 5m Timeframe of returned time series data: 5m for 5 minute resolution, 1h - 1 hour, 1d - 1 day.
filter depends on endpoint What metrics to return with the response. Set of possible values depends on particular endpoint.
start last available timestamp Timestamp of the earliest data point in returned time series. Time is assumed to be in UTC time zone. Valid format: YYYY-mm-ddTHH:MM:SS.
end last available timestamp Timestamp of the latest data point in returned time series. Time is assumed to be in UTC time zone. Valid format: YYYY-mm-ddTHH:MM:SS.

Message metrics

Structure of a full message-metrics endpoint response body:

    {
      ...
      "body":
        [
          {
            "timestamp": "2021-02-11 15:05:00+00:00",
            "symbol": "AAPL",
            "inf_positive_count": 6.0,
            "inf_neutral_count": 5.0,
            "inf_negative_count": 1.0,
            "inf_total_count": 12.0,
            "em_positive_count": 0.0,
            "em_neutral_count": 5.0,
            "em_negative_count": 1.0,
            "em_total_count": 6.0,
            "total_count": 14.0,
            "pos_index": 0.46138368455516937,
            "msg_ratio": 2.0,
            "ma": 22.333333333333332,
            "ma_diff": -8.333333333333332,
            "std_dev": 20.4,
            "ma_count_change": 1.345
          },
          {
            ...
          },
          ...
        ]
    }

Get time-aggregated statistics of a processed stream of social media messages. This data reflects the message sentiment and count dynamics for different companies. Messages are classified into informative/emotional and positive/neutral/negative. The same message can be labeled as both informative and emotional at the same time. However, the sentiment can only be either positive, neutral or negative.

HTTP query example

GET https://api.stockgeist.ai/time-series/message-metrics?symbol=AAPL

filter parameter values

Value Description
inf_positive_count Number of positive informative messages.
inf_neutral_count Number of neutral informative messages.
inf_negative_count Number of negative informative messages.
inf_total_count Total number of informative messages.
em_positive_count Number of positive emotional messages.
em_neutral_count Number of neutral emotional messages.
em_negative_count Number of negative emotional messages.
em_total_count Total number of emotional messages.
total_count Total number of messages (default).
pos_index Positivity index value reflecting the interplay between positive/neutral/negative/total messages (higher value means more positive message sentiment).
msg_ratio Ratio of informative/emotional message counts.
ma Moving average (MA) value of total message count. For 5-minute timeframe the MA window is 12, 1-hour - 24, 1-day - 30.
ma_diff Difference between total_count and ma values.
std_dev Moving standard deviation (SD) of total message count. Windows are the same as for MA.
ma_count_change Moving average of ma_diff values normalized by ma values. This metric aims to capture sudden surges/declines of total message count compared to baseline MA.

Article metrics

Structure of a full article-metrics endpoint response body:

    {
      ...
      "body":
        [
          {
            "timestamp": "2021-02-11 15:00:00+00:00",
            "symbol": "AAPL",
            "titles": 
              [
                "What Do We Do With Big Tech Here? – DataTrek Research"
              ],
            "title_sentiments": 
              [
                "neutral"
              ],
            "mentions": 
              [
                18
              ],
            "summaries": 
              [
                "Apple, Microsoft, Google, Tesla, Amazon and Facebook are 24 percent of the S&P 500: If they were their own sector they would be almost 2x the next largest group (Health Care, 13 pct) The average return of the 6 names we’re calling Big Tech at +8. Owning Big Tech is leverage to whatever comes next out of Sand Hill Road. We don't think indexing has skewed Tech valuations."
              ],
            "sentiment_spans": 
              [
                [
                  {"idx": [128, 137], "sentiment": "positive"},
                  {"idx": [254, 274], "sentiment": "positive"},
                  {"idx": [345, 355], "sentiment": "negative"}
                ]
              ]
            ,
          },
          {
            ...
          },
          ...
        ]
    }

Get time-aggregated statistics of the articles mentioned in the stream of social media messages. This data reflects what financial media articles are the most popular with social media users.

HTTP query example

GET https://api.stockgeist.ai/time-series/article-metrics?symbol=AAPL

filter parameter values

Value Description
titles Title list of articles shared on social media (default).
title_sentiments List of labels specifying the sentiment of each gathered article title.
mentions List of integer values specifying the number of times that each article URL was shared on social media.
summaries List of AI-generated article text summaries.
sentiment_spans List of objects carrying information about pieces of summary texts assigned with either positive or negative sentiment.
urls List of URLs to original articles.

Price metrics

Structure of a full price-metrics endpoint response body:

    {
      ...
      "body":
        [
          {
            "timestamp": "2021-02-11 16:50:00+00:00",
            "symbol": "AAPL",
            "open": 135.0,
            "high": 135.05,
            "low": 134.895,
            "close": 134.895,
            "volume": 4463.0
          },
          {
            ...
          },
          ...
        ]
    }

Get OHLCV price data sourced from IEX exchange. This data is represented as price bars available in 5-minute, 1-hour and 1-day resolutions.

HTTP query example

GET https://api.stockgeist.ai/time-series/price-metrics?symbol=AAPL

filter parameter values

Value Description
open Open price of bar.
high High price of bar.
low Low price of bar.
close Close price of bar (default).
volume Volume of traded shares.

Topic metrics

Structure of a full topic-metrics endpoint response body:

    {
      ...
      "body":
        [
          {
            "timestamp": "2021-02-11 16:50:00+00:00",
            "symbol": "AAPL",
            "words": 
              [
                "doubled short", "position break", "short position", "check community", "community https", "https co", "interested options", "options check", "clearly shorting", "funds clearly", "shorting er", "anyone trade", "bitcoin would", "give return", "money weed", "smart money", "trade sgit", "weed bitcoin", "would anyone", "bitcoin tank", "bleeding calls", "calls plain", "everyone take", "losses bitcoin", "plain simple", "simple sorry", "sorry everyone", "take losses"
              ],
            "scores": 
              [
                1.0, 1.0, 1.0, 0.816496580927726, 0.816496580927726, 0.816496580927726, 0.816496580927726, 0.816496580927726, 0.5773502691896257, 0.5773502691896257, 0.5773502691896257, 0.35355339059327373, 0.35355339059327373, 0.35355339059327373, 0.35355339059327373, 0.35355339059327373, 0.35355339059327373, 0.35355339059327373, 0.35355339059327373, 0.33333333333333337, 0.33333333333333337, 0.33333333333333337, 0.33333333333333337, 0.33333333333333337, 0.33333333333333337, 0.33333333333333337, 0.33333333333333337, 0.33333333333333337
              ]
          },
          {
            ...
          },
          ...
        ]
    }

Get most important topics extracted from aggregated social media messages. This data aims to capture what social media users are talking about.

HTTP query example

GET https://api.stockgeist.ai/time-series/topic-metrics?symbol=AAPL

filter parameter values

Value Description
words List of word combinations that are most frequently encountered among social media messages (default).
scores List of numbers representing how popular the corresponding word combination is.

Ranking

Structure of a full ranking-metrics endpoint response body:

    {
      ...
      "body":
        [
          {
            "timestamp": "2021-02-11 16:50:00+00:00",
            "by": "total_count",
            "symbols": 
              [
                "SNDL", "TLRY", "APHA", "SOS", "TSLA", "CLSN", ...
              ],
            "scores": 
              [
                0.0, 1.0, 2.0, 3.0, 4.0, 5.0, ...
              ],
            "score_changes":
              [
                0.0, 0.0, 5.0, 2.0, -1.0, 6.0, ...
              ],
            "values":
              [
                217.0, 117.0, 36.0, 31.0, 26.0, 20.0, ...
              ]
          },
          {
            ...
          },
          ...
        ]
    }

Get stocks ranked by their social media message metrics. This data allows seeing how different stocks compare to each other with respect to the selected criterion.

Additional query parameters

Parameter Default Description
by total_count Select message metric by which stock ranking is produced. Available options: all message metrics described in Message metrics.
direction descending Ranking direction: descending/ascending leaves stock with largest/smallest metric value at the top.
top 5 Number of top stocks to return.

HTTP query example

GET https://api.stockgeist.ai/time-series/ranking-metrics?by=total_count&top=10

filter parameter values

Value Description
symbols List of ranked company symbols (default).
scores Corresponding ranking scores. Each score shows how many companies have greater value of selected metric.
score_changes Corresponding ranking score changes with respect to previous time interval. Depending on the value of direction query parameter (descending/ascending) for each score change positive value means that the selected metric increased/decreased relative to other stocks, negative value - the selected metric decreased/increased.
values Corresponding values of the selected ranking metric.

Snapshot endpoints

This group of endpoints returns momentary snapshots of most recent available data. Relevant query parameters are listed in the descriptions of each endpoint.

Symbols

Structure of symbols endpoint response body:

    {
      ...
      "body": 
          {
            "timestamp": "2021-02-11 00:00:00+00:00",
            "symbols": 
              {
                "stocks": ["A", "AAL", "AAOI", "AAP", "AAPL", "ABBV", "ABC", ...],
                "crypto": ["ADA-USD", "BNB-USD", "BTC-USD", ...]
              },

              ],

          }
    }

Get the latest list of stock and crypto symbols followed by the StockGeist system. This list is updated every day between 5:00 and 6:00 AM UTC.

Query parameters

There are no query parameters for symbols endpoint.

HTTP query example

GET https://api.stockgeist.ai/snapshot/symbols

Credits

Structure of credits endpoint response body:

    {
      "metadata":
        {
          "status": 200,
          "message": "OK",
          "credits": 1548478,
          "server_timestamp": "2021-02-11 09:58:39.637552+00:00"
        },
      "body": 
          {}
    }

Get the current number of available credits associated with StockGeist account.

Query parameters

There are no query parameters for credits endpoint.

HTTP query example

GET https://api.stockgeist.ai/snapshot/credits

Fundamentals

Structure of fundamentals endpoint response body:

    {
      ...
      "body":
          {
            "timestamp": "2021-02-11 00:00:00+00:00",
            "symbol": "AAPL",
            "book_to_sh": 3.91,
            "rsi_14": 41.79,
            "eps_next_y": 4.68,
            "52w_range": [53.15, 145.09],
            "eps_ttm": 3.7,
            "roa": 19.4,
            "dividend_perc": 0.63,
            "beta": 1.23,
            "oper_margin": 25.2,
            ...
          }
    }

Get fundamental indicators of a company. Fundamentals are updated everyday between 5:00 and 6:00 AM UTC.

Query parameters

Parameter Default Description
symbol None (required) Company ticker.
filter all available indicators What fundamental indicators to return with the response.

HTTP query example

GET https://api.stockgeist.ai/snapshot/fundamentals?symbol=AAPL

filter parameter values

Value Description
book_to_sh Book value per share.
rsi_14 Relative strength index with look-back window of 14 days.
eps_next_y Earnings per share estimate for next year ($).
52w_range 52-week trading range ($).
eps_ttm Diluted earnings per share for trailing 12 months ($).
roa Return on assets for trailing 12 months (%).
dividend_perc Dividend yield (%).
beta Beta value.
oper_margin Operating margin for trailing 12 months (%).
p_to_fcf Price to free cash flow for trailing 12 months.
eps_this_y Earnings per share growth this year (%).
inst_trans 3-month change in institutional ownership (%).
p_to_b Price to book value.
rel_volume Relative volume.
perf_quarter Quarter performance (%).
sales Revenue for trailing 12 months ($).
roi Return on investment (%).
inst_own Institutional ownership (%).
index Major index membership.
perf_ytd Year-to-date performance (%).
eps_next_q Earnings per share estimate for next quarter ($).
avg_volume 3-month average volume.
dividend Annual dividend ($).
p_to_c Price to cash per share.
insider_trans 6-month change in insider ownership (%).
short_float Short interest share (%).
country Country of origin.
income Income for trailing 12 months ($).
perf_year Year performance (%).
perf_half_y Half-year performance (%).
atr Average true range with look-back window of 14 days.
sales_past_5_y Annual sales growth for the past 5 years (%).
52w_high_diff Difference between current and 52-week high price (%).
gross_margin Gross margin for trailing 12 months (%).
peg Price to earnings to growth value.
perf_month Month performance (%).
volatility Weekly and monthly volatility (%).
cash_to_sh Cash per share.
short_ratio Short interest ratio.
eps_past_5_y Earnings per share growth for the past 5 years (%).
debt_to_eq Total debt to equity.
sector Sector of operation.
industry Industry of operation.
eps_q_to_q Year-over-year quarterly earnings per share growth (%).
p_to_e Price to earnings value for trailing 12 months.
prev_close Previous close price ($).
volume Volume.
sma_20_diff Difference between current price and simple moving average with look-back window of 20 days ($).
p_to_s Price to sales value for trailing 12 months.
price Current stock price ($).
current_ratio Current ratio value.
forward_p_to_e Forward price to earnings value for next fiscal year.
sma_50_diff Difference between current price and simple moving average with look-back window of 50 days ($).
employees Number of employees.
profit_margin Net profit margin for trailing 12 months (%).
sma_200_diff Difference between current price and simple moving average with look-back window of 200 days ($).
sales_q_to_q Year-over-year quarterly revenue growth (%).
earnings Earnings date (BMO - before market open, AMC - after market close).
perf_week Week performance (%).
quick_ratio Quick ratio value.
payout Dividend payout ratio for trailing 12 months (%).
eps_next_5_y Earnings per share growth estimate for next 5 years (%).
recom Mean recommendation of analysts (1 - Buy, 5 - Sell).
roe Return on equity for trailing 12 months (%).
shs_outstand Shares outstanding.
description Company description.
52w_low_diff Difference between current and 52-week low price (%).
company_name Company name.
target_price Mean target price of analysts ($).
market_cap Market capitalization ($) (default).
optionable Has options trading on a market exchange.
shortable Has shares available to sell short.
insider_own Insider ownership (%).
shs_float Shares float.
lt_debt_to_eq Long term debt to equity value.