Repository files navigation

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

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

As well as the following legacy APIs:

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

• Sign up with Google Maps Platform
• A Google Maps Platformproject with the desired API(s) from the above list enabled
• AnAPI key associated with the project above

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

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

Check out theAPI Security Best Practices guide to learn more.

[!NOTE]This library for server-side onlyAttempting 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, sinceserver-side Node.js applications is the only supported environment for this library.For other environments, try theMaps JavaScript API, which contains a comparable feature set, and is explicitly intended for use with client-side JavaScript.

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.

constclient=newClient({});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);});

For more information, see the referencedocumentation. The TypeScript types are the authoritative documentation for this library and may differ slightly from the descriptions.

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

$ export MAPS_API_KEY=YOUR_API_KEY$ npm test

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 takeparams,headers,body,instance(seeAxios). This allows direct access to the transport layer without the complexity that was inherent in the old library. Below are two examples.

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

constclient=newClient({});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.

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.

constclient=newClient({});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);});

Contributions are welcome and encouraged! If you'd like to contribute, send us apull request and refer to ourcode of conduct andcontributing guide.

This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps PlatformTerms 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.

If your billing address is in the European Economic Area, effective on 8 July 2025, theGoogle Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region.Learn more.

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

This library adheres tosemantic 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, pleasefile an issue on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, ask through one of ourdeveloper community channels. If you'd like to contribute, please check thecontributing guide.

You can also discuss this library on ourDiscord server.