Open API chứng khoán có những loại dữ liệu nào?

Sau khi hiểu Open API chứng khoán là gì, câu hỏi tự nhiên tiếp theo là: một API chứng khoán thường có những loại dữ liệu nào?

Câu trả lời ngắn là: tùy mục đích của từng API. Có API tập trung vào giá và trạng thái thị trường. Có API đi sâu vào tài khoản của khách hàng. Một số nguồn có thêm báo cáo tài chính, sự kiện doanh nghiệp, dữ liệu vĩ mô hoặc tài sản quốc tế. Không có một danh sách chung mà mọi API đều phải đáp ứng.

Vì vậy, thay vì hỏi “API này có nhiều dữ liệu không?”, bạn nên hỏi cụ thể hơn:

API này trả lời được những câu hỏi nào trong quy trình nghiên cứu của mình?

Bài viết này lập bản đồ các nhóm dữ liệu thường gặp dựa trên tài liệu và kết quả thử nghiệm với nhiều Open API. Tên nguồn tại Việt Nam được che để tránh biến bài viết thành bảng so sánh hoặc truyền đạt một ảnh chụp chưa đầy đủ về bất kỳ bên nào.

Tóm tắt trong một phút

Các nhóm thường gặp gồm:

1. Dữ liệu tham chiếu: danh mục mã, sàn, loại tài sản, ngành và trạng thái thị trường.
2. Dữ liệu giá lịch sử: nến ngày hoặc trong ngày, khối lượng và chỉ số.
3. Dữ liệu trong phiên: bảng giá, các mức giá mua bán, khớp lệnh và luồng cập nhật.
4. Dòng tiền và thống kê thị trường: khối ngoại, tự doanh, độ rộng và xếp hạng.
5. Sự kiện: lịch thị trường, quyền và các mốc liên quan tới doanh nghiệp.
6. Dữ liệu tài chính: báo cáo tài chính, chỉ số, định giá và hồ sơ doanh nghiệp.
7. Dữ liệu vĩ mô và tài sản khác: lãi suất, tỷ giá, GDP, CPI, quỹ, trái phiếu hoặc thị trường quốc tế.
8. Dữ liệu gắn với tài khoản: tiền, sức mua, tài sản, vị thế và trạng thái yêu cầu.

Một API có thể chỉ bao phủ vài nhóm trong danh sách này. Ngay trong cùng một nhóm, chiều sâu lịch sử, tần suất cập nhật và ý nghĩa từng trường cũng có thể khác nhau.

1. Dữ liệu tham chiếu: biết mình đang hỏi về cái gì

Dữ liệu tham chiếu không phải phần hấp dẫn nhất khi mới khám phá API, nhưng gần như mọi quy trình đều cần nó trước tiên.

Nhóm này có thể gồm:

• danh sách cổ phiếu, chỉ số, ETF, chứng quyền hoặc hợp đồng tương lai;
• mã, tên, sàn và loại tài sản;
• thành phần của một chỉ số hoặc nhóm mã;
• phân ngành;
• giá tham chiếu, trần và sàn;
• trạng thái phiên;
• ngày làm việc và lịch thị trường;
• thông tin cơ bản của một công cụ như ngày đáo hạn hoặc tài sản cơ sở.

Dữ liệu tham chiếu giúp trả lời những câu hỏi tưởng đơn giản nhưng rất quan trọng:

• Mã này thuộc loại tài sản nào?
• Mã còn hoạt động hay đã thay đổi trạng thái?
• Danh sách thành phần của một nhóm được xác định ra sao?
• Phiên hiện tại đang ở giai đoạn nào?
• Một tham số nên gửi dưới dạng mã sàn, mã thị trường hay mã công cụ?

Nếu bỏ qua lớp tham chiếu, chương trình dễ phải ghi cứng danh sách mã hoặc suy đoán từ tên. Cách làm đó chạy được trong một ví dụ nhỏ nhưng khó duy trì khi danh mục thay đổi.

2. Dữ liệu giá lịch sử: nền của nhiều bài toán phân tích

Đây là nhóm quen thuộc nhất với người dùng Python. Dạng phổ biến là OHLCV:

• open: giá mở cửa;
• high: giá cao nhất;
• low: giá thấp nhất;
• close: giá đóng cửa;
• volume: khối lượng.

Tùy API, dữ liệu có thể được tổ chức theo:

• ngày, tuần hoặc tháng;
• khung trong ngày như phút hoặc giờ;
• cổ phiếu, ETF, chỉ số, chứng quyền hay hợp đồng tương lai;
• giá gốc hoặc một cách điều chỉnh đã được mô tả;
• một khoảng lịch sử cố định hoặc toàn bộ phần nguồn đang lưu giữ.

