DuLieu.dev API

Vietnamese Economic Data — REST API Documentation

DashboardAPI Docs

Authentication

All API requests require an API key. Sign in with Google at /settings to create one.

Plans

Free(Free)— Basic access to Vietnamese economic data
Pro($9/mo)— Full access including grocery price data
Unlimited(Contact us)— No limits — for internal use and partners
FeatureFreeProUnlimited
Economic data (exchange, gold, fuel, coffee...)✓✓✓
Interest rates (40+ banks)✓✓✓
CPI, inflation, economic indicators✓✓✓
Oil & coffee international futures✓✓✓
AI agent daily summary✓✓✓
Grocery prices (40K+ products)—✓✓
COICOP classification & unit pricing—✓✓
CSV export—✓✓
Daily API calls10010,000Unlimited

API Key (Header)

Authorization: Bearer dl_your_api_key_here

API Key (Query)

GET /api/exchange?api_key=dl_your_api_key_here

Rate Limit Headers

X-RateLimit-Plan: free | pro | unlimited
X-RateLimit-Limit: 100 (or "unlimited")
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1714003200

Base URL

https://dulieu.dev

Response Format

{
  "data": [...],
  "meta": {
    "source": "domain.com",
    "count": 42,
    "updated_at": "2026-04-23T14:00:00.000Z"
  }
}

Endpoints

32 endpoints
GET/api/exchange

Currency exchange rates (VND). Sources: Vietcombank, CafeF.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "date": "2026-04-23", "currency": "USD", "buy": 25000, "sell": 25500, "transfer": 25200, "source": "vietcombank.com.vn", "bank": "VCB" }], "meta": { "source": "vietcombank.com.vn", "count": 9, "updated_at": "..." } }
GET/api/gold

Gold prices by type (SJC, rings, jewelry). Sources: DOJI, CafeF.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "date": "2026-04-23", "type": "SJC 1L-10L", "buy_price": 92000000, "sell_price": 94000000, "unit": "tael", "source": "giavang.doji.vn" }], "meta": { "source": "giavang.doji.vn", "count": 8 } }
GET/api/silver

Silver prices (11 types). Source: CafeF.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "date": "2026-04-23", "type": "Bạc miếng SJC", "buy_price": 1200000, "sell_price": 1400000, "unit": "tael" }], "meta": { "source": "cafef.vn" } }
GET/api/weather

Weather data for 70+ Vietnamese cities (all province capitals + tourist destinations).

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)
citystringFilter by city name (partial match)

Response

{ "data": [{ "date": "2026-05-21", "city": "Hà Nội", "temperature": 28.5, "humidity": 65, "conditions": "mây thưa", "geo_location_id": 71 }] }
GET/api/weather/forecast

5-day weather forecast for 70+ Vietnamese cities. Source: OpenWeatherMap.

Query Parameters

datestringFilter by target_date (YYYY-MM-DD)
fromstringStart target_date (YYYY-MM-DD)
tostringEnd target_date (YYYY-MM-DD)
citystringFilter by city name (partial match)

Response

{ "data": [{ "forecast_date": "2026-05-21", "target_date": "2026-05-22", "city": "Đà Nẵng", "temp_min": 26.0, "temp_max": 33.0, "humidity": 70, "conditions": "mây thưa" }] }
GET/api/weather/summary

Today's weather summary for all cities.

Response

{ "data": [{ "city": "Hà Nội", "temperature": 28.5, "temp_unit": "°C", "humidity": 65, "humidity_unit": "%", "conditions": "mây thưa" }] }
GET/api/fuel

Fuel prices (6 types, zone 1 & 2). Source: webgia.com.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "date": "2026-04-23", "fuel_type": "RON 95-V", "zone": 1, "price": 23800 }] }
GET/api/coffee

Coffee prices by region. Source: webgia.com.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "date": "2026-04-23", "region": "Đắk Lắk", "price": 125000, "unit": "VND/kg" }] }
GET/api/interest

Bank deposit & lending rates (28+ banks, 8 terms). Sources: webgia, VCB, BIDV, CafeF.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "date": "2026-04-23", "bank": "Vietcombank", "term_months": 12, "deposit_rate": 4.7, "lending_rate": null }] }
GET/api/indicators

Economic indicators (CPI, inflation, IIP). Source: nso.gov.vn.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "indicator": "CPI", "value": 103.2, "period": "2026-03", "yoy_change": 3.2 }] }
GET/api/lottery

Vietnam lottery results (north/central/south, 41 provinces). Sources: CafeF + Minh Ngọc.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)
sourcestringFilter by source (cafef.vn or minhngoc.net.vn)

Response

{ "data": [{ "date": "2026-04-23", "region": "south", "province": "TP.HCM", "prize": "Giải Đặc biệt", "numbers": "123456" }] }
GET/api/pepper

