Documentation: Analyst Estimates & Trends API

Overview

‍

The FinIQ Analyst API aggregates, normalizes, and quantifies the opinions of over 5,000+ institutional analysts. We go beyond simple "Consensus" means by providing the granular revision history, standardized 1-5 ratings, and quantitative "Smart Scores" for every analyst tracking a stock.

Key Capabilities:

History: 30+ Years.
Granularity: Access both "Consensus" (Aggregated) and "Individual" (Per-Broker) data.
Normalization: 100+ broker taxonomies mapped to a standard 5-point scale.
Alpha Signals: Revision Momentum, Consensus Dispersion, and Analyst Accuracy Scores.

‍

1. Access Methods

Method	Use Case	Format
REST API	Real-time revision tracking, dashboards.	JSON
Bulk CSV	Backtesting "Consensus Momentum" strategies.	CSV / Excel
Vector Feed	New: RAG Integration. Query analyst notes.	Embeddings

‍

2. REST API: Analyst Ratings Endpoint

Endpoint: GET https://api.finiq.data/v1/analyst-ratings

Request Parameters:

Parameter	Type	Required	Description
api_token	string	Yes	Your API Key.
ticker	string	Yes	Filter by symbol (e.g., AMD).
firm	string	No	Filter by specific broker (e.g., Goldman Sachs).
action	string	No	Filter: Upgrade, Downgrade, Initiate.
include_consensus	boolean	No	Set true to include aggregated mean/median stats.

‍

Example Request (Python)

import requests

url = "https://api.finiq.data/v1/analyst-ratings"
params = {
    "api_token": "YOUR_KEY",
    "ticker": "AMD",
    "action": "Upgrade",
    "include_consensus": "true"
}

response = requests.get(url, params=params)
data = response.json()

‍

Response Structure (JSON)

{
  "ticker": "AMD",
  "date": "2025-10-15",
  "consensus": {
    "eps_mean": 3.45,
    "eps_high": 3.80,
    "eps_low": 3.10,
    "revision_trend_30d": "Positive",
    "analyst_count": 34
  },
  "recent_actions": [
    {
      "analyst_name": "Stacy Rasgon",
      "firm": "Bernstein",
      "action": "Maintain",
      "rating_standardized": 4, 
      "rating_raw": "Outperform",
      "price_target_to": 150,
      "date": "2025-10-12"
    }
  ]
}

‍

3. Data Dictionary (Key Metrics)

Field	Type	Description
consensus.eps_mean	Float	The "Smart Mean" of analyst EPS forecasts. Stale estimates (>30 days) are excluded.
revision_trend_30d	String	Alpha Signal. Positive or Negative. Indicates the direction of recent revisions.
rating_standardized	Int	Standardized 1-5 Scale. (1=Strong Sell, 3=Hold, 5=Strong Buy). Used for quantitative scoring.
price_target_to	Float	The new 12-month price forecast set by the analyst.
action	String	The specific change event: Upgrade, Downgrade, Maintain, Initiate.

‍

4. Rating Normalization Map

We map disparate broker terminologies to a single quantitative scale.

Standard Score	Interpretation	Common Broker Terms
5	Strong Buy	Conviction Buy, Top Pick, Overweight (aggressive).
4	Buy	Outperform, Buy, Accumulate, Add.
3	Hold	Neutral, Market Perform, Equal Weight, Hold.
2	Sell	Underperform, Sell, Reduce, Moderate Sell.
1	Strong Sell	Conviction Sell, Strong Sell.

‍

5. Bulk Data Access (CSV)

Download the full revision history for factor testing.

File Naming Convention: {Exchange}_Analyst_History_{Date}.csv

CSV Columns:

Ticker, Date, Firm, AnalystName, Action, Rating_Raw, Rating_Std, Price_Target_From, Price_Target_To, Consensus_Mean_At_Time

How to Download:

Navigate to Data Export.
Select Analyst Package.
Choose Ticker Universe (e.g. "Russell 3000").
Click Download ZIP.

‍

6. Vector Database Feed (RAG-Ready)

Exclusive to FinIQ.
‍Embeds the narrative justification for rating changes.

Sample Vector Output (Decoded):

"Morgan Stanley downgraded Apple to 'Equal Weight' on Oct 12, citing 'weakening consumer spend in China' and 'extended valuation multiples' despite the recent earnings beat."

Use Case:

"Which analysts are worried about China exposure for Tech stocks?"
"Summarize the reasons for the recent upgrades in the Semiconductor sector."

‍

7. Error Handling

400 Bad Request: Invalid Ticker.
401 Unauthorized: Invalid API Key.
429 Too Many Requests: Rate limit exceeded.

‍

8. Need Help?

Developer Support: email dev-support@finiq.data
Slack Community: Join our [Quant Developer Slack]

‍

Author Name

Team Nextmark