# DuLieu.dev — Vietnamese Economic Data API

> Daily-updated Vietnamese economic data: exchange rates, gold, silver, fuel, coffee, pepper, interest rates, crude oil, grocery prices (56K+ products), drug & pharmacy prices (12K+ products), electronics prices (80K+ products, 5 retailers), weather (70+ cities), forecasts, lottery (41 provinces), CPI. 41 crawlers, 40+ banks, COICOP classification.

## API Access

Base URL: https://dulieu.dev
Authentication: API key required (Bearer token or ?api_key= query param)
Get your key: https://dulieu.dev/settings (Google sign-in)
MCP monolithic: https://dulieu.dev/mcp (all 15 tools, Bearer or opaque URL)
MCP sub-servers:
  - https://dulieu.dev/mcp/dulieu-finance — exchange_rates, gold, silver, interest_rates, commodities (5 tools)
  - https://dulieu.dev/mcp/dulieu-weather — weather, weather_forecast (2 tools)
  - https://dulieu.dev/mcp/dulieu-retail — fuel, coffee, pepper, groceries, drugs, electronics (6 tools)
  - https://dulieu.dev/mcp/dulieu-reference — daily_summary, provinces_merge (2 tools)
  Each sub-server exposes a focused tool set to reduce context window usage.

## Quick Start

```
curl -H "Authorization: Bearer dl_YOUR_KEY" https://dulieu.dev/api/summary
```

## Endpoints (Free Plan — 100 calls/day)

- GET /api/summary — Daily briefing of all data (best for AI agents)
- GET /api/exchange — Currency exchange rates (20 currencies, VND)
- GET /api/gold — Gold prices (SJC, DOJI, 8+ types)
- GET /api/silver — Silver prices (11 types)
- GET /api/fuel — Fuel prices (6 types, 2 zones)
- GET /api/coffee — Domestic coffee prices (4 regions)
- GET /api/pepper — Pepper prices (domestic 5 regions + international India Kochi)
- GET /api/interest — Bank interest rates (40+ banks, 8 terms)
- GET /api/commodities — All commodity prices (crude oil, coffee futures)
- GET /api/indicators — Economic indicators (CPI, inflation, IIP)
- GET /api/weather — Weather for 70+ cities (all province capitals + tourist destinations)
- GET /api/weather/forecast — 5-day weather forecast for 70+ cities
- GET /api/weather/summary — Today's weather summary for all cities
- GET /api/lottery — Lottery results (north/central/south, 41 provinces, 2 sources). Supports ?source=cafef.vn|minhngoc.net.vn
- GET /api/geo — Vietnamese administrative geography
- GET /api/plans — Available plans and features
- GET /api/electronics — Electronics prices (5 retailers: TGDD, CellphoneS, FPT Shop, Hoang Ha Mobile, Di Dong Viet)
- GET /api/electronics/summary — Store-level summary with avg prices, brands, ratings
- GET /api/electronics/stores — Store product counts
- GET /api/provinces/summary — Vietnam 2025 province merge (63 → 34 provinces, 3,321 wards, 5 metrics)
- GET /api/provinces/map — Province GeoJSON with merge metadata + metric-based choropleth coloring
- GET /api/provinces/wards — Search merged wards (3,321 total, full-text search, province filter, pagination)
- GET /api/blog — Editorial blog posts (AI-generated posts flagged + always cite sources). ?category= slug, ?limit=
- GET /api/blog/categories — Blog categories with publish cadence (daily→annual) and post counts
- GET /api/blog/:slug — Single post with markdown body + source attributions
- GET /blog/rss.xml — Blog RSS feed (summary). Also /blog/rss-full.xml (full content:encoded)
- GET /blog/category/:slug/rss.xml — Per-category RSS (and /rss-full.xml variant)

## Endpoints (Pro Plan — $9/mo, 10K calls/day)

- GET /api/groceries — Grocery prices (56K+ products, COICOP classified, unit pricing)
- GET /api/groceries/summary — Category averages with COICOP codes
- GET /api/groceries/stores — Store product counts (6 stores)
- GET /api/drugs — Drug & pharmacy prices (12K+ products, COICOP 06 classified)
- GET /api/drugs/summary — Drug category averages with drug/Rx counts
- GET /api/drugs/stores — Pharmacy product counts

## API Key Management (session auth required)

- GET /api/keys — List your API keys
- POST /api/keys — Create a new key (body: {"name": "..."})
- POST /api/keys/:id/rotate — Rotate key (new secret, same ID, stats preserved)
- GET /api/keys/stats — Your usage stats (overview, per-key, top endpoints)
- DELETE /api/keys/:id — Revoke a key

## Admin Endpoints

- GET /api/stats — Global API usage stats (by key, user, endpoint, day)
- GET /api/stats/recent — Recent raw request logs
- GET /api/crawl-logs — Crawler execution history

## Query Parameters

All data endpoints accept date filters:
- ?date=2026-05-20 — single date
- ?from=2026-05-01&to=2026-05-20 — date range
- ?previous=7 — last N days

## Response Format

```json
{
  "source": "dulieu.dev",
  "data": [...],
  "meta": {
    "source": "domain.com",
    "count": 42,
    "updated_at": "2026-05-20T06:00:00.000Z"
  }
}
```

## Rate Limits

- Free: 100 calls/day
- Pro: 10,000 calls/day
- Unlimited: no limits (contact us)

Headers: X-RateLimit-Plan, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

## Data Sources

Exchange rates: Vietcombank, CafeF (20 currencies)
Gold: DOJI, CafeF, Webgia, VnExpress (SJC, PNJ, branded)
Silver: CafeF (11 domestic types + world)
Interest rates: Webgia, VCB, BIDV, Sacombank, VPBank, CafeF, VnExpress (40+ banks)
Fuel: Webgia, VnExpress
Coffee: Webgia, giacaphe.com, ICE London, ICE NY, B3 Brazil
Pepper: giatieu.com (domestic 5 regions + India Kochi)
Oil: Stooq (WTI, Brent)
Weather: OpenWeatherMap
Indicators: GSO (nso.gov.vn)
Groceries: Lottemart, Cooponline, MM Vietnam, King Food Mart, Bach Hoa Xanh, Sieuthi Go
Drugs: Pharmacity, Long Chau (Nha Thuoc Long Chau)
Electronics: The Gioi Di Dong, CellphoneS, FPT Shop, Hoang Ha Mobile, Di Dong Viet

## Dedicated Pages

- Dashboard: https://dulieu.dev/
- API docs: https://dulieu.dev/api/docs
- Groceries: https://dulieu.dev/groceries
- Drugs: https://dulieu.dev/drugs
- Banks: https://dulieu.dev/banks
- Provinces: https://dulieu.dev/tinh-thanh
- Settings: https://dulieu.dev/settings
- About: https://dulieu.dev/page/about