vnfinancialdata

Python interface for accessing standardized financial statement data of Vietnamese listed companies.

vnfinancialdata provides a simple programmatic interface for loading, filtering, and analyzing standardized financial statement data for Vietnamese listed companies.

The package is designed for academic research, financial data analysis, financial modeling, education, data science, and reproducible analytical workflows.

The underlying dataset is released as a versioned Parquet dataset on Hugging Face:

Vietnamese Listed Companies Financial Data
Dataset version: v1.0.0
Schema version: 1.0

---

Why vnfinancialdata?

Vietnamese company financial statements are commonly distributed as individual reports or spreadsheets with different layouts and naming conventions.

vnfinancialdata provides a standardized interface so that researchers and analysts can work with financial statement observations programmatically instead of manually processing individual files.

The underlying data has been transformed into a standardized long-format structure, making it easier to:

• filter data by company;
• filter data by reporting year;
• select individual financial statement items;
• compare companies;
• analyze financial indicators across years;
• load data efficiently with Python;
• build reproducible research workflows.

---

Key Features

• Access financial statement data of Vietnamese listed companies through Python.
• Support for HSX and HNX listed companies.
• Standardized Balance Sheet, Income Statement, and Cash Flow Statement data.
• Long-format data structure suitable for pandas-based analysis.
• Versioned dataset and schema for reproducible research.
• Company-level and year-level filtering.
• Financial statement item-level access.
• Source metadata retained with the standardized observations.
• Data distributed in efficient Parquet format.

---

Dataset

The package provides programmatic access to the following dataset:

Vietnamese Listed Companies Financial Data

The dataset contains standardized financial statement observations for Vietnamese listed companies.

Each observation represents a financial statement item for a company and reporting year.

Dataset version

Dataset version: v1.0.0
Schema version: 1.0
Format: Parquet
Data structure: Long format

The package version and dataset version are managed separately.

For example:

Python package: 0.1.0
Dataset revision: v1.0.0
Schema version: 1.0

This separation allows the Python interface to evolve independently from the underlying data release.

---

Data Provenance

The underlying financial information was collected from publicly available sources, including:

• official stock exchange portals;
• official company websites;
• publicly available financial statements;
• publicly available annual reports.

The original source documents were transformed into a standardized long-format dataset.

Source-related metadata such as source_file and source_sheet are retained where available to support traceability and reproducibility.

Users should consult the original financial statements or annual reports when verifying individual financial figures.

---

Data Structure

The standardized dataset follows a long-format design.

The main fields include:

Column	Description
ticker	Stock ticker symbol
year	Reporting year
exchange	Stock exchange
statement	Financial statement type
item_code	Standardized financial statement item code
item_name	Financial statement item name
value	Reported numerical value
source_file	Original source file identifier
source_sheet	Original worksheet identifier

Conceptually, a financial observation is represented as:

ticker
year
exchange
statement
item_code
item_name
value

This structure allows researchers to work with financial statement data using standard Python data-analysis tools.

---

Installation

Install the package from PyPI:

pip install vnfinancialdata

Python version:

Python >= 3.10

Optional development dependencies are available for development and Polars-based workflows.

---

Authentication

The package accesses the versioned dataset hosted on Hugging Face.

If authentication is required by the dataset repository or access configuration, authenticate with Hugging Face before loading data:

hf auth login

Then verify access from Python:

import vnfinancialdata as vnf

vnf.check_access()

---

Quick Start

Load a financial statement by exchange and statement type:

import vnfinancialdata as vnf

df = vnf.load(
    exchange="HSX",
    statement="balance_sheet"
)

print(df.head())

Available exchanges include:

HSX
HNX

Available statement categories include:

balance_sheet
income_statement
cash_flow

---

Example 1 — Load Financial Statements for One Company

Researchers can retrieve the financial statement data of a specific listed company over a selected period.

For example, to retrieve the balance sheet of ticker AAA from 2020 to 2025:

import vnfinancialdata as vnf

df = vnf.get(
    ticker="AAA",
    exchange="HSX",
    statement="balance_sheet",
    start=2020,
    end=2025
)

print(df.head())

The returned DataFrame can then be used for further analysis with pandas:

import pandas as pd

df = pd.DataFrame(df)

print(df[[
    "ticker",
    "year",
    "item_code",
    "item_name",
    "value"
]])

This workflow is useful for constructing company-level financial histories and longitudinal analyses.

---

Example 2 — Retrieve One Financial Indicator Across Multiple Companies

Because the dataset uses a standardized item_code and item_name, researchers can filter the same financial statement item across multiple companies.

For example:

import vnfinancialdata as vnf

df = vnf.load(
    exchange="HSX",
    statement="income_statement"
)

companies = [
    "AAA", "A", "B", "C", "D",
    "E", "F", "G", "H", "I"
]

result = df[
    df["ticker"].isin(companies)
]

print(result.head())

A specific financial statement item can then be selected using its standardized item code:

indicator = result[
    result["item_code"] == "YOUR_ITEM_CODE"
]

print(
    indicator[
        ["ticker", "year", "item_code", "item_name", "value"]
    ]
)

This structure makes it possible to construct cross-sectional datasets such as:

Company A → Indicator X
Company B → Indicator X
Company C → Indicator X
...
Company J → Indicator X

