@googlemaps/google-maps-services-js: A Server-Side Node.js Client for Google Maps Web Services

What this package replaces, and who it is for

Google Maps Platform exposes its web services as HTTP endpoints, so any Node.js service can call them with a bare HTTP client. What that leaves you to handle is the boring part: building query strings, keeping the API key out of the URL in a consistent place, wiring an HTTP agent, and deciding what a timeout or a retry means. This library is the official Node.js client that does that work, and the repository describes it as bringing the Maps Static, Elevation, Geocoding, Roads and Time Zone APIs to server-side Node.js applications, plus three legacy APIs: Directions, Places and Distance Matrix. The audience is narrow on purpose. The README carries a note in bold that server-side Node.js applications are the only supported environment, and that browser or React Native usage may sometimes work but mostly will not, with a request not to file issues for those environments. If you are building a front end, the README points you at the Maps JavaScript API instead.

How the client is put together: Axios, retry-axios and per-method params

The published package depends on axios, retry-axios, agentkeepalive, query-string and @googlemaps/url-signature, according to package.json. That dependency list explains the shape of the API. Every service method takes a single object with params, headers, body, instance and timeout, and those fields map onto the Axios request config, which is why the README says the design gives direct access to the transport layer. The client class itself holds no API key. In the older @google/maps library the key was configured once at client creation; here it is passed per method inside the params object. The README's migration table states this plainly, and also notes that retry is configurable rather than simply supported, which is where retry-axios comes in. The practical consequence is that one process can hold several clients and switch keys or Axios instances per call, and that a custom Axios instance is a supported extension point rather than a workaround. The README also states that the two libraries share no methods or interfaces, so a migration is a rewrite of call sites, not a shim.

Installing it and making a first elevation call

Installation is a single npm command against the scoped package name.

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

Import the Client class. The README shows both the ES module form and the CommonJS form; the CommonJS one is what a plain Node.js script without ES6 module support would use.

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

The first real call in the README is the elevation method. Note that the key sits inside params, the timeout is expressed in milliseconds, and the response is read from r.data.results, which is the Axios response shape rather than a bare JSON body.

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);
  });

If the call fails, the catch block reads e.response.data.error_message, so an error from the service arrives as an Axios error with the API's own message nested in it. Before any of this runs, the requirements section lists three prerequisites: sign up with Google Maps Platform, have a project with the desired APIs enabled, and hold an API key associated with that project.

The legacy split is the constraint to plan around

The most consequential detail in the README is not a method signature but a warning box. Some parts of the library are compatible only with Legacy Services, and using them requires enabling each API individually on the Google Cloud project through direct console links: Places API (Legacy), Directions API (Legacy) and Distance Matrix API (Legacy). Meanwhile the newer Google Maps APIs each ship as their own npm package, and the README names four of them: @googlemaps/places, @googlemaps/routing, @googlemaps/maps-platform-datasets and @googlemaps/addressvalidation. Read together, those two statements mean this package is not the forward path for places or routing work. It is the client for the non-legacy Elevation, Geocoding, Roads, Time Zone and Maps Static services, plus a legacy surface that Google keeps behind separate enablement. A team starting fresh on place search today would be enabling a legacy API and adopting a client whose newer sibling already exists. That is a real cost, and the README does not offer a migration path from the legacy methods in this package to the separate packages.

Where it breaks: browser code, missing APIs and key handling

Three failure modes are worth naming. First, the environment. The README's note is unambiguous that client-side use is unsupported, so bundling this into a front end is the wrong tool even if a build happens to succeed. Second, coverage. If the service you need is Places or Routing in its current form, this library is the wrong dependency, not a partial one, because the README directs those to separate packages. Third, key exposure. The library is designed for server-side applications, and the README says it is important to add API key restrictions and to keep the key out of version control, linking to Google's API Security Best Practices guide. Because the key is passed per method in params rather than configured once on the client, every call site is a place where a key can be logged, copied into a test fixture or committed by accident. The README does not document a built-in redaction or secret-loading mechanism, so that discipline is on your code. The README also does not document rollback behaviour for the client itself, and the release notes are not reproduced in the README, so version pinning is the only rollback story visible here.

How it differs from calling the REST endpoints directly

The obvious alternative is to skip the client and call the Google Maps web service endpoints with fetch or a plain HTTP library. The difference is not capability, since the endpoints are the same. It is what you inherit. Calling directly means you own query string construction, the keep-alive agent, timeout handling and retry policy, and you get raw JSON back with no TypeScript types. This library supplies axios with agentkeepalive underneath, retry-axios for configurable retries, query-string for parameter serialisation and url-signature as a dependency, and it ships TypeScript types that the README calls the authoritative documentation, noting they may differ slightly from the prose descriptions. That last point is worth taking literally: when the README and the types disagree, the types win. For a small script that geocodes one address, a direct fetch is less machinery. For a service making many calls with retries and timeouts, the client removes code you would otherwise write and test yourself.

Maintenance, licence and the upgrade question

The repository is not archived, and the last push was on 2026-09-13. The most recent release listed is v3.4.2 on 2025-07-06, preceded by v3.4.1 on 2025-03-28 and v3.4.0 on 2024-04-09, so the release cadence over that window is roughly one minor or patch release every few months. The package is published under Apache-2.0, the same licence as the repository, which permits commercial use and modification with the usual notice and attribution conditions; that is a description of the licence text, not legal advice, and anyone embedding it in a distributed product should read LICENSE.md in the repository. On upgrade cost, the version is 3.x and the README's migration section covers the 1.x-era move from @google/maps, not upgrades within 3.x. Because the client is a thin layer over Axios, most of the upgrade risk sits in the axios and retry-axios ranges declared in package.json rather than in the Maps methods themselves. The README does not describe a deprecation timeline for the legacy Directions, Places and Distance Matrix methods, so anyone depending on them should treat that silence as the open question rather than assume a date.

Editorial conclusion

Adopt it if your geocoding, routing or elevation calls already run in a Node.js backend and you want axios-level control over timeout, headers and retry behaviour. Skip it if your code runs in a browser or React Native, since the README states server-side Node.js is the only supported environment, or if you need the newer Places and Routing APIs, which ship as separate packages such as @googlemaps/places. Before committing, enable the exact APIs you intend to call in your Google Cloud project, including the Legacy variants, and confirm whether the per-method key in params fits how you inject secrets today.

Frequently asked questions

Official sources

1. googlemaps/google-maps-services-js on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases