⚠️ PROJECT ARCHIVED & DEPRECATED ⚠️

This library is no longer maintained and has been officially archived.

Why is this project being retired?

All Kotlin extensions (KTX) and coroutines functionality originally provided by this library have migrated directly into the official Places SDK for Android (v3.3.0+ / v5.x+).

Migration

1. Use Official Places SDK Extensions: Replace the com.google.maps.android:places-ktx dependency by upgrading to the official Places SDK for Android:

   implementation 'com.google.android.libraries.places:places:<latest-version>'
   

   All Kotlin extension functions (such as awaitFetchPlace, awaitFindAutocompletePredictions, awaitSearchNearby, awaitIsOpen, and model builders) are now natively provided by the SDK under the com.google.android.libraries.places.api.net.kotlin and com.google.android.libraries.places.api.model.kotlin packages.
2. Jetpack Compose: For Jetpack Compose UI components, refer to android-places-compose.
3. Detailed Guide: Refer to the Migration Guide for full step-by-step instructions.

---

Description

Requirements

• Sign up with Google Maps Platform
• A Google Maps Platform project with the Maps SDK for Android enabled
• An API key associated with the project above
• Android API level 24+
• Kotlin-enabled project
• Kotlin coroutines

Installation

If you are using the Places SDK through Google Play Services:

dependencies {
    implementation 'com.google.maps.android:places-ktx:5.0.0' // {x-release-please-version}
}

Usage

Accessing API responses made by PlacesClient can be retrieved using coroutines via the official Places SDK extensions.

This library serves as a compatibility shim and provides DSL builders for projects migrating from older versions of the Places KTX library. New projects are encouraged to use the official SDK extensions directly.

Example: Programmatic Autocomplete

The example here demonstrates how you can use the official SDK's KTX extensions alongside with Android’s ViewModel KTX’s viewModelScope and StateFlow.

Before

val bias = RectangularBounds.newInstance(
    LatLng(22.458744, 88.208162), // SW lat, lng
    LatLng(22.730671, 88.524896) // NE lat, lng
)

// Create a new programmatic Place Autocomplete request in Places SDK for Android using builders
val newRequest = FindAutocompletePredictionsRequest
    .builder()
    .setLocationBias(bias)
    .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
    .setQuery("123 Main Street")
    .setCountries("IN")
    .build()

// Perform autocomplete predictions request
placesClient.findAutocompletePredictions(newRequest).addOnSuccessListener { response ->
    // Handle response
}.addOnFailureListener { exception ->
    // Handle exception
}

After

import com.google.android.libraries.places.api.model.AutocompleteSessionToken
import com.google.android.libraries.places.api.net.kotlin.awaitFindAutocompletePredictions
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.debounce
import kotlinx.coroutines.flow.flatMapLatest

@OptIn(FlowPreview::class)
class PlacesSearchViewModel(private val placesClient: PlacesClient) : ViewModel() {
    private val _query = MutableStateFlow("")
    private var sessionToken: AutocompleteSessionToken? = null

    val results = _query
        .debounce(300)
        .flatMapLatest { query ->
            flow {
                if (sessionToken == null) {
                    sessionToken = AutocompleteSessionToken.newInstance()
                }
                val response = placesClient.awaitFindAutocompletePredictions {
                    this.query = query
                    this.sessionToken = this@PlacesSearchViewModel.sessionToken
                    countries = listOf("US")
                }
                emit(response.autocompletePredictions)
            }
        }
}

Sample App

A demo application is contained within this repository that illustrates the use of this KTX library.

To run the demo app, create a secrets.properties file in your root directory (Note: this file should NOT be under version control to protect your API key) and add your API key:

PLACES_API_KEY=YOUR_API_KEY

Replace YOUR_API_KEY with the API key you obtained in the first step. You can also refer to local.defaults.properties for an example of the expected format. Then build and run.

Documentation

You can learn more about all the extensions provided by this library by reading the [reference documents].

For more information, check out the detailed guide.

Contributing

Contributions are welcome and encouraged! If you'd like to contribute, send us a pull request and refer to our code of conduct and contributing guide.

Terms of Service

This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform Terms of Service.

If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region. Learn more.

This library is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g. Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this library.

Support

This library is offered via an open source license. It is not governed by the Google Maps Platform Support Technical Support Services Guidelines, the SLA, or the Deprecation Policy. However, any Google Maps Platform services used by the library remain subject to the Google Maps Platform Terms of Service.

This library adheres to semantic versioning to indicate when backwards-incompatible changes are introduced. Accordingly, while the library is in version 0.x, backwards-incompatible changes may be introduced at any time.

If you find a bug, or have a feature request, please file an issue on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, ask through one of our developer community channels. If you'd like to contribute, please check the contributing guide.

You can also discuss this library on our Discord server.