flutter_places_sdk

Flutter plugin wrapping the native Google Places SDK on iOS and Android, backed by the Places API (New) product in Google Cloud.

Because requests are dispatched through the native SDKs — GMSPlacesClient on iOS, PlacesClient on Android — API keys restricted by iOS bundle identifier or Android package name + SHA-1 fingerprint work without a server proxy. REST-based Places clients cannot carry that attestation.

Status

• ✅ iOS (Swift Package Manager, no CocoaPods dependency)
• ✅ Android (Kotlin, Places SDK 4.x)
• 🚫 web / macOS / linux / windows — out of scope

Installation

dependencies:
  flutter_places_sdk: ^0.1.0

iOS

Requires Flutter 3.24+ (Swift Package Manager support) and iOS 16.0+. Enable SPM once in your app:

flutter config --enable-swift-package-manager

No Podfile changes required.

Android

Requires minSdk 23. The plugin pulls in com.google.android.libraries.places:places:4.x automatically.

Google Cloud setup

1. Enable Places API (New) on your Google Cloud project.
2. Create an API key.
3. Restrict the key to your app's platform identifier:
   • iOS: com.your.bundleid
   • Android: package name + SHA-1 fingerprint

Usage

import 'package:flutter_places_sdk/flutter_places_sdk.dart';

final places = FlutterPlacesSdk(dotenv.env['GOOGLE_PLACES_API_KEY']!);

// Autocomplete
final predictions = await places.findAutocompletePredictions(
  '221B Baker',
  countries: ['GB'],
);
for (final p in predictions) {
  print('${p.primaryText} — ${p.secondaryText}');
}

// Place details
final place = await places.fetchPlace(
  predictions.first.placeId,
  fields: const [PlaceField.id, PlaceField.address, PlaceField.location],
);
print(place?.formattedAddress);
print(place?.latLng);

API

FlutterPlacesSdk(apiKey)

Creates a client. Initialisation is lazy — the first call to findAutocompletePredictions / fetchPlace triggers the native provideAPIKey / Places.initialize under the hood.

findAutocompletePredictions(query, {countries, origin, locationBias, locationRestriction, sessionToken})

Returns a List<AutocompletePrediction>.

fetchPlace(placeId, {required fields})

Returns a Place?. Only the requested `PlaceField`s are populated — each field is billed separately under Places API (New) pricing.

Errors

All native failures surface as PlacesException with a code (INIT_ERROR, API_ERROR, AUTOCOMPLETE_ERROR, FETCH_PLACE_ERROR, NOT_INITIALIZED) and a platform-reported message.

License

MIT