Understanding Fuzzy Search

TomTom maps return useful results even if you misspell a search term or provide incomplete address information. In this article we'll explain how the TomTom Search API provides "fuzzy search" results for points of interest through spell-checking, nearby search options, geometric boundary searches, route searches and more.

WHAT IS FUZZY SEARCH?

"Fuzzy search" is a feature of the TomTom Search API that expands the information returned to include not just exact results, but also useful results. “Fuzziness” is the default behavior of the TomTom Search API and it allows us to perform a search to find addresses and POIs that partially match a specific query.

Fuzzy search makes sure you get results to accommodate situations such as trying to look up a location search with a misspelling or an incorrect address, and it enables the TomTom Search API to provide approximate match results for queries that don't even contain an address. The fuzzy search can be effectively used to extend a query result set by adding nearby points-of-interest (POIs).

In this article we will explain:

• Important search concepts including fuzzy search

• How search options affect what results are returned in a search request

Search and Geocoding

When you use the TomTom Search API to find a location, you're doing something called "geocoding". You're turning a description of a location into coordinates on a map. We usually think of a location as an address such as 123 Main Street. TomTom maps use more precise information to pinpoint that location: the latitude and longitude coordinates on a map. (For more information on geocoding, check out this blog post).

So, when you search for 123 Main Street, the map service typically looks that address up and returns the coordinates, the map showing where that is, and a marker pointing out the coordinates on the map.

But mobile phone keyboards are small, and typos are pretty common. What if you accidentally type "124 Main St", but that address doesn't exist? The default fuzzy search used by TomTom's API will automatically return useful nearby POIs, which is far more useful than returning nothing, even though the address I actually want is effectively right there.

The primary advantage of fuzzy search capabilities in TomTom maps is to provide a level of spell-checking assistance to search results.

Points of Interest (POI)

The term “point of interest” refers to categories of locations such as schools, hospitals, gas stations, stores, restaurants, and many other location assets you might want to look up. The data on each of the available assets is stored in a geolocation database that you can access via the TomTom Search API. To learn more about POIs, check out this article: Understanding Places and POI APIs.

Retrieving POIs for a search is a slight variation on this fuzzy search process. Rather than performing the simple geocoding itself, it allows us to extend the results that might be interesting to a user, by including the information about prominent POIs and other assets near a specific location.

In this scenario, it might be more useful to think of the results as a "nearby search" rather than a "fuzzy search."

For example, a fuzzy search or nearby search might answer user questions such as the following:

• What landmarks are near my destination?

• Where can I get a pizza near me right now?

• Where is the nearest post office?

Fuzzy Search is the Default

The default behavior for TomTom’s Search API is to perform a fuzzy search by a partial match, extending a query result by adding near-match entries and nearby POIs. When you're using the TomTom Search API you don't need to do anything extra to get this valuable feature.

Developers using the TomTom Search API can specify the level of "fuzziness" expected in search results. The API accepts values from 1 to 4. The default level 2 means that the TomTom Search API will perform the normal n-gram spell-checking and find addresses, POIs and other assets is normally performed world-wide rather than a specific location. Other options are no spell checking or string-based spell checking.

There are also options for setting a minimum and maximum level of fuzziness in this case the API starts at the lowest level of spell-checking and increases the level of fuzziness up to the maximum specified level until it finds a match or matches.

Useful Search Options

There are some other options available through the TomTom Search API that allows developers to enable variations on "fuzzy search" functionality for users.

Limiting Search by Country

As we’ve already discussed, the default behavior of TomTom’s Search API is to perform a search to find the POIs and assets around the world. The API supports a countrySet attribute that limits the search results to a specific geographic region by country codes. When this attribute is set, it limits the potential search results, which may be relevant to the user. This option can also improve the performance of the search process itself.

Geometry Search

