Personal locations

The PersonalLocationsManager allows clients to save, retrieve, and manage personal locations in the navigation application. This includes favorites, home, work addresses, and recent destinations.

Overview

PersonalLocationsManager provides functionality for:

Saving personal locations (Home, Work, Favorites)
Retrieving saved locations by storage type
Observing favorite and recent location changes
Deleting personal locations

Storage types

Personal locations are organized by storage type:

Storage Type	Description
`StorageType.HOME`	User's home address
`StorageType.WORK`	User's work address
`StorageType.FAVORITE`	User-saved favorite locations
`StorageType.RECENT`	Automatically saved recent destinations

Saving personal locations

Save a location with a specific storage type. The same method works for Home, Work, and Favorites—just change the StorageType:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Address
3import com.tomtom.automotive.integration.client.api.model.Coordinate
4import com.tomtom.automotive.integration.client.api.model.NavigableLocation.PersonalLocation
5import com.tomtom.automotive.integration.client.api.model.NavigableLocation.Place
6import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
7import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.ReservedWordsCatalog
8import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationCallback
9import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationFailure
10import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationParameters
11import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationResponse
12import com.tomtom.automotive.integration.client.common.Callback
13import com.tomtom.automotive.integration.client.common.Result
14
15private val TAG = "PersonalLocations"
16
17fun savePersonalLocation(
18    personalLocationsManager: PersonalLocationsManager,
19    name: String,
20    coordinate: Coordinate,
21    storageType: PersonalLocation.StorageType
22) {
23    val place = Place(coordinate, address = null)
24    val personalLocation = PersonalLocation(name = name, place = place, store = storageType)
25    
26    // ReservedWordsCatalog maps keywords like "Home"/"Work" to their storage types
27    // Required when saving to HOME or WORK, optional for FAVORITE
28    val reservedWordsCatalog = ReservedWordsCatalog("Home", "Work")
29    val parameters = SavePersonalLocationParameters(personalLocation, reservedWordsCatalog)
30    
31    personalLocationsManager.savePersonalLocation(
32        parameters,
33        object : SavePersonalLocationCallback {
34            override fun onSaveCompleted(
35                result: Result<SavePersonalLocationResponse, SavePersonalLocationFailure>
36            ) {
37                when (result) {
38                    is Result.Success -> Log.d(TAG, "Location saved: ${result.value.personalLocationId}")
39                    is Result.Failure -> Log.e(TAG, "Failed to save location: ${result.reason}")
40                }
41            }
42            
43            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
44                Log.e(TAG, "Save location unavailable: ${reason.devMessage}")
45            }
46        }
47    )
48}
49
50// Usage examples:
51// savePersonalLocation(manager, "Home", homeCoordinate, PersonalLocation.StorageType.HOME)
52// savePersonalLocation(manager, "Work", workCoordinate, PersonalLocation.StorageType.WORK)
53// savePersonalLocation(manager, "Favorite Coffee Shop", cafeCoordinate, PersonalLocation.StorageType.FAVORITE)

Retrieving personal locations

Get saved locations by storage type:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.NavigableLocation.PersonalLocation
3import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
4import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationFailure
5import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationsCallback
6import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationsParameters
7import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationsResponse
8import com.tomtom.automotive.integration.client.common.Callback
9import com.tomtom.automotive.integration.client.common.Result
10
11private val TAG = "PersonalLocations"
12
13fun getPersonalLocations(personalLocationsManager: PersonalLocationsManager) {
  val storageTypes = listOf(
      PersonalLocation.StorageType.HOME,
      PersonalLocation.StorageType.WORK,
      PersonalLocation.StorageType.FAVORITE,
      PersonalLocation.StorageType.RECENT
  )
  
  personalLocationsManager.getPersonalLocations(
      GetPersonalLocationsParameters(storageTypes),
      object : GetPersonalLocationsCallback {
          override fun onCompleted(
              result: Result<GetPersonalLocationsResponse, GetPersonalLocationFailure>
          ) {
              when (result) {
                  is Result.Success -> {
                      val locations = result.value.personalLocations
                      Log.d(TAG, "Retrieved ${locations.size} locations")
                      
                      // Organize by type
                      val home = locations.filter { it.store == PersonalLocation.StorageType.HOME }
                      val work = locations.filter { it.store == PersonalLocation.StorageType.WORK }
                      val favorites = locations.filter { it.store == PersonalLocation.StorageType.FAVORITE }
                      val recent = locations.filter { it.store == PersonalLocation.StorageType.RECENT }
                  }
                  is Result.Failure -> Log.e(TAG, "Failed to get locations: ${result.reason}")
              }
          }
          
          override fun onFunctionalityUnavailable(reason: Callback.Reason) {
              Log.e(TAG, "Get locations unavailable: ${reason.devMessage}")
          }
      }
  )
47}

