Flutter What3Words Google Maps (flutter_w3w_map)

A powerful and easy-to-use Flutter package that integrates What3Words (W3W) functionality directly into Google Maps. This package allows you to display W3W grid lines, convert coordinates to 3-word addresses, and vice-versa, all within a familiar Google Maps interface.

🌟 Features

Seamless Integration: A drop-in W3WGoogleMap widget that wraps GoogleMap.
W3W Grid Rendering: Automatically fetches and displays the What3Words grid lines as you move and zoom the map.
Forward/Reverse Geocoding:
- Convert coordinates (Lat/Lng) to unique 3-word addresses (e.g., ///filled.count.soap).
- Convert 3-word addresses back to precise coordinates.
Interactive Map: Tap anywhere on the map to instantly get the What3Words address for that exact 3m x 3m square.
Customizable: Easily style the grid lines (color, opacity) and customize the information overlay.
Optimized Performance: Built-in debouncing for grid updates to optimize API usage and ensure a smooth UI experience.
️Clean Architecture: Built using Clean Architecture principles (Domain, Data, Presentation) for robustness and maintainability.

Getting Started

Prerequisites

What3Words API Key: Get your free API key from the What3Words Developer Portal.
Google Maps API Key: Set up your Google Maps API key following the official Flutter guide.

Installation

Add flutter_w3w_map to your pubspec.yaml:

dependencies:
  flutter_w3w_map: ^1.0.2

Usage

1. Initialize the Provider

Wrap your application (or the specific screen) with W3WGoogleMaps.provider. This initializes the required services and provides them to the widget tree.

import 'package:flutter_w3w_map/w3w_google_maps.dart';

W3WGoogleMaps.provider(
  w3wApiKey: "YOUR_WHAT3WORDS_API_KEY",
  child: MyApp(),
)

Use the W3WGoogleMap widget just like a standard GoogleMap.

import 'package:flutter_w3w_map/w3w_google_maps.dart';

W3WGoogleMap(
  initialCameraPosition: CameraPosition(
    target: LatLng(23.0225, 72.5714),
    zoom: 18,
  ),
  onW3WSelected: (W3WEntity w3w) {
    print("Selected Address: ///${w3w.words}");
  },
  showGrid: true, // Optional: defaults to true
  gridColor: Colors.blue, // Optional
  gridOpacity: 0.5, // Optional
)

Advanced Usage

Accessing W3W Data Programmatically

You can access the W3WProvider anywhere in your widget tree to perform manual conversions or fetch grid data.

final w3wProvider = Provider.of<W3WProvider>(context, listen: false);

// Convert Coordinates to 3WA
await w3wProvider.fetch3wa(23.0225, 72.5714);
final result = w3wProvider.result;

// Fetch Grid Section
await w3wProvider.fetchW3WGrid(
  center: LatLng(23.0225, 72.5714),
  delta: 0.001,
);

The W3WEntity Model

The W3WEntity provides detailed information about a location:

Property	Description
`words`	The 3-word address (e.g., `filled.count.soap`).
`lat` / `lng`	Precise coordinates for the center of the square.
`country`	The country code (ISO 3166-1 alpha-2).

⚙️ Configuration

W3WGoogleMap Properties

Property	Type	Description
`initialCameraPosition`	`CameraPosition`	Required. Starting position of the map.
`onW3WSelected`	`Function(W3WEntity)`	Callback triggered when a square is selected.
`showGrid`	`bool`	Whether to display the W3W grid lines.
`gridColor`	`Color`	The color of the grid lines.
`gridOpacity`	`double`	The opacity of the grid lines (0.0 to 1.0).
`markers`	`Set<Marker>`	Custom markers to display on the map.

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

Developed by

Created by Raj Shah