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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.Address
3
import com.tomtom.automotive.integration.client.api.model.Coordinate
4
import com.tomtom.automotive.integration.client.api.model.NavigableLocation.PersonalLocation
5
import com.tomtom.automotive.integration.client.api.model.NavigableLocation.Place
6
import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
7
import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.ReservedWordsCatalog
8
import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationCallback
9
import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationFailure
10
import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationParameters
11
import com.tomtom.automotive.integration.client.api.personalization.savepersonallocation.SavePersonalLocationResponse
12
import com.tomtom.automotive.integration.client.common.Callback
13
import com.tomtom.automotive.integration.client.common.Result
14

15
private val TAG = "PersonalLocations"
16

17
fun 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.NavigableLocation.PersonalLocation
3
import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
4
import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationFailure
5
import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationsCallback
6
import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationsParameters
7
import com.tomtom.automotive.integration.client.api.personalization.getpersonallocation.GetPersonalLocationsResponse
8
import com.tomtom.automotive.integration.client.common.Callback
9
import com.tomtom.automotive.integration.client.common.Result
10

11
private val TAG = "PersonalLocations"
12

13
fun getPersonalLocations(personalLocationsManager: PersonalLocationsManager) {
14
    val storageTypes = listOf(
15
        PersonalLocation.StorageType.HOME,
16
        PersonalLocation.StorageType.WORK,
17
        PersonalLocation.StorageType.FAVORITE,
18
        PersonalLocation.StorageType.RECENT
19
    )
20

21
    personalLocationsManager.getPersonalLocations(
22
        GetPersonalLocationsParameters(storageTypes),
23
        object : GetPersonalLocationsCallback {
24
            override fun onCompleted(
25
                result: Result<GetPersonalLocationsResponse, GetPersonalLocationFailure>
26
            ) {
27
                when (result) {
28
                    is Result.Success -> {
29
                        val locations = result.value.personalLocations
30
                        Log.d(TAG, "Retrieved ${locations.size} locations")
31

32
                        // Organize by type
33
                        val home = locations.filter { it.store == PersonalLocation.StorageType.HOME }
34
                        val work = locations.filter { it.store == PersonalLocation.StorageType.WORK }
35
                        val favorites = locations.filter { it.store == PersonalLocation.StorageType.FAVORITE }
36
                        val recent = locations.filter { it.store == PersonalLocation.StorageType.RECENT }
37
                    }
38
                    is Result.Failure -> Log.e(TAG, "Failed to get locations: ${result.reason}")
39
                }
40
            }
41

42
            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
43
                Log.e(TAG, "Get locations unavailable: ${reason.devMessage}")
44
            }
45
        }
46
    )
47
}

Observing location changes

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

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
3
import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.ObservablePersonalLocationsType
4
import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.ObservePersonalLocationsParameters
5
import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.PersonalLocationsInfo
6
import com.tomtom.automotive.integration.client.api.personalization.observepersonallocation.PersonalLocationsListener
7
import com.tomtom.automotive.integration.client.common.Callback
8
import com.tomtom.automotive.integration.client.common.SdkReleasable
9

10
private val TAG = "PersonalLocations"
11
private var observeReleasable: SdkReleasable? = null
12

13
fun 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

31
fun 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:

1
import android.util.Log
2
import com.tomtom.automotive.integration.client.api.model.NavigableLocation.PersonalLocation
3
import com.tomtom.automotive.integration.client.api.personalization.PersonalLocationsManager
4
import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationCallback
5
import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationFailure
6
import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationParameters
7
import com.tomtom.automotive.integration.client.api.personalization.deletepersonallocation.DeletePersonalLocationResponse
8
import com.tomtom.automotive.integration.client.common.Callback
9
import com.tomtom.automotive.integration.client.common.Result
10

11
private val TAG = "PersonalLocations"
12

13
fun 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

36
fun 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
}