gStockly API Documentation

Multi-source stock quote aggregation

Introduction

GStockly is a comprehensive RESTful API for stock market data aggregation, providing real-time quotes, historical data, and AI-powered technical analysis from multiple sources.

Key Features

✓ Multi-source quote providers (Yahoo Finance, Investing.com, TradingView)
✓ Real-time and historical data retrieval
✓ AI-powered ticker analysis (Claude + DeepSeek)
✓ Advanced caching with Redis
✓ Rate limiting and authentication
✓ Comprehensive logging and monitoring

API Architecture Overview

The API is built with PHP using a modular architecture with separate concerns for authentication, caching, database operations, and external service integrations. All endpoints return standardized JSON responses with proper HTTP status codes.

Authentication

All protected endpoints require API key authentication.

API Key Authentication

Send your API key using one of these methods:

// Method 1: X-API-Key Header GET /api/quotes/daily?ticker=AAPL X-API-Key: your_api_key_here // Method 2: Bearer Token GET /api/quotes/daily?ticker=AAPL Authorization: Bearer your_api_key_here
Response includes:
user_id - Your user ID
plan_name - Current subscription plan
max_requests_per_day - Daily limit
requests_today - Requests used today
Authentication Required

System Architecture

Core Components

Component Purpose Technology
Database Persistent data storage MySQL/MariaDB
Cache Layer In-memory caching for performance Redis
Authentication API key validation & rate limits Custom Auth class
Logger Request/error logging File-based logging
Quote Providers External data sources Multiple APIs + Web Scraping
AI Services Advanced analysis Claude API + DeepSeek API

Public Endpoints

No authentication required for these endpoints.

Health Check

GET /api/health
/api/health

Check API health status including database and cache connectivity.

Returns: 200 OK if all systems operational, 503 if degraded
{ "status": "ok", "services": { "database": "up", "cache": "up" }, "version": "1.0.0" }
Public

API Status

GET /api/status
/api/status

Get API and database statistics.

{ "api_version": "1.0.0", "database": { "tickers": 5000, "quotes_d": 2500000, "quotes_w": 500000 } }
Public

Countries Statistics

GET /api/public/countries-stats
/api/public/countries-stats

Get statistics of tickers grouped by country.

Returns: Array of countries with ticker counts and flag URLs
[ { "country": "United States", "ticker_count": 2500, "flag_url": "https://..." } ]
Public

Quote Endpoints

Retrieve stock quotes from multiple data sources.

Daily Quotes

GET /api/quotes/daily
GET /api/quotes/daily?ticker=AAPL&provider=yahoo_finance&format=json

Get the latest daily quote for a ticker.

Query Parameters
ticker (required) - Stock symbol (AAPL, MSFT, ^GSPC)
provider (optional) - Quote source: yahoo_finance, investing, tradingview
format (optional) - Response format: json (default) or csv
// Request GET /api/quotes/daily?ticker=AAPL&provider=yahoo_finance X-API-Key: your_api_key // Response { "status": "success", "data": { "ticker": "AAPL", "date": "2026-01-08", "open": 230.50, "high": 235.75, "low": 228.25, "close": 233.40, "volume": 45000000, "provider": "yahoo_finance" } }
Authentication Required

Real-time Quotes

GET /api/quotes/realtime
GET /api/quotes/realtime?ticker=AAPL&provider=yahoo_finance&use_fallback=true

Get real-time quote with automatic provider fallback.

Query Parameters
ticker (required) - Stock symbol
provider (optional) - Preferred provider (auto-fallback if not specified)
use_fallback (optional) - Enable automatic fallback (default: true)
Returns: Quote with execution_time_ms and cached status
Authentication Required

Historical Quotes

GET /api/quotes/historical
GET /api/quotes/historical?ticker=AAPL&fromdate=2025-01-01&todate=2026-01-08

Retrieve historical quotes within a date range.

Query Parameters
ticker (required) - Stock symbol
fromdate (required) - Start date (YYYY-MM-DD)
todate (required) - End date (YYYY-MM-DD)
provider (optional) - Data source (default: yahoo_finance)
format (optional) - json or csv
Authentication Required

Available Providers

GET /api/quotes/providers
/api/quotes/providers