Nến giá thường được dùng để vẽ biểu đồ, tính lợi suất, kiểm tra biến động hoặc làm đầu vào cho chỉ báo. Nhưng có endpoint OHLCV chưa có nghĩa dữ liệu từ hai API có thể ghép ngay với nhau.

Bạn vẫn cần kiểm tra:

• thời điểm của cây nến là đầu kỳ hay cuối kỳ;
• múi giờ được sử dụng;
• đơn vị giá;
• cách biểu diễn phiên không có phát sinh;
• dữ liệu có bao gồm khối lượng thỏa thuận hay không;
• giá đã được điều chỉnh theo sự kiện hay chưa.

Đây là ví dụ đầu tiên cho thấy tên nhóm dữ liệu giống nhau không bảo đảm ngữ nghĩa giống nhau.

Cùng là dữ liệu giá OHLCV nhưng các API có thể khác biệt về đơn vị giá, điều chỉnh quyền, mốc thời gian và khối lượng thỏa thuận

3. Dữ liệu trong phiên: nhiều chi tiết hơn một con số giá

Dữ liệu trong phiên mô tả những gì đang diễn ra hoặc vừa diễn ra trên thị trường. Tùy nguồn, nhóm này có thể gồm:

• giá gần nhất;
• giá tham chiếu, trần và sàn;
• tổng khối lượng và giá trị;
• các mức giá mua và bán;
• khối lượng tại từng mức giá;
• các lần khớp lệnh;
• thống kê của phiên;
• trạng thái thị trường;
• luồng cập nhật qua WebSocket.

Một số API còn có dữ liệu chi tiết hơn như giao dịch lô lẻ, giao dịch thỏa thuận, mua bán chủ động, giá dự kiến ở một số giai đoạn của phiên hoặc dữ liệu theo từng loại tài sản.

Phần này khó hơn dữ liệu lịch sử vì chương trình không chỉ đọc một bảng đã hoàn tất. Nó còn phải xử lý:

• bản tin đến liên tục;
• kết nối bị ngắt và cần nối lại;
• bản tin trùng hoặc đến lệch thứ tự;
• khoảng thời gian không có cập nhật;
• sự khác nhau giữa ảnh chụp tại một thời điểm và chuỗi sự kiện;
• việc đối chiếu lại sau khi phiên kết thúc.

Sự khác biệt giữa ảnh chụp trạng thái (snapshot) và chuỗi bản tin liên tục (stream) khi xử lý dữ liệu trong phiên

Nếu muốn tìm hiểu sâu hơn về cách truyền tải, bạn có thể đọc bài WebSocket và các giao thức truyền tải dữ liệu chứng khoán.

4. Dòng tiền và thống kê toàn thị trường

Từ dữ liệu giá và khối lượng, một số API mở rộng sang các góc nhìn tổng hợp hơn:

• mua bán của nhà đầu tư nước ngoài;
• room nước ngoài;
• hoạt động tự doanh theo mã hoặc chỉ số;
• độ rộng thị trường;
• số mã tăng, giảm và đứng giá;
• nhóm tăng hoặc giảm mạnh;
• xếp hạng theo khối lượng hoặc giá trị;
• đóng góp vào biến động của chỉ số;
• thống kê theo ngành.

Cần phân biệt hai kiểu dữ liệu:

1. Dữ liệu nguồn trả trực tiếp: API đã có endpoint và trường tương ứng.
2. Kết quả tính tại máy: chương trình lấy dữ liệu cơ sở rồi tự lọc, cộng hoặc xếp hạng.

Hai bảng có hình thức giống nhau nhưng nguồn gốc khác nhau. Khi lưu kết quả, nên ghi lại bảng nào đến trực tiếp từ API và bảng nào được tính từ dữ liệu khác. Điều này giúp bạn chạy lại và giải thích phương pháp sau này.

Cùng một bảng thống kê nhưng có thể đến trực tiếp từ endpoint API hoặc được tự tính từ dữ liệu cơ sở trên máy

5. Sự kiện thị trường và doanh nghiệp

Nhóm sự kiện có thể gồm:

• ngày làm việc và ngày nghỉ;
• trạng thái mở hoặc đóng của thị trường;
• lịch đáo hạn;
• quyền cổ tức;
• phát hành thêm;
• chia tách;
• ngày đăng ký cuối cùng;
• các sự kiện do doanh nghiệp công bố.

Dữ liệu sự kiện thường không đồng đều giữa các API. Có nguồn chỉ cho biết ngày thị trường hoạt động. Có nguồn có lịch quyền nhưng không có tệp công bố gốc. Có nguồn gắn một phần sự kiện vào hồ sơ mã thay vì tạo endpoint riêng.