Besides the “fuzziness” parameter, TomTom’s search engine also supports the number of features, including the ability to search inside geometric boundaries. When the boundary is defined, the TomTom Search API performs a search of only those POIs and assets with coordinates in the defined area.

Nearby Search

Another efficient way of using TomTom’s Search API is to search in the neighborhood of a specific location. The Search API provides a specific endpoint just for nearby searches that will only return POI results.

Along Route Search

Sometimes, it’s also useful to search for POIs and other assets along the route being planned by a user. In this case, the TomTom Search API uses a set of transitional coordinates that pinpoint to the locations along which the route is planned, as well as a search limit and detour time. The TomTom Search API finds all possible POIs and other assets of interest that reside along the route.

Search Demonstration

For a demonstration of fuzzy search from the developer's point of view, we'll show you a simple example of using the minimum and maximum fuzziness settings, along with results from both for comparison.

To specify the “fuzziness” levels we normally have to use withMinFuzzyLevel() and withMaxFuzzyLevel() methods of the generic FuzzySearchQueryBuilder class object, accepting as an argument an integer value of either the minimal or maximal “fuzziness” level as shown in the code snippet below:

// Get the application context object 
Context appContext = getApplicationContext(); 
// Instantiate TomTom's Search API object 
SearchApi searchApi = OnlineSearchApi.create(appContext); 
 
// Construct fuzzy search query object with preciseness and fuzziness level params 
FuzzySearchQuery fuzzySearchQuery = FuzzySearchQueryBuilder.create("term"). 
withPreciseness(new LatLngAcc(position, STANDARD_RADIUS)). 
withMinFuzzyLevel(1).withMaxFuzzyLevel(3).build(); 
 
// Perform a fuzzy search to find POIs and assets of interest 
searchApi.search(fuzzySearchQuery, new FuzzySearchResultListener() { 
@Override 
// Declare the successful search results observer callback method 
    public void onSearchResult(FuzzySearchResponse fuzzySearchResponse) { 
// Retrieve a list of fuzzy search results 
        List<FuzzySearchResult> results = fuzzySearchResponse.getResults(); 
// Modify the recycler view adapter object by passing a list of 
// search results as an argument of its constructor 
        mAdapter = new TTSearchAdapter(results); 
// Set the new recycler view adapter object 
        recyclerView.setAdapter(mAdapter); 
// Notify the recycler view object of the changes committed 
        mAdapter.notifyDataSetChanged(); 
} 
 
@Override 
public void onSearchError(SearchError searchError) { 
// Handle search engine exceptions 
    } 
}); 

Here’s a brief example of search query results returned by the code at the end of its execution (query: “cort” – misspelled “court”, lat: 40.7128, lon: -74.0060, place: New York, countrySet: US, radius: 1000 meters):

“Fuzziness” level 1 (the number of entries “1”):

• (917.4m) Ceres Cafe Cort, 378 Canal St, New York, NY 10013, USA, +(1)-(917)-9652740

“Fuzziness” level 4 (the number of entries more than “5”):

• (917.4m) Ceres Cafe Cort, 378 Canal St, New York, NY 10013, USA, +(1)-(917)-9652740}

• (261.4m) N Y S Supreme Court Officers Associates Union Headquarters, 299 Broadway, New York, NY, USA, 10007 +(1)-(212)-4064292

• (309.1m) Thurgood Marshall United States Courthouse, 40 Centre St, New York, NY, USA 10007, +(1)-(212)-8578500

• (226.1m) Robilotti Dante Marshal, 1 Federal Plz, New York, NY, USA 10007, +(1)-(212)-2642812

• (314.4m) Wireless Warehouse, 107 Chambers Street, New York, NY, USA 10007, +(1)-(212)-2270770

As you can see, the higher fuzziness level returns additional results, but even the lowest level, with no spell checking at all, returns at least one result to the user.

Conclusion

For more on Fuzzy Search, check out these resources:

• Search API and Extended Search API
• Fuzziness Parameters for Android
• What is Fuzzy Search?