TomTom 搜索 API：实现模糊搜索
4.92/5 (8投票s)
深入了解模糊搜索 API 调用。
包含地址和 POI（兴趣点）搜索功能的 Web 应用程序可以通过第三方 API 极大地受益。TomTom 搜索 API 就是其中一个。在本文中，我将解释如何开始使用 TomTom 搜索 API 以及其用途。
在文章中，我们将深入探讨模糊搜索 API 调用，定义一些可以利用此 API 调用来增强应用程序功能的方法。我还将提供一个模糊搜索调用的示例实现，以演示如何将模糊搜索集成到简单的 Web 应用程序中。
在文章的最后，我还会快速回顾一下实现相同结果的另一种方法：使用 TomTom SDK。SDK 通常更快、更易于使用，但如果您是开发人员，您首先会想到 API。
什么是 TomTom 搜索 API？
TomTom 搜索 API 是一个 RESTful API，它使需要在其应用程序中提供地址或兴趣点搜索的开发人员的生活更加轻松。此 API 提供了模糊搜索、兴趣点搜索和类别搜索等调用。注册使用此 API 既免费又简单，开发人员只需访问 TomTom for Developers 网站，然后点击页面右上角的链接进行注册。
注册后，开发人员将获得对开发者仪表板的访问权限，这将允许开发人员访问“我的应用”屏幕并添加应用程序。只需在此处添加应用程序并请求访问搜索 API 产品，TomTom 就会向开发人员提供一个永久有效的 API 密钥供搜索 API 使用。然后，开发人员每天将获得 2,500 次免费 API 事务来支持他们的应用程序。应注意的是，如果每天 2,500 次 API 事务不够，可以通过访问开发者仪表板中的“我的积分”屏幕来购买更多事务。
什么是模糊搜索？
那么，模糊搜索到底是什么？从技术上讲，模糊搜索是指 TomTom 搜索 API 产品中的一个 API 调用，它提供基于“模糊输入”的位置搜索服务。这种“模糊输入”可以是地址、兴趣点或甚至地理编码（纬度和经度）的任意组合。此 API 调用旨在接收此输入并提供与搜索相关的地址和兴趣点结果集。模糊搜索输入的示例如下：
- 明尼苏达附近的披萨
- 洛杉矶加州咖啡店
- 新泽西的购物中心
- 餐馆
模糊搜索服务旨在简单地接收此搜索输入，并以几种响应格式之一（JSON、JSONP、JS、XML）提供结果。此外，此服务可以利用用户位置（或任何位置）的纬度和经度表示来过滤结果集，以提供与该特定位置最相关aneous 的结果。
让我们以最后一个例子为例——“餐馆”。也许使用模糊搜索的开发人员正在为用户设计一个应用程序，用于搜索与他们所在位置直接相关的地点。在这种情况下，用户正在寻找他们附近的餐馆。模糊搜索服务只需开发人员将代表用户位置的纬度和经度信息作为参数提供给 API 调用，即可为“餐馆”搜索加权，从而为用户提供更相关的附近餐馆结果集。这仅仅是模糊搜索 API 调用可以根据开发人员在应用程序中的意图以特定方式自定义以过滤结果集的几种方法之一。
在 Web 应用程序中实现模糊搜索
模糊搜索服务可以相对简单且无缝地集成到 Web 应用程序中。为了演示这一点，我使用 Express 框架构建了一个简单的 Node.js Web 应用程序。我选择用于我的示例应用程序的视图引擎是 Pug.js。（在这里，您可以找到一个简单的指南，介绍如何将 Pug 与 Express 集成，作为您使用 TomTom 模糊搜索服务的 Web 应用程序的潜在模板引擎。）
在我的特定应用程序中，只有四个文件需要提及才能完全理解我的实现。这些文件都包含在下面显示的我的项目资源管理器截图中
在此图像中，您可以看到用于为我的应用程序中将使用的搜索表单设置样式的 Bootstrap CSS 文件。此外，您还可以看到我创建了两个视图文件：index.pug 和 layout.pug，用于显示搜索表单以及从模糊搜索 API 调用返回的结果。最后，*app.js* 文件为表单和整个 Express 应用程序提供了功能。
视图文件 *layout.pug* 简单地提供了可用于我们网站上每个页面的模板。它包含 *bootstrap.min.css* 文件，以便我们可以使用 Bootstrap 类在任何扩展此布局文件的页面上设置表单的样式。
layout.pug
doctype html
html
head
title= title
link(rel='stylesheet', href='/stylesheets/bootstrap.min.css')
body
block content
*Index.pug* 扩展了布局，使我们能够访问 Bootstrap 类。这也是大部分工作完成的地方。此视图将负责显示用于提供模糊搜索输入的搜索表单，以及显示 API 调用的结果。该表单非常简单，提供一个用于搜索词的文本输入和一个提交按钮。
如果名为 resultSet 的数组中有结果，则会遍历这些结果，并添加一个列表项，该列表项将以易于阅读的格式显示该机构的名称（如果是兴趣点）和地址（存储在结果的 address 节点中，名为 freeformAddress）。
Index.pug
extends layout
block content
h1="Search for Places"
form(norm="fuzzy-search", method="get", action="/")
div.form-group
span.label Search Term
input(type="text", name="searchterm" value=searchedTerm)
div.form-group
input(type="submit", value="Search")
h2="Results for: " + searchedTerm
ul
each result, i in resultSet
if result.poi
li=result.poi.name + " -- " + result.address.freeformAddress
else
li=result.address.freeformAddress
与此应用程序关联的 JavaScript 文件名为 *app.js*。*app.js* 中用于向 *index.pug* 发出请求的代码显示在下面的图像中
app.js
app.get('/', function(req, res){
var query = req.query.searchterm;
console.log(query);
if (query) {
request('https://api.tomtom.com/search/2/search' + query + '.JSON?key=YOUR_API_KEY_HERE', function(error, response, body) {
if (!error && response.statusCode == 200) {
var jsonResponse = JSON.parse(body);
//print our response to the console
console.log(jsonResponse);
res.render('index', {
resultSet: jsonResponse.results,
searchTerm: query
});
}
});
}
});
为每个发往主页的请求执行的函数将查找提交的搜索词。如果提供了搜索词，则使用 Express 的“request”库进行模糊搜索 API 调用。该请求是一个简单的 HTTP GET 请求，发送到 TomTom API，并提供相应的参数。参数的完整列表可以在在线的 模糊搜索文档 中找到。就本文示例而言，我仅提供必需的参数。如您在 *App.js* 代码片段中所见，根据下面 TomTom 搜索 API 文档中模糊搜索的格式片段，我们将以下参数与请求一起发送：
https://<baseURL>/search/<versionNumber>/search/<query>.<ext>?key=<apiKey>
样本 API 调用中提供的参数
- baseURL: api.tomtom.com
- versionNumber: 2
- query: query 参数
- ext: JSON
在此示例中，我没有提供文档中不需要的任何参数。
现在来测试应用程序。加载应用程序的主页后，我们会看到以下屏幕
作为一个示例搜索，我在搜索框中输入了“coffee shop Los Angeles CA”。单击“搜索”后，加载了以下页面，并将搜索结果填充到屏幕上
如您所见，API 调用返回了兴趣点及其相关的地址。在解析 JSON 响应后，很容易将机构名称和地址添加到显示中。此外，通过在搜索词中包含“Los Angeles CA”，API 调用确保返回与提供的位置相关的咖啡店。下面，我提供了 HTTP GET 请求在示例应用程序中发送到 TomTom API 返回的 JSON 响应中的摘要和第一个结果
{
"summary":{
"query":"coffee shop los angeles ca",
"queryType":"NON_NEAR",
"queryTime":121,
"numResults":10,
"offset":0,
"totalResults":1354,
"fuzzyLevel":1
},
"results":[
{
"type":"POI",
"id":"US/POI/p1/1991172",
"score":15.6,
"info":"search:ta:840069009242067-US",
"poi":{
"name":"Dunkin' Donuts",
"phone":"+(1)-(424)-2872119",
"url":"www.dunkindonuts.com",
"categories":[
"café/pub",
"coffee shop"
],
"classifications":[
{
"code":"CAFE_PUB",
"names":[
{
"nameLocale":"en-US",
"name":"coffee shop"
},
{
"nameLocale":"en-US",
"name":"café/pub"
}
]
}
]
},
"address":{
"streetNumber":"1326",
"streetName":"W Anaheim St",
"municipalitySubdivision":"Los Angeles, LA, Wilmington",
"municipality":"Los Angeles, Wilmington, LA",
"countrySecondarySubdivision":"Los Angeles",
"countryTertiarySubdivision":"Los Angeles",
"countrySubdivision":"CA",
"postalCode":"90744",
"countryCode":"US",
"country":"United States Of America",
"countryCodeISO3":"USA",
"freeformAddress":"1326 W Anaheim St, Los Angeles, CA 90744",
"countrySubdivisionName":"California"
},
"position":{
"lat":33.7788,
"lon":-118.27913
},
"viewport":{
"topLeftPoint":{
"lat":33.7797,
"lon":-118.28021
},
"btmRightPoint":{
"lat":33.7779,
"lon":-118.27805
}
},
"entryPoints":[
{
"type":"main",
"position":{
"lat":33.77906,
"lon":-118.27914
}
}
]
},
…
}
替代方法：使用 TomTom SDK
在 Web 应用程序中实现模糊搜索的另一种有用方法是使用 TomTom 的 Maps SDK。此开发工具包通过简单地利用 SDK 库中提供的各种方法，轻松地在您的 Web 应用程序中利用许多 TomTom 服务。Maps SDK 的下载和文档可以在 这里 找到。
为了展示使用 SDK 实现模糊搜索服务的便捷性，我使用纯 HTML 和 JavaScript 开发了一个非常简单的 Web 应用程序。HTML 页面包含一个表单字段以及一个用于提供搜索词的文本输入。然后，使用搜索词执行模糊搜索调用，并将结果添加到包含有关每个搜索结果信息的交互式地图中。
这是我的代码的样子
<!DOCTYPE html>
<html>
<head>
<title>Sample Map</title>
<link rel='styesheet' type='text/css' href='maps_sdk/map.css' />
<script src='maps_sdk/tomtom.min.js'></script>
</head>
<body>
<form id="form">
Search: <input id="fuzzySearchTerm" type="text" />
<br />
<input type="submit" />
</form>
<br />
<div id="map" style="height: 500px; width: 500px;"></div>
<script>
tomtom.searchKey('YOUR-API-KEY-HERE');
var map = L.map('map', {key: 'YOUR-API-KEY-HERE'});
var form = document.getElementById("form");
form.onsubmit = function() {
var value = document.getElementById("fuzzySearchTerm").value;
tomtom.fuzzySearch()
.query(value)
.go(function(result) {
var markers = new L.TomTomMarkersLayer().addTo(map);
markers.setMarkersData(result);
markers.addMarkers();
map.fitBounds(markers.getBounds());
});
return false;
}
</script>
</body>
</html>
从代码中可以看到，页面上添加了一个地图以及表单字段和提交按钮。提交表单时，会从输入元素中收集搜索词，并使用 SDK 的 fuzzySearch 函数执行模糊搜索。对于每个结果，都会在地图上添加一个标记来指示位置。与本文前面涉及 API 的示例相比，SDK 更简单，代码量更少，从而节省了开发人员的时间，并减少了出错的可能性。
下面是网页搜索的屏幕截图。在此示例中，我搜索了“coffee houston texas”。这是模糊搜索调用中使用的词。结果在地图上标出，并在每个标记旁边附加了描述兴趣点的附加信息
结论
模糊搜索服务可以轻松地集成到任何需要位置/兴趣点搜索的 Web 应用程序中。只需向 TomTom 搜索 API 发送一个 HTTP GET 请求，几乎可以返回任何单行“模糊”搜索的相关结果。在其最基本的形式中，开发人员可以通过提供单行表单并返回结果列表（如上所示）来利用模糊搜索服务，或者他们甚至可以通过映射每个结果位置的位置来构建更复杂的解决方案，利用结果集中返回的每个位置的纬度和经度。