Skip to content

README.md

Latest commit

 

History

History
243 lines (193 loc) · 5.86 KB

README.md

File metadata and controls

243 lines (193 loc) · 5.86 KB

Market Cap API

A real-time market capitalization tracking API that aggregates data from multiple free financial data sources, similar to companiesmarketcap.com.

Features

  • Real-time Market Data: Collects current stock prices and market caps from multiple free APIs
  • Historical Tracking: Stores historical market cap data for trend analysis
  • Automated Collection: Scheduled data collection every 15 minutes during market hours
  • Multiple Data Sources: Fallback system using Yahoo Finance, Alpha Vantage, FMP, and SEC EDGAR
  • RESTful API: Clean endpoints for accessing market cap rankings and company data
  • Rate Limiting: Built-in protection against API abuse
  • Railway Deployment Ready: Configured for easy cloud deployment

Data Sources

Primary (Free)

  • Yahoo Finance: Main source for real-time prices (unofficial but reliable)
  • SEC EDGAR API: Official government data for fundamental information
  • Alpha Vantage: 25 calls/day free tier for backup data
  • Financial Modeling Prep (FMP): 250 calls/day free tier

Data Collection Strategy

  • Price Updates: Every 15 minutes during market hours (9 AM - 4 PM EST)
  • Fundamental Data: Daily collection of shares outstanding from SEC filings
  • Fallback System: If one API fails, automatically tries the next source
  • Rate Limiting: Respects all API rate limits with intelligent delays

Installation

  1. Clone and Setup:
cd market-cap-api
npm install
  1. Environment Configuration:
cp .env.example .env

Edit .env with your API keys:

# Free API Keys (all optional, system works with fallbacks)
ALPHA_VANTAGE_API_KEY=your_key_here  # Get free at alphavantage.co
FMP_API_KEY=your_key_here           # Get free at financialmodelingprep.com

# Database
DATABASE_PATH=./data/market_caps.db

# Server
PORT=3001
NODE_ENV=development
  1. Initialize Database:
npm run collect  # This will create the database and collect initial data

Usage

Development

npm run dev        # Start with auto-reload
npm run collect    # Manual data collection

Production

npm start          # Production server

API Endpoints

Get Current Top Companies

GET /api/top-companies?limit=50

Response:

{
  "success": true,
  "data": [
    {
      "rank": 1,
      "ticker": "AAPL",
      "name": "Apple Inc.",
      "market_cap": 3000.5,
      "price": 185.42,
      "change_percent": 1.23,
      "sector": "Technology",
      "exchange": "NASDAQ",
      "last_updated": "2025-01-21T15:30:00Z"
    }
  ],
  "meta": {
    "total": 50,
    "lastUpdated": "2025-01-21T15:30:00Z"
  }
}

Get Company Details

GET /api/company/AAPL?days=30

Get Historical Rankings

GET /api/rankings/2025-01-21?limit=10

Get System Stats

GET /api/stats

Health Check

GET /health

Database Schema

Companies Table

  • Basic company information (ticker, name, sector, etc.)
  • Shares outstanding from SEC filings
  • IPO dates and metadata

Market Cap History

  • Daily price and market cap snapshots
  • Source attribution for each data point
  • Volume and change percentage tracking

Current Rankings

  • Optimized table for fast ranking queries
  • Updated after each price collection
  • Top 100 companies by market cap

Collection Log

  • Tracks all data collection attempts
  • Success/failure rates and error logging
  • Performance metrics

Data Quality

Update Frequency

  • Market Hours: Every 15 minutes (9 AM - 4 PM EST, Mon-Fri)
  • After Hours: Every hour
  • Weekends: Every 6 hours (for international markets)

Data Accuracy

  • Real-time prices: 15-minute delay (similar to companiesmarketcap.com)
  • Market caps: Calculated as Price × Shares Outstanding
  • Shares outstanding: Updated daily from SEC filings
  • Multiple source validation: Cross-checks between APIs

Error Handling

  • Automatic fallback between data sources
  • Graceful handling of API failures
  • Comprehensive logging and monitoring
  • Data integrity checks

Railway Deployment

Automatic Deployment

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway deploy

Environment Variables (Railway)

Set these in your Railway dashboard:

ALPHA_VANTAGE_API_KEY=your_key
FMP_API_KEY=your_key  
NODE_ENV=production
DATABASE_PATH=/app/data/market_caps.db

Railway Configuration

The app includes a railway.toml file with optimized settings:

  • Build Command: npm install
  • Start Command: npm start
  • Health Check: /health
  • Auto-scaling: Enabled

Cost Analysis

Free Tier Usage

  • Yahoo Finance: Unlimited (unofficial)
  • SEC EDGAR: Unlimited (official government API)
  • Alpha Vantage: 25 calls/day (covers 25 companies)
  • FMP: 250 calls/day (covers major companies)

Scaling Costs

  • Alpha Vantage Pro: $29.99/month (500 calls/day)
  • FMP Premium: $19.99/month (unlimited calls)
  • Railway Hosting: $5-20/month depending on usage

Total Cost Estimate

  • Free tier: $0/month (covers top 50-100 companies)
  • Premium tier: $50-100/month (covers all US stocks)

Monitoring

Built-in Logging

  • Request/response logging with Winston
  • Performance metrics tracking
  • Data collection success rates
  • Error tracking and alerting

Health Monitoring

  • /health endpoint for uptime monitoring
  • Database connectivity checks
  • API source availability tracking

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues or questions:

  1. Check the logs in logs/ directory
  2. Verify API keys are valid
  3. Test individual endpoints with curl/Postman
  4. Check Railway deployment logs if using cloud hosting