@googlemaps/google-maps-services-js

This client library provides access to the following Google Maps Web Services APIs:

Standard APIs:

• Maps Static API
• Elevation API
• Geocoding API
• Roads API
• Time Zone API

Legacy APIs:

• Directions API (Legacy)
• Places API (Legacy)
• Distance Matrix API (Legacy)

To use this client library in your Node.js application, install it using npm:

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

The library is designed for server-side Node.js applications. You can import the Client using ES6 modules (TypeScript) or CommonJS. Methods take an object containing params, timeout, and optionally headers or an axiosInstance. Note that the API key is configured within the params object of each method call, rather than at the client instantiation level.

import {Client} from "@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
  })
  .then((r) => {
    console.log(r.data.results[0].elevation);
  })
  .catch((e) => {
    console.log(e.response.data.error_message);
  });

The new library differs significantly from the old @google/maps package. Key differences include:

• Parameter Passing: Instead of individual arguments, methods now take an object containing params, headers, body, instance, and timeout.
• API Key Configuration: The API key is now passed within the params object of each method call, not during client creation.
• Promises: Promises are now the default return type.
• Typings: TypeScript types are included in the package (previously required @types/googlemaps).
• Advanced Features: Supports keep-alive, interceptors, cancellation, and configurable retries (via axios-retry or retry-axios).

For legacy applications using the Google Maps Platform Premium Plan, you can authenticate using a client_id and client_secret within the params object of your method calls.

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
  })
  .then(r => {
    console.log(r.data.results[0].elevation);
  })
  .catch(e => {
    console.log(e.response.data.error_message);
  });

The LatLng type is flexible and accepts several formats for representing geographic coordinates. You can use:

• A two-item array: [latitude, longitude]
• A comma-separated string: 'latitude,longitude'
• An object with lat and lng properties: { lat: number, lng: number }
• An object with latitude and longitude properties: { latitude: number, longitude: number }

export type LatLng =
  | LatLngArray
  | LatLngString
  | LatLngLiteral
  | LatLngLiteralVerbose;

The Client class is a wrapper around Google Maps API methods that provides shared configuration for Axios settings, including retry logic (via retry-axios) and gzip encoding. You can instantiate the client in three ways:

1. With defaults: Uses default timeout (10000ms), default HTTPS agent, and default retry settings.
2. With a config object: Provides custom AxiosRequestConfig (including raxConfig for retries).
3. With an existing Axios instance: For advanced use cases where you want to provide your own pre-configured instance.

Note: You cannot provide both axiosInstance and config simultaneously.