Pepper prices — domestic (5 regions) + international (India Kochi). Source: giatieu.com.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)

Response

{ "data": [{ "date": "2026-05-20", "region": "Đắk Lắk", "price": 148000, "unit": "VND/kg" }] }
GET/api/commodities

All commodity prices — crude oil (WTI, Brent), international coffee futures.

Query Parameters

datestringSingle date (YYYY-MM-DD)
fromstringStart date (YYYY-MM-DD)
tostringEnd date (YYYY-MM-DD)
symbolstringFilter by symbol (e.g. WTI, BRENT, ROBUSTA)

Response

{ "data": [{ "date": "2026-05-20", "symbol": "WTI", "name": "WTI Crude Oil", "price": 72.50, "unit": "USD/barrel" }] }
GET/api/groceries

Grocery prices (56K+ products, COICOP classified, unit pricing). Pro plan required.

Query Parameters

storestringFilter by store (e.g. lottemart, cooponline)
categorystringFilter by category
limitnumberMax results (default: 500)

Response

{ "data": [{ "store": "lottemart", "name": "Sữa TH True Milk 1L", "price": 32000, "coicop": "01.1.4", "unit_price_per_l": 32000 }] }
GET/api/groceries/summary

Grocery category averages with COICOP codes. Pro plan required.

Response

{ "data": [{ "category": "Sữa", "coicop": "01.1.4", "products": 450, "avg_price": 85000, "stores": 4 }] }
GET/api/groceries/stores

Store product counts and latest crawl dates.

Response

{ "data": [{ "store": "lottemart", "products": 26610, "latest_date": "2026-05-20" }] }
GET/api/drugs

Drug & pharmacy prices (12K+ products, COICOP 06 classified). Pharmacity, Long Chau.

Query Parameters

storestringFilter by store (pharmacity, longchau)
limitnumberMax results (default: 500)

Response

{ "data": [{ "store": "pharmacity", "name": "Panadol Extra", "price": 52000, "is_drug": 1, "is_prescription": 0, "coicop": "06.1.1" }] }
GET/api/drugs/summary

Drug category averages with COICOP 06 codes and drug/Rx counts.

Response

{ "data": [{ "category": "Thuốc", "coicop": "06.1.1", "products": 5431, "drugs": 5431, "prescription": 4309 }] }
GET/api/drugs/stores

Pharmacy product counts and latest crawl dates.

Response

{ "data": [{ "store": "pharmacity", "products": 7610, "latest_date": "2026-05-20" }] }
GET/api/geo

Vietnamese administrative geography (provinces, districts, wards).

Query Parameters

provincestringProvince code or name (partial match)

Response

{ "data": [{ "province_code": "79", "province_name": "TP. Hồ Chí Minh", "district_code": null }] }
GET/api/summary

Daily summary of all data domains. Ideal for AI agent daily briefing.

Response

{ "date": "2026-05-20", "last_crawl": "...", "exchange": [...], "gold": [...], "weather": [...], "fuel": [...], "coffee": [...], "interest": [...], "indicators": [...] }
GET/api/stats

API usage statistics — by key, by user, by endpoint, by day. Admin only.

Query Parameters

daysnumberLookback period (default: 7)

Response

{ "overview": { "total": 1234, "unique_keys": 5 }, "by_key": [...], "by_user": [...], "by_endpoint": [...] }
GET/api/crawl-logs

Crawler execution history.

Query Parameters

limitnumberMax results (default: 20)

Response

{ "data": [{ "crawler": "exchange-vietcombank", "status": "success", "records_inserted": 9, "duration_ms": 1200 }] }
GET/api/electronics

Electronics prices from 5 major Vietnamese retailers (TGDD, CellphoneS, FPT Shop, Hoang Ha Mobile, Di Dong Viet). 80K+ products with ratings, reviews, variants.

Query Parameters

storestringFilter by store (thegioididong, cellphones, fptshop, hoanghamobile, didongviet)
brandstringFilter by brand
categorystringFilter by category (partial match)
limitnumberMax results (default: 500)

Response

{ "data": [{ "store": "thegioididong", "name": "iPhone 15 Pro Max", "price": 29990000, "brand": "Apple", "rating": 4.5, "in_stock": 1 }] }
GET/api/electronics/summary

Electronics store-level summary — product counts, avg prices, brand/category diversity, ratings.

Response

{ "data": [{ "store": "thegioididong", "products": 9000, "avg_price": 8500000, "categories": 15, "brands": 120, "avg_rating": 4.2 }] }
GET/api/electronics/stores

Electronics store product counts and latest crawl dates.

Response

