Analyst recommendations offer a helpful baseline for understanding how the broader market views a specific company. However, manually checking these ratings across different platforms is inefficient for developers and analysts building data-driven applications.
By using the Ratings Snapshot API, you can programmatically extract not just a summary rating, but the underlying fundamental scores that drive it. This guide walks you through setting up a free account, querying the Ratings Snapshot endpoint, and reading the response data so you can test the API before integrating it into your broader research workflows.
Key Takeaways
- Access Sub-Scores: Retrieve an overall summary rating alongside specific fundamental scores, such as Return on Equity and Discounted Cash Flow, in a single API call.
- Sandbox Testing: A free API key allows you to safely test the endpoint functionality, JSON structures, and data parsing before building production-scale applications.
- Standardized JSON: Ensure your data pipelines receive clean, structured arrays directly from the database instead of relying on web scraping.
- Research Input Only: Analyst ratings and snapshot scores serve as analytical inputs to help measure financial health, not standalone tools to predict stock performance.
What Analyst Ratings Show
The Ratings Snapshot API goes beyond a simple "Buy" or "Sell" label. It delivers a comprehensive snapshot of a company's financial standing by grading its performance across several key metrics.
Instead of forcing you to build complex financial models from scratch to evaluate a company's balance sheet, this endpoint aggregates ratios like Price-to-Earnings, Debt-to-Equity, and
Return on Assets into easy-to-read integer scores. This data provides developers, students, and analysts with a fast, structured way to evaluate a company's operational efficiency and valuation at a glance.
Step 1: Create a Free FMP API Key
Before making any programmatic requests, you need to generate a unique API key. This key authenticates your requests and grants you access to the data endpoints.
- Go to the Financial Modeling Prep pricing page to view the available data tiers.
- Select the Free Plan option to open a baseline testing account.
- Complete the registration using a valid email address no credit card or billing details are required.
- Open your developer dashboard and copy your personal API key from the top of the page.
Step 2: Retrieve Analyst Ratings for a Supported Symbol
With your API key ready, you can issue a direct HTTP GET request to pull the ratings data. On the free tier, you can easily test the endpoint's behavior using highly liquid sandbox symbols like Apple (AAPL).
Verified Request URL
https://financialmodelingprep.com/stable/ratings-snapshot?symbol=AAPL&apikey=YOUR_API_KEY
Sample JSON Response
When you call the Ratings Snapshot endpoint for AAPL, the API returns a structured JSON array containing the summary rating and the individual fundamental scores:
[
{
"symbol": "AAPL",
"rating": "B",
"overallScore": 3,
"discountedCashFlowScore": 3,
"returnOnEquityScore": 5,
"returnOnAssetsScore": 5,
"debtToEquityScore": 1,
"priceToEarningsScore": 2,
"priceToBookScore": 1
}
]
Step 3: Understand the Rating Fields
The JSON response breaks down the company's financial health into precise, easy-to-parse key-value pairs:
- rating & overallScore: These fields provide the baseline summary of the company's financial standing. In the example, AAPL receives a "B" rating and an overall score of 3.
- discountedCashFlowScore: This score (a 3 for AAPL) helps you understand the company's valuation compared to its estimated future cash flow potential.
- returnOnEquityScore & returnOnAssetsScore: These metrics gauge operational efficiency. High scores (like the 5s awarded to AAPL) indicate the company is effectively utilizing its equity and assets to generate profit.
- debtToEquityScore: Analyzes capital structure and leverage risk.
- priceToEarningsScore & priceToBookScore: These integers score the company's stock price relative to its earnings and book value, helping users assess current market valuation.
Step 4: Understand What You Can Test for Free
The free tier is built specifically for prototyping, testing data frames, and configuring your parsing scripts. When working with a free account, keep the following technical boundaries in mind:
- Supported Symbol Sandbox: Free queries are restricted to a select list of major, highly liquid equities and indexes (such as AAPL, TSLA, MSFT, NVDA, and SPY). Querying unlisted symbols outside this sandbox will return a parameter limitation error.
- Rate Limits: Free accounts feature daily API call limits. These are perfect for development testing and building proof-of-concept apps, but scaling to production workflows will require moving beyond the baseline tier.
Step 5: Use Ratings Alongside Other Financial Data
Analyst ratings and financial snapshots are most effective when paired with adjacent datasets. To build a comprehensive application, you should cross-reference these static ratings with broader market data.
For example, a high Return on Equity score should be analyzed alongside actual pricing trends to see how the market is reacting. Furthermore, companies frequently rebrand or undergo corporate actions, so pairing your ratings queries with a reliable reference database ensures your application always calls the correct, active ticker symbols.
Explore More Free Ways to Use and Test Our APIs
If you are developing a financial app or learning how to work with programmatic data feeds, a free FMP account allows you to explore multiple endpoints. Check out these step-by-step guides to expand your project:
- How to Pull Clean Historical Stock Price Data Using a Free API - Learn how to retrieve structured end-of-day pricing data for your applications.
- How to Compare Adjusted vs Unadjusted Stock Prices With a Free API - Understand the impact of dividends and stock splits on historical price charts.
- How to Track Stock Symbol Changes and Ticker Renames With a Free API - Keep your database clean by tracking corporate identity changes programmatically.
FAQs
What does the Ratings Snapshot API return?
The endpoint delivers an overall financial rating (e.g., "A", "B") along with numerical scores for key fundamental metrics like Return on Equity, Discounted Cash Flow, and Debt-to-Equity ratios.
Is the Ratings Snapshot API available on the free tier?
Yes. You can test the Ratings Snapshot endpoint using a free API key, provided you query symbols included in the free-tier sandbox (like AAPL or TSLA).
Can I use these ratings to predict stock prices?
No. The Ratings Snapshot API provides an evaluation of a company's current fundamental financial metrics. It is a research input used to assess financial health, not a predictive trading model.
Why do I get an error when querying certain symbols?
If you are on the free tier, you are limited to a specific list of liquid symbols. Attempting to pull data for symbols outside of this sandbox will result in a parameter limitation error.
Do I need to enter credit card information to test the API?
No. Creating a free developer account requires only a valid email address. You can generate your API key and start making requests immediately without billing details.