List all available quote providers.

Providers: yahoo_finance, investing, tradingview
Public

Ticker Endpoints

Manage and search stock information.

List All Tickers

GET /api/tickers
GET /api/tickers?sector=Technology&limit=50&page=1

Get paginated list of tickers with optional filtering.

Query Parameters
sector (optional) - Filter by sector
limit (optional) - Results per page (max 500)
page (optional) - Page number (default: 1)
enabled (optional) - Filter by status (default: 1)
Authentication Required
GET /api/tickers/search
GET /api/tickers/search?q=Apple&limit=20

Search tickers by symbol or name.

Query Parameters
q (required) - Search query (min 2 characters)
limit (optional) - Max results (default: 20, max: 100)
Authentication Required

Ticker Details

GET /api/tickers/{ticker}
GET /api/tickers/AAPL

Get detailed information about a specific ticker.

Returns: Ticker details including sector, industry, last quote, volatility metrics
Authentication Required

AI Analysis Endpoints

AI-powered stock analysis powered by Claude and DeepSeek.

Claude Ticker Analysis

POST /api/ai/ticker-analysis
POST /api/ai/ticker-analysis

Get AI analysis for a ticker with custom request.

Request Body
ticker (required) - Stock symbol
request (required) - Analysis request (min 10 chars)
// Request POST /api/ai/ticker-analysis X-API-Key: your_api_key Content-Type: application/json { "ticker": "AAPL", "request": "Analyze technical and fundamental setup for swing trading" } // Response (cached for 24 hours) { "status": "success", "data": { "type": "ticker_analysis", "ticker": "AAPL", "cached": false, "analysis": "Detailed AI analysis..." } }
Authentication Required Claude AI

Trading System Creation

POST /api/ai/trading-system
POST /api/ai/trading-system

Generate a custom trading system with entry/exit rules.

Request Body
request (required) - System description (min 20 chars)
user_req_id (optional) - Request identifier
{ "request": "Create a mean reversion system using RSI and Bollinger Bands for daily timeframe", "user_req_id": "custom_id_123" }
Authentication Required Claude AI

DeepSeek Analysis

POST /api/deepseek/ticker-analysis
POST /api/deepseek/ticker-analysis

Alternative AI analysis powered by DeepSeek.

Provider: DeepSeek Chat Model - Same interface as Claude analysis
Authentication Required DeepSeek AI

Technical Architecture

Database Schema

The system uses MySQL/MariaDB with optimized tables for quotes, tickers, and analysis results.

Table Purpose Key Fields
tickers Stock information ticker, name, sector, exchange, country
quotes_d Daily quotes ticker, date, open, high, low, close, volume
quotes_w Weekly quotes ticker, date, open, high, low, close, volume
quotes_m Monthly quotes ticker, date, open, high, low, close, volume
ai_ticker_analysis AI analysis results ticker, analysis, created_on
ai_trading_system Trading system specs user_req, prompt, answer, created_on
subscriptions User subscriptions user_id, api_key, plan_name, max_requests_per_day
api_logs Request logging user_id, endpoint, status_code, response_time_ms

Caching System

Redis is used for high-performance caching with configurable TTLs:

Cache Policies
Quote Data - 5 minutes TTL
Ticker Details - 30 minutes TTL
API Key - 1 hour TTL
AI Analysis - 24 hours TTL
Rate Limits - 1 second TTL

Rate Limiting

The API implements two-tier rate limiting:

Tier Per Second Per Day
Standard 100 req/s 5,000 req/day
Premium 500 req/s 50,000 req/day
Enterprise Unlimited Unlimited

FAQ

How do I get an API key?

Contact the API administrator or visit the customer portal to generate API keys for your account.

What's the difference between the quote providers?

Yahoo Finance: Most comprehensive, high reliability | Investing.com: Commodity and CFD data | TradingView: Advanced charting integration

How often is quote data updated?

Daily data is updated after market close. Real-time quotes are cached for 5 seconds to balance latency and performance.

Can I use the API for automated trading?

Yes, the API is designed for automated applications. Ensure you comply with exchange regulations and risk management best practices.

What happens if I exceed rate limits?

The API returns 429 (Too Many Requests) with remaining requests info. Implement exponential backoff in your client.