Khi dùng nhóm này, đừng chỉ nhìn tên sự kiện. Bạn còn cần kiểm tra:

• ngày công bố, ngày hiệu lực và ngày thực hiện;
• sự kiện dự kiến hay đã xác nhận;
• giá trị cũ và giá trị mới;
• mã định danh để tránh ghi trùng;
• lần cập nhật gần nhất.

6. Báo cáo tài chính và thông tin doanh nghiệp

Một số Open API có thêm lớp dữ liệu phục vụ phân tích cơ bản:

• bảng cân đối kế toán;
• báo cáo kết quả hoạt động;
• báo cáo lưu chuyển tiền tệ;
• chỉ số tài chính;
• tăng trưởng theo kỳ;
• thông tin niêm yết;
• cơ cấu sở hữu;
• hồ sơ doanh nghiệp;
• một số thước đo định giá.

Độ phủ của nhóm này thường khác đáng kể giữa các nguồn. Một API có thể có ba báo cáo chính nhưng không có thuyết minh. Một API khác có hàng trăm chỉ tiêu phân tích nhưng tên trường là mã kỹ thuật hoặc chuỗi viết liền. Một số thông tin như danh sách tệp báo cáo gốc, công ty con, lịch sử vốn hay chi tiết từng cổ đông có thể không xuất hiện.

Đây cũng là nhóm không nên chuẩn hóa chỉ bằng cách đổi tên cột. Cùng một chỉ tiêu có thể khác theo:

• loại hình doanh nghiệp;
• báo cáo riêng hoặc hợp nhất;
• quý riêng lẻ hoặc lũy kế;
• kỳ năm hoặc bốn quý gần nhất;
• đơn vị;
• hệ thống phân loại khoản mục.

Muốn biến dữ liệu tài chính thành đầu vào đáng tin cậy, chương trình cần một từ điển khoản mục và lưu lại phương pháp ánh xạ.

7. Vĩ mô, quỹ, trái phiếu và dữ liệu quốc tế

Ngoài dữ liệu cổ phiếu trong nước, một số API có thể mở rộng sang:

• GDP, CPI và xuất nhập khẩu;
• cung tiền, lãi suất hoặc tỷ giá;
• chỉ số quốc tế;
• ngoại hối và hàng hóa;
• tiền mã hóa;
• trái phiếu niêm yết;
• quỹ mở và chuỗi NAV;
• dữ liệu doanh nghiệp hoặc thị trường nước ngoài.

Đây là nhóm dễ tạo cảm giác “có mọi thứ”, nhưng thực tế mỗi nhánh có thể chỉ bao phủ một phần nhỏ. Ví dụ, có chuỗi NAV không đồng nghĩa có danh mục nắm giữ của quỹ. Có tỷ giá thị trường không đồng nghĩa có tỷ giá mua bán của ngân hàng. Có chỉ số quốc tế không đồng nghĩa có đầy đủ thành phần hoặc phương pháp tính chỉ số.

Khi đọc tài liệu, nên tách rõ ba mức:

• có danh mục mã;
• có giá hiện tại;
• có chuỗi lịch sử đủ dài cho bài toán của bạn.

8. Dữ liệu gắn với tài khoản của khách hàng

Open API của một công ty chứng khoán có thể có phần gắn với tài khoản đã đăng ký, chẳng hạn:

• tiền và sức mua;
• tài sản đang nắm giữ;
• vị thế;
• lịch sử hoạt động;
• các yêu cầu đang chờ xử lý;
• kết quả và trạng thái phản hồi;
• thông báo trong phiên theo độ trễ của nguồn, liên quan tới tài khoản.

Nhóm này khác dữ liệu thị trường ở chỗ kết quả phụ thuộc vào chính tài khoản và phạm vi được kích hoạt. Cơ chế xác thực cũng có thể chặt hơn, chẳng hạn token riêng, OTP, danh sách IP hoặc bước xác nhận bổ sung.

Nếu mục tiêu chỉ là nghiên cứu dữ liệu thị trường, bạn không nhất thiết phải bắt đầu từ nhóm tài khoản. Tách hai phạm vi giúp chương trình đơn giản hơn và giảm số thông tin nhạy cảm phải quản lý.

Không phải Open API nào cũng có đủ mọi nhóm

Qua việc đối chiếu nhiều API, có thể thấy một quy luật khá rõ:

