🌜
🌞
@googlemaps/google-maps-services-js

@googlemaps/google-maps-services-js

v3.3.16

Node.js client library for Google Maps API Web Services

npm install @googlemaps/google-maps-services-js

README

Node.js Client for Google Maps Services

npm Test Release codecov GitHub contributors semantic-release Discord

This library is a refactor of a previous version published to @google/maps. It is now being published to @googlemaps/google-maps-services-js.

Use Node.js? Want to geocode something? Looking for directions? This library brings the Google Maps API Web Services to your Node.js application.

The Node.js Client for Google Maps Services is a Node.js Client library for the following Google Maps APIs:

Keep in mind that the same terms and conditions apply to usage of the APIs when they're accessed through this library.

Attention!

This library is designed for server-side Node.js applications. Attempting to use it client-side, in either the browser or any other environment like React Native, may in some cases work, but mostly will not. Please refrain from reporting issues with these environments when attempting to use them, since server-side Node.js applications is the only supported environment for this library. For other environments, try the Maps JavaScript API, which contains a comparable feature set, and is explicitly intended for use with client-side JavaScript.

Quick Start

$ npm install @googlemaps/google-maps-services-js

Below is a simple example calling the elevation method on the client class.

Import the Google Maps Client using Typescript and ES6 module:

import {Client} from "@googlemaps/google-maps-services-js";

Alternatively using JavaScript without ES6 module support:

const {Client} = require("@googlemaps/google-maps-services-js");

Now instantiate the client to make a call to one of the APIs.

const client = new Client({});

client
  .elevation({
    params: {
      locations: [{ lat: 45, lng: -110 }],
      key: "asdf",
    },
    timeout: 1000, // milliseconds
  })
  .then((r) => {
    console.log(r.data.results[0].elevation);
  })
  .catch((e) => {
    console.log(e.response.data.error_message);
  });

Reference Documentation

The generated reference documentation can be found here. The TypeScript types are the authoritative documentation for this library and may differ slightly from the descriptions.

Developing

In order to run the end-to-end tests, you'll need to supply your API key via an environment variable.

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

Migration

This section discusses the migration from @google/maps to @googlemaps/google-maps-services-js and the differences between the two.

Note: The two libraries do not share any methods or interfaces.

The primary difference is @google/maps exposes a public method that takes individual parameters as arguments while @googlemaps/google-maps-services-js exposes methods that take params, headers, body, instance(see Axios). This allows direct access to the transport layer without the complexity that was inherent in the old library. Below are two examples.

Old (@google/maps):

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

googleMapsClient
  .elevation({
    locations: {lat: 45, lng: -110}
  })
  .asPromise()
  .then(function(r) {
    console.log(r.json.results[0].elevation);
  })
  .catch(e => {
  console.log(e);
  });

New (@googlemaps/google-maps-services-js):

const client = new Client({});

client
  .elevation({
    params: {
      locations: [{ lat: 45, lng: -110 }],
      key: process.env.GOOGLE_MAPS_API_KEY
    },
    timeout: 1000 // milliseconds
  }, axiosInstance)
  .then(r => {
    console.log(r.data.results[0].elevation);
  })
  .catch(e => {
    console.log(e);
  });

The primary differences are in the following table.

Old New
Can provide params Can provide params, headers, instance, timeout (see Axios Request Config)
API key configured at Client API key configured per method in params object
Retry is supported Retry is configurable via axios-retry or retry-axios
Does not use promises by default Promises are default
Typings are in @types/googlemaps Typings are included
Does not support keep alive Supports keep alive
Does not support interceptors Supports interceptors
Does not support cancelalation Supports cancellation

Premium Plan Authentication

Authentication via client ID and URL signing secret is provided to support legacy applications that use the Google Maps Platform Premium Plan. The Google Maps Platform Premium Plan is no longer available for sign up or new customers. All new applications must use API keys.

const client = new Client({});

client
  .elevation({
    params: {
      locations: [{ lat: 45, lng: -110 }],
      client_id: process.env.GOOGLE_MAPS_CLIENT_ID,
      client_secret: process.env.GOOGLE_MAPS_CLIENT_SECRET
    },
    timeout: 1000 // milliseconds
  })
  .then(r => {
    console.log(r.data.results[0].elevation);
  })
  .catch(e => {
    console.log(e.response.data.error_message);
  });

