Financial Data APIs

Relevant source files

The following files were used as context for generating this wiki page:

• client/src/app/quote/[ticker]/page.tsx
• client/src/components/Hero/index.tsx
• client/src/app/portal/page.tsx
• client/src/components/StockSummary/index.tsx
• client/src/components/StockRating/index.tsx
• client/src/components/Navbar/index.tsx
• client/src/components/NewsSection/index.tsx
• client/src/components/StockChart/index.tsx
• client/src/components/StockCardMini/index.tsx
• client/src/components/TickerChat/index.tsx

Introduction

The Greenline application relies on a suite of external APIs to provide users with comprehensive financial data, market insights, and AI-powered analysis. These APIs are the backbone of the application, supplying everything from real-time stock prices and historical data to company information, news, and analytical ratings. The front-end client directly queries these third-party services to populate its various components.

The primary data providers are Polygon.io for market data and news, Financial Modeling Prep for stock ratings, and OpenAI for generating analytical summaries and powering conversational chat features. All API interactions are initiated from the client-side within React components, using a standard pattern of fetching data on component mount or user interaction. API keys are managed through environment variables.

API Providers Overview

The application integrates three main external API providers, each serving a distinct purpose.

Provider	Purpose	Key Components
Polygon.io	Provides core market data, including stock prices (real-time and historical), company details, market status, and financial news.	StockChart, StockSummary, Hero, NewsSection, Navbar
Financial Modeling Prep	Supplies detailed stock rating analysis, including overall scores and breakdowns by financial metrics.	StockRating
OpenAI	Powers AI-driven features, such as generating narrative summaries for stock price movements and enabling conversational chat with a stock ticker persona.	StockSummary, TickerChat

Sources: client/src/components/Hero/index.tsx:23, client/src/components/StockRating/index.tsx:50, client/src/components/StockSummary/index.tsx:81

Data Fetching Architecture

A consistent pattern is used across the application for fetching data from these APIs within React components.

1. State Management: useState hooks are used to manage the data, loading status, and potential errors.
2. Effect Hook: Data fetching is initiated within a useEffect hook, which runs when the component mounts or when its dependencies (like a stock ticker) change.
3. API Call: The native fetch API is used to make GET requests to the API endpoints.
4. Environment Variables: API keys are retrieved from process.env to authenticate requests.

The following diagram illustrates the typical client-side data fetching flow for a component.

Sources: client/src/components/StockChart/index.tsx:184-206, client/src/components/NewsSection/index.tsx:32-51

Polygon.io API Usage

Polygon.io is the primary source for most of the financial market data displayed in the application.

Endpoints Summary

Endpoint	Method	Description	Used In
/v2/aggs/ticker/{ticker}/prev	GET	Fetches the previous day's open, high, low, and close (OHLC) for a ticker.	Hero, StockCardMini
/v2/aggs/ticker/{ticker}/range/...	GET	Fetches aggregate bars (candles) for a ticker over a given date range and timespan.	StockChart, StockSummary, StockCard
/v3/reference/tickers/{ticker}	GET	Retrieves detailed information about a specific ticker, including name, description, market cap, and branding.	quote/[ticker]/page, StockCardMini
/v3/reference/tickers?search=...	GET	Searches for tickers based on a query string.	Navbar
/v2/reference/news	GET	Fetches recent news articles, either for the general market or a specific ticker.	portal/page, NewsSection
/v1/marketstatus/now	GET	Gets the current status of the stock market (e.g., open, closed, after-hours).	portal/page
/v1/related-companies/{ticker}	GET	Finds companies related to a given ticker.	quote/[ticker]/page

Sources: client/src/components/Hero/index.tsx:25, client/src/components/StockChart/index.tsx:179, client/src/app/quote/[ticker]/page.tsx:55, client/src/components/Navbar/index.tsx:53, client/src/app/portal/page.tsx:69, client/src/app/quote/[ticker]/page.tsx:88

Flow: Fetching Stock Chart Data

The StockChart component fetches historical price data from Polygon's aggregates endpoint to render the main chart on a stock's page. The time window (e.g., '1D', '1M') determines the parameters of the API call.

Sources: client/src/components/StockChart/index.tsx:184-206, client/src/components/StockChart/index.tsx:210

Financial Modeling Prep API Usage

The application uses the Financial Modeling Prep API exclusively for fetching detailed stock ratings.

Endpoint: Stock Rating

• Endpoint: https://financialmodelingprep.com/api/v3/rating/{ticker}
• Method: GET
• Description: Retrieves a comprehensive rating for a given stock ticker, including an overall score and recommendation, as well as scores for individual financial metrics like DCF, ROE, and P/E.
• Usage: The StockRating component calls this endpoint to display the "Rating Analysis" card.

Sources: client/src/components/StockRating/index.tsx:49-52

Data Structure: RatingData

The response from the rating endpoint is parsed into the RatingData interface.

Field	Type	Description
rating	string	The overall letter-grade rating (e.g., "A", "B").
ratingScore	number	The overall numerical score.
ratingRecommendation	string	The overall recommendation (e.g., "Strong Buy", "Neutral").
ratingDetailsDCFScore	number	Score for Discounted Cash Flow.
ratingDetailsDCFRecommendation	string	Recommendation based on DCF.
ratingDetailsROEScore	number	Score for Return on Equity.
ratingDetailsROERecommendation	string	Recommendation based on ROE.
ratingDetailsROAScore	number	Score for Return on Assets.
ratingDetailsROARecommendation	string	Recommendation based on ROA.
ratingDetailsDEScore	number	Score for Debt to Equity.
ratingDetailsDERecommendation	string	Recommendation based on DE.
ratingDetailsPEScore	number	Score for Price to Earnings.
ratingDetailsPERecommendation	string	Recommendation based on PE.
ratingDetailsPBScore	number	Score for Price to Book.
ratingDetailsPBRecommendation	string	Recommendation based on PB.

Sources: client/src/components/StockRating/index.tsx:18-37

OpenAI API Usage

The OpenAI API is leveraged to add a layer of artificial intelligence and natural language processing to the application.

Use Cases

1. Critical Summary Generation (StockSummary): The StockSummary component identifies significant daily price changes ( > 2%) over the last six months from Polygon.io data. For each significant event, it calls the OpenAI API (gpt-3.5-turbo) with a prompt to generate a concise explanation of potential market influences.
   Sources: client/src/components/StockSummary/index.tsx:57-93

2. Conversational AI (TickerChat): The TickerChat component provides a chat interface where users can "talk" to a stock ticker. It uses the OpenAI API (gpt-4o-mini) to generate responses from the perspective of the stock itself, based on a system prompt and user messages.
   Sources: client/src/components/TickerChat/index.tsx:43-46, client/src/components/TickerChat/index.tsx:81-90

Flow: AI-Powered Summary Generation

The following diagram illustrates how the StockSummary component combines data from Polygon.io with analysis from OpenAI.

Sources: client/src/components/StockSummary/index.tsx:57-93

Conclusion

The Greenline application's functionality is deeply intertwined with its use of external financial data APIs. By integrating Polygon.io, Financial Modeling Prep, and OpenAI, the platform can offer a rich, multi-faceted view of the market. Polygon.io serves as the foundation for quantitative data, Financial Modeling Prep adds an analytical rating layer, and OpenAI provides qualitative, human-readable insights. This strategic combination of data sources allows Greenline to deliver a powerful and informative experience to its users.