npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

@googlemaps/google-maps-services-js

v3.4.1

Published

Node.js client library for Google Maps API Web Services

Downloads

1,697,367

Readme

npm Release Stable Tests/Build

codecov semantic-release

Contributors License StackOverflow Discord

Node.js Client for Google Maps Services

[!IMPORTANT]

Some parts of this library are only compatible with Legacy Services. Using the Legacy Services requires enabling each API on your Google Cloud project by following the direct links: Places API (Legacy), Directions API (Legacy), Distance Matrix API (Legacy).

The newer Google Maps APIs each provide their own npm-package:

Description

This client library brings the following [Google Maps Web Services APIs] to your server-side Node.js applications:

As well as the following legacy APIs:

Requirements

API Key Security

This client library is designed for use in server-side applications.

In either case, it is important to add API key restrictions to improve its security. Additional security measures, such as hiding your key from version control, should also be put in place to further improve the security of your API key.

Check out the API Security Best Practices guide to learn more.

[!NOTE] This library for server-side only 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.

Usage

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: process.env.MAPS_API_KEY,
    },
    timeout: 1000, // milliseconds
  })
  .then((r) => {
    console.log(r.data.results[0].elevation);
  })
  .catch((e) => {
    console.log(e.response.data.error_message);
  });

Documentation

For more information, see the reference documentation. 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 MAPS_API_KEY=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.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);
  });

Contributing

Contributions are welcome and encouraged! If you'd like to contribute, send us a pull request and refer to our code of conduct and contributing guide.

Terms of Service

This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform Terms of Service.

This library is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g. Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this library.

Support

This library is offered via an open source license. It is not governed by the Google Maps Platform Support [Technical Support Services Guidelines, the SLA, or the Deprecation Policy. However, any Google Maps Platform services used by the library remain subject to the Google Maps Platform Terms of Service.

This library adheres to semantic versioning to indicate when backwards-incompatible changes are introduced. Accordingly, while the library is in version 0.x, backwards-incompatible changes may be introduced at any time.

If you find a bug, or have a feature request, please file an issue on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, ask through one of our developer community channels. If you'd like to contribute, please check the contributing guide.

You can also discuss this library on our Discord server.