google_places_kit #

Google Places and Geocoding for Flutter: place autocomplete, place details, nearby and text search, photos, and converting between coordinates and addresses. It uses Places API (New), works on Android, iOS, web and desktop from the same code, and turns every response into typed Dart models.

This is an independent package, not an official Google plugin.

Autocomplete	Place details	Nearby search	Full place
Full-screen search	Your own UI	Lat/lng → address	Address → lat/lng

GooglePlaces.initialize(apiKey: apiKey); // once, in main()

final places = GooglePlaces.instance;    // anywhere
final suggestions = await places.autocomplete('Gateway of In');
final place = await places.details(suggestions.first.placeId);
final cafes = await places.searchNearby(
  LocationArea.circle(place.location!, 1000),
  includedTypes: ['cafe'],
);
final addresses = await places.reverseGeocode(Coordinates(18.922, 72.834));
print(addresses.first.formattedAddress);

Contents #

• Why this package
• Getting started
• Methods
  • autocomplete · details · searchText · searchNearby · photoUrl · reverseGeocode · geocode
• Widgets
• Theming
• Build your own UI
• Response models
• Choosing fields (PlaceField)
• Errors
• Keeping the API key safe
• Google's display rules
• Platforms
• Example

💡 Why this package #

🚀 Getting started #

Install #

dependencies:
  google_places_kit: ^0.1.0

Google Cloud setup (once) #

1. In Google Cloud Console, pick or create a project and link a billing account. Google requires one for these APIs, even within the free monthly usage.
2. In APIs & Services → Library, enable Places API (New), and Geocoding API if you need coordinates ↔ addresses.
3. In APIs & Services → Credentials, create an API key. Under API restrictions, allow those two APIs.
4. Optional but wise: set a daily quota for each API and a budget alert in Billing.

Pass the key when you build, so it stays out of your code:

flutter run --dart-define=PLACES_API_KEY=your-api-key

Initialize once #

Call GooglePlaces.initialize in main(). Then any screen, service or widget can use GooglePlaces.instance, and the widgets use it without a places: argument.

void main() {
  GooglePlaces.initialize(
    apiKey: const String.fromEnvironment('PLACES_API_KEY'),
    languageCode: 'en',
    regionCode: 'IN',
  );
  runApp(const MyApp());
}

// Anywhere in the app:
final suggestions = await GooglePlaces.instance.autocomplete('pizza');

// Widgets need no client:
PlaceAutocompleteField(onSelected: (place) => print(place.name));

A service class works the same way:

class LocationService {
  final _places = GooglePlaces.instance;

  Future<String?> addressAt(Coordinates point) async {
    final results = await _places.reverseGeocode(point);
    return results.isEmpty ? null : results.first.formattedAddress;
  }
}

You can still create clients yourself with GooglePlaces(apiKey: ...), for example with a second key, and pass them to the widgets with places:. Your own GooglePlaces objects are independent of the shared one.

Call close() on a client you no longer need. Closing the shared instance also clears it, so only do that when the app no longer uses it.

The examples below use places for GooglePlaces.instance or your own client.

Location permission #

The package doesn't need location permission. It only sends web requests and never reads the device's location, so an app that just searches places or addresses needs no extra setup.

To show results near the user, get their position with a package such as geolocator (which adds the location permission to your app), then pass it in:

final position = await Geolocator.getCurrentPosition();
final here = Coordinates(position.latitude, position.longitude);

places.autocomplete(text, locationBias: LocationArea.circle(here, 5000), origin: here);
places.searchNearby(LocationArea.circle(here, 1000), includedTypes: ['cafe']);
places.reverseGeocode(here);

The example app does this for its "My location" buttons.

🧭 Methods #

Every method throws a PlacesException when the request fails.

autocomplete #

Suggestions for what the user is typing, such as "Gateway Of India" for "gateway of in".

Future<List<PlaceSuggestion>> autocomplete(String input, {...})

Returns a list of PlaceSuggestion.

var session = PlacesSession();

