zircon-tech · gtorterolo-zircon · Feb 5, 2024 · Feb 5, 2024 · Feb 5, 2024 · Feb 5, 2024
diff --git a/.github/release-please-config.json b/.github/release-please-config.json
@@ -0,0 +1,3 @@
+{
+  "bump-minor-pre-major": true
+}
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -21,11 +21,11 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup node
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
-        node_version: 18
+        node_version: 22
         cache: npm
         cache-dependency-path: package-lock.json
     - run: npm ci

diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
@@ -32,27 +32,27 @@ jobs:
     steps:
       - id: release
         name: Release Please
-        uses: google-github-actions/release-please-action@v3
+        uses: googleapis/release-please-action@v4
 
         with:
           release-type: node
           token: ${{ secrets.SYNCED_GITHUB_TOKEN_REPO }}
           package-name: "@googlemaps/google-maps-services-js"
-          bump-minor-pre-major: true
+          config-file: .github/release-please-config.json
 
       # Everything below is for NPM publishing when a release is cut.
       # Note the "if" statement on all commands to make sure that publishing
       # only happens when a release is cut.
 
       - if: ${{ steps.release.outputs.release_created }}
         name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - if: ${{ steps.release.outputs.release_created }}
         name: Setup Node for Dependency Installation
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
 
       - if: ${{ steps.release.outputs.release_created }}
