Analyst ratings
Analyst ratings
GET
/openapi/v3/instruments/{ref}/analyst-ratingsRefresh: Minute / daily
This endpoint uses v3 at https://openapi.sosovalue.com/openapi/v3. Do not append it to /openapi/v1; see version-specific conventions.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| ref | string | Required | Instrument reference. A full_symbol such as AAPL.US or BTC-USDT-PERP.BINANCE is recommended; a stable id, symbol or FIGI also works |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| include | string | Optional | history — additionally returns data.history, a price series for charting the target price against (e.g. GET /instruments/NVDA/analyst-ratings?include=history) |
Request Example
curl "https://openapi.sosovalue.com/openapi/v3/instruments/AAPL.US/analyst-ratings" \ -H "x-soso-api-key: $SOSO_API_KEY"
Response Fields
data.analyst_rating (consensus snapshot):
| Field | Type | Description |
|---|---|---|
| rating | Number | Composite rating |
| target_price | Number | 12-month consensus target price |
| strong_buy / buy / hold / sell / strong_sell | Number | Vote counts per bucket |
| currency | String | Target-price currency |
| updated_at | String | Last updated |
data.price_target (target-price range):
| Field | Type | Description |
|---|---|---|
| high / average / low | Number | Highest / consensus average / lowest analyst target price |
| anchor_price | Number | The current price the forecast is anchored to (the last point of history) |
| forecast_date | String | Forecast horizon date |
| currency | String | Currency |
| as_of | String | As-of date |
data.rating_distribution (bucket shares):
| Field | Type | Description |
|---|---|---|
| buy_pct / hold_pct / sell_pct | Number | Percentage as a number (88.889 = 88.889%); divide by 100 for calculations (see Percentage Fields) |
| as_of | String | As-of date |
data.history (only when include=history is passed): array of [date, price] pairs, e.g. ["2026-08-04", "218.59"], with the price as a decimal string. A sparse historical price series intended for charting alongside the target-price range; its last point equals anchor_price as of as_of.
Notes
- If the instrument exists but has no rating data,
dataisnull.