final suggestions = await places.autocomplete(
  'pizza hut colaba',
  session: session,
  locationBias: LocationArea.circle(userLocation, 20000),
  origin: userLocation,
);
for (final s in suggestions) {
  print('${s.mainText} — ${s.secondaryText} (${s.distanceMeters} m)');
}

// When the user picks one, end the session with details():
final place = await places.details(suggestions.first.placeId, session: session);
session = PlacesSession(); // a new one for the next search

What is a session?

When a user types "statue of lib", your app may call autocomplete several times, once for each pause in typing. A session tells Google that all those calls, plus the details call for the place the user finally picks, belong to one search.

user types "sta"     → autocomplete(session: A)  ┐
user types "statue"  → autocomplete(session: A)  │ one session (A)
user types "statue o"→ autocomplete(session: A)  │
user picks a result  → details(session: A)       ┘ session A ends here
next search          → autocomplete(session: B)  ← a new session

Why it matters: billing. With a session that ends in a details call, Google bills the search as one session plus the details request, instead of charging every autocomplete call on its own. Without a session, each keystroke request is billed separately, which adds up quickly in a search box. See Google's Places API usage and billing page for current prices.

How it works: a session is a random ID (a version 4 UUID) sent with each request. PlacesSession() creates one.

Rules:

1. Create a new PlacesSession when the user starts a new search.
2. Pass the same session to every autocomplete call of that search.
3. Pass it to the details call for the place the user picks. That ends the session.
4. Never reuse a session after its details call, and never share one between users.
5. If the user leaves without picking anything, just make a new session next time. Those requests are billed one by one, as if there were no session.

Sessions are only for autocomplete followed by details. searchText, searchNearby, photos and geocoding don't use them.

You don't need to do this yourself if you use PlaceAutocompleteField, showPlaceSearch or PlaceAutocompleteController: they create a session per search, pass it along, and start a new one after each pick.

details #

The full place for a place ID, with the fields you ask for.

Future<Place> details(String placeId, {...})

Returns a Place. Only the fields you asked for are set.

final place = await places.details(placeId, fields: PlaceField.details);
print(place.name);              // Gateway Of India Mumbai
print(place.rating);            // 4.6
print(place.openNow);           // true
print(place.addressComponents.city); // Mumbai

searchText #

Places matching a text query, like the Google Maps search box: "pizza", "petrol pump near Andheri", "hotels in Goa".

Future<PlaceSearchResults> searchText(String query, {...})

Returns PlaceSearchResults: a normal List<Place> with a nextPageToken for more results (up to 60 in total).

final page1 = await places.searchText(
  'pizza',
  locationBias: LocationArea.circle(userLocation, 5000),
  openNow: true,
  minRating: 4,
  fields: [PlaceField.id, PlaceField.displayName, PlaceField.rating],
);
if (page1.nextPageToken != null) {
  final page2 = await places.searchText(
    'pizza',
    locationBias: LocationArea.circle(userLocation, 5000),
    openNow: true,
    minRating: 4,
    fields: [PlaceField.id, PlaceField.displayName, PlaceField.rating],
    pageToken: page1.nextPageToken,
  );
}

searchNearby #

Places of certain types in a circle, such as ATMs within a kilometer.

Future<List<Place>> searchNearby(LocationArea area, {...})

Returns up to 20 Places.

final atms = await places.searchNearby(
  LocationArea.circle(userLocation, 1000),
  includedTypes: ['atm'],
  rankByDistance: true,
);
for (final atm in atms) {
  print('${atm.name}: ${formatDistance(userLocation.distanceTo(atm.location!))}');
}

photoUrl #

An image URL for a place photo.

Future<String> photoUrl(PlacePhoto photo, {int? maxWidth = 800, int? maxHeight})

Returns the URL. It doesn't contain your API key, so it's safe to cache.

final url = await places.photoUrl(place.photos.first, maxWidth: 600);
Image.network(url);
Text('Photo: ${place.photos.first.authorAttributions.first.displayName}');

reverseGeocode #

The addresses at a latitude and longitude, for "use my location". Uses the Geocoding API.

Future<List<GeocodingResult>> reverseGeocode(Coordinates location, {...})

Returns GeocodingResults, most precise first: usually the street address, then the area, city, state and country. No address there (such as at sea) returns [].

