Set up a Flutter Project

  • Before starting, ensure you've completed the prerequisites, enabled billing, and created an API key.

  • Install the Flutter SDK, create a new Flutter project, and add the Google Maps for Flutter package.

  • Configure platform-specific settings for Android and iOS, including minimum SDK versions.

  • Add your API key to the Android, iOS, and web versions of your project using the provided instructions.

  • Add a simple map to your Flutter app by updating thelib/main.dart file and running the application.

Before you set up a Flutter project be sure you've completed the prerequisitesteps underBefore you begin. After youenablebillingand create an API key, you can set up the Flutter project that you use todevelop your app.

Step 1: Install the required software

To build a project using the Google Maps for Flutter package, you must install theFlutter SDK and setup your development environment for your target platform.Check out theFlutter installguide 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`:
    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 ingoogle_maps_in_flutter/lib/main.dart. To run your application, type:
    cd google_maps_in_flutterflutter 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.
    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.

Step 4: Add your API key to the project

InBefore you begin, you generated an API key for your app. Now addthat key to your Flutter project. For Flutter, you should add this API key toall target platforms: iOS, Android, and Web.

In the following examples, replaceYOUR_API_KEY with your API key.

Note: It's recommended to useseparate API keys and utilizeapplication restrictions for Android, iOS and Web.

Android

To streamline this task, we recommend that you use theSecrets Gradle Plugin for Android.

To install the Secrets Gradle Plugin for Android and store your API key:

  1. In Android Studio, open your root-levelbuild.gradle file and add the following code to thedependencies element underbuildscript.

    Groovy

    buildscript{dependencies{// ...classpath"com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"}}

    Kotlin

    buildscript{dependencies{// ...classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")}}
  2. Open your app-levelbuild.gradle file and add the following code to theplugins element.

    Groovy

    plugins{id'com.android.application'// ...id'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'}

    Kotlin

    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.
  4. Open thelocal.properties in your project level directory, and then add the following code. ReplaceYOUR_API_KEY with your API key.
    MAPS_API_KEY=YOUR_API_KEY
  5. In yourAndroidManifest.xml file, go tocom.google.android.geo.API_KEY and update theandroid:value attribute as follows:
    <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.

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 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.

iOS

Add your API key to yourAppDelegate.swift file.

  1. Open theios/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:
    3. importGoogleMaps
  3. Add your API to yourapplication(_:didFinishLaunchingWithOptions:) method, substituting your API key forYOUR_API_KEY:
    GMSServices.provideAPIKey("YOUR_API_KEY")
  4. Save and close theAppDelegate.swift file.

The completedAppDelegate.swift file should resemble the following:

importUIKitimportFlutterimportGoogleMaps//Addthisimport@UIApplicationMain@objcclassAppDelegate:FlutterAppDelegate{overridefuncapplication(_application:UIApplication,didFinishLaunchingWithOptionslaunchOptions:[UIApplication.LaunchOptionsKey:Any]?)->Bool{GeneratedPluginRegistrant.register(with:self)//TODO:AddyourGoogleMapsAPIkeyGMSServices.provideAPIKey("YOUR_API_KEY")returnsuper.application(application,didFinishLaunchingWithOptions:launchOptions)}}

Web

Add your API key to yourindex.html application file.

  1. Open theweb/index.html file in your Flutter project with your preferred IDE.
  2. Add the following script tag inside the<head> tag, substituting your API key forYOUR_API_KEY.
    <script>(g=>{varh,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});vard=b.maps||(b.maps={}),r=newSet,e=newURLSearchParams,u=()=>h||(h=newPromise(async(f,n)=>{await(a=m.createElement("script"));e.set("libraries",[...r]+"");for(king)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 theversion to use (weekly, beta, alpha, etc.).// Add otherbootstrap parameters as needed, using camel case.});</script>
  3. Save and close theindex.html file.

    The completehead section of theindex.html should resemble the following:

    <head><basehref="/">
<metacharset="UTF-8"><metacontent="IE=Edge"http-equiv="X-UA-Compatible"><metaname="description"content="A new Flutter project.">
<!--iOSmetatags&icons--><metaname="apple-mobile-web-app-capable"content="yes"><metaname="apple-mobile-web-app-status-bar-style"content="black"><metaname="apple-mobile-web-app-title"content="google_maps_in_flutter"><linkrel="apple-touch-icon"href="icons/Icon-192.png">
<script>(g=>{varh,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});vard=b.maps||(b.maps={}),r=newSet,e=newURLSearchParams,u=()=>h||(h=newPromise(async(f,n)=>{await(a=m.createElement("script"));e.set("libraries",[...r]+"");for(king)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",//Usethe'v'parametertoindicatetheversiontouse(weekly,beta,alpha,etc.).//Addotherbootstrapparametersasneeded,usingcamelcase.});</script>
<title>google_maps_in_flutter</title><linkrel="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.

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 thelib/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 ofmapController.
    import'package:flutter/material.dart';import'package:google_maps_flutter/google_maps_flutter.dart';      
voidmain()=>runApp(constMyApp());      
classMyAppextendsStatefulWidget{constMyApp({super.key});      
@overrideState<MyApp>createState()=>_MyAppState();}      
class_MyAppStateextendsState<MyApp>{lateGoogleMapControllermapController;      
finalLatLng_center=constLatLng(-33.86,151.20);      
void_onMapCreated(GoogleMapControllercontroller){mapController=controller;}      
@overrideWidgetbuild(BuildContextcontext){returnMaterialApp(home:Scaffold(appBar:AppBar(title:constText('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:
    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 invokeflutter 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 thatcan help you get started. To learn more, check out the following resources:

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-11 UTC.