--- title: Capacitor Geocoder Plugin for Android, iOS & Web description: Capacitor plugin for handling geocoding and reverse geocoding with cross-platform support and high performance. tags: - Insiders - Android - iOS - Web search: boost: 2 faq: true github_repo: capawesome-team/capacitor-plugins --- # Capacitor Geocoder Plugin Capacitor plugin for handling geocoding and reverse geocoding.
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## Features The Capacitor Geocoder plugin is one of the most complete geocoding solutions for Capacitor apps. Here are some of the key features: - πŸ–₯️ **Cross-platform**: Supports Android, iOS and Web. - πŸ“ **Geocoding**: Convert addresses into geographic coordinates. - πŸ—ΊοΈ **Reverse Geocoding**: Convert geographic coordinates into human-readable addresses. - 🌐 **Multiple Providers**: Support for Google Maps and OpenStreetMap on Web. - 🌍 **Localization**: Customize the locale for geocoding requests. - πŸ”’ **Configurable Results**: Limit the number of addresses returned in reverse geocoding operations. - πŸ› οΈ **Native APIs**: Uses platform-native geocoding services on Android and iOS for reliable and accurate results. - 🀝 **Compatibility**: Works alongside the [Compass](https://capawesome.io/docs/sdks/capacitor/compass/) and [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/) plugins. - πŸ“¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. - πŸ” **Up-to-date**: Always supports the latest Capacitor version. - ⭐️ **Support**: Priority support from the Capawesome Team. - ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases The Geocoder plugin is typically used whenever an app needs to translate between addresses and coordinates, for example: - **Address search**: Convert a user-entered address into geographic coordinates to display the location on a map. - **Location labeling**: Show a human-readable address for given coordinates, for example the user's current position. - **Address forms**: Prefill address fields such as postal code, country, or administrative area based on coordinates. - **Localized results**: Return addresses in the user's preferred language using the `locale` option. ## Compatibility | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support | | 0.1.x | 7.x.x | Deprecated | ## Demo | Android | iOS | Web | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | Android Demo | iOS Demo | Web Demo | ## Installation This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: ``` npm config set @capawesome-team:registry https://npm.registry.capawesome.io npm config set //npm.registry.capawesome.io/:_authToken ``` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash npx skills add capawesome-team/skills --skill capacitor-plugins ``` Then use the following prompt: ``` Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-geocoder` plugin in my project. ``` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: ```bash npm install @capawesome-team/capacitor-geocoder universal-geocoder npx cap sync ``` ## Usage The following examples show how to convert an address into coordinates and how to convert coordinates back into an address. ### Convert an address into coordinates Use the `geocode(...)` method to translate a human-readable address into geographic coordinates, for example to display the location on a map: ```typescript import { Geocoder } from '@capawesome-team/capacitor-geocoder'; const geocode = async () => { const result = await Geocoder.geocode({ address: '1600 Amphitheatre Parkway, Mountain View, CA', }); console.log('Geocode result:', result); }; ``` ### Convert coordinates into an address Use the `geodecode(...)` method to translate geographic coordinates into one or more human-readable addresses. The number of returned addresses can be limited with the `limit` option: ```typescript import { Geocoder } from '@capawesome-team/capacitor-geocoder'; const geodecode = async () => { const result = await Geocoder.geodecode({ latitude: 37.422, longitude: -122.084, }); console.log('Geodecode result:', result); }; ``` ## API * [`geocode(...)`](#geocode) * [`geodecode(...)`](#geodecode) * [Interfaces](#interfaces) ### geocode(...) ```typescript geocode(options: GeocodeOptions) => Promise ``` Translate an address into geographic coordinates. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------- | | **`options`** | GeocodeOptions | **Returns:** Promise<GeocodeResult> **Since:** 0.0.1 -------------------- ### geodecode(...) ```typescript geodecode(options: GeodecodeOptions) => Promise ``` Translate geographic coordinates into a human-readable address. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------- | | **`options`** | GeodecodeOptions | **Returns:** Promise<GeodecodeResult> **Since:** 0.0.1 -------------------- ### Interfaces #### GeocodeResult | Prop | Type | Description | Since | | --------------- | ------------------- | --------------------------------------- | ----- | | **`latitude`** | number | The latitude of the geocoded location. | 0.0.1 | | **`longitude`** | number | The longitude of the geocoded location. | 0.0.1 | #### GeocodeOptions | Prop | Type | Description | Default | Since | | ------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- | | **`address`** | string | The address to geocode. | | 0.0.1 | | **`locale`** | string | The locale (BCP 47 language tag) to use for the geocoding request. By default, the device's locale is used. | | 0.0.1 | | **`webApiKey`** | string | The API key to use for the geocoding service. Only available on Web. | | 0.0.1 | | **`webProvider`** | 'googlemaps' \| 'openstreetmaps' | The provider to use for the geocoding service. Only available on Web. | 'openstreetmaps' | 0.0.1 | | **`webUserAgent`** | string | The User-Agent identifying your application. Only available on the web. | | 0.0.1 | #### GeodecodeResult | Prop | Type | Description | Since | | --------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----- | | **`addresses`** | Address[] | The list of addresses that match the given coordinates. The number of addresses returned is limited by the `limit` option. | 0.0.1 | #### Address | Prop | Type | Description | Since | | ------------------ | --------------------- | ---------------------------------------------------------------- | ----- | | **`adminArea`** | string | The administrative area (e.g. state or province) of the address. | 0.0.1 | | **`addressLines`** | string[] | The lines of the address. | 0.0.1 | | **`countryCode`** | string | The country code of the address. | 0.0.1 | | **`countryName`** | string | The name of the country. | 0.0.1 | | **`phoneNumber`** | string | The phone number of the address. | 0.0.1 | | **`postalCode`** | string | The postal code of the address. | 0.0.1 | | **`subAdminArea`** | string | The sub-administrative area (e.g. county) of the address. | 0.0.1 | | **`url`** | string | The URL of the address. | 0.0.1 | #### GeodecodeOptions | Prop | Type | Description | Default | Since | | ------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----- | | **`latitude`** | number | The latitude of the location to reverse geocode. | | 0.0.1 | | **`limit`** | number | The maximum number of results to return. | 5 | 0.0.1 | | **`longitude`** | number | The longitude of the location to reverse geocode. | | 0.0.1 | | **`webApiKey`** | string | The API key to use for the geocoding service. Only available on Web. | | 0.0.1 | | **`webProvider`** | 'googlemaps' \| 'openstreetmaps' | The provider to use for the geocoding service. Only available on Web. | 'openstreetmaps' | 0.0.1 | | **`webUserAgent`** | string | The User-Agent identifying your application. Only needed if `webProvider` is set to `openstreetmaps` which uses the Nominatim service (see https://operations.osmfoundation.org/policies/nominatim/). The goal is to be able to limit the number of requests per application. Only available on the web. | | 0.0.1 | ## FAQ ### What is the difference between geocoding and reverse geocoding? Geocoding translates a human-readable address into geographic coordinates, which is what the `geocode` method does. Reverse geocoding is the opposite: the `geodecode` method translates a latitude and longitude into one or more human-readable addresses. ### Which geocoding services does the plugin use? On Android and iOS, the plugin uses the platform-native geocoding services for reliable and accurate results. On the Web, you can choose between Google Maps and OpenStreetMap using the `webProvider` option, with OpenStreetMap being the default. ### Do I need an API key to use this plugin? No API key is required on Android and iOS since the plugin uses the platform-native geocoding services. On the Web, you can provide an API key for the geocoding service using the `webApiKey` option. When using the default OpenStreetMap provider, you should also set the `webUserAgent` option to identify your application, as required by the [Nominatim usage policy](https://operations.osmfoundation.org/policies/nominatim/). ### How can I limit the number of addresses returned by a reverse geocoding request? Use the `limit` option of the `geodecode` method. By default, a maximum of 5 addresses is returned for the given coordinates. ### Can I get results in a specific language? Yes, both methods accept a `locale` option that takes a BCP 47 language tag. If no locale is provided, the device's locale is used. ### Can I use this plugin with Ionic, React, Vue or Angular? Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins - [Compass](https://capawesome.io/docs/sdks/capacitor/compass/): Read the device compass heading. - [Maps Launcher](https://capawesome.io/docs/sdks/capacitor/maps-launcher/): Launch navigation apps with turn-by-turn directions. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geocoder/CHANGELOG.md). ## Breaking Changes See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geocoder/BREAKING.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/geocoder/LICENSE).