Google Places SDK Flutter
Address autocomplete for Flutter on Google Places API (New): the user types, picks a place, and your app gets its coordinates and a parsed address.
Open a search and wait for the pick:
final selection = await PlacesAutocompleteOverlay.show(context, apiKey: 'YOUR_API_KEY');
final coordinates = selection?.place?.location;
final address = selection?.place?.formattedAddress;
Or put a search field on the page:
PlacesAutocompleteField(
apiKey: 'YOUR_API_KEY',
onSelection: (selection) => debugPrint(selection.place?.formattedAddress),
)
When to use this package
- One pick gives you coordinates and a parsed address — street, city, postal code, country — at the lowest Place Details billing tier that returns an address.
- Billing sessions are handled for you. Each search and the pick that ends it are grouped into one Google autocomplete session, with no setup.
- The widget's text speaks your users' language. It follows the app's language in English, Hebrew, Arabic, Russian, French, German, Spanish and Portuguese with no setup, and lays out right-to-left in Hebrew and Arabic apps.
- It works in any Flutter app, whether it uses
material_uior still usespackage:flutter/material.dart, with no extra code. - Pure Dart on Android, iOS, web (including Wasm), macOS, Windows, and Linux. It is not a
plugin, and its only runtime dependencies are
http,web, and Flutter's ownmaterial_ui. - Your Google key can stay off the device behind an authenticated proxy, and the package never asks for location permission.
Not a fit if your users need to pick a point on a map: this package searches by text.
Contents
- Ways to use it
- Quick start
- What you get back
- Restricting results
- Costs
- Security
- Troubleshooting
- What's new
- More documentation
- Recipes — forms, dialogs, the widget's text, areas, search without a widget, and advanced setup
Ways to use it
| You want | Use | Guide |
|---|---|---|
| A search field on a page or in a form | PlacesAutocompleteField, PlacesAutocompleteFormField |
Quick start, forms |
| Search in a dialog or on a full screen, awaiting the pick | PlacesAutocompleteOverlay.show() |
Dialog and full screen |
| Place data with no UI — details, Text Search, Nearby Search, photos, time zone | PlacesClient |
Search without a widget |
| The widget, with your own field, rows, or styling | fieldBuilder, suggestionItemBuilder, suggestionsViewBuilder |
Customize |
| Your own search UI, still billed per session | PlacesAutocompleteController |
Your own autocomplete UI |
Every option and default is in the API reference.
Quick start
Add the package:
flutter pub add google_places_sdk_flutter
In the Google Cloud console, enable Places API (New) — and, for web, the Maps JavaScript API — on a project with billing enabled, and create an API key.
Pass the key to a widget. Reading it from --dart-define keeps it out of source control:
import 'package:google_places_sdk_flutter/google_places_sdk_flutter.dart';
const apiKey = String.fromEnvironment('GOOGLE_MAPS_API_KEY');
PlacesAutocompleteField(
apiKey: apiKey,
onSelection: (selection) {
debugPrint(selection.displayText);
debugPrint('${selection.place?.location}');
},
)
flutter run --dart-define=GOOGLE_MAPS_API_KEY=your_key_here
Given apiKey:, the widget creates its own PlacesClient and closes it when it is disposed. Pass
client: instead to share one client across screens, to use a key restricted to your Android or
iOS app (see Security), or to use a keyless proxy.
The widget's own text — the hint, the loading and error messages — follows your app's language in
eight languages, and distances use the device region's units, with nothing to set. Pass strings:
to change a string or force a language.
Apps that still use package:flutter/material.dart
The widgets work there too, with no extra code. They use material_ui's default theme, following
your app's light or dark brightness, and print a one-time note in debug builds. To style the field,
wrap it in material_ui's Theme; to keep your app's own theme, return your own TextField from
fieldBuilder, or migrate
the app with dart fix --apply --code=migrate_design_widgets.
Passing decoration: from such an app needs material_ui's InputDecoration, imported with a
prefix — see MIGRATION.md.
What you get back
onSelection receives a PlaceSelection. Its place holds the details:
final place = selection.place!;
place.location; // PlaceCoordinates(latitude: 40.71, longitude: -74.01)
place.formattedAddress; // 151 Broadway, New York, NY 10007, USA
place.streetAddress; // 151 Broadway
place.unit; // 4B
place.city; // New York
place.administrativeArea; // New York
place.postalCode; // 10007
place.country; // United States
place.countryShort; // US
city falls back to the postal town and other components for addresses that have no locality,
which is common in the UK. The place's name is selection.suggestion.primaryText.text. For an
address format the getters do not fit, place.addressComponents holds Google's parts as
PlaceAddressComponent values — see the API reference.
To fill the rest of an address form from one pick, see the recipe.
Asking for more
selectionFields chooses what the details request returns. Google bills it at the tier of its most
expensive field:
selectionFields |
Returns | Highest field tier |
|---|---|---|
PlaceFieldPresets.address (default) |
coordinates, the address, and its parsed parts | Essentials |
PlaceFieldPresets.recommended |
coordinates, the address, name, type, Maps link, icon, and rating — not the parsed parts | Enterprise |
PlaceFieldPresets.rich |
recommended plus the parsed parts, phone, website, opening hours, photos, reviews, and amenities |
Enterprise + Atmosphere |
Your own set of PlaceField values |
exactly what you list, from all 80 fields | the highest among them |
PlaceFieldPresets.all |
every field — for exploring the data and for admin tools | Enterprise + Atmosphere, always |
PlaceFieldPresets.all is not for production;
the API reference says why.
To keep the parsed address, add to the default rather than replacing it:
PlacesAutocompleteField(
apiKey: apiKey,
selectionFields: {...PlaceFieldPresets.address, PlaceField.photos},
)
PlaceField.photos is an Essentials (IDs Only) field, so this pick stays at Essentials; fetching
each photo is billed separately. The field table lists every field
with its tier, and Costs explains how the tier affects a session.
The place's time zone
Ask for it in the same details request:
PlacesAutocompleteField(
apiKey: apiKey,
selectionFields: {...PlaceFieldPresets.address, PlaceField.timeZone},
onSelection: (selection) => debugPrint(selection.place?.timeZone?.id), // America/New_York
)
or from Google's Time Zone API:
PlacesAutocompleteField(
apiKey: apiKey,
fetchTimeZoneOnSelection: true,
onSelection: (selection) => debugPrint(selection.timeZone?.timeZoneName), // Eastern Daylight Time
)
PlaceField.timeZone needs no second API, but it is a Pro field, so the details request is no
longer Essentials — see Costs. fetchTimeZoneOnSelection leaves the details request as
it is and makes a second request to the Time Zone API, which is billed separately and must be
enabled for the key. It also returns the offset at a given moment, including daylight saving; set
the moment with selectionTimeZoneAt. The recipe shows
what each way returns.
Photos
Add PlaceField.photos to selectionFields, then show one with PlacePhotoView:
// import 'package:url_launcher/url_launcher.dart';
PlacePhotoView(
photo: place.photos.first,
apiKey: apiKey,
height: 200,
onOpenLink: (uri) => launchUrl(uri),
)
It fetches the image at that size and draws the author's name and a "View on Google Maps" link
over it. Google requires that link. On web it opens in a new tab by itself. On Android, iOS,
macOS, Windows and Linux the package cannot open a link without a plugin, so onOpenLink is
what shows the link there — here with url_launcher, added to your app. Without it the link is
not shown.
Each photo shown is one billed Place Photos request. On web the lookup is a REST call, so with
apiKey: the key is sent from the browser; pass a proxy client: to avoid that.
The recipe covers strips, galleries, and your own look.
Restricting results
PlacesAutocompleteField(
apiKey: apiKey,
includedRegionCodes: const ['us', 'ca'],
includedPrimaryTypes: PlaceTypePresets.cities,
languageCode: 'fr',
)
includedRegionCodes— only places in these countries, as CLDR region codes.includedPrimaryTypes— only these place types, such asrestaurant.PlaceTypePresetshascities,regions,postalCode,address(precise addresses), andestablishment.locationBiasprefers an area;locationRestrictiononly returns places inside it. Use one, not both. Each takes a circle or a rectangle.languageCode— the language of the results;regionCodeadjusts ranking and formatting.origin— not a filter: Google returns the straight-line distance to each suggestion and the field shows it. See the recipe for using the device's location.
To prefer places near a point:
PlacesAutocompleteField(
apiKey: apiKey,
locationBias: LocationBias.circle(
center: const PlaceCoordinates(latitude: 51.5074, longitude: -0.1278),
radiusMeters: 20000,
),
)
Limit results to an area covers rectangles, restriction,
and which shapes each call accepts — through Maps JavaScript, the web default, locationRestriction
must be a rectangle.
All of them are listed with their defaults in the API reference.
Costs
Google bills autocomplete per session.
The widgets put each search in one session and end it with the Place Details request made when the
user picks a place. With the default PlaceFieldPresets.address, a session bills its first 12
autocomplete requests and one Place Details Essentials request — the lowest tier that returns an
address. One Pro or Enterprise field in selectionFields — displayName, timeZone, rating, or
anything in PlaceFieldPresets.recommended — changes that: Google then bills the details request at
Enterprise + Atmosphere, and the session's autocomplete requests are free.
Two options send fewer autocomplete requests: debounceDuration, how long the field waits after
the last keystroke (300 ms by default), and minInputLength, the characters needed before it
searches at all (1 by default). fetchPlaceDetailsOnSelection: false skips the details request,
but Google then bills each autocomplete request on its own, so it is not automatically cheaper.
PlacesClient's own calls bill the fields they request: Place Details defaults to
PlaceFieldPresets.address, Text Search and Nearby Search to PlaceFieldPresets.minimal. The
field table gives each field's tier.
Security
A Google key shipped in an app can be extracted from it. Restrict every key, and pick the setup that fits:
| Setup | Key in the app | Use when |
|---|---|---|
Key restricted to your Android or iOS app, with PlacesApplicationIdentity |
Yes, usable only by your app | A mobile app calling Google directly |
| Key restricted to your website, for the Maps JavaScript API | Yes, usable only from your domains | Autocomplete and details on web |
PlacesClient.proxy() to your own authenticated server |
No | The key must never ship, or you need per-user quotas |
An app-restricted mobile key needs PlacesClientOptions.applicationIdentity, so pass a client:
built with it rather than apiKey:. The security guide has the
setup for each row.
Troubleshooting
The widget shows a short error message. Pass onError: (error) => debugPrint('$error') to see the
PlacesException, which carries Google's own explanation.
| Symptom | Fix |
|---|---|
HTTP 403, PERMISSION_DENIED: "Places API (New) has not been used in project…" |
Enable Places API (New) for the key's project. The legacy Places API is a different API and cannot be enabled on new projects. |
HTTP 403, PERMISSION_DENIED mentioning billing |
Enable billing on the Google Cloud project. |
HTTP 403, PERMISSION_DENIED: "Requests from this Android client application…" or "…iOS client application… are blocked" |
The key is restricted to your app but the request carried no identity. Pass a client: with PlacesClientOptions.applicationIdentity — see Security. |
On web, including --wasm builds, nothing loads and the browser console shows ApiNotActivatedMapError or RefererNotAllowedMapError |
Enable the Maps JavaScript API, and add your site to the key's website restrictions. Wasm builds use it from 0.7.0 on. |
REQUEST_DENIED from a time-zone lookup |
Enable the Time Zone API for the key, or turn off fetchTimeZoneOnSelection. |
place.photos is always empty |
Photos are not in the default fields. Add PlaceField.photos to selectionFields, as shown in Photos. |
place.displayName is null |
It is a Pro field, not in the default. Use selection.suggestion.primaryText.text, or add PlaceField.displayName. |
What's new
Version 0.8.0 shows the widgets' text in your app's language, in English, Hebrew, Arabic,
Russian, French, German, Spanish and Portuguese, with no code. Distances read in km, or in mi and
ft on US, GB, LR and MM devices, and custom rows get the formatted distance as
PlacesSuggestionItemData.distanceText. A few layout fixes round it out. See
What's new in 0.8.0 for details and examples; no source change is
required to upgrade.
Earlier releases: What's new in 0.7.0, 0.6.1 and 0.6.0.
More documentation
- Recipes — forms, dialogs, search without a widget, your own UI, distances, photos, proxies, errors
- API reference and defaults
- Generated API docs — every class and member
- Example app — run it with
flutter run --dart-define=GOOGLE_MAPS_API_KEY=your_key_herefromexample/ - What's new in 0.8.0
- What's new in 0.7.0
- What's new in 0.6.1
- What's new in 0.6.0
- Migration guide
- Security and transport configuration
- Places API (New)
- Place Autocomplete (New)
- Place Details (New)
- Time Zone API
Libraries
- google_places_sdk_flutter
- Cross-platform Flutter package for Google Places API (New).