for comparative financial analysis.

Replace YOUR_ITEM_CODE with the standardized item code corresponding to the financial statement item of interest.

---

Example 3 — Compare a Financial Statement Item Across Companies and Years

The long-format structure is particularly useful for panel-data analysis.

For example:

import vnfinancialdata as vnf

df = vnf.load(
    exchange="HSX",
    statement="income_statement"
)

result = df[
    (df["ticker"].isin(["AAA", "BBB", "CCC"])) &
    (df["year"].between(2020, 2025)) &
    (df["item_code"] == "YOUR_ITEM_CODE")
]

result = result.sort_values(
    ["ticker", "year"]
)

print(
    result[
        ["ticker", "year", "item_name", "value"]
    ]
)

The resulting structure can be used directly for:

• panel-data analysis;
• company comparison;
• time-series analysis;
• financial modeling;
• visualization;
• econometric research.

---

Financial Statements

The current dataset includes standardized information from three major financial statement categories:

Balance Sheet

balance_sheet

Income Statement

income_statement

Cash Flow Statement

cash_flow

The exact records available depend on the released dataset snapshot.

---

Long-Format Design

Unlike the original spreadsheet-oriented financial reports, the standardized dataset stores observations in long format.

This design allows users to easily:

• filter by ticker;
• filter by year;
• select a financial statement;
• select a financial statement item;
• compare multiple companies;
• compare multiple reporting periods;
• create panel datasets;
• integrate financial data into statistical and machine-learning workflows.

For example:

ticker | year | statement         | item_code | item_name | value
-------|------|--------------------|-----------|-----------|------
AAA    | 2023 | income_statement   | ...       | ...       | ...
AAA    | 2024 | income_statement   | ...       | ...       | ...
BBB    | 2023 | income_statement   | ...       | ...       | ...
BBB    | 2024 | income_statement   | ...       | ...       | ...

---

Data Quality and Transformation

The released dataset was generated through a structured transformation process:

1. Source financial statement files are collected.
2. Financial statement structures are standardized.
3. Source data are converted into long format.
4. Company, year, exchange, and statement information are preserved.
5. Standardized item codes and item names are assigned.
6. Data are exported to Parquet.
7. Dataset schema and record counts are validated.
8. The resulting dataset is released as a versioned snapshot.

The current released dataset corresponds to:

Dataset version: v1.0.0
Schema version: 1.0

---

Reproducibility

For reproducible research, users should record both the package version and dataset version used in their analysis.

For example:

Package:
vnfinancialdata 0.1.x

Dataset:
v1.0.0

Schema:
1.0

Recording the dataset revision is particularly important because future releases may contain additional companies, reporting years, corrections, additional statement types, metadata improvements, or schema changes.

---

Intended Use

vnfinancialdata is intended for:

• academic research;
• financial data analysis;
• financial econometrics;
• financial modeling;
• data science;
• educational projects;
• quantitative finance experiments;
• reproducible research;
• development of analytical applications.

The package is especially useful when researchers need standardized financial statement data across multiple Vietnamese listed companies and reporting periods.

---

Citation

If you use vnfinancialdata or the underlying dataset in academic research, publications, reports, or other analytical work, please cite the corresponding dataset version.

Suggested dataset citation:

Vietnamese Listed Companies Financial Data.
Dataset version v1.0.0.

Please also acknowledge the original public sources from which the financial statements and annual reports were collected.

When reproducibility is important, we recommend reporting:

Python package: vnfinancialdata
Package version: <version used>
Dataset version: v1.0.0
Schema version: 1.0

---

Related Dataset

The underlying dataset is available on Hugging Face:

Vietnamese Listed Companies Financial Data

Dataset repository:

thanhnp-uel/vietnam-listed-companies-financial-statements

The dataset card contains additional information about data provenance, structure, transformation, licensing, versioning, and reproducibility.

---

Versioning

The project uses separate version identifiers for the Python package and the underlying dataset.

Python package

vnfinancialdata

Dataset

v1.0.0

Schema

1.0

Future dataset releases may include:

• additional companies;
• additional reporting years;
• additional financial statements;
• corrections;
• metadata improvements;
• schema changes.

Changes between dataset releases will be documented in the corresponding release information.

---

License

The underlying dataset is released as:

Open Data / Public Domain

The dataset is derived from publicly available financial statements and annual reports.

Users should nevertheless verify the applicable terms associated with original source documents when using the data for commercial redistribution or other specific purposes.

---

Disclaimer

This package and dataset are provided for research, educational, analytical, and data-processing purposes.

Although the data have been standardized and validated during the transformation process, no guarantee is made that every observation is completely free from errors or omissions.

Users should verify important financial information against original financial statements, annual reports, stock exchange publications, or company disclosures before making investment, financial, legal, or other consequential decisions.

vnfinancialdata and its underlying dataset do not constitute investment advice.

---

Contact and Issues

For data-quality issues, reproducibility questions, or technical issues related to the package or dataset, please use the project's designated issue or contact channel.

---

Project Information

Package:       vnfinancialdata
Current data:  v1.0.0
Schema:        1.0
Python:        >=3.10
Exchanges:     HSX, HNX
Format:        Parquet

Built for reproducible research and programmatic access to Vietnamese listed-company financial data.