Flutter Integration

The geophrase_flutter package provides the GeophraseConnect widget for integrating the Geophrase address selector into any Flutter app, including Android, iOS, and Web.

Web Support: No extra configuration is needed for Flutter Web. The widget runs inside a sandboxed iframe with allow="geolocation".

Prerequisites

Create a Geophrase Account.
Generate an API Key from the Dashboard. Every integration needs its Key ID (the public prefix, shown in the dashboard); client mode also needs the secret key.

1. Install

flutter pub add geophrase_flutter

iOS

Add to ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to accurately place the pin on your address.</string>

Android

Add to android/app/src/main/AndroidManifest.xml (inside <manifest>):

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

2. Implementation

The snippet below uses mode: 'server', so the only credential you need in the app is your public Key ID. No secret API key is required. Swap in your own apiKeyId and drop it into your app to see the widget.

Important: Do not wrap GeophraseConnect inside a Scaffold with an AppBar. The widget renders its own header. Push it as a full-screen route and let it fill the screen.

import 'package:flutter/material.dart';
import 'package:geophrase_flutter/geophrase_flutter.dart';

void openGeophrase(BuildContext context) {
  Navigator.of(context).push(
    MaterialPageRoute(
      fullscreenDialog: true,
      builder: (routeContext) => GeophraseConnect(
        apiKeyId: 'YOUR_API_KEY_ID', // required in both modes; your public Key ID

        // 'server' (used here): widget returns a requestId. Pass it to your backend to resolve the address. No secret key needed.
        // 'client' (default):   widget resolves and returns the full address directly. Requires apiKey.
        mode: 'server',

        // apiKey: 'YOUR_API_KEY', // secret key, required when mode is 'client'
        theme: 'system',            // 'light' | 'dark' | 'system'
        orderId: 'ORD-98765',       // your internal reference ID
        phone: '9999999999',        // prefills the phone field

        onSuccess: (result) {
          // server mode → GeophraseRequestId. POST result.requestId to your backend.
          // client mode → GeophraseAddress. Use directly.
          if (result is GeophraseRequestId) {
            debugPrint('Request ID: ${result.requestId}');
          } else if (result is GeophraseAddress) {
            debugPrint('Address: ${result.shortCode}');
          }
          Navigator.of(routeContext).pop();
        },
        onError: (error) => debugPrint('Geophrase error: ${error.message}'),
        onClose: () => Navigator.of(routeContext).pop(),
      ),
    ),
  );
}

Wire it up to any trigger in your UI:

ElevatedButton(
  onPressed: () => openGeophrase(context),
  child: const Text('Select delivery address'),
);

View full example on GitHub

3. Configuration Props

Parameter	Type	Default	Required	Description
`apiKeyId`	`String`	None	Yes	Your 8-character public Key ID (shown in the dashboard). Required in both modes; identifies your account to the widget.
`mode`	`String`	`'client'`	No	`'client'` resolves the address in the app. `'server'` returns a `requestId` for your backend to exchange.
`apiKey`	`String`	None	Conditional	Your secret Geophrase API key (the full key string). Required when `mode: 'client'`.
`theme`	`String`	`'system'`	No	`'light'`, `'dark'`, or `'system'` (follows OS preference).
`orderId`	`String`	None	No	Your internal reference ID. In client mode it is forwarded to the Resolve endpoint; in server mode you forward it yourself.
`noteForAgent`	`String`	None	No	Note shown to your delivery agent, never to the customer. Client mode only; notes over 300 characters are cut. It is sent from the customer's device, so the customer can change it; send payment instructions, such as cash to collect, from your server or the dashboard. In server mode, send `note_for_agent` with your resolve call.
`phone`	`String`	None	No	Pre-fills the phone field with a 10-digit Indian mobile number.
`onSuccess`	`Function(dynamic)`	None	Yes	Receives a `GeophraseAddress` in client mode, or a `GeophraseRequestId` in server mode.
`onError`	`Function(GeophraseError)`	None	No	Receives `{ type, status?, message }` on API or network errors.
`onClose`	`VoidCallback`	None	No	Called when the user dismisses the widget without selecting an address.

Response Types

The package ships with fully typed Dart classes. Use is checks in onSuccess to branch on mode.

Client mode: GeophraseAddress

All fields are non-nullable. Top-level: shortCode, shortLink, qrCode, capturedAt, orderId, address, and a rawData map for forward compatibility. The nested address is a GeophraseAddressDetails with city, state, digiPin, landmark, latitude, longitude, postalCode, addressType, addressLineOne, addressLineTwo, contactFullName, and verifiedMobileNum. See The Address Object for the full payload.

Server mode: GeophraseRequestId

class GeophraseRequestId {
  final String requestId;
}

Pass requestId to your backend to exchange it for the full address using your Geophrase API key.

Next step

Resolve Endpoint