Support

This library is community supported. We're comfortable enough with the stability and features of the library that we want you to build real production applications on it. We will try to support, through Stack Overflow, the public surface of the library and maintain backwards compatibility in the future; however, while the library is in version 0.x, we reserve the right to make backwards-incompatible changes. If we do remove some functionality (typically because better functionality exists or if the feature proved infeasible), our intention is to deprecate and give developers a year to update their code.

If you find a bug, or have a feature suggestion, please log an issue. If you'd like to contribute, please read How to Contribute.

Release Notes

3.3.16
Published on June 13, 2022

3.3.16 (2022-06-13)

Build System

  • deps-dev: bump @types/node from 17.0.36 to 17.0.40 (#826) (183a156)
  • deps-dev: bump @types/node from 17.0.40 to 17.0.42 (#829) (9be4093)
  • deps-dev: bump nock from 13.2.4 to 13.2.6 (#824) (b155220)
  • deps-dev: bump typedoc from 0.22.16 to 0.22.17 (#823) (60aace9)
  • deps-dev: bump typescript from 4.6.4 to 4.7.3 (#825) (25f4b3a)
3.3.15
Published on June 1, 2022

3.3.15 (2022-06-01)

Bug Fixes

  • bump @googlemaps/url-signature from 1.0.21 to 1.0.24 (#821) (3040a72)

Build System

  • deps-dev: bump @types/node from 17.0.35 to 17.0.36 (#820) (e428a00)
  • deps-dev: bump typedoc from 0.22.15 to 0.22.16 (#819) (231bd9b)
3.3.14
Published on May 25, 2022

3.3.14 (2022-05-25)

Bug Fixes

Documentation

Miscellaneous Chores

  • add --approve (7bd96d1)
  • Created local '.github/workflows/dependabot.yml' from remote '.github/workflows/dependabot.yml' (#809) (bfe9c99)
  • fix approval by providing url to pr (6303890)
  • fix typo in check name (#808) (51731aa)
  • only approve (ba74bac)
  • simplify dependabot workflow (9407bc2)
  • Synced file(s) with googlemaps/.github (#802) (be73d5b)
  • Synced local '.github/sync-repo-settings.yaml' with remote '.github/sync-repo-settings.yaml' (#803) (af836fa)
  • Synced local '.github/workflows/dependabot.yml' with remote '.github/workflows/dependabot.yml' (#810) (8e1bf94)
  • update owners (#816) (b7dbe63)
  • update pull request approval comment (2493a2b)

Build System

3.3.13
Published on April 18, 2022

3.3.13 (2022-04-18)

Build System

  • deps-dev: bump @types/node from 17.0.23 to 17.0.25 (#793) (5bb902f)
  • deps-dev: bump prettier from 2.6.1 to 2.6.2 (#790) (63c9b11)
  • deps-dev: bump typedoc from 0.22.13 to 0.22.15 (#792) (3833682)
  • deps: bump @googlemaps/url-signature from 1.0.18 to 1.0.19 (#791) (09e0fa4)
  • deps: bump @googlemaps/url-signature from 1.0.19 to 1.0.20 (#794) (6b2378b)
3.3.12
Published on March 28, 2022

3.3.12 (2022-03-28)

Build System

  • deps-dev: bump @types/node from 17.0.21 to 17.0.22 (#781) (9cc11c8)
  • deps-dev: bump @types/node from 17.0.22 to 17.0.23 (#785) (2f30a44)
  • deps-dev: bump prettier from 2.5.1 to 2.6.0 (#783) (403d115)
  • deps-dev: bump prettier from 2.6.0 to 2.6.1 (#784) (bc029e5)
  • deps-dev: bump ts-jest from 27.1.3 to 27.1.4 (#786) (7b0f066)
  • deps-dev: bump typescript from 4.6.2 to 4.6.3 (#788) (93c48d0)
  • deps: bump @googlemaps/url-signature from 1.0.16 to 1.0.17 (#782) (2b2dc7e)
  • deps: bump @googlemaps/url-signature from 1.0.17 to 1.0.18 (#787) (62bbcbd)
  • deps: bump minimist from 1.2.5 to 1.2.6 (#789) (34d9879)
3.3.11
Published on March 14, 2022

3.3.11 (2022-03-14)

Build System

  • deps-dev: bump @types/jest from 27.4.0 to 27.4.1 (#773) (e61d3d7)
  • deps-dev: bump @types/node from 17.0.19 to 17.0.21 (#772) (2772079)
  • deps-dev: bump typedoc from 0.22.12 to 0.22.13 (#777) (4360393)
  • deps-dev: bump typescript from 4.5.5 to 4.6.2 (#778) (708dc76)
  • deps: bump @googlemaps/url-signature from 1.0.15 to 1.0.16 (#776) (1e4c81d)
  • deps: bump axios from 0.26.0 to 0.26.1 (#779) (9e925a8)
3.3.10
Published on February 21, 2022

3.3.10 (2022-02-21)

Build System

  • deps-dev: bump @types/node from 17.0.16 to 17.0.18 (#766) (0a7772a)
  • deps-dev: bump @types/node from 17.0.18 to 17.0.19 (#770) (1c6658d)
  • deps-dev: bump jest from 27.5.0 to 27.5.1 (#763) (a9a4355)
  • deps-dev: bump typedoc from 0.22.11 to 0.22.12 (#768) (b963438)
  • deps: bump @googlemaps/url-signature from 1.0.13 to 1.0.14 (#764) (3c2c324)
  • deps: bump @googlemaps/url-signature from 1.0.14 to 1.0.15 (#769) (8a1856d)
  • deps: bump agentkeepalive from 4.2.0 to 4.2.1 (#771) (633a5d8)
  • deps: bump axios from 0.25.0 to 0.26.0 (#765) (7b6408b)
  • deps: bump follow-redirects from 1.14.7 to 1.14.8 (#762) (ded22ee)
3.3.9
Published on February 8, 2022

3.3.9 (2022-02-08)

Bug Fixes

Build System

  • deps-dev: bump @types/node from 17.0.13 to 17.0.16 (#757) (74fab7b)
  • deps-dev: bump jest from 27.4.7 to 27.5.0 (#755) (bf03597)
  • deps-dev: bump nock from 13.2.2 to 13.2.4 (#756) (7fa5aef)
  • deps: bump @googlemaps/url-signature from 1.0.12 to 1.0.13 (#759) (2c39f7e)
  • deps: bump query-string from 7.1.0 to 7.1.1 (#758) (2e1b22d)
3.3.8
Published on January 31, 2022

3.3.8 (2022-01-31)

Build System

  • deps-dev: bump @types/node from 17.0.10 to 17.0.13 (#751) (172fa7d)
  • deps-dev: bump @types/node from 17.0.9 to 17.0.10 (#746) (4dcffa1)
  • deps-dev: bump typedoc from 0.22.10 to 0.22.11 (#747) (c8a3b39)
  • deps: bump @googlemaps/url-signature from 1.0.11 to 1.0.12 (#745) (4285f68)
  • deps: bump axios from 0.24.0 to 0.25.0 (#748) (dfa33e1)

General

License
Apache-2.0
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
2,554
Community Interest
3,127
Number of Forks
597

Maintenance

Commits
11/2110/22025
Last Commit
Open Issues
8
Closed Issues
314
Open Pull Requests
1
Closed Pull Requests
99

Versions

Versions Released
11/2110/2203
Latest Version Released
Jun 13, 2022
Current Tags
latest3.3.16

Contributors

stephenmcd
stephenmcd
Commits: 116
jpoehnelt
jpoehnelt
Commits: 115
stephenfarrar
stephenfarrar
Commits: 98
amuramoto
amuramoto
Commits: 26
googlemaps-bot
googlemaps-bot
Commits: 8
tqhoughton
tqhoughton
Commits: 5
sarahmaddox
sarahmaddox
Commits: 5
semantic-release-bot
semantic-release-bot
Commits: 4
artofspeed
artofspeed
Commits: 4
arriolac
arriolac
Commits: 3
sverps
sverps
Commits: 3
yfr
yfr
Commits: 2
DaddyWarbucks
DaddyWarbucks
Commits: 2
monajafi
monajafi
Commits: 2
avin-kavish
avin-kavish
Commits: 2