API Reference

01 Base URL

HTTP

https://xangdau.nthanhtai.xyz

Default Endpoint — Khuyến nghị

Endpoint mặc định duy nhất để lấy giá xăng dầu. Một request, đầy đủ dữ liệu và có nhãn nguồn.

KHUYẾN NGHỊ

GET /api/fuel-prices

Default Endpoint: dữ liệu đầy đủ từ 11 nguồn, trả về theo dạng data[] -> sources[].

11 nguồn tích hợp Nhãn source từng giá Grouped theo mặt hàng 60 req/min

JavaScript (Fetch)

const res = await fetch('https://xangdau.nthanhtai.xyz/api/fuel-prices');
const json = await res.json();

console.log(json.meta.dataSources.length); // 11
console.log(json.data[0].name);            // "Xăng RON 95-V"
console.log(json.data[0].sources);         // [{ source, region1, region2, price }, ...]

Python

import requests

json = requests.get('https://xangdau.nthanhtai.xyz/api/fuel-prices').json()
print(json['meta']['dataSources'])
print(json['data'][0]['name'])
print(json['data'][0]['sources'])

DANH SÁCH NGUỒN TÍCH HỢP

KEY	NGUỒN	URL
`petrolimex`	Petrolimex	https://www.petrolimex.com.vn
`kv2_petrolimex`	Petrolimex KV2	https://kv2.petrolimex.com.vn
`saigon_petrolimex`	Petrolimex SAI GON	https://saigon.petrolimex.com.vn
`vungtau_petrolimex`	Petrolimex VUNG TAU	https://vungtau.petrolimex.com.vn
`pvoil`	PVOil	https://www.pvoil.com.vn
`mipec`	Mipec	https://www.mipec.com.vn/pages/gia-xang-dau-ban-le
`comeco`	COMECO	https://comeco.vn
`saigonpetro`	Saigon Petro	https://saigonpetro.com.vn/ban-le-xang-dau
`petrotimes`	Petro Times	https://petrotimesgroup.com
`webgia`	WebGia (Mirror)	https://webgia.com/gia-xang-dau/petrolimex/
`giaxanghomnay`	GiaXangHomNay	https://giaxanghomnay.com

petrolimex + mirrors Vùng 1 & 2

Nguồn lõi của hệ thống gồm Petrolimex và các mirror KV2/SAIGON/VUNGTAU để tăng độ ổn định.

pvoil Giá thống nhất

PVOil thường công bố theo một mức giá toàn quốc (không tách Vùng 1/2), kèm ngày giờ công bố.

mipec · saigonpetro Bổ sung đối chiếu

Nhóm nguồn bổ sung dùng để đối chiếu mức giá theo từng mặt hàng và tăng độ phủ dữ liệu.

comeco · petrotimes · webgia Linked/Mirror

Nguồn linked/mirror giúp tăng khả năng phục hồi của hệ thống và đóng góp vào mảng dataSources.

giaxanghomnay 63 Tỉnh thành

Nguồn tổng hợp mạnh cho quốc gia và tra cứu theo tỉnh thành, đặc biệt hữu ích cho endpoint theo tỉnh.

Dữ liệu từ 11 nguồn được làm mới tự động theo quy định (NĐ 80/2023). Endpoint mặc định /api/fuel-prices luôn là lựa chọn khuyến nghị.

Lưu ý pháp lý: Việc sử dụng dữ liệu phải tuân thủ Tuyên bố miễn trừ trách nhiệm.

meta.primarySource luôn cho biết nguồn thực sự đang cung cấp data. Nếu có warning trong response → Petrolimex đang down, hệ thống đã tự động chuyển sang nguồn dự phòng.

02 Rate Limiting

API áp dụng giới hạn truy cập tự động theo IP để bảo vệ hệ thống.

ENDPOINT	GIỚI HẠN	ĐẦU ĐẾM	GHI CHÚ
`/api/*` Tất cả	60 req / phút	IP Address	KV counter, auto-reset 60s
`/api/fuel-prices/province/:slug`	60 req / phút	IP Address	On-demand scraping

Khi vượt giới hạn → HTTP 429 với Retry-After: 60.

JSON — 429 Response

{
  "success": false,
  "error": {
    "code": 429,
    "message": "Too Many Requests — vượt giới hạn 60 req/phút."
  }
}

03 Các Endpoint

Click vào thanh tiêu đề để mở rộng thẻ. Khuyến khích sử dụng /api/fuel-prices để có dữ liệu tổng hợp.

