openstockapi 0.2.1

Vietnam stock market data library — open source data plane

OpenStockAPI

A modular, multi-source Python Data Plane for Vietnamese & International financial market data.

Read the Docs »  ·  Report Bug  ·  Request Feature

---

📋 Table of Contents

1. About The Project
2. Features
3. Quick Start
4. Installation
5. Usage & Documentation
6. Supported Providers
7. Data Modules
8. Roadmap
9. Contributing
10. Changelog
11. License

---

About The Project

OpenStockAPI is an open-source Python library that acts as a modular Data Plane for collecting and standardizing financial data from multiple Vietnamese and international sources.

It is designed to be the upstream data acquisition layer for financial applications — handling provider fallback, rate limiting, and tier-based access control — so your application logic never has to worry about data source reliability.

📘 A Vietnamese version of this README is available: README_VN.md

(back to top ↑)

---

Features

• ** Multi-market Support** — Covers Vietnamese (VN) equities and can be extended to International (US) markets with the same API.
• ** Automatic Multi-source Fallback** — Integrates providers (KBS, VCI, MSN, MAS, Maybank, Fmarket) with transparent automatic failover when any source is unavailable.
• ** Freemium Tier Access Control** — Supports Free, Pro (200 req/min), and Premium (500 req/min) tiers with a client-side Token Bucket Rate Limiter.
• ** Async Support** — First-class async/await support via async_ohlcv() for high-throughput data pipelines.

(back to top ↑)

---

Quick Start

import openstockapi as osapi

# Initialize with your API key (required for all tiers)
# Register for free at: https://openstockapi.com/register
osapi.init("free_YOUR_KEY")   # or "pro_YOUR_KEY" / "premium_YOUR_KEY"

# Historical OHLCV price data
df = osapi.ohlcv("VNM", resolution="1D", start="2025-01-01", end="2025-12-31")
print(df.head())

# Company financial statements
bs = osapi.balance_sheet("VNM", period="annual")

# Realtime market quote
quote = osapi.quote("HPG")
print(f"{quote.symbol}: {quote.price:,.0f} VND ({quote.pct_change:+.2f}%)")

# Corporate news & events
news   = osapi.company_news("FPT", limit=5)
events = osapi.company_events("FPT", limit=5)

(back to top ↑)

---

Installation

Minimum install:

pip install openstockapi

With Pandas DataFrame & Excel export support:

pip install openstockapi[pandas]

Requirements: Python 3.8+

(back to top ↑)

---

Usage & Documentation

Full documentation, use case examples, and sample outputs are available in the User Guide:

User Guide — Getting Started

Module	Description	Guide
01 — OHLCV & Profile	Historical price data, company profile
02 — Financial Statements	Balance sheet, income, cash flow, ratios
03 — Realtime Quote	Live price, order book depth
04 — Market Indices	VNINDEX, VN30 constituents
05 — Macro Indicators	CPI, M2 money supply, credit growth
06 — Mutual Funds	Fund NAV, portfolio holdings
07 — News & Events	Corporate news, dividends, events

(back to top ↑)

---

Supported Providers

Provider	Source	Tier	Data Types
kbs	KB Securities Vietnam	Free	OHLCV, Profile, News, Events
vci	Vietcap Securities	Free	OHLCV, Profile, Financial Statements, Insider/Foreign/Prop Trading, Events
msn	MSN Finance (Bing)	Free	OHLCV (VN & International)
mas	MAS (Mass Asset Securities)	Free	Financial Statements, Ratios
mbk	Maybank Securities Vietnam	Free	Macro Indicators (M2, Credit)
fmarket	Fmarket Vietnam	Free	Mutual Fund NAV & Holdings
tcbs	TCBS (Techcom Securities)	Free	Realtime Quote, Order Book

Providers are tried in priority order per data type. If one fails, the next is used automatically.

(back to top ↑)

---

Data Modules Overview

openstockapi
├── ohlcv()                  # Historical OHLCV (sync)
├── async_ohlcv()            # Historical OHLCV (async)
├── profile()                # Company profile
├── balance_sheet()          # Balance sheet
├── income_statement()       # Income statement
├── cashflow()               # Cash flow statement
├── ratios()                 # Financial ratios (PE, PB, ROE...)
├── quote()                  # Realtime price quote
├── order_book()             # Order book depth
├── market_index()           # Market index OHLCV
├── index_constituents()     # Index member list
├── macro_indicators()       # Macroeconomic data
├── fund_details()           # Mutual fund info
├── company_news()           # Corporate news
└── company_events()         # Corporate events (dividends, ESOP...)

(back to top ↑)

---

Roadmap

• Vietnamese equity OHLCV (KBS, VCI, MSN)
• Financial statements (MAS, VCI)
• Macroeconomic indicators (World Bank, Maybank)
• Mutual fund data (Fmarket)
• Corporate news & events (KBS, VCI)
• International equity OHLCV
• Cryptocurrency data
• Derivatives / Futures data
• WebSocket streaming quotes

(back to top ↑)

---

Contributing

Contributions are welcome! If you'd like to add a new provider, fix a bug, or improve documentation:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-provider
3. Commit your changes
4. Open a Pull Request

Please make sure your changes pass the UAT suite before submitting:

python uat/run_uat.py

(back to top ↑)

---

Changelog

See all version updates, new features, and bug fixes at:

CHANGELOG.md

(back to top ↑)

---

License

Distributed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for more information.

(back to top ↑)