Fuzzy Match & Dedupe API

Compare strings (Levenshtein, Jaro-Winkler, token set, trigram), find the best matches in a list and cluster duplicates, with Vietnamese accent folding.

GETPOSThttps://apibox.io.vn/v1/fuzzy-match

Text▶ Try it online

Three modes. compare (a, b) returns every score between 0 and 1: normalised Levenshtein, Jaro-Winkler, token sort and token set ratio (as rapidfuzz), trigram similarity (as PostgreSQL pg_trgm) and combined, their mean, plus the edit distance. search (query, choices up to 10,000) returns the best matches above threshold with their index. dedupe (items up to 5,000) groups near-duplicates into clusters with a representative and returns the deduplicated list; pairs are blocked by shared trigrams, so large lists stay fast.

Before comparing, strings are normalised: case and Vietnamese accents are folded (Nguyễn = nguyen, đ = d), punctuation becomes spaces and common Vietnamese abbreviations are expanded (TP. = thành phố, Q. = quận, P. = phường, Cty = công ty, CP = cổ phần, TM = thương mại, HCM = Hồ Chí Minh…). Turn these off with keep_accents, case_sensitive and abbreviations=false, and drop noise words with ignore (for example "tnhh, cong ty").

Choose the score with algorithm: token_set for names whose word order or extra words vary (company names, product titles), jaro_winkler for short strings and typos at the end, levenshtein for codes, trigram for long texts. Nothing is stored.

Parameters

Name	In	Type	Required	Default
`mode`	body\|query	string	no		`compare`, `search` or `dedupe` (guessed from the parameters when absent).
`a`	body\|query	string	no		compare: first string.
`b`	body\|query	string	no		compare: second string.
`query`	body\|query	string	no		search: the string to look for.
`choices`	body	array	no		search: list of candidates (JSON array or one per line), up to 10,000.
`items`	body	array	no		dedupe: list to cluster (JSON array or one per line), up to 5,000.
`algorithm`	body\|query	string	no	`combined`	`combined`, `levenshtein`, `jaro_winkler`, `token_sort`, `token_set` or `trigram` (search and dedupe).
`threshold`	body\|query	number	no		Minimum score 0-1: 0.5 for search, 0.85 for dedupe by default.
`limit`	body\|query	number	no	`10`	search: number of matches returned (1-1000).
`keep_accents`	body\|query	boolean	no	`false`	Compare with Vietnamese accents (no folding).
`case_sensitive`	body\|query	boolean	no	`false`	Upper and lower case differ.
`abbreviations`	body\|query	boolean	no	`true`	Expand Vietnamese abbreviations (TP., Q., P., Cty, CP, TM…).
`ignore`	body\|query	array	no		Words to drop before comparing, e.g. ["tnhh", "cong ty"].

Example

curl -X POST "https://apibox.io.vn/v1/fuzzy-match" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"a":"Cty TNHH Thương mại ABC, Q.1, TP.HCM","b":"Công ty TNHH TM ABC Quận 1 Hồ Chí Minh"}'

const res = await fetch('https://apibox.io.vn/v1/fuzzy-match', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "a": "Cty TNHH Thương mại ABC, Q.1, TP.HCM",
    "b": "Công ty TNHH TM ABC Quận 1 Hồ Chí Minh"
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/fuzzy-match",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"a": "Cty TNHH Thương mại ABC, Q.1, TP.HCM", "b": "Công ty TNHH TM ABC Quận 1 Hồ Chí Minh"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/fuzzy-match');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"a":"Cty TNHH Thương mại ABC, Q.1, TP.HCM","b":"Công ty TNHH TM ABC Quận 1 Hồ Chí Minh"}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "mode": "compare",
  "a": "Cty TNHH Thương mại ABC, Q.1, TP.HCM",
  "b": "Công ty TNHH TM ABC Quận 1 Hồ Chí Minh",
  "normalized_a": "cong ty tnhh thuong mai abc quan 1 thanh pho ho chi minh",
  "normalized_b": "cong ty tnhh thuong mai abc quan 1 ho chi minh",
  "levenshtein_distance": 10,
  "jaro": 0.9151,
  "indel_ratio": 0.902,
  "scores": {
    "combined": 0.9107,
    "levenshtein": 0.8214,
    "jaro_winkler": 0.9491,
    "token_sort": 0.902,
    "token_set": 1,
    "trigram": 0.8723
  },
  "options": {
    "algorithm": "combined",
    "accent_insensitive": true,
    "case_insensitive": true,
    "abbreviations": true,
    "ignore": []
  }
}

Use cases

Deduplicate customer or supplier names in a CRM import
Match product titles between marketplaces (Shopee, Lazada, Tiki)
Find the closest province, bank or partner name from user input
Reconcile payee names on bank statements with invoices

FAQ

Which score should I use?

combined is a good default. token_set ignores word order and extra words, jaro_winkler favours common prefixes, levenshtein counts edits, trigram suits longer texts.

Are Vietnamese accents ignored?

Yes by default, together with case and punctuation; set keep_accents=true when "Hà" and "Ha" must differ.

How large can the lists be?

search accepts 10,000 choices, dedupe 5,000 items of up to 1,000 characters each.

Fuzzy Match & Dedupe API

Parameters

Example

Response

Use cases

FAQ

Related APIs

Text Diff

Slugify

Text Statistics