Angular Geocoder Autocomplete

Angular component wrapper around @geoapify/geocoder-autocomplete. It adds Angular-friendly inputs, outputs, and tooling so you can search addresses or Geoapify Places categories with minimal setup.

Quick Links

• 📚 Full documentation – includes Quick Start, API reference, and examples.
• ⚡ Quick Start guide – install + configure in minutes.
• 🎯 Examples – ready-to-copy snippets (filters, category search, events).
• 🧪 Demo application – Angular app showcasing every feature.
• 🛠 Build guide – scripts, docs, and publishing checklist.

Repository Layout

Path	Description
projects/angular-geocoder-autocomplete/	Source for the Angular wrapper library and public API.
projects/demo/	Showcases address autocomplete, category search, and event logging.
docs-site/	MkDocs-powered documentation site (Quick Start, API reference, examples).
dist/angular-geocoder-autocomplete/	Build artefacts generated by npm run build.
BUILD.md	Step-by-step instructions for building the library, demo, and docs.

Documentation & Resources

The full docs live in docs-site/ and can be previewed locally with MkDocs (mkdocs serve). Key topics:

• Installation & configuration (Angular module setup, styles, API key management)
• Inputs / outputs tables, including the placesByCategory* API
• Category-search tutorials and lazy loading tips
• Code samples for filters, bias, and event handling

If you publish the docs, link the hosted site here (e.g. GitHub Pages or internal portal).

Getting Started

1. Install dependencies

   npm install @geoapify/geocoder-autocomplete @geoapify/angular-geocoder-autocomplete

2. Configure the module (use an environment-stored API key):

   import { GeoapifyGeocoderAutocompleteModule } from '@geoapify/angular-geocoder-autocomplete';
   
   @NgModule({
     imports: [
       GeoapifyGeocoderAutocompleteModule.withConfig(environment.geoapifyKey)
     ]
   })
   export class AppModule {}

3. Load a theme (angular.json snippet):

   "styles": [
     "node_modules/@geoapify/geocoder-autocomplete/styles/round-borders.css",
     "src/styles.scss"
   ]

4. Drop the component into a template:

   <geoapify-geocoder-autocomplete
     [lang]="'en'"
     [limit]="10"
     (placeSelect)="onPlaceSelected($event)">
   </geoapify-geocoder-autocomplete>

5. Category search essentials (new placesByCategory* API):

   <geoapify-geocoder-autocomplete
     [addCategorySearch]="true"
     [showPlacesByCategoryList]="true"
     [enablePlacesByCategoryLazyLoading]="true"
     [placesByCategoryLimit]="15"
     (placesByCategoryChange)="onPlaces($event)"
     (placeByCategorySelect)="onPlaceFromList($event)"
     (placesByCategoryRequestStart)="onPlacesLoading($event)">
   </geoapify-geocoder-autocomplete>

   The docs contain the full list of inputs/outputs and advanced hooks (placesByCategoryFilter, sendPlacesByCategoryRequestFunc, etc.).

Demo Application

The projects/demo workspace illustrates real-world forms and all event emitters.

1. Replace the demo API key in projects/demo/src/app/app.module.ts.
2. Run npm run start from the repo root (Angular CLI serves the demo on http://localhost:4200).
3. Edits in the library automatically hot-reload into the demo.

npm Scripts

Command	Description
npm run build	Builds the Angular library via ng build angular-geocoder-autocomplete.
npm run start	Serves the demo application.
npm run test	Runs unit tests.
npm run lint	Lints the workspace using ESLint.
npm run e2e	Placeholder for end-to-end tests (configure as needed).

More detail on these workflows lives in BUILD.md.

Compatibility Matrix

@geoapify/angular-geocoder-autocomplete	Angular Version
1.0.x	9.x
1.1.x	9.x
1.2.x	10.x
1.3.0 - 1.3.1	11.x
1.3.2 - 1.3.3	12.x
1.3.4 - 1.3.5	13.x
1.3.6 - 1.3.x	14.x
2.0.0	15.x
2.0.1	15.x-16.x
2.0.2	17.x-18.x
2.2.0	19.x-20.x
3.0.0	19.x-20.x

Installation

@geoapify/angular-geocoder-autocomplete has a peer dependency on @geoapify/geocoder-autocomplete. To install both dependencies, use the following commands:

npm install @geoapify/geocoder-autocomplete @geoapify/angular-geocoder-autocomplete
# or 
yarn add @geoapify/geocoder-autocomplete @geoapify/angular-geocoder-autocomplete

Transitioning from version 1.x to 2.x: Replacing skipDetails with addDetails

In version 2.x of the library, we've replaced the skipDetails option with addDetails. This update provides greater clarity, indicating whether you want to include or exclude additional details in your search results. To ensure compatibility with the new version, remember to adjust your code accordingly by using the addDetails option when you need place details in your search results.

Getting Your Geoapify API Key

If you opt to integrate the Geoapify API for address searches, securing an API key is a prerequisite.

To obtain your API key, you can complete the registration process at myprojects.geoapify.com. It's worth noting that Geoapify offers a versatile Freemium pricing model, affording you the opportunity to initiate your API usage at no initial cost and seamlessly expand your access to our services to align with your evolving requirements.

Usage

1. Import the module

Incorporate the GeoapifyGeocoderAutocompleteModule into your Angular application by importing it as demonstrated below:

// Import necessary modules from Angular and external libraries.
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { GeoapifyGeocoderAutocompleteModule } from '@geoapify/angular-geocoder-autocomplete';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    // Configure the Angular application's modules.
    BrowserModule,
    // Integrate the Geoapify Geocoder Autocomplete Module.
    // Make sure to replace 'YOUR_API_KEY' with your actual API key.
    GeoapifyGeocoderAutocompleteModule.withConfig('YOUR_API_KEY')
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

2. Import styles

Import the CSS styling file from @geoapify-geocoder-autocomplete to ensure the proper appearance of the control. You have the flexibility to choose from a variety of styles to suit your webpage's aesthetics, including options such as:

• minimal and round-borders for webpages with light background colors.
• minimal-dark and round-borders-dark for webpages with dark background colors.

Option 1: Adding to angular.json when Using Angular CLI:

"styles": [
  "node_modules/@geoapify/geocoder-autocomplete/styles/minimal.css",
  "src/styles.css"
]

Option 2: Direct import into your global stylesheet:

@import "~@geoapify/geocoder-autocomplete/styles/minimal.css";

3. Use the control in templates

<geoapify-geocoder-autocomplete
  [placeholder]="'Search address or places'"
  (placeSelect)="onPlaceSelected($event)">
</geoapify-geocoder-autocomplete>

Standalone usage

If you prefer to integrate the geocoder-autocomplete without the Angular wrapper, refer to the standalone usage guide.

License

MIT