flutter_w3w_map 1.0.2

A Flutter package that integrates What3Words with Google Maps, allowing for easy 3-word address conversions and grid rendering.

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

1. What3Words API Key: Get your free API key from the What3Words Developer Portal.
2. 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(),
)

2. Add the W3WGoogleMap Widget

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