Consensus Ratings

Retrieve consensus analyst ratings and aggregated investment recommendations for stocks.

GET/3.0/research/consensus

Description

This endpoint returns aggregated consensus analyst ratings by analyzing all available analyst price targets and recommendations for a stock. It provides a consolidated view of market sentiment including buy/hold/sell count, average price target, and consensus action.

Request

Authentication

• Type: Bearer Token
• Required: Yes

Parameters

Name	Type	Required	Description	Example
symbol	string	Yes	Stock symbol to retrieve consensus ratings for	UBL
period	string	No	Analysis period (1M, 3M, 6M, 1Y, all). Default: all	6M

Response

Success Response (200)

{
  "status": "ok",
  "message": "",
  "data": {
    "symbol": "UBL",
    "name": "United Bank Limited",
    "sector_code": "0802",
    "sector_name": "Commercial Banks",
    "consensus": {
      "action": "Buy",
      "rating_distribution": {
        "buy": 9,
        "hold": 2,
        "sell": 0,
        "total": 11
      }
    },
    "price_target": {
      "average": 465.45,
      "high": 520.00,
      "low": 420.00,
      "period": "2025-06-30"
    },
    "earnings": {
      "average": 25.50,
      "high": 28.00,
      "low": 22.30,
      "period": "2024-12-31"
    },
    "recommendation_summary": [
      {
        "analyst": "Ahmed Hassan Khan",
        "client_id": 18,
        "research_id": "507f1f77bcf86cd799439031",
        "action": "Buy",
        "target": 450.00,
        "date": "2024-12-08T10:30:00+05:00"
      },
      {
        "analyst": "Bilal Shahid",
        "client_id": 18,
        "research_id": "507f1f77bcf86cd799439032",
        "action": "Buy",
        "target": 480.00,
        "date": "2024-12-07T14:15:00+05:00"
      },
      {
        "analyst": "Fatima Malik",
        "client_id": 18,
        "research_id": "507f1f77bcf86cd799439033",
        "action": "Hold",
        "target": 440.00,
        "date": "2024-12-05T11:45:00+05:00"
      },
      {
        "analyst": "Maria Saeed",
        "client_id": 150,
        "research_id": "507f1f77bcf86cd799439034",
        "action": "Buy",
        "target": 520.00,
        "date": "2024-11-30T09:00:00+05:00"
      },
      {
        "analyst": "Usama Khan",
        "client_id": 148,
        "research_id": "507f1f77bcf86cd799439035",
        "action": "Buy",
        "target": 470.00,
        "date": "2024-11-25T13:30:00+05:00"
      }
    ]
  }
}

Response Fields

Field	Type	Description
symbol	string	Stock symbol
name	string	Company name
sector_code	string	Sector classification code
sector_name	string	Sector name
consensus.action	string	Consensus action (Buy, Hold, Sell)
consensus.rating_distribution.buy	integer	Number of Buy recommendations
consensus.rating_distribution.hold	integer	Number of Hold recommendations
consensus.rating_distribution.sell	integer	Number of Sell recommendations
consensus.rating_distribution.total	integer	Total number of ratings
price_target.average	float	Average price target across all analysts
price_target.high	float	Highest price target
price_target.low	float	Lowest price target
price_target.period	string	Target period (YYYY-MM-DD)
earnings.average	float	Average (consensus) EPS estimate
earnings.high	float	Highest EPS estimate
earnings.low	float	Lowest EPS estimate
earnings.period	string	EPS estimate period (YYYY-MM-DD)
recommendation_summary[]	array	Array of individual analyst recommendations
recommendation_summary[].analyst	string	Analyst name
recommendation_summary[].client_id	integer	Client/Organization ID (see Research Organizations)
recommendation_summary[].research_id	string	Research report ID for the recommendation
recommendation_summary[].action	string	Individual analyst action
recommendation_summary[].target	float	Individual analyst price target
recommendation_summary[].date	string (ISO 8601)	Rating update timestamp

Error Responses

For detailed Common Error responses, see the Error Handling.

Missing Symbol (200)

{
  "status": "error",
  "message": "no `symbol` provided"
}

Examples

Get Consensus Ratings for Stock

curl -X GET "https://csapis.com/3.0/research/consensus?symbol=UBL" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Cases

• Consensus Tracking: Monitor analyst sentiment trends across a stock
• Buy/Hold/Sell Signals: Use majority analyst recommendation for trading signals
• Target Price Analysis: Compare market price with consensus price targets
• Risk Assessment: Analyze dispersion of analyst targets for volatility estimation
• Investment Committee Decisions: Use consensus data for institutional investment decisions
• Earnings Forecasts: Track consensus EPS and dividend estimates for projections
• Due Diligence: Verify analyst coverage and sentiment during company analysis