Tài liệu API

API REFERENCE

Toàn bộ endpoint, cấu trúc dữ liệu và hướng dẫn tích hợp VietFuelAPI.

01 Base URL

HTTP
http://localhost:3000

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('http://localhost:3000/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('http://localhost:3000/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
petrolimexPetrolimexhttps://www.petrolimex.com.vn
kv2_petrolimexPetrolimex KV2https://kv2.petrolimex.com.vn
saigon_petrolimexPetrolimex SAI GONhttps://saigon.petrolimex.com.vn
vungtau_petrolimexPetrolimex VUNG TAUhttps://vungtau.petrolimex.com.vn
pvoilPVOilhttps://www.pvoil.com.vn
mipecMipechttps://www.mipec.com.vn/pages/gia-xang-dau-ban-le
comecoCOMECOhttps://comeco.vn
saigonpetroSaigon Petrohttps://saigonpetro.com.vn/ban-le-xang-dau
petrotimesPetro Timeshttps://petrotimesgroup.com
webgiaWebGia (Mirror)https://webgia.com/gia-xang-dau/petrolimex/
giaxanghomnayGiaXangHomNayhttps://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.

NHÓM ENDPOINT GIỚI HẠN GHI CHÚ
/api/fuel-prices Default 60 req / phút Default, cache RAM
/api/fuel-prices, /api/fuel-prices/:source, /api/provinces, /api/health 60 req / phút Cache RAM, độ trễ thấp
/api/fuel-prices/province/:slug 20 req / phút On-demand scraping, cache thích ứng

Khi vượt giới hạn, API trả về HTTP 429 với thông báo lỗi.

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.

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('http://localhost:3000/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

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

JavaScript (Fetch)
fetch('http://localhost:3000/api/fuel-prices/comeco')
  .then(res => res.json())
  .then(data => console.log(data));

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('http://localhost:3000/api/provinces?region=2').json()
print(data)

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('http://localhost:3000/api/fuel-prices/province/ha-noi');
const data = await res.json();

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

cURL
curl http://localhost:3000/api/health

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

ĐỐI TƯỢNG META

TRƯỜNG KIỂU MÔ TẢ
primarySource /api/fuel-prices/:sourceStringNguồn dữ liệu chính
primarySourceUrl /api/fuel-prices/:sourceStringURL nguồn chính
dataSources /api/fuel-pricesString[]Các nguồn tổng hợp
sourceStringTên nguồn
sourceUrlStringURL nguồn
scrapedAtISO 8601Thời điểm thu thập
priceDateYYYY-MM-DDNgày niêm yết (ISO)
priceDateDisplayDD/MM/YYYYNgày niêm yết (hiển thị)
cacheHitBooleanTrạng thái cache
cacheTtlRemainingSecondsNumberThời gian cache còn lại
totalItemsNumberSố mặt hàng

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

TRƯỜNG KIỂU MÔ TẢ
nameStringTên nhiên liệu
unitStringĐơn vị tính
sourcesArrayMảng giá các hãng

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

TRƯỜNG KIỂU MÔ TẢ
sourceStringTên hãng
region1Number | nullGiá Vùng 1 (VND)
region2Number | nullGiá Vùng 2 (VND)
priceNumber | nullGiá thống nhất

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

TRƯỜNG KIỂU MÔ TẢ
idStringMã tỉnh (2 chữ số)
nameStringTên tỉnh thành
slugStringSlug URL
region'1' | '2'Vùng giá
partialRegionBoolean?Tỉnh bán phần
vung2DistrictsString[]?Huyện Vùng 2
noteString?Ghi chú

VÍ DỤ RESPONSE

{
  "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 }
      ]
    }
  ]
}
{
  "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" }
  ]
}
{
  "meta": { "source": "PVOil", "totalItems": 5, "..." : "..." },
  "data": [
    { "name": "Xăng RON 95-III", "region1": null, "region2": null, "price": 24330, "unit": "VND/lít" }
  ]
}
{
  "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" }
  ]
}
Mô phỏng tương tác

Terminal Demo

Xem thao tác gọi API thực tế — từ health check đến lấy giá tỉnh thành.

bash — VietFuelAPI Terminal
$█
Đang khởi động...