Vietnamese date parser API

Turn Vietnamese date and time expressions into ISO: “thứ 2 tuần sau”, “8h tối nay”, “cuối tháng này”, “mùng 5 Tết”, “15/8 âm lịch”, in Vietnam time.

GETPOSThttps://apibox.io.vn/v1/vn-date-parse

Text▶ Try it online

The parser reads the date and time expressions people type in Vietnamese chats and forms, with or without accents, and resolves them against a reference time (ref, default now in Asia/Ho_Chi_Minh): relative days (hôm nay, ngày mai, ngày kia, hôm qua), offsets (3 ngày nữa, 2 tiếng nữa, cách đây 2 tháng), weekdays with week modifiers (thứ 2 tuần sau, t6 này, chủ nhật tuần trước, thứ 6 tới), periods (tuần sau, cuối tháng này, đầu năm sau, tháng 8), explicit dates (20/11, ngày 15 tháng 8 năm 2027, mùng 2 tháng 9) and times (8h, 8h30, 8 giờ rưỡi, 9 giờ kém 15, 3h chiều, 8h tối).

Lunar dates use the Vietnamese lunar calendar (UTC+7): 15/8 âm lịch, rằm tháng 7, mùng 5 Tết, 28 Tết, giao thừa, plus holidays such as Trung thu, Vu Lan, Giỗ Tổ, Noel or Quốc khánh. The answer has a type (date, datetime or range with start and end), the ISO date and date-time with the +07:00 offset, the weekday, the lunar date of the result and the words that were matched. Without a year, the next occurrence is chosen (prefer=past or nearest to change it).

Works on whole sentences (“đặt bàn 7h tối thứ 7 này nhé”); texts handles up to 500 strings. Expressions it does not understand return found: false rather than a guess.

Parameters

Name	In	Type	Required	Default
`text`	query\|body	string	yes		The expression or sentence (max 500 characters).
`ref`	query\|body	string	no		Reference time, ISO (`2026-11-11` or `2026-11-11T09:30`, Vietnam time unless an offset is given). Default: now.
`prefer`	query\|body	string	no	`future`	`future`, `past` or `nearest` when the year or week is not written.
`texts`	body	array	no		Up to 500 strings (batch).

Example

curl "https://apibox.io.vn/v1/vn-date-parse?text=th%E1%BB%A9%202%20tu%E1%BA%A7n%20sau%209h%20s%C3%A1ng&ref=2026-11-11T09:30" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-date-parse?text=th%E1%BB%A9%202%20tu%E1%BA%A7n%20sau%209h%20s%C3%A1ng&ref=2026-11-11T09:30', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-date-parse?text=th%E1%BB%A9%202%20tu%E1%BA%A7n%20sau%209h%20s%C3%A1ng&ref=2026-11-11T09:30",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-date-parse?text=th%E1%BB%A9%202%20tu%E1%BA%A7n%20sau%209h%20s%C3%A1ng&ref=2026-11-11T09:30');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "ref": "2026-11-11T09:30:00+07:00",
  "timezone": "Asia/Ho_Chi_Minh",
  "prefer": "future",
  "text": "thứ 2 tuần sau 9h sáng",
  "found": true,
  "type": "datetime",
  "date": "2026-11-16",
  "time": "09:00",
  "datetime": "2026-11-16T09:00:00+07:00",
  "part_of_day": "morning",
  "weekday": "Monday",
  "weekday_vi": "Thứ Hai",
  "calendar": "solar",
  "lunar": {
    "day": 8,
    "month": 10,
    "year": 2026,
    "leap": false,
    "text": "08/10/2026"
  },
  "holiday": null,
  "matched": [
    "sáng",
    "thứ 2 tuần sau",
    "9h"
  ],
  "notes": []
}

Use cases

Book appointments from chatbot messages (spa, clinic, restaurant)
Turn notes such as “gọi lại thứ 6 tuần sau” into CRM reminders
Fill date fields from voice assistants
Resolve lunar dates for festivals and memorial days

FAQ

Which week does “tuần sau” mean?

Weeks run Monday to Sunday. “Thứ 2 tuần sau” is the Monday of the next week; “thứ 6 tới” is the next Friday after today.

How is the year chosen?

When no year is written, the next occurrence on or after the reference date (prefer=future). Use prefer=past for past events or nearest.

Does it handle text without accents?

Yes: “thu 2 tuan sau”, “toi nay 8h” work; ambiguous words such as “tôi” (I) versus “tối” (evening) are checked against the accents when present.

Vietnamese date parser API

Parameters

Example

Response

Use cases

FAQ

Related APIs

Text Diff

Slugify

Text Statistics