DOCSEARCHbyAlgolia
Submit Docs

geocoding Flutter Plugin

repository·main·Indexed 41 days ago

https://github.com/baseflow/flutter-geocoding

A Flutter plugin providing geocoding capabilities to convert addresses to coordinates and vice versa using a federated architecture. Starting with version 5.0.0, all methods are grouped within the Geocoding class. It provides key methods such as locationFromAddress, placemarkFromAddress, and placemarkFromCoordinates, and supports locale configuration via the Geocoding constructor or individual method parameters.

Tokens
3.5K
Snippets
13
Records
16
Agent score
100%

What's inside geocoding

  1. Understand the geocoding federated plugin architecture

    main

    The flutter-geocoding plugin uses a federated plugin architecture. This means the functionality is split into specialized packages to separate the user-facing API from the platform-specific implementations:

    1. geocoding: The primary app-facing package. This is the only package you should depend on in your Flutter project to access geocoding features. It currently includes the Android and iOS platform implementations.
    2. geocoding_platform_interface: Defines the interface that all platform-specific packages must implement to ensure compatibility with the main geocoding package.

    If you are a consumer of this plugin, you only need to interact with the geocoding package.

  2. Implement a new platform for the geocoding plugin

    main

    To add support for a new platform (e.g., a new OS or web implementation), you must extend the GeocodingPlatform class with your platform-specific logic. Once implemented, you must register your implementation as the default instance by assigning it to GeocodingPlatform.instance during plugin registration.

    Follow the Flutter Federated plugins architecture to ensure your implementation is compatible with the existing geocoding plugin ecosystem.

    // 1. Extend GeocodingPlatform with your implementation
class MyPlatformGeocoding extends GeocodingPlatform {
  // Implement required methods here
}

// 2. Register your implementation
GeocodingPlatform.instance = MyPlatformGeocoding();

  3. Use the Geocoding class for version 5.0.0+

    main

    Starting from version 5.0.0, all geocoding methods are grouped within the Geocoding class. You can no longer call methods directly at the top level; you must first create an instance of the Geocoding class.

    Because the Geocoding class is stateless and its constructor performs no heavy operations, you can safely store a single instance in a class variable or a singleton to reuse across your application, or create a new instance for each call.

    // Create an instance of the `Geocoding` class.
final Geocoding geocoding = Geocoding();

// Use the conversion methods on the `Geocoding` class instance.
final List<Placemark> placemarks = await geocoding.placemarkFromLocation(52.2165157, 6.9437819);
final List<Location> locations = await geocoding.locationFromAddress('Gronausestraat 710, Enschede');

  4. Customize the iOS launch screen assets

    main

    To change the launch screen image for the iOS version of the plugin example, you can either replace the image files directly in the geocoding_darwin/example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory or use Xcode for a visual approach.

    Using Xcode:

    1. Open the iOS project workspace using: open ios/Runner.xcworkspace.
    2. In the Xcode Project Navigator, locate and select Runner/Assets.xcassets.
    3. Drag and drop your desired images into the asset catalog.
    open ios/Runner.xcworkspace

  5. Use the geocoding plugin in Android apps

    main

    The geocoding_android package is the Android-specific implementation of the federated geocoding plugin. Because it is an endorsed plugin, you do not need to install geocoding_android directly. Instead, simply add the main geocoding package to your pubspec.yaml dependencies, and the Android implementation will be automatically included in your application.

    dependencies:
  geocoding: ^latest_version

  6. How to use geocoding_darwin in a Flutter project

    main

    The geocoding_darwin package is an endorsed implementation of the geocoding plugin for Apple platforms.

    Because it is an endorsed federated plugin, you do not need to add geocoding_darwin to your pubspec.yaml if you are using the main geocoding package. It will be automatically included in your app build.

    You only need to add geocoding_darwin to your pubspec.yaml if you intend to import this specific package to access its APIs directly.

    dependencies:
  geocoding: ^latest_version
  # geocoding_darwin is included automatically

  7. Customize iOS launch screen assets

    main

    To customize the iOS launch screen, you can replace the existing image files in the geocoding/example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.

    Alternatively, you can manage these assets through Xcode:

    1. Open the iOS project using open ios/Runner.xcworkspace.
    2. In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
    3. Drag and drop your desired images into the asset catalog.
    open ios/Runner.xcworkspace

  8. Set the locale in version 5.0.0+

    main

    The setLocaleIdentifier method is deprecated in version 5.0.0. To specify a locale, use one of the following two patterns:

    1. Global/Instance Locale: Pass a Locale object to the Geocoding constructor. This sets the locale for all subsequent calls made with that instance.
    2. Method-specific Locale: Pass a locale parameter directly to specific methods like locationFromAddress, placemarkFromCoordinates, or placemarkFromAddress to override the instance's locale for a single call.
    // Option 1: Set the locale via the Geocoding constructor
final Geocoding geocoding = Geocoding(locale: Locale('nl_NL'));

final List<Placemark> placemarks = await geocoding.placemarkFromCoordinates(52.2165157, 6.9437819);

// Option 2: Override the locale for a specific method call
final List<Placemark> placemarks = await geocoding.placemarkFromCoordinates(
    52.2165157, 6.9437819,
    locale: Locale('de_DE'),
);

  10. Extend GeocodingCreationParams for platform-specific parameters

    main

    The GeocodingCreationParams class is used to specify creation parameters for the Geocoding service. While the base class is empty, platform-specific implementations (like Android or iOS) can extend it to provide additional configuration.

    When extending this class, ensure that additional parameters are either nullable or have default values to maintain backward compatibility and prevent breaking changes.

    class AndroidGeocodingCreationParams extends GeocodingCreationParams {
  AndroidGeocodingCreationParams._(
    // This parameter prevents breaking changes later.
    // ignore: avoid_unused_constructor_parameters
    GeocodingCreationParams params, {
    this.filter,
  }) : super();

  factory AndroidGeocodingCreationParams.fromGeocodingCreationParams(
      GeocodingCreationParams params, {
      String? filter,
  }) {
    return AndroidGeocodingCreationParams._(params, filter: filter);
  }

  final String? filter;
}

  12. Access the native geocoding_darwin API from iOS native code

    main

    The plugin provides a stable native API for iOS applications or packages. This API follows the Dart API's breaking change conventions: non-backwards compatible changes are only introduced with major version updates.

    To use the native API, import geocoding_darwin in your Dart code to access the underlying native classes CLGeocoder and MapKit.

    import 'package:geocoding_darwin/geocoding_darwin.dart';

// Access native classes: CLGeocoder and MapKit