@@ -62,7 +62,7 @@ jobs:
       # Now configure node with the registry used for publishing
       - if: ${{ steps.release.outputs.release_created }}
         name: Setup Node for Publishing
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 20
           registry-url: "https://wombat-dressing-room.appspot.com/"

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -25,13 +25,13 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [16.x, 18.x, 20.x]
+        node-version: [18.x, 20.x, 22.x]
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: npm

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,22 @@
+# Changelog
+
+## [3.4.2](https://github.com/googlemaps/google-maps-services-js/compare/v3.4.1...v3.4.2) (2025-07-06)
+
+
+### Documentation
+
+* update readme with remark on EEA ToS ([#1379](https://github.com/googlemaps/google-maps-services-js/issues/1379)) ([2da8802](https://github.com/googlemaps/google-maps-services-js/commit/2da880287a31022922e8c3bb5915913e7ee291a6))
+
+## [3.4.1](https://github.com/googlemaps/google-maps-services-js/compare/v3.4.0...v3.4.1) (2025-03-28)
+
+
+### Bug Fixes
+
+* trigger release-please ([#1337](https://github.com/googlemaps/google-maps-services-js/issues/1337)) ([1e7c9e6](https://github.com/googlemaps/google-maps-services-js/commit/1e7c9e6da0a8350421a558c027a6759daa8a4c50))
+
+## [3.4.0](https://github.com/googlemaps/google-maps-services-js/compare/v3.3.42...v3.4.0) (2024-04-09)
+
+
+### Features
+
+* Added Address Descriptors to Geocoding response. ([#1187](https://github.com/googlemaps/google-maps-services-js/issues/1187)) ([47db368](https://github.com/googlemaps/google-maps-services-js/commit/47db36856c2235433d01b1d82d6965cdef07b6b6))
diff --git a/README.md b/README.md
@@ -1,43 +1,70 @@
-Node.js Client for Google Maps Services
-=======================================
-
-[![npm](https://img.shields.io/npm/v/@googlemaps/google-maps-services-js.svg)](https://www.npmjs.com/package/@googlemaps/google-maps-services-js)
-![Test](https://github.com/googlemaps/google-maps-services-js/workflows/Test/badge.svg)
+[![npm](https://img.shields.io/npm/v/@googlemaps/google-maps-services-js)][npm-pkg]
 ![Release](https://github.com/googlemaps/google-maps-services-js/workflows/Release/badge.svg)
+![Stable](https://img.shields.io/badge/stability-stable-green)
+[![Tests/Build](https://github.com/googlemaps/google-maps-services-js/actions/workflows/test.yml/badge.svg)](https://github.com/googlemaps/google-maps-services-js/actions/workflows/test.yml)
+
 [![codecov](https://codecov.io/gh/googlemaps/google-maps-services-js/branch/master/graph/badge.svg)](https://codecov.io/gh/googlemaps/google-maps-services-js)
-![GitHub contributors](https://img.shields.io/github/contributors/googlemaps/google-maps-services-js?color=green)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
-[![Discord](https://img.shields.io/discord/676948200904589322)](https://discord.gg/jRteCzP)
 
+![Contributors](https://img.shields.io/github/contributors/googlemaps/google-maps-services-js?color=green)
+[![License](https://img.shields.io/github/license/googlemaps/google-maps-services-js?color=blue)][license]
+[![StackOverflow](https://img.shields.io/stackexchange/stackoverflow/t/google-maps?color=orange&label=google-maps&logo=stackoverflow)](https://stackoverflow.com/questions/tagged/google-maps)
+[![Discord](https://img.shields.io/discord/676948200904589322?color=6A7EC2&logo=discord&logoColor=ffffff)][Discord server]
+
+# Node.js Client for Google Maps Services
+
+> [!IMPORTANT]
+> 
+> Some parts of this library are only compatible with [Legacy Services](https://developers.google.com/maps/legacy).
+> Using the Legacy Services requires enabling each API on your Google Cloud project by following the direct links:
+> [Places API (Legacy)](https://console.cloud.google.com/apis/library/places-backend.googleapis.com),
+> [Directions API (Legacy)](https://console.cloud.google.com/apis/library/directions-backend.googleapis.com),
+> [Distance Matrix API (Legacy)](https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com).
+>
+> The newer Google Maps APIs each provide their own npm-package:
+>  - [`@googlemaps/places`](https://www.npmjs.com/package/@googlemaps/places)
+>  - [`@googlemaps/routing`](https://www.npmjs.com/package/@googlemaps/routing)
+>  - [`@googlemaps/maps-platform-datasets`](https://www.npmjs.com/package/@googlemaps/maps-platform-datasets)
+>  - [`@googlemaps/addressvalidation`](https://www.npmjs.com/package/@googlemaps/addressvalidation)
+
+## Description
+
+This client library brings the following [Google Maps Web Services APIs] to your server-side Node.js applications:
 
-> This library is a refactor of a previous version published to [@google/maps](https://www.npmjs.com/package/@google/maps). It is now being published to [@googlemaps/google-maps-services-js](https://www.npmjs.com/package/@googlemaps/google-maps-services-js).
+- [Maps Static API]
+- [Elevation API]
+- [Geocoding API]
+- [Roads API]
+- [Time Zone API]
 
-Use Node.js? Want to [geocode][Geocoding API] something? Looking
-for [directions][Directions API]?
-This library brings the [Google Maps API Web Services] to your Node.js
-application.
+As well as the following legacy APIs:
 
-The Node.js Client for Google Maps Services is a Node.js Client library
-for the following Google Maps APIs:
+- [Directions API (Legacy)][Directions API]
+- [Places API (Legacy)][Places API]
+- [Distance Matrix API (Legacy)][Distance Matrix API]
 
- - [Directions API]
- - [Distance Matrix API]
- - [Elevation API]
- - [Geocoding API]
- - [Places API]
- - [Roads API]
- - [Time Zone API]
+## Requirements
 
-Keep in mind that the same [terms and conditions](https://developers.google.com/maps/terms)
-apply to usage of the APIs when they're accessed through this library.
+- [Sign up with Google Maps Platform]
+- A Google Maps Platform [project] with the desired API(s) from the above list enabled
+- An [API key] associated with the project above
 
-## Attention!
+## API Key Security
 
-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.
+This client library is designed for use in server-side applications.
 
-## Quick Start
+In either case, it is important to add [API key restrictions](https://developers.google.com/maps/api-security-best-practices#restricting-api-keys) 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.
 
-    $ npm install @googlemaps/google-maps-services-js
+Check out the [API Security Best Practices](https://developers.google.com/maps/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.
 
@@ -61,7 +88,7 @@ client
   .elevation({
     params: {
       locations: [{ lat: 45, lng: -110 }],
-      key: process.env.GOOGLE_MAPS_API_KEY,
+      key: process.env.MAPS_API_KEY,
     },
     timeout: 1000, // milliseconds
   })
@@ -73,27 +100,28 @@ client
   });
 ```
 
-## Reference Documentation
+## Documentation
 
-The generated reference documentation can be found [here](https://googlemaps.github.io/google-maps-services-js/). The TypeScript types are the authoritative documentation for this library and may differ slightly from the descriptions.
+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 GOOGLE_MAPS_API_KEY=AIza-your-api-key
+    $ export MAPS_API_KEY=YOUR_API_KEY
     $ npm test
 
 ## Migration
 
-This section discusses the migration from [@google/maps](https://www.npmjs.com/package/@google/maps) to [@googlemaps/google-maps-services-js](https://www.npmjs.com/package/@googlemaps/google-maps-services-js) and the differences between the two.
+This section discusses the migration from [@google/maps](https://npmjs.com/package/@google/maps) to [@googlemaps/google-maps-services-js][npm-pkg] 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](https://github.com/axios/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`):
+### Old (`@google/maps`)
+
 ```js
 const googleMapsClient = require('@google/maps').createClient({
   key: 'your API key here'
@@ -120,7 +148,7 @@ client
   .elevation({
     params: {
       locations: [{ lat: 45, lng: -110 }],
-      key: process.env.GOOGLE_MAPS_API_KEY
+      key: process.env.MAPS_API_KEY
     },
     timeout: 1000 // milliseconds
   }, axiosInstance)
@@ -138,9 +166,9 @@ The primary differences are in the following table.
 | ------------- |:-------------:|
 | Can provide params     | Can provide params, headers, instance, timeout (see [Axios Request Config](https://github.com/axios/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](https://www.npmjs.com/package/axios-retry) or [retry-axios](https://www.npmjs.com/package/retry-axios)      |
+| Retry is supported      | Retry is configurable via [axios-retry](https://npmjs.com/package/axios-retry) or [retry-axios](https://npmjs.com/package/retry-axios)      |
 | Does not use promises by default | Promises are default     |
-| Typings are in [@types/googlemaps](https://www.npmjs.com/package/@types/googlemaps) | Typings are included |
+| Typings are in [@types/googlemaps](https://npmjs.com/package/@types/googlemaps) | Typings are included |
 | Does not support keep alive | Supports keep alive |
 | Does not support interceptors | Supports [interceptors](https://github.com/axios/axios#interceptors)|
 | Does not support cancelalation | Supports [cancellation](https://github.com/axios/axios#cancellation) |
@@ -169,36 +197,59 @@ client
   });
 ```
 
+## 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.
+
+
+### European Economic Area (EEA) developers
+
+If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](https://developers.google.com/maps/comms/eea/faq).
 
 ## 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][issues]. If you'd like to contribute, please read
-[How to Contribute][contrib].
-
-[apikey]: https://developers.google.com/maps/faq#keysystem
-[clientid]: https://developers.google.com/maps/documentation/business/webservices/auth
-
-[Google Maps API Web Services]: https://developers.google.com/maps/apis-by-platform#web_service_apis
-[Directions API]: https://developers.google.com/maps/documentation/directions/
+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].
+
+[Google Maps Platform Web Services APIs]: https://developers.google.com/maps/apis-by-platform#web_service_apis
+[Maps Static API]: https://developers.google.com/maps/documentation/maps-static
+[Directions API]: https://developers.google.com/maps/documentation/directions
 [directions-key]: https://developers.google.com/maps/documentation/directions/get-api-key#key
-[Distance Matrix API]: https://developers.google.com/maps/documentation/distancematrix/
-[Elevation API]: https://developers.google.com/maps/documentation/elevation/
-[Geocoding API]: https://developers.google.com/maps/documentation/geocoding/
-[Time Zone API]: https://developers.google.com/maps/documentation/timezone/
-[Roads API]: https://developers.google.com/maps/documentation/roads/
-[Places API]: https://developers.google.com/places/web-service/
-
-[issues]: https://github.com/googlemaps/google-maps-services-js/issues
-[contrib]: https://github.com/googlemaps/google-maps-services-js/blob/master/CONTRIBUTING.md
-[Maps JavaScript API]: https://developers.google.com/maps/documentation/javascript/
+[Distance Matrix API]: https://developers.google.com/maps/documentation/distancematrix
+[Elevation API]: https://developers.google.com/maps/documentation/elevation
+[Geocoding API]: https://developers.google.com/maps/documentation/geocoding
+[Time Zone API]: https://developers.google.com/maps/documentation/timezone
+[Roads API]: https://developers.google.com/maps/documentation/roads
+[Places API]: https://developers.google.com/places/web-service
+[Maps JavaScript API]: https://developers.google.com/maps/documentation/javascript
+
+[API key]: https://developers.google.com/maps/documentation/javascript/get-api-key
+[documentation]: https://googlemaps.github.io/google-maps-services-js
+[npm-pkg]: https://npmjs.com/package/@googlemaps/google-maps-services-js
+
+[code of conduct]: ?tab=coc-ov-file#readme
+[contributing guide]: CONTRIBUTING.md
+[Deprecation Policy]: https://cloud.google.com/maps-platform/terms
+[developer community channels]: https://developers.google.com/maps/developer-community
+[Discord server]: https://discord.gg/hYsWbmk
+[file an issue]: https://github.com/googlemaps/google-maps-services-js/issues/new/choose
+[license]: LICENSE
+[pull request]: https://github.com/googlemaps/google-maps-services-js/compare
+[project]: https://developers.google.com/maps/documentation/javascript/cloud-setup#enabling-apis
+[semantic versioning]: https://semver.org
+[Sign up with Google Maps Platform]: https://console.cloud.google.com/google/maps-apis/start
+[similar inquiry]: https://github.com/googlemaps/google-maps-services-js/issues
+[SLA]: https://cloud.google.com/maps-platform/terms/sla
+[Technical Support Services Guidelines]: https://cloud.google.com/maps-platform/terms/tssg
+[Terms of Service]: https://cloud.google.com/maps-platform/terms
diff --git a/e2e/geocode/reversegeocode.test.ts b/e2e/geocode/reversegeocode.test.ts
@@ -36,3 +36,19 @@ test("reverseGeocode should return correct response using place_id", async () =>
   const r = await reverseGeocode({ params: params });
   expect(r.data.results.length).toBeTruthy();
 });
+
+
+test("reverseGeocode should return correct response when address descriptors are enabled", async () => {
+  const params = {
+    latlng: {
+      lat: 28.650080,
+      lng: 77.233172,
+    },
+    enable_address_descriptor: true,
+    key: process.env.GOOGLE_MAPS_API_KEY,
+  };
+  const r = await reverseGeocode({ params: params });
+  console.log("Response data:", r.data);
+  console.log("Address descriptor:", r.data.address_descriptor);
+  expect(r.data.address_descriptor.landmarks.length > 0).toBeTruthy();
+});