> ## Documentation Index
> Fetch the complete documentation index at: https://docs.benzinga.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Ratings Stream
> 실시간 애널리스트 투자의견 및 목표가 변경 사항.
## 개요
실시간 애널리스트 투자의견 변경과 목표가 업데이트를 구독합니다. 상향·하향 조정, 신규 커버리지 개시, 목표가 변경을 발생하는 즉시 모니터링합니다.
### 주요 기능
* **실시간 투자의견**: 애널리스트 투자의견 변경을 실시간 알림으로 수신
* **목표가**: 현재 및 과거 목표가와 그 변동 내역을 추적
* **애널리스트 세부 정보**: 애널리스트 이름, 소속사, 과거 정확도 지표 포함
* **조치 유형 분류**: 상향 조정, 하향 조정, 유지, 신규 개시, 재확인
* **종목 기준 필터링**: 특정 티커 또는 국제증권식별번호(ISIN)을 기준으로 구독
### 사용 사례
* 실시간 투자의견 변경 알림 및 알림 시스템 구축
* 애널리스트 및 소속 기관의 성과와 적중률 추적
* 목표주가 컨센서스 변동 모니터링
* 투자의견 상향/하향 조정 대시보드 구축
* 애널리스트 행동을 기반으로 한 트레이딩 전략 자동화
## 빠른 시작
상단의 인터랙티브 웹소켓 테스트 도구를 사용하여 스트림에 실시간으로 연결해 테스트하세요.
### 접속 URL
```
wss://api.benzinga.com/api/v2.1/calendar/ratings/stream?token=YOUR_TOKEN
```
### 쿼리 파라미터
| 파라미터 | 필수 여부 | 설명 |
| --------- | ----- | ----------------------------------------- |
| `token` | 예 | Benzinga 웹소켓 API 토큰 (bz.production\*\*\*) |
| `tickers` | 아니요 | 쉼표로 구분된 티커 목록 (예: `AAPL,TSLA`) |
| `isins` | 아니요 | 필터링에 사용할 쉼표로 구분된 국제증권식별번호(ISIN) 목록 |
## 메시지 예시
```json theme={null}
{
"id": "e9e75b31-604e-422c-a532-362725b2d59d",
"api_version": "websocket/v1",
"kind": "data/v2.1/calendar/ratings",
"data": {
"action": "created",
"id": "66fffdc08f3f630001a2ea51",
"timestamp": "2024-10-04T19:21:06Z",
"content": {
"ticker": "AAPL",
"name": "Apple",
"exchange": "NASDAQ",
"date": "2024-10-04",
"time": "10:37:52",
"action_company": "Upgrades",
"rating_current": "Buy",
"rating_prior": "Neutral",
"pt_current": "200.00",
"pt_prior": "180.00",
"analyst": "Goldman Sachs",
"firm_id": "57f832ab6b87f600016fa383",
"importance": 4
}
}
}
```
### Rating 액션
| Action | 설명 |
| ------------ | -------------------------- |
| `Upgrades` | 투자의견 상향 (예: Neutral → Buy) |
| `Downgrades` | 투자의견 하향 (예: Buy → Hold) |
| `Maintains` | 투자의견 유지 |
| `Initiates` | 최초 투자의견 개시 |
| `Reiterates` | 기존 투자의견 재확인 |
### 메시지 action 값
| Action | 설명 |
| --------------------- | -------- |
| `created` / `Created` | 새 레이팅 게시 |
| `updated` / `Updated` | 레이팅 수정 |
| `deleted` / `Deleted` | 레이팅 삭제 |
## 대화형 명령어
| Command | Description |
| -------- | ---------------------------------- |
| `ping` | 연결을 유지합니다 (`pong`으로 응답) |
| `replay` | 캐시에 저장된 최근 메시지를 최대 100개까지 다시 전송합니다 |
## 모범 사례
* **변경 사항 추적**: 업그레이드/다운그레이드 감지를 위해 `rating_current`와 `rating_prior`를 비교합니다
* **목표가 변동**: 목표가 변경을 모니터링하기 위해 `pt_current`와 `pt_prior`를 확인합니다
* **애널리스트 신뢰도**: 기관의 중요도와 과거 정확도를 함께 고려합니다
* **중요도 필터**: 큰 영향이 있는 평가에 대해서는 중요도 4–5 등급의 평가에 집중합니다
## AsyncAPI
````yaml asyncapi/calendar-ratings-stream.yml calendarRatings
id: calendarRatings
title: Calendar ratings
description: Send action commands; receive real-time ratings updates
servers:
- id: production
protocol: wss
host: api.benzinga.com/api/v2.1/calendar/ratings
bindings: []
variables: []
address: stream
parameters: []
bindings: []
operations:
- &ref_2
id: calendarRatings.publish
title: Calendar ratings.publish
description: Send commands to the server
type: receive
messages:
- &ref_4
id: publish
contentType: text/plain
payload:
- type: string
enum: &ref_0
- ping
- replay
description: Send action commands (ping, replay)
x-parser-schema-id:
name: publish
headers: []
jsonPayloadSchema:
type: string
enum: *ref_0
description: Action to perform (ping for heartbeat, replay for message history)
x-parser-schema-id:
title: Publish
description: Send action commands (ping, replay)
example: '{}'
bindings: []
extensions:
- id: x-parser-unique-object-id
value: publish
- id: x-parser-message-name
value: ActionRequest
bindings: []
extensions: &ref_1
- id: x-parser-unique-object-id
value: calendarRatings
- &ref_3
id: calendarRatings.subscribe
title: Calendar ratings.subscribe
description: Receive real-time ratings data
type: send
messages:
- &ref_5
id: subscribe
contentType: application/json
payload:
- name: subscribe
description: Analyst ratings event
type: object
properties:
- name: id
type: string
description: Unique UUID for the websocket response
required: true
- name: api_version
type: string
description: Websocket API version
enumValues:
- websocket/v1
required: true
- name: kind
type: string
description: Websocket connection stream type
enumValues:
- data/v2.1/calendar/ratings
required: true
- name: data
type: object
required: true
properties:
- name: action
type: string
description: Websocket data action
enumValues:
- created
- updated
- deleted
- Created
- Updated
- Deleted
required: true
- name: id
type: string
description: Data ID for the rating
required: true
- name: timestamp
type: string
description: Timestamp of the data
required: true
- name: content
type: object
required: true
properties:
- name: id
type: string
description: Unique ID of this entry
required: true
- name: date
type: string
description: Date for rating
required: true
- name: time
type: string
description: Time for rating
required: false
- name: ticker
type: string
description: >-
Ticker symbol of the company that is the subject of
the rating
required: true
- name: exchange
type: string
description: Exchange (NYSE, NASDAQ, etc...)
required: true
- name: isin
type: string
description: International Securities Identification Number
required: false
- name: cusip
type: string
description: CUSIP identifier
required: false
- name: name
type: string
description: Name of the company that is the subject of the rating
required: true
- name: currency
type: string
description: Currency the data is denominated in
required: false
- name: action_pt
type: string
description: >-
Description of the change in price target from the
firm's last price target
required: false
- name: action_company
type: string
description: >-
Description of the change in rating from the firm's
last rating
required: false
- name: rating_current
type: string
description: The analyst's current rating for the company
required: false
- name: pt_current
type: string
description: Analyst's current price target
required: false
- name: adjusted_pt_current
type: string
description: >-
Analyst's current price target, adjusted for stock
splits and dividends
required: false
- name: rating_prior
type: string
description: Prior analyst rating for the company
required: false
- name: pt_prior
type: string
description: Analyst's prior price target
required: false
- name: adjusted_pt_prior
type: string
description: >-
Analyst's prior price target, adjusted for stock
splits and dividends
required: false
- name: url
type: string
description: >-
URL for the analyst ratings page for this ticker on
Benzinga.com
required: false
- name: url_calendar
type: string
description: >-
URL for the analyst ratings page for this ticker on
Benzinga.com
required: false
- name: url_news
type: string
description: >-
URL for the analyst ratings news articles for this
ticker on Benzinga.com
required: false
- name: analyst
type: string
description: Name of the analyst firm that published the rating
required: false
- name: analyst_id
type: string
description: ID of the analyst
required: false
- name: analyst_name
type: string
description: Name of the analyst (person) that published the rating
required: false
- name: firm_id
type: string
description: Unique identifier for the firm
required: false
- name: importance
type: integer
description: >-
Subjective basis of how important the event is to the
market (5 = High)
required: false
- name: notes
type: string
description: >-
Additional notes provided by the Benzinga Newsdesk
where applicable
required: false
- name: updated
type: integer
description: Last updated timestamp in UTC
required: false
headers: []
jsonPayloadSchema:
type: object
required:
- id
- api_version
- kind
- data
properties:
id:
type: string
format: uuid
description: Unique UUID for the websocket response
x-parser-schema-id:
api_version:
type: string
enum:
- websocket/v1
description: Websocket API version
x-parser-schema-id:
kind:
type: string
enum:
- data/v2.1/calendar/ratings
description: Websocket connection stream type
x-parser-schema-id:
data:
type: object
required:
- action
- id
- content
- timestamp
properties:
action:
type: string
enum:
- created
- updated
- deleted
- Created
- Updated
- Deleted
description: Websocket data action
x-parser-schema-id:
id:
type: string
description: Data ID for the rating
x-parser-schema-id:
timestamp:
type: string
format: date-time
description: Timestamp of the data
x-parser-schema-id:
content:
type: object
required:
- id
- date
- ticker
- exchange
- name
properties:
id:
type: string
description: Unique ID of this entry
x-parser-schema-id:
date:
type: string
format: date
description: Date for rating
x-parser-schema-id:
time:
type: string
description: Time for rating
x-parser-schema-id:
ticker:
type: string
description: >-
Ticker symbol of the company that is the subject of the
rating
x-parser-schema-id:
exchange:
type: string
description: Exchange (NYSE, NASDAQ, etc...)
x-parser-schema-id:
isin:
type: string
description: International Securities Identification Number
x-parser-schema-id:
cusip:
type: string
description: CUSIP identifier
x-parser-schema-id:
name:
type: string
description: Name of the company that is the subject of the rating
x-parser-schema-id:
currency:
type: string
description: Currency the data is denominated in
x-parser-schema-id:
action_pt:
type: string
description: >-
Description of the change in price target from the
firm's last price target
x-parser-schema-id:
action_company:
type: string
description: >-
Description of the change in rating from the firm's last
rating
x-parser-schema-id:
rating_current:
type: string
description: The analyst's current rating for the company
x-parser-schema-id:
pt_current:
type: string
description: Analyst's current price target
x-parser-schema-id:
adjusted_pt_current:
type: string
description: >-
Analyst's current price target, adjusted for stock
splits and dividends
x-parser-schema-id:
rating_prior:
type: string
description: Prior analyst rating for the company
x-parser-schema-id:
pt_prior:
type: string
description: Analyst's prior price target
x-parser-schema-id:
adjusted_pt_prior:
type: string
description: >-
Analyst's prior price target, adjusted for stock splits
and dividends
x-parser-schema-id:
url:
type: string
format: uri
description: >-
URL for the analyst ratings page for this ticker on
Benzinga.com
x-parser-schema-id:
url_calendar:
type: string
format: uri
description: >-
URL for the analyst ratings page for this ticker on
Benzinga.com
x-parser-schema-id:
url_news:
type: string
format: uri
description: >-
URL for the analyst ratings news articles for this
ticker on Benzinga.com
x-parser-schema-id:
analyst:
type: string
description: Name of the analyst firm that published the rating
x-parser-schema-id:
analyst_id:
type: string
description: ID of the analyst
x-parser-schema-id:
analyst_name:
type: string
description: Name of the analyst (person) that published the rating
x-parser-schema-id:
firm_id:
type: string
description: Unique identifier for the firm
x-parser-schema-id:
importance:
type: integer
minimum: 0
maximum: 5
description: >-
Subjective basis of how important the event is to the
market (5 = High)
x-parser-schema-id:
notes:
type: string
description: >-
Additional notes provided by the Benzinga Newsdesk where
applicable
x-parser-schema-id:
updated:
type: integer
format: int64
description: Last updated timestamp in UTC
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
title: Subscribe
description: Analyst ratings event
example: No examples found
bindings: []
extensions:
- id: x-parser-unique-object-id
value: subscribe
- id: x-parser-message-name
value: RatingsMessage
bindings: []
extensions: *ref_1
sendOperations:
- *ref_2
receiveOperations:
- *ref_3
sendMessages:
- *ref_4
receiveMessages:
- *ref_5
extensions:
- id: x-parser-unique-object-id
value: calendarRatings
securitySchemes:
- id: tokenAuth
name: token
type: httpApiKey
description: Benzinga WebSocket API token (bz.production***)
in: query
extensions: []
````