Observing location changes

Subscribe to receive updates when favorites or recent destinations change. Use ObservablePersonalLocationsType.FAVORITES or ObservablePersonalLocationsType.RECENTS:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
3import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.ObservablePersonalLocationsType
4import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.ObservePersonalLocationsParameters
5import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.PersonalLocationsInfo
6import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.PersonalLocationsListener
7import com.tomtom.automotive.integration.client.common.Callback
8import com.tomtom.automotive.integration.client.common.SdkReleasable
9
10private val TAG = "PersonalLocations"
11private var observeReleasable: SdkReleasable? = null
12
13fun observePersonalLocations(
14    personalLocationsManager: PersonalLocationsManager,
15    type: ObservablePersonalLocationsType
16) {
17    observeReleasable = personalLocationsManager.observePersonalLocations(
18        ObservePersonalLocationsParameters(type),
19        object : PersonalLocationsListener {
20            override fun onPersonalLocations(info: PersonalLocationsInfo) {
21                Log.d(TAG, "${type.name} updated: ${info.personalLocations.size} locations")
22            }
23            
24            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
25                Log.e(TAG, "Observe ${type.name} unavailable: ${reason.devMessage}")
26            }
27        }
28    )
29}
30
31fun stopObserving() {
32    observeReleasable?.release()
33    observeReleasable = null
34}
35
36// Usage:
37// observePersonalLocations(manager, ObservablePersonalLocationsType.FAVORITES)
38// observePersonalLocations(manager, ObservablePersonalLocationsType.RECENTS)

Deleting personal locations

Remove a specific location or all locations:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.NavigableLocation.PersonalLocation
3import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
4import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationCallback
5import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationFailure
6import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationParameters
7import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationResponse
8import com.tomtom.automotive.integration.client.common.Callback
9import com.tomtom.automotive.integration.client.common.Result
10
11private val TAG = "PersonalLocations"
12
13fun deletePersonalLocation(
14    personalLocationsManager: PersonalLocationsManager,
15    personalLocation: PersonalLocation
16) {
17    personalLocationsManager.deletePersonalLocation(
18        DeletePersonalLocationParameters.Delete(personalLocation),
19        object : DeletePersonalLocationCallback {
20            override fun onDeleteCompleted(
21                result: Result<DeletePersonalLocationResponse, DeletePersonalLocationFailure>
22            ) {
23                when (result) {
24                    is Result.Success -> Log.d(TAG, "Location deleted")
25                    is Result.Failure -> Log.e(TAG, "Failed to delete: ${result.reason}")
26                }
27            }
28            
29            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
30                Log.e(TAG, "Delete location unavailable: ${reason.devMessage}")
31            }
32        }
33    )
34}
35
36fun deleteAllPersonalLocations(personalLocationsManager: PersonalLocationsManager) {
37    personalLocationsManager.deletePersonalLocation(
38        DeletePersonalLocationParameters.DeleteAll(),
39        object : DeletePersonalLocationCallback {
40            override fun onDeleteCompleted(
41                result: Result<DeletePersonalLocationResponse, DeletePersonalLocationFailure>
42            ) {
43                when (result) {
44                    is Result.Success -> {
45                        val response = result.value as? DeletePersonalLocationResponse.DeleteAllResponse
46                        Log.d(TAG, "Deleted ${response?.deletedPersonalLocations?.size ?: 0} locations")
47                    }
48                    is Result.Failure -> Log.e(TAG, "Failed to delete all: ${result.reason}")
49                }
50            }
51            
52            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
53                Log.e(TAG, "Delete all unavailable: ${reason.devMessage}")
54            }
55        }
56    )
57}