[Video](https://www.youtube.com/watch?v=oOLWiJ-G_hA)

Maps Android Kotlin extensions (KTX) are a collection of Kotlin extensions for the Maps SDK for
Android and the Maps SDK for Android Utility Library. These extensions provide
Kotlin language features that enable you to write concise and idiomatic Kotlin
when developing for the Maps SDK for Android. Maps KTX is open-sourced and
available on [GitHub](https://github.com/googlemaps/android-maps-ktx) along with
examples.

## Installation

To install KTX for the Maps SDK for Android, and optionally for the Maps SDK for
Android Utility Library, add the following dependencies to your `build.gradle.kts`
file.

```
dependencies {

    // Maps SDK for Android Utils library (includes KTX extensions)
    implementation(libs.android.maps.utils)
}
```

## Example Usages

With the KTX library, you can take advantage of several Kotlin language
features such as extension functions, named parameters and default arguments,
destructuring declarations, and coroutines.

### Retrieving a GoogleMap using coroutines

Accessing a [`GoogleMap`](https://developers.google.com/maps/documentation/android-sdk/reference/com/google/android/libraries/maps/GoogleMap.md.txt) can be retrieved
using coroutines.

```
scope.launch {
    if (context is FragmentActivity) {
        val mapFragment =
            context.supportFragmentManager.findFragmentById(R.id.map) as? SupportMapFragment
        val googleMap = mapFragment?.awaitMap()
    }
}
```

### Adding a marker

Adding a marker can be done using the DSL-style method `addMarker()`.

```
val sydney = LatLng(-33.852, 151.211)
val marker = googleMap.addMarker {
    position(sydney)
    title("Marker in Sydney")
}
```

### Collecting camera events

Events, such as camera moves, can be collected via [Kotlin Flow](https://developer.android.com/kotlin/flow).

```
scope.launch {
    googleMap.cameraMoveEvents().collect {
        Log.d("KTX", "Received camera move event")
    }
}
```

You can see a full list of supported features by reading the
[reference documentation](https://googlemaps.github.io/android-maps-ktx).

## Try the sample application

The GitHub repository for this library also contains a [demo application](https://github.com/googlemaps/android-maps-ktx/tree/main/app)
that shows how you can use the Maps KTX library in your own app.

To try the demo application, follow these steps:

1. From [GitHub](https://github.com/googlemaps/android-maps-ktx), clone the or download the ZIP file.
2. In Android Studio, choose **File -\> Open** and navigate to the directory and open the folder that you just cloned or downloaded.
3. Add an API key to the demo app.
   1. [Get a Maps SDK for Android key](https://developers.google.com/maps/documentation/android-sdk/get-api-key.md.txt).
   2. In the root directory, create a file called `secrets.properties`. This file should NOT be under version control to protect your API key.
   3. Add this single line to `secrets.properties`  

      ```
      MAPS_API_KEY="YOUR_API_KEY"
      ```
      where `YOUR_API_KEY` is the actual API key you obtained in the first step. You can look at the [`secrets.defaults.properties`](https://github.com/googlemaps/android-maps-ktx/blob/main/secrets.defaults.properties) as an example.
4. Under the run configuration, select the module **app-ktx**.
5. Select **Run 'app-ktx'.**

### What's next

You may also be interested in other Kotlin extension libraries for Google Maps
Platform:

- [KTX](https://developers.google.com/maps/documentation/android-sdk/utility/setup.md.txt#ktx) for the Map SDK for Android Utility Library
- [KTX](https://developers.google.com/maps/documentation/places/android-sdk/ktx.md.txt#install) for the Places SDK for Android