Angular Google Maps Places API

Angular Google Maps Places Logo
Angular library that provides a seamless integration with new Google Maps Places API, offering easy-to-use services for place details retrieval and management in Angular applications.
Compatible with Angular **>= 18.x.x**. See Versioning.

Demo

[![Build](https://github.com/lekhmanrus/ngx-google-maps-places/actions/workflows/build.yml/badge.svg)](https://github.com/lekhmanrus/ngx-google-maps-places/actions/workflows/build.yml) [![Publish](https://github.com/lekhmanrus/ngx-google-maps-places/actions/workflows/publish.yml/badge.svg)](https://github.com/lekhmanrus/ngx-google-maps-places/actions/workflows/publish.yml) [![npm version](https://img.shields.io/npm/v/ngx-google-maps-places-api.svg)](https://www.npmjs.com/package/ngx-google-maps-places-api) [![npm](https://img.shields.io/npm/dm/ngx-google-maps-places-api.svg)](https://www.npmjs.com/package/ngx-google-maps-places-api) ![Example](https://raw.githubusercontent.com/lekhmanrus/ngx-google-maps-places/main/assets/animation.gif)
## Features * Autocomplete suggestions for places * Place details fetching * Address component parsing ## Installation ```sh npm install --save ngx-google-maps-places-api ``` ## Getting the API Key Follow [these steps](https://developers.google.com/maps/gmp-get-started) to get an API key that can be used to load Google Maps. ## Loading the API Include the [Dynamic Library Import script](https://developers.google.com/maps/documentation/javascript/load-maps-js-api#dynamic-library-import) in the `index.html` of your app. When a Google Map is being rendered, it'll use the Dynamic Import API to load the necessary JavaScript automatically. ```html ... ``` **Note:** the component also supports loading the API using the [legacy script tag](https://developers.google.com/maps/documentation/javascript/load-maps-js-api#use-legacy-tag), however it isn't recommended because it requires all of the Google Maps JavaScript to be loaded up-front, even if it isn't used. ## Usage Inject the `NgxGoogleMapsPlacesApiService` in your Angular component/directive/etc: ```ts import { Directive, inject } from '@angular/core'; import { NgxGoogleMapsPlacesApiService } from 'ngx-google-maps-places-api'; @Directive({ selector: 'app-test', standalone: true }) export class AppTestDirective { private readonly _ngxGoogleMapsPlacesApiService = inject(NgxGoogleMapsPlacesApiService); // Use the service methods } ``` ## Versioning Library tested for Angular versions **>= 18.x.x**. Versions are consistent with major Angular version. E.g.: Use `v18.x.x` with Angular `18.x.x`. ## Dependencies * Angular * RxJs ## API reference ### NgxGoogleMapsPlacesApiService **Methods** * `refreshToken`
Refreshes the Google Maps Places autocomplete session token. The session token is used to associate autocomplete suggestions with a particular session. This method creates a new session token and stores it in the service. * `fetchSuggestions`
Fetches autocomplete suggestions from the Google Maps Places API based on the provided request or input string. | Name | Description | |--------------------------------------------------------------------|------------------------------------------------------------------------------| | **Parameters** | | | `requestOrInput: google.maps.places.AutocompleteRequest \| string` | The autocomplete request object or an input string to fetch suggestions for. | | **Returns** | | | `Observable` | An observable that emits an array of autocomplete suggestions. | * `fetchPlaceDetails`
Fetches the details of a Google Maps place based on an autocomplete suggestion or place prediction. | Name | Description | |-----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------| | **Parameters** | | | `suggestionOrPrediction: google.maps.places.AutocompleteSuggestion \| google.maps.places.PlacePrediction` | The autocomplete suggestion or place prediction to fetch details for. | | `fields: string[]` | An optional array of fields to fetch for the place. Defaults to `[ 'addressComponents' ]`. | | **Returns** | | | `Observable` | An observable that emits the fetched place details, or null if the place prediction is invalid. | * `parseAddressComponents`
Parses the address components of a Google Maps place and returns an `AddressModel` object. | Name | Description | |-------------------------------------------|---------------------------------------------------------------------| | **Parameters** | | | `place: google.maps.places.Place \| null` | The Google Maps place object to parse the address components from. | | **Returns** | | | `AddressModel \| null` | An `AddressModel` object containing the parsed address components, or `null` if the place is null or has no address components. | * `applyBoldToMatches`
Applies bold formatting to the matched text within the provided `FormattableText` (see [FormattableText](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places/autocomplete#formattabletext)).. | Name | Description | |---------------------------------------------------------------|-------------------------------------------------------------| | **Parameters** | | | `formattableText: google.maps.places.FormattableText \| null` | The `FormattableText` object containing the text and match information. | | **Returns** | ****| | `string` | The formatted text with the matched portions wrapped in `` tags. | ## Build Run `ng build ngx-google-maps-places-api` to build the project. The build artifacts will be stored in the `dist/` directory. ## Running unit tests Run `ng test ngx-google-maps-places-api` to execute the unit tests via [Jest](https://jestjs.io/). ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.