Before you set up a Flutter project be sure you've completed the prerequisite steps under [Before you begin](https://developers.google.com/maps/flutter-package/overview.md.txt). After you [enable billing](https://developers.google.com/maps/documentation/ios-sdk/cloud-setup) and create an API key, you can set up the Flutter project that you use to develop your app. ## Step 1: Install the required software To build a project using the Google Maps for Flutter package, you must install the Flutter SDK and setup your development environment for your target platform. Check out the [Flutter install guide](https://docs.flutter.dev/get-started/install) for details. ## Step 2: Install the Google Maps for Flutter package in a new project Flutter offers the Google Maps for Flutter package as a Flutter plugin. Create the Flutter project and add the Maps plugin. 1. Create a new Flutter project using \`flutter create\`: ```console `flutter create google_maps_in_flutter --platforms=android,ios,web` Creating project google_maps_in_flutter... [Listing of created files elided] Wrote 127 files. All done! ``` Your application code is in `google_maps_in_flutter/lib/main.dart`. To run your application, type: ```console `cd google_maps_in_flutter` `flutter run` ``` This application targets iOS, Android and Web. Google Maps SDK does not support desktop applications outside of a browser at this time. 2. Add the Google Maps for Flutter package plugin to this project. ```console flutter pub add google_maps_flutter Resolving dependencies... [Listing of dependencies elided] Changed 14 dependencies! ``` ## Step 3: Set the platform version **Note:** Setting a platform version is required for deploying app to iOS, Android or both. Web apps are not require to set a minimum version. ### Android Set the minimum SDK version for Android. 1. Open the `android/app/build.gradle` config file in your preferred IDE. 2. Change the value of `android.defaultConfig.minSdkVersion` to `21`: ``` android { //... defaultConfig { applicationId "com.example.google_maps_in_flutter" minSdkVersion 21 // Set to 21 targetSdkVersion flutter.targetSdkVersion versionCode flutterVersionCode.toInteger() versionName flutterVersionName } //... } ``` 3. When configuring `defaultConfig`, specify your own unique [ApplicationID](https://developer.android.com/studio/build/application-id.html). 4. [Sync your project changes with Gradle.](https://developer.android.com/studio/build#sync-files) ### iOS Set the minimum iOS platform version. 1. Open the `ios/Podfile` config file in your preferred IDE. 2. Add the following lines to the beginning of this Podfile: ``` # Set platform to 14.0 to enable latest Google Maps SDK platform :ios, '14.0' ``` ## Step 4: Add your API key to the project In [Before you begin](https://developers.google.com/maps/flutter-package/overview.md.txt), you generated an API key for your app. Now add that key to your Flutter project. For Flutter, you should add this API key to all target platforms: iOS, Android, and Web. In the following examples, replace `YOUR_API_KEY` with your API key. **Note:** It's recommended to use [separate API keys](https://developers.google.com/maps/api-security-best-practices.md.txt#separate-apikey) and utilize [application restrictions](https://developers.google.com/maps/api-security-best-practices.md.txt#application-restriction) for Android, iOS and Web. ### Android To streamline this task, we recommend that you use the [Secrets Gradle Plugin for Android](https://github.com/google/secrets-gradle-plugin). To install the Secrets Gradle Plugin for Android and store your API key: 1. In Android Studio, open your top-level `build.gradle.kts` or `build.gradle` file and add the following code to the `plugins` block. ### Kotlin ```kotlin plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false } ``` ### Groovy ```groovy plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false } ``` 2. Open your module-level `build.gradle.kts` or `build.gradle` file and add the following code to the `plugins` element. ### Kotlin ```kotlin plugins { id("com.android.application") // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") } ``` ### Groovy ```groovy plugins { id 'com.android.application' // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' } ``` 3. If you use Android Studio, [sync your project with Gradle](https://developer.android.com/studio/build#sync-files). 4. Open the `secrets.properties` file in your top-level directory, and then add the following code. Replace `YOUR_API_KEY` with your API key. Make sure to add `secrets.properties` to your `.gitignore` file (or otherwise exclude it from your version control system) so that you don't check your API key into version control. > [!NOTE] > **Note:** If the `secrets.properties` file doesn't exist, create it in the same folder as the `local.properties` file. ``` MAPS_API_KEY=YOUR_API_KEY ``` 5. Create the `local.defaults.properties` file in your top-level directory, the same folder as the `secrets.properties` file, and then add the following code. > [!NOTE] > **Note:** Enter the code as shown. Don't replace `DEFAULT_API_KEY` with your API key. ``` MAPS_API_KEY=DEFAULT_API_KEY ``` The purpose of this file is to provide a backup location for the API key if the `secrets.properties` file isn't found so that builds don't fail. This can happen if you clone the app from a version control system that omits `secrets.properties` and you haven't yet created a `secrets.properties` file locally to provide your API key. 6. In your `AndroidManifest.xml` file, go to `com.google.android.geo.API_KEY` and update the `android:value` attribute as follows: ```html ``` **Note:** `com.google.android.geo.API_KEY` is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Flutter SDK. For backwards compatibility, the API also supports the name `com.google.android.maps.v2.API_KEY`. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. 7. In Android Studio, open your module-level `build.gradle.kts` or `build.gradle` file and edit the `secrets` property. If the `secrets` property doesn't exist, add it. Edit the properties of the plugin to set `propertiesFileName` to `"secrets.properties"`, set `defaultPropertiesFileName` to `"local.defaults.properties"`, and set any other properties. ### Kotlin ```kotlin secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file). // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" } ``` ### Groovy ```groovy secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file). // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" } ``` **Note:** As shown above, `com.google.android.geo.API_KEY` is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Flutter SDK. For backwards compatibility, the API also supports the name `com.google.android.maps.v2.API_KEY`. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. ### iOS Add your API key to your `AppDelegate.swift` file. 1. Open the `ios/Runner/AppDelegate.swift` file in your Flutter project with your preferred IDE. 2. Add the following import statement to add Google Maps for Flutter package to your app: ``` import GoogleMaps ``` 3. Add your API to your `application(_:didFinishLaunchingWithOptions:)` method, substituting your API key for YOUR_API_KEY: ``` GMSServices.provideAPIKey("YOUR_API_KEY") ``` 4. Save and close the `AppDelegate.swift` file. The completed `AppDelegate.swift` file should resemble the following: ``` import UIKit import Flutter import GoogleMaps // Add this import @UIApplicationMain @objc class AppDelegate: FlutterAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self) // TODO: Add your Google Maps API key GMSServices.provideAPIKey("YOUR_API_KEY") return super.application(application, didFinishLaunchingWithOptions: launchOptions) } } ``` ### Web Add your API key to your `index.html` application file. 1. Open the `web/index.html` file in your Flutter project with your preferred IDE. 2. Add the following script tag inside the `` tag, substituting your API key for `YOUR_API_KEY`. ```javascript ``` 3. Save and close the `index.html` file. The complete `head` section of the `index.html` should resemble the following: ``` google_maps_in_flutter ``` ## Step 5: Add a map The following code demonstrates how to add a simple map to a new Flutter app. > [!NOTE] > **Note:** Assuming the prior steps were accomplished successfully, the following main Dart function should work across all platforms, including Android, iOS and Web. 1. Open the `lib/main.dart` file in your Flutter project with your preferred IDE. 2. Add or update methods in your app's default main method to create and initialize an instance of `mapController`. ``` import 'package:flutter/material.dart'; import 'package:google_maps_flutter/google_maps_flutter.dart'; void main() => runApp(const MyApp()); class MyApp extends StatefulWidget { const MyApp({super.key}); @override State createState() => _MyAppState(); } class _MyAppState extends State { late GoogleMapController mapController; final LatLng _center = const LatLng(-33.86, 151.20); void _onMapCreated(GoogleMapController controller) { mapController = controller; } @override Widget build(BuildContext context) { return MaterialApp( home: Scaffold( appBar: AppBar( title: const Text('Maps Sample App'), backgroundColor: Colors.green[700], ), body: GoogleMap( onMapCreated: _onMapCreated, initialCameraPosition: CameraPosition( target: _center, zoom: 11.0, ), ), ), ); } } ``` 3. Start any emulators or devices on which you want to run your application. 4. Run your application. You should see output resembling the following: ```console `flutter run` Multiple devices found: Android phone (mobile) • emulator-5554 • android-arm64 • Android 13 (API 33) (emulator) iPhone (mobile) • ios • com.apple.CoreSimulator.SimRuntime.iOS-16-2 (simulator) Chrome (web) • chrome • web-javascript • Google Chrome 108.0.5359.124 [1]: Android phone [2]: iPhone [3]: Chrome Please choose one (To quit, press "q/Q"): ``` Type the number of the platform you want to run. Each time you invoke `flutter run`, Flutter will present you with these choices. If your development system has no emulator running or connected test device, Flutter should choose to open Chrome. Each platform should display a map centered over Sydney, Australia. If you didn't see the map, check that you added your API key to the appropriate target project. ## Next steps Now that you have an API key and a Flutter project, you can create and run apps. The Google Maps for Flutter package provides many tutorials and sample apps that can help you get started. To learn more, check out the following resources: - [Adding a Map with a Marker](https://developers.google.com/maps/flutter-plugin/map-with-marker) tutorial - [Codelabs](https://codelabs.developers.google.com/?cat=mapsplatform&product=googlemapsplatform&text=flutter) for Flutter with Google Maps Platform - [Code samples](https://github.com/flutter/samples/tree/main/google_maps) on GitHub