Before you set up a Flutter project be sure you've completed the prerequisite steps under Before you begin. After you enable billing 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 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.
-
Create a new Flutter project using `flutter create`:
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!google_maps_in_flutter/lib/main.dart
. To run your application, type:cd google_maps_in_flutter
flutter run
-
Add the Google Maps for Flutter package plugin to this project.
flutter pub add google_maps_flutter
Resolving dependencies... [Listing of dependencies elided] Changed 14 dependencies!
Step 3: Set the platform version
Android
Set the minimum SDK version for Android.
- Open the
android/app/build.gradle
config file in your preferred IDE. - Change the value of
android.defaultConfig.minSdkVersion
to21
:android { //... defaultConfig { applicationId "com.example.google_maps_in_flutter" minSdkVersion 21 // Set to 21 targetSdkVersion flutter.targetSdkVersion versionCode flutterVersionCode.toInteger() versionName flutterVersionName } //... }
- When configuring
defaultConfig
, specify your own unique ApplicationID. - Save the file and sync your project changes with Gradle.
iOS
Set the minimum iOS platform version.
- Open the
ios/Podfile
config file in your preferred IDE. - 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, 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.
Android
To streamline this task, we recommend that you use the Secrets Gradle Plugin for Android.
To install the Secrets Gradle Plugin for Android in your Google Maps project:
-
In Android Studio, open your top-level
build.gradle.kts
orbuild.gradle
file and add the following code to thedependencies
element underbuildscript
.Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
Open your module-level
build.gradle.kts
orbuild.gradle
file and add the following code to theplugins
element.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- In your module-level
build.gradle.kts
orbuild.gradle
file, ensure thattargetSdk
andcompileSdk
are set to 34. - Save the file and sync your project with Gradle.
-
Open the
secrets.properties
file in your top-level directory, and then add the following code. ReplaceYOUR_API_KEY
with your API key. Store your key in this file becausesecrets.properties
is excluded from being checked into a version control system.MAPS_API_KEY=YOUR_API_KEY
- Save the file.
-
Create the
local.defaults.properties
file in your top-level directory, the same folder as thesecrets.properties
file, and then add the following code.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 is not found so that builds don't fail. This can happen if you clone the app from a version control system which omitssecrets.properties
and you have not yet created asecrets.properties
file locally to provide your API key. - Save the file.
-
In your
AndroidManifest.xml
file, go tocom.google.android.geo.API_KEY
and update theandroid:value attribute
. If the<meta-data>
tag does not exist, create it as a child of the<application>
tag.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
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 namecom.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. -
In Android Studio, open your module-level
build.gradle.kts
orbuild.gradle
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Kotlin
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the 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" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Groovy
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the 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" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
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.
- Open the
ios/Runner/AppDelegate.swift
file in your Flutter project with your preferred IDE. - Add the following import statement to add Google Maps for Flutter package to your app:
- Add your API to your
application(_:didFinishLaunchingWithOptions:)
method, substituting your API key for YOUR_API_KEY:GMSServices.provideAPIKey("YOUR_API_KEY")
- Save and close the
AppDelegate.swift
file.
import GoogleMaps
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.
- Open the
web/index.html
file in your Flutter project with your preferred IDE. - Add the following script tag inside the
<head>
tag, substituting your API key forYOUR_API_KEY
.<script> (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({ key: "YOUR_API_KEY", v: "weekly", // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.). // Add other bootstrap parameters as needed, using camel case. }); </script>
- Save and close the
index.html
file.The complete
head
section of theindex.html
should resemble the following:<head> <base href="/"> <meta charset="UTF-8"> <meta content="IE=Edge" http-equiv="X-UA-Compatible"> <meta name="description" content="A new Flutter project."> <!-- iOS meta tags & icons --> <meta name="apple-mobile-web-app-capable" content="yes"> <meta name="apple-mobile-web-app-status-bar-style" content="black"> <meta name="apple-mobile-web-app-title" content="google_maps_in_flutter"> <link rel="apple-touch-icon" href="icons/Icon-192.png"> <script> (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({ key: "YOUR_API_KEY", v: "weekly", // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.). // Add other bootstrap parameters as needed, using camel case. }); </script> <title>google_maps_in_flutter</title> <link rel="manifest" href="manifest.json"> </head>
Step 5: Add a map
The following code demonstrates how to add a simple map to a new Flutter app.
- Open the
lib/main.dart
file in your Flutter project with your preferred IDE. - 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<MyApp> createState() => _MyAppState(); } class _MyAppState extends State<MyApp> { 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, ), ), ), ); } }
- Start any emulators or devices on which you want to run your application.
- Run your application. You should see output resembling the following:
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 tutorial
- Codelabs for Flutter with Google Maps Platform
- Code samples on GitHub