final results = await places.reverseGeocode(Coordinates(18.922, 72.8347));
final address = results.first;
print(address.formattedAddress);             // ..., Colaba, Mumbai 400001, India
print(address.addressComponents.postalCode); // 400001
print(address.locationType);                 // LocationType.rooftop

geocode #

The coordinates of an address. Uses the Geocoding API.

Future<List<GeocodingResult>> geocode(String address, {...})

Returns GeocodingResults, best match first. No match returns [].

final results = await places.geocode(
  'Shahid Bhagat Singh Rd, Colaba, Mumbai 400005',
  countries: ['IN'],
);
print(results.first.location);     // Coordinates(18.91..., 72.82...)
print(results.first.locationType); // how exact it is

Geocoding is made for addresses. For the name of a place or business, such as "Taj Mahal" or "Pizza Hut Colaba", use searchText or autocomplete: geocoding may only find the city, with LocationType.approximate.

🧩 Widgets #

The widgets are optional. Use them as they are, restyle them with a theme, swap parts with builders, or skip them and build your own UI. All of them use GooglePlaces.instance unless you pass places:.

PlaceAutocompleteField #

A rounded search field that suggests places in a floating panel while the user types, and gives you the full Place when they pick one.

• Each suggestion has an icon for its kind of place (plane, fork and knife, coffee cup, hotel, temple, road and more), the typed part highlighted, and the distance when you give an origin.
• While it loads, the panel shows a shimmering skeleton. It says "No places found" when nothing matches, and shows the error when a request fails.
• The panel and rows animate in. Arrow keys, Enter and Escape work on web and desktop.
• It waits for a pause in typing, uses one session per search, and shows the "Google Maps" attribution Google requires (see display rules).

PlaceAutocompleteField(
  fields: PlaceField.address,
  options: const PlaceAutocompleteOptions(countries: ['IN']),
  onSelected: (place) => print(place.formattedAddress),
  onError: (error) => print(error.message),
)

Colors, corners and shadows come from PlacesKitTheme.

A restyled field with your own rows:

PlaceAutocompleteField(
  onSelected: (place) => setState(() => _place = place),
  decoration: InputDecoration(
    hintText: 'Pickup location',
    prefixIcon: const Icon(Icons.my_location),
    border: OutlineInputBorder(borderRadius: BorderRadius.circular(8)),
  ),
  suggestionBuilder: (context, suggestion, onSelected) => ListTile(
    leading: const Icon(Icons.local_taxi),
    title: Text(suggestion.mainText),
    subtitle: Text(suggestion.secondaryText),
    onTap: onSelected,
  ),
)

PlaceAutocompleteOptions #

Filters used by the widgets and PlaceAutocompleteController, matching the autocomplete parameters:

showPlaceSearch and PlaceSearchPage #

A full-screen search, nicer on phones and handy for "choose a location" buttons. It has the same rounded field, a friendly empty state before the user types, a skeleton while loading, and "No places found" and error states. On wide screens the content stays at a comfortable width. Returns the picked place, or null if the user goes back.

final place = await showPlaceSearch(
  context,
  fields: PlaceField.details,
  hintText: 'Where to?',
);

PlaceSearchPage is the page itself, for your own routes. It also takes debounce and minLength.

Helpers #

🎨 Theming #

The widgets take their colors from your app's ColorScheme, so they match your brand, and light and dark mode, with no setup. To change their look everywhere at once, add a PlacesKitTheme to your ThemeData. Every value is optional.

MaterialApp(
  theme: ThemeData(
    colorSchemeSeed: Colors.teal,
    extensions: const [
      PlacesKitTheme(
        fieldBorderRadius: BorderRadius.all(Radius.circular(12)),
        panelBorderRadius: BorderRadius.all(Radius.circular(16)),
        matchColor: Colors.deepOrange,
      ),
    ],
  ),
)

Use a different theme for one widget by wrapping it in Theme(data: Theme.of(context).copyWith(extensions: [...])). Read the resolved values in your own widgets with PlacesKitTheme.of(context).

🛠️ Build your own UI #

You don't need the widgets. There are two ways to use your own design.

