Vietnamese Sort & Collation API

Q: Why not sort in the database?

Many databases (SQLite / D1, default MongoDB, binary collations) sort by code point, which puts Đ after Z and accented letters at the end. Store the sort_key from action=key to sort correctly anywhere.

Q: What is the tone order?

ngang, huyền, hỏi, ngã, sắc, nặng: the order used by Vietnamese dictionaries and the CLDR / ICU Vietnamese collation (ba, bà, bả, bã, bá, bạ).

Q: Are "hoà" and "hòa" the same?

Yes: tones are compared per syllable, so both tone placements sort and compare equal; action=normalize rewrites them in one style.

Sort Vietnamese lists in dictionary order (a ă â, d đ, tones), compare strings, make DB sort keys, group by letter, sort names by given name.

GETPOSThttps://apibox.io.vn/v1/vn-sort

Text▶ Try it online

Send a list (items, or one item per line in text) and get it sorted in Vietnamese dictionary order: the letters a ă â b c d đ e ê g h i k l m n o ô ơ p q r s t u ư v x y, then the tones ngang < huyền < hỏi < ngã < sắc < nặng, then case: the same order as Vietnamese dictionaries and the CLDR "vi" collation, unlike the byte order of databases (where "Đ" sorts after "Z") or the long-standing glibc vi_VN bugs. Tones are compared per syllable, so "hoà" and "hòa" are equal; numbers sort naturally (item 9 before item 10); ignore_tones compares letters only; case_sensitive, desc and unique are available.

by=given_name sorts personal names the way Vietnamese class and staff lists do (given name, then family name, then middle name: An before Bình whatever the family name); objects are sorted by a field. Other actions: compare (a, b → -1 / 0 / 1), key (a byte-sortable sort_key to store in a database column with binary collation, and an accent-free search_key), group (by first letter, Đ separate from D, for contact lists) and normalize (tone mark placement old / new style: hòa ↔ hoà, thúy ↔ thuý).

Up to 10,000 items per request; pure computation, nothing stored.

Parameters

Name	In	Type	Required	Default
`items`	body	array	no		Strings (or objects with `field`) to sort, max 10,000. Or `text`: one item per line.
`action`	body\|query	string	no	`sort`	`sort`, `compare` (with `a`, `b`), `key`, `group` or `normalize`.
`by`	body\|query	string	no	`full`	`full`, `given_name` (Tên rồi Họ) or `family_name` for personal names.
`ignore_tones`	body\|query	boolean	no	`false`	Compare letters only (bá = ba).
`numeric`	body\|query	boolean	no	`true`	Natural order of numbers (2 before 10).
`field`	body\|query	string	no		Property to sort by when items are objects.
`desc`	body\|query	boolean	no	`false`	Descending order. Also `case_sensitive`, `unique`; `tone_style` old / new for normalize.

Example

curl -X POST "https://apibox.io.vn/v1/vn-sort" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":["Đức","Dũng","anh","ăn","An","bà","ba","bá","item 10","item 9"]}'

const res = await fetch('https://apibox.io.vn/v1/vn-sort', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "items": [
      "Đức",
      "Dũng",
      "anh",
      "ăn",
      "An",
      "bà",
      "ba",
      "bá",
      "item 10",
      "item 9"
    ]
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/vn-sort",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"items": ["Đức", "Dũng", "anh", "ăn", "An", "bà", "ba", "bá", "item 10", "item 9"]},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-sort');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"items":["Đức","Dũng","anh","ăn","An","bà","ba","bá","item 10","item 9"]}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "count": 10,
  "sorted": [
    "An",
    "anh",
    "ăn",
    "ba",
    "bà",
    "bá",
    "Dũng",
    "Đức",
    "item 9",
    "item 10"
  ],
  "options": {
    "tones": true,
    "caseSensitive": false,
    "numeric": true,
    "by": "full"
  },
  "collation": "Vietnamese alphabet a ă â b c d đ e ê g h i k l m n o ô ơ p q r s t u ư v x y; tones ngang < huyền < hỏi < ngã < sắc < nặng"
}

Use cases

Sort customer or product names correctly in apps backed by SQLite, D1 or MongoDB
Print class lists ordered by given name
Store sort and search keys for Vietnamese text in a database
Build A–Z contact indexes with Đ as its own letter

FAQ

Why not sort in the database?

Many databases (SQLite / D1, default MongoDB, binary collations) sort by code point, which puts Đ after Z and accented letters at the end. Store the sort_key from action=key to sort correctly anywhere.

What is the tone order?

ngang, huyền, hỏi, ngã, sắc, nặng: the order used by Vietnamese dictionaries and the CLDR / ICU Vietnamese collation (ba, bà, bả, bã, bá, bạ).

Are "hoà" and "hòa" the same?

Yes: tones are compared per syllable, so both tone placements sort and compare equal; action=normalize rewrites them in one style.

Vietnamese Sort & Collation API

Parameters

Example

Response

Use cases

FAQ

Related APIs

Text Diff

Slugify

Text Statistics