Text Match Ranking — rank strings by distance

Best Match Text Search API

Hosted on ApyHub

What it does

Text Match Ranking compares a source string against a list of candidate strings and returns them ordered by Levenshtein distance. Send a source, a candidates array, and an optional limit; get back a data array of matches with their distance values.

Use it when you need to find the closest spelling, product name, or user-entered value without building your own fuzzy matching logic. The response is straightforward: each item includes the matched string and its edit distance from the source, so you can rank, filter, or display the best options in your app.

Because the service works on plain strings, it fits deduplication workflows, search suggestions, typo correction, and lightweight record linking. If you are normalizing incoming text or comparing one value against a short candidate list, Text Match Ranking gives you the nearest matches in a format that is easy to sort and consume.

Quickstart

Rank a list of candidate strings by how closely they match a source string.

curl -X POST "http://localhost:8080/apyhub/best-match-text-search" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "apple",
    "candidates": ["ape", "applet", "banana", "apply"]
  }'

What you'll get back

Returns a JSON object with a data array. Each item in data is an object with match as a string and distance as an integer, where distance is the Levenshtein distance from the source.

{
  "data": [
    { "match": "applet", "distance": 1 },
    { "match": "apply", "distance": 2 },
    { "match": "ape", "distance": 2 }
  ]
}

About this endpoint

What it does

Ranks the provided candidate strings against a source string and returns the matches ordered by closeness. You send the source plus one or more candidates, and the response returns the ranked matches with their distances.

Request Body

Parameter	Type	Mandatory	Description
source	String	Yes	The reference string to match against.
candidates	String Array	Yes	Candidate strings to rank.
limit	Integer	No	Max results to return. `0` means all. Minimum `0`.

Response

Returns a JSON object with a data array field. Each item in data is an object with a match string and a distance integer, where distance is the Levenshtein distance from the source.

Parameter	Type	Mandatory	Description
data	Object Array	Yes	Ranked match results. Each item contains `match` and `distance`.
data[].match	String	Yes	The matching candidate string.
data[].distance	Integer	Yes	Levenshtein distance from the source.

Body

Name

Type

Description

bodyREQUIRED

object

—

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Body

Errors any endpoint can return