GET /api/fuel-prices Khuyến nghị

Default Endpoint: Gom nhóm giá từ tất cả 11 nguồn, bao gồm 3 mirror Petrolimex, Comeco, SaigonPetro, Petrotimes, GiaXangHomNay và các nguồn quốc gia khác.

JavaScript (Fetch)

const res = await fetch('https://xangdau.nthanhtai.xyz/api/fuel-prices');
const json = await res.json();
console.log(json.data[0].name); // "Xăng RON 95-V"
console.log(json.data[0].sources); // Array chứa giá của các hãng

GET /api/fuel-prices/:source

Lấy giá từ một nguồn cấp cụ thể (ví dụ: petrolimex, pvoil, comeco...).

JavaScript (Fetch)

fetch('https://xangdau.nthanhtai.xyz/api/fuel-prices/comeco')
  .then(res => res.json())
  .then(data => console.log(data));

GET /api/provinces

Lấy danh sách 63 tỉnh thành & mã slug tương ứng để tra cứu từng tỉnh.

Python

import requests
data = requests.get('https://xangdau.nthanhtai.xyz/api/provinces?region=2').json()
print(data)

GET /api/fuel-prices/province/:slug On-demand

Giá xăng dầu chi tiết theo tỉnh thành (ví dụ: ha-noi, ho-chi-minh). Tự động xác định vùng!

JavaScript (Fetch)

// Lấy giá khu vực Hà Nội
const res = await fetch('https://xangdau.nthanhtai.xyz/api/fuel-prices/province/ha-noi');
const data = await res.json();

GET /api/health Health Check

Theo dõi sức khỏe các Scraper và Metadata hệ thống (Uptime).

cURL

curl https://xangdau.nthanhtai.xyz/api/health

GET /api/history Database

Lấy lịch sử biến động giá xăng dầu đã được lưu trong cơ sở dữ liệu.

cURL

curl "https://xangdau.nthanhtai.xyz/api/history?limit=10"

04 Cấu trúc dữ liệu

ĐỐI TƯỢNG META

TRƯỜNG	KIỂU	MÔ TẢ
`primarySource` /api/fuel-prices/:source	String	Nguồn dữ liệu chính
`primarySourceUrl` /api/fuel-prices/:source	String	URL nguồn chính
`dataSources` /api/fuel-prices	String[]	Các nguồn tổng hợp
`sourceCount` /api/fuel-prices	Number	Số nguồn thực tế
`source`	String	Tên nguồn
`sourceUrl`	String	URL nguồn
`scrapedAt`	ISO 8601	Thời điểm thu thập
`priceDate`	YYYY-MM-DD	Ngày niêm yết (ISO)
`priceDateDisplay`	DD/MM/YYYY	Ngày niêm yết (hiển thị)
`cacheHit`	Boolean	Trạng thái cache
`cacheTtlRemainingSeconds`	Number	Thời gian cache còn lại
`totalItems`	Number	Số mặt hàng

ĐỐI TƯỢNG NHIÊN LIỆU (MẢNG DATA)

TRƯỜNG	KIỂU	MÔ TẢ
`name`	String	Tên nhiên liệu
`unit`	String	Đơn vị tính
`sources`	Array	Mảng giá các hãng

ĐỐI TƯỢNG GIÁ TỪNG HÃNG

TRƯỜNG	KIỂU	MÔ TẢ
`source`	String	Tên hãng
`region1`	Number \| null	Giá Vùng 1 (VND)
`region2`	Number \| null	Giá Vùng 2 (VND)
`price`	Number \| null	Giá thống nhất

ĐỐI TƯỢNG TỈNH THÀNH

TRƯỜNG	KIỂU	MÔ TẢ
`id`	String	Mã tỉnh (2 chữ số)
`name`	String	Tên tỉnh thành
`slug`	String	Slug URL
`region`	'1' \| '2'	Vùng giá
`partialRegion`	Boolean?	Tỉnh bán phần
`vung2Districts`	String[]?	Huyện Vùng 2
`note`	String?	Ghi chú

VÍ DỤ RESPONSE

Default Endpoint /api/fuel-prices

