Establishes a persistent connection to the Firehose stream, through which the realtime data will be delivered.
| Request Method | HTTP GET |
| Accept | text/event-stream
This should be specified in the header of the request. |
| URL | Found on the stream's API Help page of your dashboard, using the following structure:
https://firestream.stocktwits.com/stream |
| Params | The last stream item received can be specified, the stream will attempt to continue from that point (if the item was sent in the past 24 hours).
https://firestream.stocktwits.com/stream?seq_id=49562553817515093231064627491680393519832340977378394114 |
| Compression | Gzip. To connect to the stream using Gzip compression, simply send an Accept-Encoding header in the connection request. The header should look like the following:
Accept-Encoding: gzip |
| Read Timeout | Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds. |
The following responses may be returned by the API for these requests. Most error codes are returned with a string with additional details in the body. For non-200 responses, clients should attempt to reconnect.
| Status | Text | Description |
|---|---|---|
| 200 | Success | The connection was successfully opened, and new activities will be sent through as they arrive. |
| 401 | Unauthorized | HTTP authentication failed due to invalid credentials. Verify that your login combination matches this sites. |
| 406 | Not Acceptable | Generally, this occurs where your client fails to properly include the headers to accept gzip encoding from the stream, but can occur in other circumstances as well.
Will contain a JSON message similar to "This connection requires compression. To enable compression, send an 'Accept-Encoding: gzip' header in your request and be ready to uncompress the stream as it is read on the client end." |
| 503 | Service Unavailable | stocktwits server issue. Reconnect using an exponential backoff pattern. If no notice about this issue has been posted on this site under status, email support@stocktwits.com. |
The following example request is accomplished using cURL on the command line.
curl --no-buffer -u 'username':'password' -H"Accept: text/event-stream" "https://firestream.stocktwits.com/stream"
If you are working on Windows, you may need to use double quotes instead of single quotes for the username and password.
curl --no-buffer -u "username":"password" -H"Accept: text/event-stream" "https://firestream.stocktwits.com/stream"
The following example request is accomplished using a python script with the requests library.
'''
This script uses the "requests" library to connect to the stream.
It should be installed using pip before running this script.
'''
import requests
from requests.auth import HTTPBasicAuth
username = "myusername"
password = "mypassword"
# Create a new request, the stream parameter is set to True to keep the connection open
try:
resp = requests.get("https://firestream.stocktwits.com/stream", auth=HTTPBasicAuth(username, password), stream=True)
except Exception as e:
print(f"Error creating request: {e}")
exit()
# Check for errors on the response a HTTP status code of 200 is expected
if resp.status_code != 200:
print(f"Error response: {resp.status_code} {resp.reason}")
exit()
# Read the response body on a loop
try:
for line in resp.iter_lines():
if line: # filter out keep-alive new lines
print(line.decode())
except Exception as e:
print(f"Error reading stream: {e}")
exit()
|
object |
The type of data contained in this object. Current types are: "object" : "Message" |
|
action |
This is either a create, or a destroy data type. "action" : "create" |
|
data |
The body of this data of the type specified in 'object'. "data" : {...}
|
|
time |
Timestamp of the data's creation or destruction. "time" : "2017-02-01T19:19:18Z" |
|
seq_id |
Sequence Id used to identify the streams position. Can be used for recovery for up to 24 hours. (Not present in backups) "seq_id":"49567487888076093524624994048752032346222860024699420674" |
|
id |
A unique ID for the message. "id" : 5556662 |
||||||||||||||||||||||||||||||||||||||||||||
|
body |
The messages's text. "body" : "$AAPL is moving today" |
||||||||||||||||||||||||||||||||||||||||||||
|
created_at |
Timestamp of the message's creation. "created_at" : "2017-02-01T19:16:54Z" |
||||||||||||||||||||||||||||||||||||||||||||
|
user |
An object representing the StockTwits user who posted the message.
"user": {
"id": 222222,
"username": "StocksGuy",
"name": "John Smith",
"avatar_url": "http://avatars.stocktwits.com/production/222222/thumb-1481680974.png",
"avatar_url_ssl": "https://s3.amazonaws.com/st-avatars/production/222222/thumb-1481680974.png",
"join_date": "2016-11-04",
"official": false,
"identity": "User",
"classification": [],
"followers": 16,
"following": 14,
"ideas": 966,
"watchlist_stocks_count": 24,
"like_count": 1170,
"subscribers_count": 2, // DEPRECATED
"subscribed_to_count": 1, // DEPRECATED
"following_stocks": 0,
"location": "California",
"bio": "Learning a lot with a lot to learn.",
"website_url": null,
"trading_strategy": {
"assets_frequently_traded": ["Equities","Private Companies"],
"approach": "Value",
"holding_period": "Position Trader",
"experience": "Professional"
}
}, |
||||||||||||||||||||||||||||||||||||||||||||
|
source |
The source of the message posting. Can be stocktwits web, mobile apps, or third party applications.
"source": {
"id": 1149,
"title": "StockTwits for iOS",
"url": "http://www.stocktwits.com/mobile"
},
|
||||||||||||||||||||||||||||||||||||||||||||
|
conversation |
If the current activity is part of a conversation, this is an object containing information about the parent and conversation statistics. Not present if the message is not part of a conversation. The replies value is the number of messages in the conversation started by parent_message_id.
"conversation": {
"parent_message_id": 5555662,
"in_reply_to_message_id": 73300365,
"parent": false,
"replies": 5
},
|
||||||||||||||||||||||||||||||||||||||||||||
|
symbols |
A JSON list of stocks mentioned in the message.
"symbols": [{
"id": 686,
"symbol": "ABC",
"title": "Alpha Bravo Charlie, inc.",
"is_following": false,
"exchange": "NASDAQ",
"sector": "Technology",
"industry": "Personal Computers",
"logo_url": "http://logos.xignite.com/NASDAQGS/00011843.gif",
"trending": true,
"trending_score": 16.4019,
"watchlist_count": 12370
}], |
||||||||||||||||||||||||||||||||||||||||||||
|
prices |
A JSON list of stocks mentioned in the message.
"prices": [{
"id": 686,
"symbol": "ABC",
"price": "29.84"
}],
|
||||||||||||||||||||||||||||||||||||||||||||
|
reshares |
Provides the count of message's reshares and the users that reshared it.
"reshares": {
"reshared_count": 0,
"user_ids": []
},
|
||||||||||||||||||||||||||||||||||||||||||||
|
reshare_messages |
Contains details about the reshared message.
"reshare_message": {
"reshared_count": 1,
"message": {
"id": 5556662,
"body": "$AAPL is moving today",
"created_at": "2017-02-01T19:16:54Z",
"user": {
"id": 222222,
"username": "StocksGuy",
"name": "John Smith",
"avatar_url": "http://avatars.stocktwits.com/production/222222/thumb-1481680974.png",
"avatar_url_ssl": "https://s3.amazonaws.com/st-avatars/production/222222/thumb-1481680974.png",
"join_date": "2016-11-04",
"official": false,
"identity": "User",
"classification": [],
"followers": 16,
"following": 14,
"ideas": 966,
"watchlist_stocks_count": 24,
"like_count": 1170,
"subscribers_count": 2, // DEPRECATED
"subscribed_to_count": 1, // DEPRECATED
"following_stocks": 0,
"location": "California",
"bio": "Learning a lot with a lot to learn.",
"website_url": null,
"trading_strategy": {
"assets_frequently_traded": ["Equities","Private Companies"],
"approach": "Value",
"holding_period": "Position Trader",
"experience": "Professional"
}
},
"source": {
"id": 1149,
"title": "StockTwits for iOS",
"url": "http://www.stocktwits.com/mobile"
},
"symbols": [{
"id": 686,
"symbol": "ABC",
"title": "Alpha Bravo Charlie, inc.",
"is_following": false,
"exchange": "NASDAQ",
"sector": "Technology",
"industry": "Personal Computers",
"logo_url": "http://logos.xignite.com/NASDAQGS/00011843.gif",
"trending": true,
"trending_score": 16.4019,
"watchlist_count": 12370
}],
"prices": [{
"id": 686,
"symbol": "ABC",
"price": "29.84"
}],
"mentioned_users": [],
"entities": {}
}
},
|
||||||||||||||||||||||||||||||||||||||||||||
|
mentioned_users |
A list of users mentioned in this post. "mentioned_users" : ["@OtherPerson"] |
||||||||||||||||||||||||||||||||||||||||||||
|
entities |
The entities object from the StockTwits data format. It can contain charts, sentiment, stock symbols, and videos associated with the activity.
"entities" :
{
"chart" : {
"thumb": "http://charts.stocktwits.com/production/small_31307994.png",
"large": "http://charts.stocktwits.com/production/large_31307994.png",
"original": "http://charts.stocktwits.com/production/original_31307994.png",
"url": "http://stks.co/g1Ye8"
},
"sentiment" :
{
"basic" : "Bearish"
}
} |
||||||||||||||||||||||||||||||||||||||||||||
|
links |
A JSON list of Links mentioned in the message.
"links": [{
"title": "How to Stock Market",
"url": "https://www.stocks.com/the-how-to-guide/",
"shortened_url": "https://www.stocks.com/the-how-to-guide/",
"shortened_expanded_url": "stocks.com/the-how-to-guide",
"description": "A guide to getting started in the stock market",
"image": "https://www.stocks.com/icon.png",
"created_at": "2017-02-01T19:17:29Z",
"video_url": null,
"source": {
"name": "Stocks",
"website": "https://www.stocks.com"
}
}]
|
||||||||||||||||||||||||||||||||||||||||||||
| sentiment [DEPRECATED] |
A JSON data object containing estimated sentiment data.
"sentiment": {
"sentiment_score": 0.854
}
|
||||||||||||||||||||||||||||||||||||||||||||
| network |
An object containing the externally shared ids for third party networks. "network" :
{
"twitter": { "id" : "12345678" },
"facebook": { "id" : "abcdefghi" }
}
|
{
"id": 5556662,
"body": "@OtherPerson I believe $ABC will be going up in value!",
"created_at": "2017-02-01T19:16:54Z",
"user": {
"id": 222222,
"username": "StocksGuy",
"name": "John Smith",
"avatar_url": "http://avatars.stocktwits.com/production/222222/thumb-1481680974.png",
"avatar_url_ssl": "https://s3.amazonaws.com/st-avatars/production/222222/thumb-1481680974.png",
"join_date": "2016-11-04",
"official": false,
"identity": "User",
"classification": [],
"followers": 16,
"following": 14,
"ideas": 966,
"watchlist_stocks_count": 24,
"like_count": 1170,
"subscribers_count": 2, // DEPRECATED
"subscribed_to_count": 1, // DEPRECATED
"following_stocks": 0,
"location": "California",
"bio": "Learning a lot with a lot to learn.",
"website_url": null,
"trading_strategy": {
"assets_frequently_traded": ["Equities","Private Companies"],
"approach": "Value",
"holding_period": "Position Trader",
"experience": "Professional"
}
},
"source": {
"id": 1149,
"title": "StockTwits for iOS",
"url": "http://www.stocktwits.com/mobile"
},
"conversation": {
"parent_message_id": 5555662,
"in_reply_to_message_id": 73300365,
"parent": false,
"replies": 5
},
"symbols": [{
"id": 686,
"symbol": "ABC",
"title": "Alpha Bravo Charlie, inc.",
"is_following": false,
"exchange": "NASDAQ",
"sector": "Technology",
"industry": "Personal Computers",
"logo_url": "http://logos.xignite.com/NASDAQGS/00011843.gif",
"trending": true,
"trending_score": 16.4019,
"watchlist_count": 12370
}],
"prices": [{
"id": 686,
"symbol": "ABC",
"price": "29.84"
}],
"reshares": {
"reshared_count": 0,
"user_ids": []
},
"mentioned_users": ["@OtherPerson"],
"entities": {
"sentiment": {
"basic": "Bullish"
}
}
}
A friendship object is created when a user follows or unfollows another user on StockTwits.
|
id |
The friendship unique id. "id" : "Message" |
|
user_id |
This is the id of the user creating the friendship "user_id" : 654527 |
|
following_user_id |
This is the id of the user being followed or unfollowed. "following_user_id" : 654527 |
|
created_at |
Timestamp of the friendships creation. "created_at" : "2015-12-24T20:00:01Z" |
{
"id": 19037074,
"user_id": 654527,
"following_user_id": 364216,
"created_at": "2015-12-24T20:00:01Z"
}
A block object is created when a user blocks or unblocks another user on StockTwits.
|
id |
The block unique id. "id" : "Message" |
|
user_id |
This is the id of the user creating the block "user_id" : 654527 |
|
blocked_user_id |
This is the id of the user being blocked or unblocked. "blocked_user_id" : 654527 |
|
muted |
Indicates is the blocked user was muted "muted" : false |
|
created_at |
Timestamp of the blocks creation. "created_at" : "2015-12-24T20:00:01Z" |
{
"id": 19037074,
"user_id": 654527,
"muted": false,
"blocked_user_id": 364216,
"created_at": "2015-12-24T20:00:01Z"
}
A like message object is created when a user likes a message on StockTwits.
|
id |
The like message unique id. "id" : 27169457 |
|
message_id |
This is the id of the message being liked. "message_id" : 73300225 |
|
user_id |
This is the id of the user who liked the message. "user_id" : 654527 |
|
liked_user_id |
This is the id of the user whose message was liked. "liked_user_id" : 654527 |
|
created_at |
Timestamp of the likes creation. "created_at" : "2015-12-24T20:00:01Z" |
{
"id": 19037074,
"message_id": 73300225,
"user_id": 654527,
"liked_user_id": 364216,
"created_at": "2015-12-24T20:00:01Z"
}