1. Introduction
Flutter is Google's UI toolkit for crafting high-quality experiences across mobile, web, and desktop from a single codebase.
With the google_maps_flutter plugin, you can embed interactive maps powered by Google Maps data directly into your Flutter application. The plugin automatically handles access to Google Maps servers, map rendering, and user gestures such as taps, drags, and pinch-to-zoom. You can also overlay markers and info windows on your map to highlight locations and let users interact with map data.
What you'll build
In this codelab, you'll collaborate with Google Antigravity to iteratively build a Flutter app featuring an interactive Google Map.
Your finished app will:
|
|
Your learning journey
This codelab guides you through building the Google Maps app step by step:
- Set up your Flutter environment - Configure the Flutter SDK, Google Antigravity, and your target device or browser.
- Create a project - Prompt Antigravity to scaffold a Flutter project with
google_maps_flutterandmaterial_ui, and configure platform settings. - Add Google Maps to the app - Configure Google Maps Platform API keys for Android, iOS, and the web, and render an initial
GoogleMapcentered on Portland. - Put Google on the map - Model and deserialize Google office locations from a JSON asset using
json_serializable, and display interactive markers on the map.
What you'll learn
- How to collaborate with Google Antigravity to iteratively build and customize a Google Maps Flutter app.
- How to configure the
google_maps_flutterplugin and platform API keys for Android, iOS, and the web. - How to embed a
GoogleMapwidget and control its initial camera position. - How to parse JSON location data with
json_serializableand renderMarkeroverlays on a map.
Prerequisites
- Basic familiarity with Flutter widgets and Dart syntax.
- A Google Maps Platform API key (optional for local development testing, required to render map tiles without a watermark).
What would you like to learn from this codelab?
2. Set up your Flutter environment
Editor
This codelab uses Google Antigravity as your AI-first development environment. In each step, you prompt Antigravity to generate or evolve your app's code, review the key Flutter and Google Maps concepts in the generated files, and optionally explore creative variations.
Choose a development target
You can run this codelab using any of the following targets:
- A physical Android or iOS device connected to your computer and set to Developer mode.
- The iOS Simulator (requires installing Xcode on macOS).
- The Android Emulator (requires setup in Android Studio).
- A web browser such as Chrome.
Install Flutter
The most up-to-date instructions on installing the Flutter SDK are always on docs.flutter.dev.
For this codelab, install the following software:
- Flutter SDK
- Google Antigravity with the official Dart and Flutter plugin enabled (available in the Plugin Marketplace under the Build with Google section).
- Platform tools for your chosen development target (such as Xcode for iOS, Android Studio for Android, or Chrome for the web).
3. Create a project
Prompt Antigravity to create the project
- Launch Google Antigravity and open an empty directory where you'd like to build your project (choose a path that doesn't require elevated privileges or contain spaces, such as a folder in your home directory or
C:\src\). - In the Antigravity agent chat panel, send the following prompt to scaffold the Flutter project, add the required packages, and configure the platform settings:
Create a new Flutter project named `google_maps_in_flutter` in the current directory targeting Android, iOS, and web (`--platforms android,ios,web`). Add the `google_maps_flutter` and `material_ui` packages, update `lib/main.dart` and `test/widget_test.dart` to import `package:material_ui/material_ui.dart` instead of `package:flutter/material.dart`, and set the minimum iOS platform version in `ios/Podfile` to `platform :ios, '16.0'`.
Understanding the generated configuration
Antigravity creates the google_maps_in_flutter project for Android, iOS, and web, adds google_maps_flutter and material_ui to pubspec.yaml, and configures the platform project files.
Configuring the iOS platform version
The Google Maps SDK for iOS requires a minimum deployment target of iOS 16.0 (see the Google Maps Flutter package configuration guide). Antigravity updates the top of ios/Podfile to declare platform :ios, '16.0':
# Google Maps SDK for iOS requires iOS 16.0
# https://developers.google.com/maps/flutter-package/config#ios
platform :ios, '16.0'
# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
ENV['COCOAPODS_DISABLE_STATS'] = 'true'
Android minSdk configuration
The Google Maps SDK for Android requires minSdk 21 or higher. Modern Flutter templates configure minSdk = flutter.minSdkVersion (which defaults to Android API 24 or higher) in android/app/build.gradle.kts, so Android meets the minimum SDK requirement out of the box.
4. Add Google Maps to the app
Get a Google Maps Platform API key
To display live map tiles in your Flutter app, configure an API project with the Google Maps Platform and generate an API key by following the setup guides for the platforms you target:
Prompt Antigravity to configure API keys and display a map
With your API key ready (or using a placeholder key while developing), send the following prompt in the Antigravity agent chat panel to wire up the platform API key entries and display a Google Map centered on Portland, Oregon:
Configure the project for Google Maps and display an initial map on the screen:
1. Add Google Maps API key configuration entries to `android/app/src/main/AndroidManifest.xml` (`com.google.android.geo.API_KEY` with value `YOUR-KEY-HERE`), `ios/Runner/AppDelegate.swift` (`import GoogleMaps` and `GMSServices.provideAPIKey("YOUR-API-KEY")` inside `didInitializeImplicitFlutterEngine`), and `web/index.html` (`<script src="https://maps.googleapis.com/maps/api/js?key=YOUR-KEY-HERE"></script>`).
2. Update `lib/main.dart` (importing `package:material_ui/material_ui.dart` and `package:google_maps_flutter/google_maps_flutter.dart`) so `MyApp` is a `StatefulWidget` with `ThemeData(colorSchemeSeed: Colors.green[700])`, an `AppBar` titled `'Maps Sample App'` with `elevation: 2`, and a `GoogleMap` widget centered on Portland (`LatLng(45.521563, -122.677433)`) with zoom `11.0` and an `_onMapCreated` callback that stores the `GoogleMapController`. Also update `test/widget_test.dart` with a basic widget test that pumps `const MyApp()`.
Understanding the generated code
Platform API key registration
Each target platform loads the Google Maps API key from its platform-specific entry point. Replace YOUR-KEY-HERE or YOUR-API-KEY with your actual Google Maps Platform API key:
- Android (
android/app/src/main/AndroidManifest.xml): Registers aelement inside thetag:
<application
android:label="google_maps_in_flutter"
android:name="${applicationName}"
android:icon="@mipmap/ic_launcher">
<!-- Add your Google Maps API key here -->
<meta-data android:name="com.google.android.geo.API_KEY"
android:value="YOUR-KEY-HERE"/>
- iOS (
ios/Runner/AppDelegate.swift): Imports theGoogleMapsmodule and passes your API key toGMSServices.provideAPIKey(_:)when the Flutter engine initializes:
import Flutter
import UIKit
import GoogleMaps
@main
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
// Add your Google Maps API key here
GMSServices.provideAPIKey("YOUR-API-KEY")
}
}
- Web (
web/index.html): Loads the Maps JavaScript API script inside theelement:
<!-- Add your Google Maps API key here -->
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR-KEY-HERE"></script>
Rendering the GoogleMap widget (lib/main.dart)
In lib/main.dart, _MyAppState embeds a GoogleMap widget inside a Scaffold and captures the GoogleMapController once the map view is initialized:
class _MyAppState extends State<MyApp> {
late GoogleMapController mapController;
final LatLng _center = const LatLng(45.521563, -122.677433);
void _onMapCreated(GoogleMapController controller) {
mapController = controller;
}
@override
Widget build(BuildContext context) {
return MaterialApp(
theme: ThemeData(colorSchemeSeed: Colors.green[700]),
home: Scaffold(
appBar: AppBar(title: const Text('Maps Sample App'), elevation: 2),
body: GoogleMap(
onMapCreated: _onMapCreated,
initialCameraPosition: CameraPosition(target: _center, zoom: 11.0),
),
),
);
}
}
CameraPosition: Defines where the map camera initially points (target) and how closely it zooms in (zoom: 11.0shows a city-level view).onMapCreated: Invoked when the platform map view is ready, providing aGoogleMapControllerthat you can use to programmatically pan, zoom, or query the map.
Run and test the app
Because this step modifies platform configuration files (AndroidManifest.xml, AppDelegate.swift, and web/index.html), perform a full run (rather than a hot reload) on your target device or simulator:
flutter run
You should see an interactive map centered on Portland, Oregon:
|
|
5. Put Google on the map
Google has offices around the world, from North America and Latin America to Europe, Asia Pacific, and Africa and the Middle East. In this step, you'll prompt Antigravity to create a bundled assets/locations.json dataset of Google office coordinates, addresses, and regions, generate strongly typed JSON serialization classes using json_serializable and build_runner, and display every office as an interactive Marker on the map.
Prompt Antigravity to load and display Google office markers
Send the following prompt in the Antigravity agent chat panel:
Display Google office locations from a bundled JSON asset as markers on the map:
1. Add the `json_annotation` and `json_serializable` packages, plus `build_runner` as a dev dependency (`dev:build_runner`).
2. Create `assets/locations.json` containing a JSON object with `offices` (a list of Google offices around the world, each with `id`, `name`, `address`, `lat`, `lng`, `phone`, `image`, and `region`) and `regions` (each with `id`, `name`, `zoom`, and `coords` containing `lat` and `lng`), and register `assets/locations.json` under the `flutter:` `assets:` section of `pubspec.yaml`.
3. Create `lib/src/locations.dart` with `@JsonSerializable()` classes `LatLng`, `Region`, `Office`, and `Locations` (using `part 'locations.g.dart';`), and a `Future<Locations> getGoogleOffices()` function that loads `'assets/locations.json'` from `rootBundle` and decodes it with `Locations.fromJson`. Run `dart run build_runner build` to generate `lib/src/locations.g.dart`.
4. Update `lib/main.dart` (importing `'src/locations.dart' as locations;`) so `_MyAppState` stores `final Map<String, Marker> _markers = {};`, loads `locations.getGoogleOffices()` in `_onMapCreated`, populates `_markers` inside `setState()` with a `Marker` for each office (using `MarkerId(office.name)`, `LatLng(office.lat, office.lng)`, and `InfoWindow(title: office.name, snippet: office.address)`), updates the `AppBar` title to `'Google Office Locations'`, sets `initialCameraPosition` to `const CameraPosition(target: LatLng(0, 0), zoom: 2)`, and passes `markers: _markers.values.toSet()` to `GoogleMap`.
Understanding the generated code
JSON data modeling and code generation (lib/src/locations.dart)
Rather than manually extracting fields from untyped Map structures, lib/src/locations.dart annotates strongly typed Dart classes with @JsonSerializable() and delegates serialization boilerplate to locations.g.dart (generated by dart run build_runner build):
@JsonSerializable()
class Office {
Office({
required this.address,
required this.id,
required this.image,
required this.lat,
required this.lng,
required this.name,
required this.phone,
required this.region,
});
factory Office.fromJson(Map<String, dynamic> json) => _$OfficeFromJson(json);
Map<String, dynamic> toJson() => _$OfficeToJson(this);
final String address;
final String id;
final String image;
final double lat;
final double lng;
final String name;
final String phone;
final String region;
}
Loading the bundled JSON asset (getGoogleOffices)
In lib/src/locations.dart, getGoogleOffices() reads the bundled assets/locations.json file through Flutter's rootBundle and deserializes the JSON map into a Locations instance:
Future<Locations> getGoogleOffices() async {
return Locations.fromJson(
json.decode(await rootBundle.loadString('assets/locations.json'))
as Map<String, dynamic>,
);
}
Populating Markers on the GoogleMap (lib/main.dart)
In lib/main.dart, _onMapCreated awaits locations.getGoogleOffices() and converts each Office into a Marker inside setState():
class _MyAppState extends State<MyApp> {
final Map<String, Marker> _markers = {};
Future<void> _onMapCreated(GoogleMapController controller) async {
final googleOffices = await locations.getGoogleOffices();
setState(() {
_markers.clear();
for (final office in googleOffices.offices) {
final marker = Marker(
markerId: MarkerId(office.name),
position: LatLng(office.lat, office.lng),
infoWindow: InfoWindow(title: office.name, snippet: office.address),
);
_markers[office.name] = marker;
}
});
}
import 'src/locations.dart' as locations;: Prefixes thelocations.dartlibrary so itsLatLngmodel class doesn't collide withLatLngfrompackage:google_maps_flutter/google_maps_flutter.dart.Marker&InfoWindow: Each marker has a uniqueMarkerId, a geographicposition, and anInfoWindowthat displays the office'snameandaddresswhen tapped.markers: _markers.values.toSet(): CallingsetState()triggers a rebuild, passing the updatedSetto theGoogleMapwidget so the pins appear across the globe.
Run and test the app
Perform a hot restart (or re-run flutter run so the newly added assets/locations.json bundle is loaded). Zoom out or pan around the globe and tap any pin to inspect the Google office's name and address:

6. Congratulations!
You've completed the codelab and built a Flutter application that displays an interactive Google Map populated with JSON location data!
What you've built
- Configured a multi-platform Flutter app with
google_maps_flutterandmaterial_ui. - Set up Google Maps Platform API keys for Android, iOS, and the web.
- Created a typed JSON data layer using
json_serializable,build_runner, androotBundleassets. - Rendered interactive
Markerpins andInfoWindowpopups for Google offices worldwide.