• dữ liệu tham chiếu, giá lịch sử và trạng thái thị trường xuất hiện phổ biến hơn;
• dữ liệu trong phiên thường có nhiều khác biệt về cấu trúc và chiều sâu;
• báo cáo tài chính, vĩ mô, quỹ và trái phiếu chỉ tập trung ở một số nguồn;
• một số bảng có thể tính từ dữ liệu cơ sở thay vì cần endpoint riêng;
• nhiều dữ liệu chuyên sâu không xuất hiện trong bất kỳ API nào đang được đánh giá.

Điều này không có nghĩa API nào “thiếu” theo nghĩa tuyệt đối. Mỗi API được thiết kế cho một nhóm nhu cầu riêng. Một nguồn tập trung vào bảng giá và tài khoản không nhất thiết phải có dữ liệu vĩ mô. Một nguồn thiên về phân tích doanh nghiệp không nhất thiết có luồng dữ liệu trong phiên.

Vì vậy, bảng đánh giá đúng nên bắt đầu từ nhu cầu của người dùng, không bắt đầu từ số lượng endpoint.

Khi API không có dữ liệu bạn cần

API không phải con đường duy nhất để đưa dữ liệu vào một quy trình phân tích. Người dùng có thể đã có:

• tệp CSV xuất từ một hệ thống khác;
• bảng Excel tự duy trì;
• dữ liệu Parquet trong kho cá nhân;
• kết quả tính toán từ một notebook;
• bảng do người dùng tự nhập hoặc tổng hợp từ tài liệu được phép sử dụng.

Một engine xử lý dữ liệu tốt nên tách đầu vào khỏi phần chuẩn hóa và tính toán. Khi đó, dữ liệu có thể đi vào từ API hoặc từ tệp trên máy, miễn là người dùng mô tả được cấu trúc, đơn vị, thời gian và nguồn gốc.

Tách rời đầu vào khỏi phần chuẩn hóa và phân tích giúp quy trình linh hoạt kết hợp cả Open API lẫn tệp dữ liệu trên máy

Cách tổ chức này tạo ra hai mức tự chủ:

1. Bạn có thể chọn kết nối phù hợp với tài khoản và nhu cầu của mình.
2. Bạn vẫn có thể tiếp tục quy trình khi dữ liệu cần thiết đã nằm trong tệp riêng hoặc đến từ một nguồn khác.

Tuy nhiên, cho phép nạp tệp không đồng nghĩa có thể bỏ qua kiểm tra. Chương trình vẫn cần biết tên trường, kiểu dữ liệu, đơn vị, múi giờ, giá trị thiếu và quy tắc ánh xạ.

Từ “có dữ liệu” đến “dùng được dữ liệu”

Biết API có nhóm dữ liệu nào mới chỉ giải quyết câu hỏi về phạm vi. Để dùng được, còn ít nhất năm câu hỏi:

1. Trường dữ liệu mang ý nghĩa gì?
2. Đơn vị và múi giờ là gì?
3. Dữ liệu được cập nhật theo cách nào?
4. Khi thiếu hoặc gián đoạn, chương trình xử lý ra sao?
5. Có thể thay nguồn mà không viết lại toàn bộ phần phân tích không?

Đây là lúc bài toán chuyển từ kết nối API sang chuẩn hóa dữ liệu.

Bạn có thể đọc tiếp Chuẩn hóa dữ liệu chứng khoán khi vibe coding để tránh lỗi. Bài tiếp theo trong chuỗi này sẽ đi sâu hơn vào một vấn đề cụ thể: vì sao hai Open API cùng nói về một loại dữ liệu nhưng lại không dùng chung tên trường, đơn vị và quy ước.

Điều cần nhớ

Open API chứng khoán có thể bao gồm nhiều lớp, từ danh mục mã, giá lịch sử và dữ liệu trong phiên tới báo cáo tài chính, vĩ mô hoặc thông tin gắn với tài khoản. Nhưng không có API nào mặc nhiên phải bao phủ toàn bộ các lớp đó.

Thay vì đếm endpoint, hãy bắt đầu từ câu hỏi nghiên cứu, xác định nhóm dữ liệu cần thiết rồi kiểm tra chiều sâu, ngữ nghĩa và lịch sử của từng nguồn. Khi API chưa có phần bạn cần, dữ liệu tự chuẩn bị trên máy vẫn có thể trở thành đầu vào nếu hệ thống xử lý được thiết kế tách rời khỏi nguồn kết nối.

---

Nội dung phục vụ học tập, nghiên cứu và tham khảo, không phải khuyến nghị đầu tư. Phạm vi API có thể thay đổi; hãy dùng tài liệu hiện hành do bên vận hành công bố và tự kiểm tra dữ liệu trước khi sử dụng.