{ "data": [{ "store": "cellphones", "products": 58000, "crawl_days": 15, "latest_date": "2026-05-20" }] }
GET/api/provinces/summary

Vietnam 2025 province/ward merge summary. 63 → 34 provinces, 3,321 wards. Before/after metrics: Population, Area, Density, GRDP, Budget.

Response

{ "slug": "vn-2025-province-merge", "total_before": 63, "total_after": 34, "metrics": [...], "before": {...}, "after": {...} }
GET/api/provinces/map

Province GeoJSON with merge metadata. Returns Leaflet-ready GeoJSON + per-province metrics for choropleth coloring.

Response

{ "data": [{ "id": "An Giang", "name": "An Giang", "merged_from": "...", "metrics": {...} }], "geoJSON": {...}, "metricExtents": {...} }
GET/api/provinces/wards

Search merged wards (3,321 total). Supports search, province filter, pagination.

Query Parameters

qstringSearch by ward name (new or old)
provincestringFilter by province name (exact)
per_pagenumberResults per page (default: 50, max: 5000)

Response

{ "data": [{ "new_name": "Phường 1", "province": "TP HCM", "old_names": "Phường 1, Phường 2" }], "meta": { "total_wards": 3321 } }
GET/api/blog

Editorial blog posts (AI-generated posts are flagged via ai_generated and always cite sources). Newest first.

Query Parameters

categorystringFilter by category slug (e.g. tin-kinh-te)
limitnumberMax results (default: 50, max: 200)

Response

{ "data": [{ "slug": "...", "title": "...", "summary": "...", "ai_generated": true, "cadence": "daily", "category": "tin-kinh-te", "published_at": "..." }], "meta": { "count": 12, "updated_at": "..." } }
GET/api/blog/categories

Blog categories with publish cadence (daily/weekly/monthly/quarterly/biannual/annual) and post counts.

Response

{ "data": [{ "slug": "tin-kinh-te", "name_vi": "Tin Kinh Tế Hàng Ngày", "cadence": "daily", "post_count": 12 }] }
GET/api/blog/:slug

Single blog post including markdown body and source attributions (source_refs).

Response

{ "data": { "slug": "...", "title": "...", "body_md": "...", "ai_generated": true, "ai_model": "...", "source_refs": [{ "title": "...", "url": "...", "source": "vnexpress" }], "cadence": "daily" } }

API Key Management

GET/api/keys

List your API keys. Requires authentication (session cookie).

Response

{ "data": [{ "id": "uuid", "name": "my-agent", "key_prefix": "dl_a1b2c3d4", "created_at": "..." }] }
POST/api/keys

Create a new API key. The raw key is only shown once.

Query Parameters

namestringLabel for this key (required)

Response

{ "data": { "id": "uuid", "name": "my-agent", "key_prefix": "dl_a1b2c3d4", "key": "dl_a1b2c3d4e5f6..." } }
POST/api/keys/:id/rotate

Rotate an API key — generates a new secret while keeping the same ID. All usage stats are preserved.

Response

{ "data": { "id": "uuid", "name": "my-agent", "key_prefix": "dl_e7f8g9h0", "key": "dl_e7f8g9h0i1j2..." } }
GET/api/keys/stats

Your API usage stats — overview, per-key breakdown, top endpoints (30d).

Query Parameters

daysnumberLookback period (default: 30)

Response

{ "data": { "overview": { "total_calls": 450, "avg_ms": 12, "keys_count": 2 }, "by_key": [...], "by_endpoint": [...] } }
DELETE/api/keys/:id

Revoke an API key. Cannot be undone.

Response

{ "data": { "revoked": true } }

Admin Endpoints

Require session cookie from a user with role=admin.

GET/api/admin/users

List all users with their roles and plans.

Response

{ "data": [{ "user_id": "...", "role": "admin", "plan": "unlimited", "email": "...", "name": "..." }] }
PUT/api/admin/users/:id/plan

Set a user's plan. Only admins can change plans.

Query Parameters

planstringOne of: free, pro, unlimited (in JSON body)

Response

{ "data": { "user_id": "...", "plan": "pro" } }

Quick Start (for LLMs / Agents)

# 1. Sign in at /settings and create an API key
# 2. Use the key in all requests:

# Get today's summary (best for daily briefing)
curl -H "Authorization: Bearer dl_YOUR_KEY" https://dulieu.dev/api/summary

# Get exchange rates for a date range
curl -H "Authorization: Bearer dl_YOUR_KEY" "https://dulieu.dev/api/exchange?from=2026-05-01&to=2026-05-20"

# Or use query parameter
curl "https://dulieu.dev/api/gold?date=2026-05-20&api_key=dl_YOUR_KEY"

# Free plan: 100 calls/day. Upgrade to Pro for grocery data + higher limits.