# @google/maps 中文文档

规范地址：https://npmcn.com/package/%40google/maps/

版本：1\.1\.3
npm 元数据更新时间：2022-06-12T19:14:46.417Z
中文译文更新时间：2026-11-16T19:57:41.720Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40google/maps
原文对照：https://npmcn.com/package/%40google/maps/?lang=original
项目主页：https://github.com/googlemaps/google-maps-services-js
源码仓库：https://github.com/googlemaps/google-maps-services-js

弃用说明：Please use @googlemaps/google-maps-services-js instead\.

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

- 包体积（解压后）：111 kB，26 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2016-08-16T00:26:59.771Z
- 最新版本发布：2020-04-30T15:08:08.097Z
- 近 30 天下载量：327877（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 0 个）

## 中文简介

用于 Google Maps API 网络服务的 Node.js 客户端库

## 安装

```sh
npm install @google/maps
```

也可以使用：`pnpm add @google/maps`、`yarn add @google/maps`、`bun add @google/maps`

## README

# 谷歌地图服务节点.js 客户端

[![Build Status](https://travis-ci.org/googlemaps/google-maps-services-js.svg?branch=master)](https://travis-ci.org/googlemaps/google-maps-services-js) [![npm](https://img.shields.io/npm/v/@google/maps.svg)](https://www.npmjs.com/package/@google/maps) [![codecov](https://codecov.io/gh/googlemaps/google-maps-services-js/branch/master/graph/badge.svg)](https://codecov.io/gh/googlemaps/google-maps-services-js) ![GitHub contributors](https://img.shields.io/github/contributors/googlemaps/google-maps-services-js?color=green)

> 这个图书馆已经贬值了,有利于 [@googlemaps/google-maps-服务-js](https://www.npmjs.com/package/@googlemaps/google-maps-services-js)。错误修正将继续下去,但所有新特性开发都将在 [主分支](https://github.com/googlemaps/google-maps-services-js) 并出版到新图书馆.

用节点? 喜欢 [地理编码](https://developers.google.com/maps/documentation/geocoding/) 什么东西? 寻找 页:1 [方向](https://developers.google.com/maps/documentation/directions/)? 吗? 这个图书馆带来了 [谷歌地图 API 网络服务](https://developers.google.com/maps/apis-by-platform#web_service_apis) 到您的节点js 应用. ![Analytics](https://maps-ga-beacon.appspot.com/UA-12846745-20/google-maps-services-js/readme?pixel)

Google Maps 服务的节点客户端是一个节点.js客户端库 用于下列谷歌地图 API:

-   [方向 API](https://developers.google.com/maps/documentation/directions/)
-   [距离矩阵 API](https://developers.google.com/maps/documentation/distancematrix/)
-   [高级 API](https://developers.google.com/maps/documentation/elevation/)
-   [地理编码 API](https://developers.google.com/maps/documentation/geocoding/)
-   [位置 API](https://developers.google.com/places/web-service/)
-   [路由规划](https://developers.google.com/maps/documentation/roads/)
-   [时区 API](https://developers.google.com/maps/documentation/timezone/)

记住,同样的 [条款和条件](https://developers.google.com/maps/terms) 适用于通过此库访问的API的使用.

## 请注意!

这个库是为服务器端的Node.js应用程序而设计的. 尝试在浏览器或任何其他环境中使用它客户端,比如React Industrial,在某些情况下可能可行,但大多不会成功. 请在试图利用这些环境时不要报告与这些环境有关的问题,因为 **服务器侧 Node.js 应用程序是此库唯一支持的环境**对于其他环境,请尝试 [地图 JavaScript API](https://developers.google.com/maps/documentation/javascript/),其中包含可比较的功能集,并明确用于客户端JavaScript.

## 特征

-   **在失败时重试** 间歇性故障时自动重试 . 也就是说,当任何可重试的5xx错误从API中返回时.
    
-   **限制费率** 请求受客户的费率限制,这有助于 防止达到服务器强制费率限制.
    

## 快速启动

```
$ npm install @google/maps
```

**说明:** 您需要安装 npm 2. 7.0 或 更多, 因为这个库是一个主机 [范围软件包](https://docs.npmjs.com/getting-started/scoped-packages)。 。 。 .

通过调用创建新客户端对象 `createClient()`

```js
const googleMapsClient = require('@google/maps').createClient({
  key: 'your API key here'
});
```

通过调用客户端对象上的方法向Google Maps API请求.

```js
// Geocode an address.
googleMapsClient.geocode({
  address: '1600 Amphitheatre Parkway, Mountain View, CA'
}, function(err, response) {
  if (!err) {
    console.log(response.json.results);
  }
});
```

你也可以使用基于承诺的解决办法.

```js
const googleMapsClient = require('@google/maps').createClient({
  key: 'your API key here',
  Promise: Promise
});

googleMapsClient.geocode({address: '1600 Amphitheatre Parkway, Mountain View, CA'})
  .asPromise()
  .then((response) => {
    console.log(response.json.results);
  })
  .catch((err) => {
    console.log(err);
  });
```

更多信息请查看 [测试](https://npmcn.com/package/%40google/maps/spec/e2e/)。 。 。 .

查看 [参考文件](https://googlemaps.github.io/google-maps-services-js/docs/)

包括网络服务的其他文件可在下列网址查阅: [https://developers.google.com/maps/ 页面存档备份,存于互联网档案馆](https://developers.google.com/maps/)。 。 。 .

## API 密钥

每个Google Maps Web Service请求都需要一个API密钥. 要获得 API 密钥, 请遵循 [获取 API 密钥](https://developers.google.com/maps/documentation/javascript/get-api-key#get-the-api-key) (原始内容存档于2018-03-21). Professional in our maps JS API docs.

当您有 API 密钥时, 您可以创建客户端对象 :

```js
var googleMapsClient = require('@google/maps').createClient({
  key: 'your API key here'
});
```

### 客户身份

Google Maps APIs Premium 计划客户可以使用他们的 [客户身份和秘密](https://developers.google.com/maps/documentation/business/webservices/auth) 要认证, 而不是 API 密钥 .

```js
var googleMapsClient = require('@google/maps').createClient({
  clientId: 'Add your client ID here',
  clientSecret: 'Add your client secret here',
});
```

**重要内容:** 此密钥应保密于您的服务器 .

## 字体

该图书馆的社区建设打字机可使用 `@types/google__maps` (注意双下划线).

`npm install @types/google__maps`

## 发展中国家

为了进行端到端测试,您需要通过一个 环境变量.

```
$ export GOOGLE_MAPS_API_KEY=AIza-your-api-key
$ npm test
```

## 支助

这个图书馆是社区支持的。 我们很自在 我们想要你建立真正的图书馆的稳定性和特征 生产应用。 我们会尽力支持,通过Stack 过度流出、图书馆的公共表面和维护 向后兼容;然而,当库处于 0.x版本,我们保留了让反相兼容的权利 变化。 如果我们确实去掉了一些功能(通常是因为更好) 功能存在或特性证明不可行时,我们的意图 即对开发者进行贬值并给予一年时间更新其代码.

如果您发现错误, 或者有特性建议, 请 [日志一个问题](https://github.com/googlemaps/google-maps-services-js/issues)请阅读 [如何贡献](https://github.com/googlemaps/google-maps-services-js/blob/master/CONTRIBUTING.md)。 。 。 .

## 命令行接口

通过 npm 安装也提供了 `googlemaps` 命令行工具, 用于向其他命令行程序管道 JSON 结果:

```
$ googlemaps directions --origin 'Sydney Town Hall' --destination 'Parramatta, NSW'
```

## 常见问题

### @google/maps 是什么？

用于 Google Maps API 网络服务的 Node\.js 客户端库注意：该包已被作者标记为弃用——Please use @googlemaps/google-maps-services-js instead\.

### 如何安装 @google/maps？

在项目目录运行 npm install @google/maps，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 googlemaps，可以用 npx googlemaps 直接运行。

### @google/maps 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/google\_\_maps 是否存在。

### @google/maps 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @google/maps 可以商用吗？

@google/maps 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @google/maps 的下载量有多少？

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

### @google/maps 还在维护吗？

最新版本 1\.1\.3 发布于 2020/04/30（6 年前）；至今共发布 24 个版本，其中过去 12 个月发布了 0 个；首次发布于 2016/08/16。作者已将其标记为弃用，新项目建议寻找替代方案。

