Skip to content

Commit 7eee91f

Browse files
tommycottertommycotter
authored
Merge pull request #168 from Benzinga/feature-websocket-overview
2 parents 5cce1b1 + fca0967 commit 7eee91f

4 files changed

Lines changed: 100 additions & 4 deletions

File tree

‎docs.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,7 @@
215215
{
216216
"group": "Websockets",
217217
"pages": [
218+
"ws-reference/overview",
218219
"ws-reference/introduction",
219220
"ws-reference/authentication",
220221
"ws-reference/errors",
@@ -542,6 +543,7 @@
542543
{
543544
"group": "اتصالات ويب سوكيت",
544545
"pages": [
546+
"ar/ws-reference/overview",
545547
"ar/ws-reference/introduction",
546548
"ar/ws-reference/authentication",
547549
"ar/ws-reference/errors",
@@ -869,6 +871,7 @@
869871
{
870872
"group": "WebSockets",
871873
"pages": [
874+
"es/ws-reference/overview",
872875
"es/ws-reference/introduction",
873876
"es/ws-reference/authentication",
874877
"es/ws-reference/errors",
@@ -1196,6 +1199,7 @@
11961199
{
11971200
"group": "ウェブソケット",
11981201
"pages": [
1202+
"ja/ws-reference/overview",
11991203
"ja/ws-reference/introduction",
12001204
"ja/ws-reference/authentication",
12011205
"ja/ws-reference/errors",
@@ -1523,6 +1527,7 @@
15231527
{
15241528
"group": "웹소켓",
15251529
"pages": [
1530+
"ko/ws-reference/overview",
15261531
"ko/ws-reference/introduction",
15271532
"ko/ws-reference/authentication",
15281533
"ko/ws-reference/errors",

‎openapi/delivery_api.spec.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -962,5 +962,5 @@ components:
962962
- 'Null'
963963
- Present
964964
servers:
965-
- url: https://api.benzinga.com/api/v1
965+
- url: https://api.benzinga.com
966966
description: PROD

‎scripts/add_servers.sh‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ find "$OPENAPI_DIR" -type f \( -name "*.yaml" -o -name "*.yml" -o -name "*.json"
6969
;;
7070
"earnings-call-transcripts-api_api.spec.yml")
7171
servers='[
72-
{"url": "https://api.benzinga.com/api/v1", "description": "V1"}
72+
{"url": "https://api.benzinga.com", "description": "PROD"}
7373
]'
7474
;;
7575
"analyst-reports-raw-text-api_api.spec.yml")
@@ -84,13 +84,13 @@ find "$OPENAPI_DIR" -type f \( -name "*.yaml" -o -name "*.yml" -o -name "*.json"
8484
;;
8585
"delivery_api.spec.yml")
8686
servers='[
87-
{"url": "https://api.benzinga.com/api/v1", "description": "PROD"}
87+
{"url": "https://api.benzinga.com", "description": "PROD"}
8888
]'
8989
;;
9090
*)
9191
# Default servers if filename doesn't match
9292
servers='[
93-
{"url": "https://api.benzinga.com", "description": "Default"}
93+
{"url": "https://api.benzinga.com", "description": "PROD"}
9494
]'
9595
;;
9696
esac

‎ws-reference/overview.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: "Overview"
3+
description: "A high-level guide to Benzinga's real-time WebSocket data streams."
4+
---
5+
6+
Benzinga's WebSocket API delivers low-latency, push-based financial data directly to your application. Instead of repeatedly polling a REST endpoint, you open a single persistent connection and receive events the moment they're available — analyst ratings, earnings results, news, transcripts, and more.
7+
8+
All streams share the same base endpoint, authentication model, and message envelope, so the patterns you learn on one stream apply everywhere.
9+
10+
## How it works
11+
12+
<Steps>
13+
<Step title="Authenticate">
14+
Obtain a Benzinga API token from the [Benzinga Console](https://www.api.benzinga.com/token) and append it as a `token` query parameter when opening the connection.
15+
</Step>
16+
<Step title="Connect">
17+
Open a WebSocket connection to the stream URL for the data you need — for example `wss://api.benzinga.com/api/v1/analyst/insights/stream?token=YOUR_TOKEN`.
18+
</Step>
19+
<Step title="Receive events">
20+
Messages arrive as JSON objects with a consistent envelope: an `id`, `api_version`, `kind`, and a `data` block that carries the action (`created`, `updated`, or `deleted`) and the payload.
21+
</Step>
22+
<Step title="Keep the connection alive">
23+
Send a `ping` plain-text frame periodically (every 30–60 s). The server responds with `pong`. The server also sends its own ping every 10 s — most WebSocket libraries handle this automatically.
24+
</Step>
25+
</Steps>
26+
27+
## Available streams
28+
29+
<CardGroup cols={2}>
30+
<Card title="Analyst Insights" icon="chart-line" href="/ws-reference/data-websocket/get-analyst-insights-stream">
31+
Real-time analyst ratings, price targets, and detailed recommendations as they're published.
32+
</Card>
33+
<Card title="Ratings" icon="star" href="/ws-reference/data-websocket/get-calendar-ratings-stream">
34+
Analyst rating changes and price target updates from major firms.
35+
</Card>
36+
<Card title="Consensus Ratings" icon="scale-balanced" href="/ws-reference/data-websocket/get-consensus-ratings-stream">
37+
Aggregated consensus ratings and price targets across all tracked analysts.
38+
</Card>
39+
<Card title="Earnings" icon="sack-dollar" href="/ws-reference/data-websocket/get-calendar-earnings-stream">
40+
Earnings announcements with EPS, revenue, estimates, and surprise metrics.
41+
</Card>
42+
<Card title="Bulls/Bears Say" icon="comments" href="/ws-reference/data-websocket/get-bulls-bears-say-stream">
43+
Bull and bear case scenarios for securities, published in real time.
44+
</Card>
45+
<Card title="News" icon="newspaper" href="/ws-reference/data-websocket/get-news-stream">
46+
Breaking news articles and market updates from Benzinga's editorial team.
47+
</Card>
48+
<Card title="Earnings Call Transcripts" icon="microphone" href="/ws-reference/data-websocket/get-transcripts-stream">
49+
Live earnings call transcripts delivered sentence-by-sentence as they're spoken.
50+
</Card>
51+
</CardGroup>
52+
53+
## Message envelope
54+
55+
Every stream message follows the same top-level structure:
56+
57+
```json
58+
{
59+
"id": "550e8400-e29b-41d4-a716-446655440000",
60+
"api_version": "websocket/v1",
61+
"kind": "<stream-type>",
62+
"data": {
63+
"action": "created",
64+
"id": "<record-id>",
65+
"timestamp": "2024-10-08T10:00:00Z",
66+
"content": { ... }
67+
}
68+
}
69+
```
70+
71+
| Field | Description |
72+
|-------|-------------|
73+
| `id` | Unique message ID — use this to deduplicate on reconnect |
74+
| `api_version` | Protocol version of the message |
75+
| `kind` | Identifies which stream the message came from |
76+
| `data.action` | One of `created`, `updated`, or `deleted` |
77+
| `data.content` | Stream-specific payload |
78+
79+
## Reference pages
80+
81+
<CardGroup cols={3}>
82+
<Card title="Authentication" icon="key" href="/ws-reference/authentication">
83+
How to obtain and use your API token.
84+
</Card>
85+
<Card title="Supported Actions" icon="bolt" href="/ws-reference/actions">
86+
`ping` and `replay` commands you can send on any stream.
87+
</Card>
88+
<Card title="Errors" icon="triangle-exclamation" href="/ws-reference/errors">
89+
Error codes and how to handle connection failures.
90+
</Card>
91+
</CardGroup>

0 commit comments

Comments
 (0)