# @azure/maps-search 中文文档

规范地址：https://npmcn.com/package/%40azure/maps-search/

版本：1\.0\.0-beta\.2
npm 元数据更新时间：2026-03-19T19:53:00.854Z
中文译文更新时间：2026-11-07T16:45:36.308Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/maps-search
原文对照：https://npmcn.com/package/%40azure/maps-search/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-search/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

弃用说明：Please use @azure-rest/maps-search

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.4 MB，126 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：8 个
- 首次发布：2022-10-01T06:45:32.041Z
- 最新版本发布：2022-11-08T05:48:29.063Z
- 近 30 天下载量：4579（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

Azure 地图地图搜索客户端库

## 安装

```sh
npm install @azure/maps-search
```

也可以使用：`pnpm add @azure/maps-search`、`yarn add @azure/maps-search`、`bun add @azure/maps-search`

## README

# Azure Maps 搜索 JavaScript/ TypeScript 客户端库

Azure地图搜索服务是一组RESTful API,旨在帮助开发者按名称,类别,和其他地理信息搜索地址,地点,和企业上市. 除了支持传统的地理编码外,服务还可以倒转以纬度和经度为基础的地理编码地址并横穿街道. 搜索返回的纬度和经度值可作为参数用于其他 Azure 映射服务,例如 [路线](https://docs.microsoft.com/rest/api/maps/route) 财务报告和审定财务报表 [天气](https://docs.microsoft.com/rest/api/maps/weather) 服务.

这个软件包包含一个Azure Maps搜索客户端的同位素 SDK(运行于Node.js和浏览器中).

[源代码](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-search) | [软件包( NPM)](https://www.npmjs.com/package/@azure/maps-search) | [样本](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-search/samples) | [产品信息](https://docs.microsoft.com/rest/api/maps/search)

## 开始

### 目前得到支持的环境

-   [节点.js的LTS版本](https://nodejs.org/about/releases/)
-   最新版本有"萨法里","克罗姆","边缘"和"火狐"等.

### 先决条件

-   一个 [Azure 订阅](https://azure.microsoft.com/free/)。 。 。 .
-   一个 [Azure 地图账户](https://docs.microsoft.com/azure/azure-maps/how-to-manage-account-keys)您可以通过 [Azure 门户](https://portal.azure.com/),则 [Azure 动力壳](https://docs.microsoft.com/powershell/module/az.maps/new-azmapsaccount),或 [阿苏尔CLI](https://docs.microsoft.com/cli/azure)。 。 。 .

如果您使用 Azure CLI, 请替换 `<resource-group-name>` 财务报告和审定财务报表 `<map-account-name>` 选择一个合适的 [定价等级](https://docs.microsoft.com/azure/azure-maps/choose-pricing-tier) 根据您的需要,通过 `<sku-name>` 参数。 请参考 [此页面](https://docs.microsoft.com/cli/azure/maps/account?view=azure-cli-latest#az_maps_account_create) 更多细节.

```bash
az maps account create --resource-group <resource-group-name> --name <map-account-name> --sku <sku-name>
```

### 安装 `@azure/maps-search` 软件包

安装 Azure 地图搜索客户端库 `npm`数字 :

```bash
npm install @azure/maps-search
```

### 创建和认证 a `MapsSearchClient`

要创建访问 Azure 映射搜索 API 的客户端对象, 您需要一个 `credential` 对象。 Azure地图搜索客户端可以使用Azure Active Directory证书或Azure密钥证书认证.

#### 使用 Azure 活动目录证书

您可以使用 Azure 活动目录认证 [Azure 身份库](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity)使用 [默认标记](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) 下面显示的提供者,或提供Azure SDK的其他证书提供者,请安装 `@azure/identity` 软件包 :

```bash
npm install @azure/identity
```

您还需要注册一个新的 AAD 申请,并通过指定您的服务负责人承担合适的角色来获取 Azure 地图。 请参看 [管理认证](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication) 页 次.

设置客户端ID, 租户ID, 以及客户端AAD应用程序秘密的值为环境变量 : `AZURE_CLIENT_ID`, (中文(简体) ), `AZURE_TENANT_ID`, (中文(简体) ), `AZURE_CLIENT_SECRET`。 。 。 .

您还需要指定您打算使用的 Azure 映射资源, 请指定 `clientId` 在客户端选项中. Azure Maps 资源客户端 id 在 Azure Maps 资源中的认证部分中可以找到. 请参看 [文档](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication#view-authentication-details) 关于如何找到它.

```javascript
const { MapsSearchClient } = require("@azure/maps-search");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const client = new MapsSearchClient(credential, "<maps-account-client-id>");
```

#### 使用订阅密钥证书

您可以使用您的 Azure 地图订阅密钥认证 .

```javascript
const { MapsSearchClient, AzureKeyCredential } = require("@azure/maps-search");

const credential = new AzureKeyCredential("<subscription-key>");
const client = new MapsSearchClient(credential);
```

## 关键概念

### 地图搜索客户端

`MapsSearchClient` 是使用 Azure Maps 搜索客户端库开发者的主要界面. 探索此客户端上的方法对象,以了解Azure地图搜索服务的不同特性,您可以访问.

## 实例

以下各节提供多个代码片段,涵盖一些最常用的Azure地图搜索任务,包括:

-   [请求获得经纬度坐标地址](https://npmcn.com/package/%40azure/maps-search/#readme-request-latitude-and-longitude-coordinates-for-an-address)
-   [搜索地址或利益点](https://npmcn.com/package/%40azure/maps-search/#readme-search-for-an-address-or-point-of-interest)
-   [创建反向地址搜索, 将坐标位置翻译为街道地址](https://npmcn.com/package/%40azure/maps-search/#readme-make-a-reverse-address-search-to-translate-coordinate-location-to-street-address)
-   [将坐标位置转换成人类可以理解的交叉街道](https://npmcn.com/package/%40azure/maps-search/#readme-translate-coordinate-location-into-a-human-understandable-cross-street)

### 请求获得经纬度坐标地址

您可以使用认证的客户端将地址转换为经纬度坐标. 这个过程也叫地理编码. 除回回坐标外,答复还将回回街道、邮政编码、市政府和国家/区域信息等详细的地址属性.

```javascript
const searchResult = await client.searchAddress("400 Broad, Seattle");
for (const {
  position: { lat, lon },
} of searchResult.results) {
  console.log(`Latitude: ${lat}, Longitude: ${lon}`);
}
```

### 搜索地址或利益点

您可以使用Fuzzy Search搜索地址或兴趣点(POI). 以下例子说明如何寻找 `pizza` 特定国家范围`France`,在本例子中).

```javascript
const fuzzySearchResult = await client.fuzzySearch({ query: "pizza", countryCodeFilter: ["fr"] });
for (const result of fuzzySearchResult.results) {
  console.log(result);
}
```

### 创建反向地址搜索, 将坐标位置翻译为街道地址

你可以将坐标转换成人类可读的街道地址. 这个过程也被称为倒向地理学编码. 这经常被用于使用GPS种子并想在特定坐标点发现地址的应用.

```javascript
const coordinates: LatLon = [47.59118, -122.3327]; // [latitude, longitude]

const { addresses } = await client.reverseSearchAddress(coordinates);
for (const { address } of addresses) {
  console.log(address);
}
```

### 将坐标位置转换成人类可以理解的交叉街道

通过使用搜索地址逆向交叉街API,将坐标位置翻译为人类可以理解的交叉街. 在跟踪从设备或资产接收GPS种子的应用程序时往往需要这样做,并希望知道坐标的位置.

```javascript
const coordinates: LatLon = [47.59118, -122.3327];

const { addresses } = await client.reverseSearchCrossStreetAddress(coordinates);
for (const { address } of addresses) {
  console.log(address);
}
```

## 解决问题

### 日志

允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 `AZURE_LOG_LEVEL` 环境变量改为 `info`。或者,可以在运行时拨打 `setLogLevel` 输入 `@azure/logger`数字 :

```javascript
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
```

关于如何启用日志的更详细指示,您可以查看 [@ azure/ logger 包文件](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/core/logger)。 。 。 .

## 今后的步骤

请看一下 [样本](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-search/samples) 关于如何使用此库的详细示例的目录.

## 捐款

如果您想为图书馆捐钱 请读一下 [贡献指南](https://github.com/Azure/azure-sdk-for-js/tree/main/CONTRIBUTING.md) 学习如何构建和测试密码.

## 相关项目

-   [微软 Azure SDK 用于 JavaScript](https://github.com/Azure/azure-sdk-for-js)

![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fmaps%2Fmaps-search%2FREADME.png)

## 常见问题

### @azure/maps-search 是什么？

Azure 地图地图搜索客户端库注意：该包已被作者标记为弃用——Please use @azure-rest/maps-search

### 如何安装 @azure/maps-search？

在项目目录运行 npm install @azure/maps-search，或使用 pnpm add / yarn add / bun add。

### @azure/maps-search 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/maps-search 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/maps-search 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/maps-search 可以商用吗？

@azure/maps-search 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/maps-search 的下载量有多少？

根据 npm 官方下载统计，@azure/maps-search 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,579 次，日均约 153 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/maps-search 还在维护吗？

最新版本 1\.0\.0-beta\.2 发布于 2022/11/08（3 年前）；至今共发布 5 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/10/01。作者已将其标记为弃用，新项目建议寻找替代方案。