object:getUserLocation()

Type Function
Object Map
Library native.*
Return value Table
Revision Release 2024.3703
Keywords getUserLocation

Overview

Returns a table containing values for the user's current location, including:

Syntax

object:getUserLocation()

Error Handling

If the returned table's errorCode field is not nil, this indicates that the application has failed to fetch the user's current location. This can happen for the following reasons:

The specific error codes (errorCode) and messages (errorMessage) are as follows:

Code Message / Description
-3 "Current location is unknown" — Occurs if location services is enabled but the device's location hardware is still activating.
-2 "Current location tracking is not available on this device" — Occurs if this device doesn't have any means of determining the current location.
-1 "Location services are disabled" — Occurs when the device can determine the current location, but the user has disabled location services.
0 "Pending user authorization" — Occurs when the device is prompting the user for authorization to use location services.
1 "App is missing location permissions" — Available on Android only. Occurs if neither "android.permission.ACCESS_FINE_LOCATION" nor "android.permission.ACCESS_COARSE_LOCATION" is defined in build.settings.
2 "Location is denied by user" — On iOS, this occurs if the user has denied access to location data for the app. On Android 6.0 and above, this occurs if the user has denied the app access to location data and has requested that location permission is never requested again.

Gotchas

Android

In order to retrieve current location on Android, you must set the following permissions in the build.settings file.

settings =
{
    android =
    {
        usesPermissions =
        {
            -- Permission to retrieve current location from the GPS.
            "android.permission.ACCESS_FINE_LOCATION",

            -- Permission to retrieve current location from WiFi or cellular service.
            "android.permission.ACCESS_COARSE_LOCATION",
        },
    },
}

iOS

Starting with iOS 8, you must add the NSLocationWhenInUseUsageDescription key to the plist section of the build.settings file which contains the reason why you need access to location services.

settings =
{
    iphone =
    {
        plist =
        {
            NSLocationWhenInUseUsageDescription = "A description of why the app needs access to location services."
        },
    },
}

Example

-- Create a native map view
local myMap = native.newMapView( 20, 20, 280, 360 )
myMap.x = display.contentCenterX

local attempts = 0

local locationText = display.newText( "Location: ", 0, 400, native.systemFont, 16 )
locationText.anchorY = 0
locationText.x = display.contentCenterX

local function locationHandler( event )

    local currentLocation = myMap:getUserLocation()

    if ( currentLocation.errorCode or ( currentLocation.latitude == 0 and currentLocation.longitude == 0 ) ) then
        locationText.text = currentLocation.errorMessage

        attempts = attempts + 1

        if ( attempts > 10 ) then
            native.showAlert( "No GPS Signal", "Can't sync with GPS.", { "Okay" } )
        else
            timer.performWithDelay( 1000, locationHandler )
        end
    else
        locationText.text = "Current location: " .. currentLocation.latitude .. "," .. currentLocation.longitude
        myMap:setCenter( currentLocation.latitude, currentLocation.longitude )
        myMap:addMarker( currentLocation.latitude, currentLocation.longitude )
    end
end

locationHandler()