{
  "success": true,
  "status": "ok",
  "meta": {
    "primarySource": "Petrolimex",
    "primarySourceUrl": "https://www.petrolimex.com.vn",
    "dataSources": [
      "petrolimex", "kv2_petrolimex", "saigon_petrolimex",
      "vungtau_petrolimex", "pvoil", "mipec", "comeco",
      "saigonpetro", "petrotimes", "webgia", "giaxanghomnay"
    ],
    "scrapedAt": "2026-04-02T06:30:00.000Z",
    "priceDate": "2026-03-27",
    "priceDateDisplay": "27/03/2026",
    "cacheHit": true,
    "cacheTtlRemainingSeconds": 3240,
    "totalItems": 7
  },
  "data": [
    {
      "name": "Xăng RON 95-V",
      "unit": "VND/lít",
      "sources": [
        { "source": "petrolimex", "region1": 24730, "region2": 25220, "price": null },
        { "source": "kv2_petrolimex", "region1": 24730, "region2": 25220, "price": null },
        { "source": "comeco", "region1": 24730, "region2": 25220, "price": null }
      ]
    }
  ]
}

Petrolimex / GiaXangHomNay (Vùng 1 & 2)

{
  "success": true,
  "status": "ok",
  "meta": {
    "source": "Petrolimex",
    "sourceUrl": "https://www.petrolimex.com.vn",
    "scrapedAt": "2026-03-31T16:04:30.000Z",
    "priceDate": "2026-03-27",
    "priceDateDisplay": "27/03/2026",
    "cacheHit": true,
    "cacheTtlRemainingSeconds": 3240,
    "totalItems": 7
  },
  "data": [
    { "name": "Xăng RON 95-V", "region1": 24730, "region2": 25220, "price": null, "unit": "VND/lít" },
    { "name": "Xăng E5 RON 92-II", "region1": 23320, "region2": 23780, "price": null, "unit": "VND/lít" }
  ]
}

PVOil (Giá thống nhất)

{
  "meta": { "source": "PVOil", "totalItems": 5, "..." : "..." },
  "data": [
    { "name": "Xăng RON 95-III", "region1": null, "region2": null, "price": 24330, "unit": "VND/lít" }
  ]
}

Tỉnh thành /api/provinces

{
  "success": true,
  "meta": { "total": 63, "region1Count": 48, "region2Count": 15, "filterApplied": null },
  "data": [
    { "id": "01", "name": "Hà Nội", "slug": "ha-noi", "region": "1" },
    { "id": "91", "name": "Kiên Giang", "slug": "kien-giang", "region": "1",
      "partialRegion": true,
      "vung2Districts": ["Phú Quốc", "Kiên Hải"],
      "note": "TP. Phú Quốc và huyện Kiên Hải thuộc Vùng 2"
    }
  ]
}

05 Phân vùng giá xăng dầu

Theo quy định, giá xăng dầu được chia thành 2 vùng tại Việt Nam:

VÙNG	MÔ TẢ	PHẠM VI
Vùng 1	Gần kho đầu mối. Giá tiêu chuẩn.	48 tỉnh thành
Vùng 2	Vùng sâu, hải đảo. Tối đa +2%.	15 tỉnh + 4 bán phần

4 tỉnh bán phần: Quảng Ninh, Bình Thuận, Bà Rịa-Vũng Tàu, Kiên Giang. Xem /api/provinces để biết chi tiết huyện Vùng 2.

06 Mã lỗi

MÃ HTTP	STATUS KEY	Ý NGHĨA
200	`ok`	Thành công
400	`invalid_source`	Nguồn không hợp lệ
404	`not_found`	Tỉnh thành không tồn tại
429	`rate_limited`	Vượt giới hạn truy cập
502	`scrape_error`	Lỗi scraping tỉnh thành
503	`unavailable`	Dữ liệu chưa sẵn sàng

JSON — Error Response

{
  "success": false,
  "status": "invalid_source",
  "message": {
    "vi": "Nguồn không hợp lệ. Xem danh sách đầy đủ trong availableSources.",
    "en": "Invalid source. See full list in availableSources."
  },
  "availableSources": [
    { "id": "petrolimex", "label": "Petrolimex", "url": "https://www.petrolimex.com.vn" }
  ]
}

01 Base URL

Default Endpoint — Khuyến nghị

DANH SÁCH NGUỒN TÍCH HỢP

02 Rate Limiting

03 Các Endpoint

04 Cấu trúc dữ liệu

ĐỐI TƯỢNG META

ĐỐI TƯỢNG NHIÊN LIỆU (MẢNG DATA)

ĐỐI TƯỢNG GIÁ TỪNG HÃNG

ĐỐI TƯỢNG TỈNH THÀNH

VÍ DỤ RESPONSE

05 Phân vùng giá xăng dầu

06 Mã lỗi

Terminal Demo