Option 1: call the methods #

Everything the widgets do is a public method that returns typed models. Use them from any widget, state management or plain Dart code:

class MySearch extends StatefulWidget {
  const MySearch({super.key});

  @override
  State<MySearch> createState() => _MySearchState();
}

class _MySearchState extends State<MySearch> {
  final _places = GooglePlaces.instance;
  var _session = PlacesSession();
  var _suggestions = <PlaceSuggestion>[];
  Timer? _debounce;

  void _onChanged(String text) {
    _debounce?.cancel();
    _debounce = Timer(const Duration(milliseconds: 300), () async {
      try {
        final suggestions = await _places.autocomplete(
          text,
          session: _session,
        );
        if (mounted) setState(() => _suggestions = suggestions);
      } on PlacesException catch (e) {
        print(e.message);
      }
    });
  }

  Future<void> _pick(PlaceSuggestion suggestion) async {
    final place = await _places.details(
      suggestion.placeId,
      fields: PlaceField.address,
      session: _session,
    );
    _session = PlacesSession();
    print(place.formattedAddress);
  }

  @override
  void dispose() {
    _debounce?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => Column(
    children: [
      TextField(onChanged: _onChanged),
      for (final s in _suggestions)
        ListTile(title: Text(s.mainText), onTap: () => _pick(s)),
      if (_suggestions.isNotEmpty) const GoogleMapsAttribution(),
    ],
  );
}

Remember the parts the widgets would handle: wait for a pause in typing, reuse one PlacesSession until details, catch PlacesException, and show the attribution.

Option 2: PlaceAutocompleteController #

PlaceAutocompleteController is the widgets' search logic with no UI. It waits for a pause in typing, manages the session, ignores answers to older searches, and keeps suggestions, loading and error for you. It's a ChangeNotifier, so rebuild with ListenableBuilder, AnimatedBuilder, or your state management.

Want our panel under your own field? Put a PlaceSuggestionsPanel(controller: search, onSelected: ...) below it.

late final search = PlaceAutocompleteController(
  fields: PlaceField.details,
  options: const PlaceAutocompleteOptions(countries: ['IN']),
);

@override
Widget build(BuildContext context) => ListenableBuilder(
  listenable: search,
  builder: (context, _) => Column(
    children: [
      SearchBar(
        hintText: 'Where to?',
        onChanged: search.search,
        trailing: [if (search.loading) const CircularProgressIndicator()],
      ),
      if (search.error case final error?) Text(error.message),
      if (search.hasNoResults) const Text('No places found'),
      for (final suggestion in search.suggestions)
        MyPlaceCard(
          suggestion: suggestion,
          onTap: () async {
            final place = await search.select(suggestion);
            if (place != null) print(place.name);
          },
        ),
      if (search.suggestions.isNotEmpty) const GoogleMapsAttribution(),
    ],
  ),
);

@override
void dispose() {
  search.dispose();
  super.dispose();
}

The example app's Your own UI page is built this way.

📦 Response models #

Every response is turned into these classes. Fields Google didn't send, or that you didn't ask for, are null or empty.

PlaceSuggestion #

From autocomplete.

Place #

From details, searchText and searchNearby. The field to ask for is in brackets.

Basics and address

Type and status

Contact and links

Ratings, price and hours

Photos, reviews and summaries

What it offers

PlaceAmenities #

place.amenities. Each is bool?: true, false, or null when Google doesn't know. Ask for each with the PlaceField of the same name.

delivery, dineIn, takeout, curbsidePickup, reservable, servesBreakfast, servesBrunch, servesLunch, servesDinner, servesVegetarianFood, servesDessert, servesCoffee, servesBeer, servesWine, servesCocktails, outdoorSeating, liveMusic, menuForChildren, goodForChildren, goodForGroups, goodForWatchingSports, allowsDogs, restroom.

if (place.amenities.servesVegetarianFood ?? false) print('Veg options');

AccessibilityOptions, ParkingOptions, PaymentOptions #

All fields are bool?.

OpeningHours #

OpeningTime (in open and close): day (0 = Sunday … 6 = Saturday), hour, minute, and date for current hours.

PlacePhoto #

PlaceReview #

AiSummary #

place.generativeSummary and place.reviewSummary.

GoogleMapsLinks #

placeUri, directionsUri, reviewsUri, writeAReviewUri, photosUri: all String?.

launchUrl(Uri.parse(place.googleMapsLinks!.directionsUri!)); // with url_launcher

AddressDescriptor #

Where the place is, in words people use.

final landmark = place.addressDescriptor!.landmarks.first;
print('${landmark.spatialRelationship} ${landmark.name}'); // ACROSS_THE_ROAD Sassoon Dock

FuelOptions and EvChargeOptions #

Money #

currencyCode ("INR") and amount (num, such as 104.21). Used by PriceRange and FuelPrice.

PostalAddress #

regionCode, languageCode, postalCode, administrativeArea (state), locality (city), sublocality, addressLines (street lines), organization.

PlaceSearchResults #

What searchText returns: a List<Place> you can loop over as usual, plus nextPageToken (String?) for the next page.

GeocodingResult #

From reverseGeocode and geocode.

AddressComponent and address parts #

Each AddressComponent has longText ("Maharashtra"), shortText ("MH"), types and languageCode. The list has getters for the usual parts:

Location types #

🎛️ Choosing fields (PlaceField) #

details, searchText, searchNearby and the widgets take fields. Google bills a request by its most expensive field, so ask only for what you show.

Presets

Or pick fields yourself, grouped by the tier Google bills them at:

Check Google Maps Platform pricing for the current prices and free monthly calls of each tier.

final place = await places.details(id, fields: [
  PlaceField.displayName,
  PlaceField.location,
  PlaceField.rating,
]);

Any other field from Google's documentation works with PlaceField('fieldName'); its value is in place.json.

⚠️ Errors #

Every method throws a PlacesException when a request fails.

try {
  await places.details(id);
} on PlacesException catch (e) {
  print('${e.code.name}: ${e.message}');
}

No results is not an error: searches and geocoding return an empty list.

🔐 Keeping the API key safe #

An API key inside an app can always be extracted, so limit what it can do:

• API restrictions: allow only Places API (New) and Geocoding API.
• Quotas and budget alerts: cap the daily requests and get an email if anything is charged.
• App restrictions: restrict the key to your Android app (package name + SHA-1), your iOS app (bundle ID) or your website (HTTP referrers). For Android and iOS, pass the same values to the client so it sends them with each request:

GooglePlaces.initialize(
  apiKey: apiKey,
  androidPackageName: 'com.example.app',
  androidCertFingerprint: 'DA:39:A3:...', // SHA-1 of the signing certificate
  iosBundleId: 'com.example.app',
);

Use separate keys per platform if you restrict them differently. Keep the key out of git with --dart-define or --dart-define-from-file.

📜 Google's display rules #

Google's terms ask apps to show attribution with Places data:

• "Google Maps" next to results shown without a Google map. The widgets add it; in your own UI, use GoogleMapsAttribution().

  You can hide the label for one widget with showAttribution: false, or for the whole app with PlacesKitTheme(showAttribution: false). Only do that if your app shows the results on a Google map (which has its own attribution) or credits Google somewhere else on the screen.

• Photo authors: photo.authorAttributions with each photo.

• Review authors: review.author with each review.

• AI summaries: disclosureText with each summary.

See Google's Places API policies for the details.

📱 Platforms #

There's no native code. On Android, the app needs the INTERNET permission in AndroidManifest.xml (Flutter adds it only to debug builds). On macOS, enable outgoing connections (com.apple.security.network.client).

Example #

The example app initializes the client once in main() and has three tabs: place search with the autocomplete field, the full-screen page and a fully custom page built on PlaceAutocompleteController; nearby and text search with a full place sheet; and coordinates ↔ address. Run it with your key:

cd example
flutter run --dart-define=PLACES_API_KEY=your-api-key

☕ Support #

If this package saves you time, you can support its maintenance with a coffee:

Or scan the code:

License #

MIT. Google, Google Maps and Google Places are trademarks of Google LLC; this package is not affiliated with or endorsed by Google.