README.md

metadata

title: MarketLens
emoji: 📈
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false

MarketLens - Stock Research Assistant

A personal stock research assistant that provides real-time market information and AI-powered insights. Users can explore stock data, news, earnings, and performance metrics powered by the Polygon API.

Project Structure

MarketLens/
├── be/                          # Python backend
│   ├── app.py                   # Flask application
│   ├── config.py                # Configuration management
│   ├── polygon_api.py           # Polygon API client
│   └── requirements.txt         # Python dependencies
├── fe/                          # JavaScript frontend
│   ├── index.html              # Main HTML page
│   ├── app.js                  # Frontend logic
│   └── styles.css              # Styling
├── company_tickers.json        # List of stock tickers
├── .env.example                # Environment variables template
└── README.md                   # This file

Features

• Stock Selection: Search and select from thousands of stock tickers
• Real-time Data: View current market data including price, volume, and market cap
• Price Charts: Interactive charts with multiple timeframes (1M, 3M, 6M, 1Y, 5Y)
• Financial Data: Access quarterly and annual financial statements
• News Feed: Latest news articles related to selected stocks
• Clean UI: Simple, responsive interface built with vanilla JavaScript

Setup Instructions

Prerequisites

• Python 3.8 or higher
• Polygon API key (get one at polygon.io)

1. Install Python Dependencies

Navigate to the project directory and install the required Python packages:

cd "MarketLens"
pip install -r be/requirements.txt

2. Configure API Key

Create a .env file in the project root directory:

cp .env.example .env

Edit the .env file and add your Polygon API key:

POLYGON_API_KEY=your_actual_api_key_here
PORT=5000

Important: Get your free Polygon API key from https://polygon.io/

3. Run the Application

Start the Flask backend server:

cd be
python app.py

The application will start on http://localhost:5000

4. Access the Application

Open your web browser and navigate to:

http://localhost:5000

Usage

1. Search for a Stock: Use the search box to filter stocks by ticker symbol or company name
2. Select a Stock: Click on a stock from the dropdown list
3. Explore Data: Navigate through different tabs:
   • Overview: Key metrics and company description
   • Chart: Price performance over various timeframes
   • Financials: Quarterly and annual financial statements
   • News: Latest news articles about the company

API Endpoints

The backend provides the following REST API endpoints:

• GET /api/ticker/<ticker>/details - Get detailed ticker information
• GET /api/ticker/<ticker>/previous-close - Get previous day's close data
• GET /api/ticker/<ticker>/aggregates - Get historical price data
• GET /api/ticker/<ticker>/news - Get news articles
• GET /api/ticker/<ticker>/financials - Get financial statements
• GET /api/ticker/<ticker>/snapshot - Get current market snapshot

Technology Stack

Backend

• Flask: Lightweight Python web framework
• Requests: HTTP library for API calls
• python-dotenv: Environment variable management
• Flask-CORS: Cross-origin resource sharing

Frontend

• Vanilla JavaScript: No frameworks, pure JavaScript
• HTML5 Canvas: For rendering price charts
• CSS3: Modern styling with flexbox and grid

Polygon API

This application uses the Polygon API to fetch:

• Real-time and historical stock prices
• Company information and details
• Financial statements
• News articles
• Market snapshots

API Documentation: https://polygon.io/docs

Development

Running in Development Mode

The Flask server runs in debug mode by default, which provides:

• Auto-reload on code changes
• Detailed error messages
• Interactive debugger

Environment Variables

• POLYGON_API_KEY: Your Polygon API key (required)
• PORT: Server port (default: 5000)

Troubleshooting

API Key Issues

• Ensure your .env file is in the project root directory
• Verify your API key is valid at polygon.io
• Check that the API key is properly set in the .env file

CORS Errors

• Make sure Flask-CORS is installed: pip install Flask-CORS
• The backend should be running on http://localhost:5000

No Data Displayed

• Check browser console for error messages
• Verify the backend server is running
• Ensure your Polygon API key has sufficient permissions

License

This is a personal project for educational and personal use.

Future Enhancements

• AI-powered stock analysis and recommendations
• Portfolio tracking
• Real-time price updates with WebSockets
• Advanced charting with technical indicators
• User authentication and saved preferences