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:

latitude — The latitude in degrees of the current GPS location.
longitude — The longitude in degrees of the current GPS location.
altitude — The altitude in meters of the current GPS location.
accuracy — The accuracy of the GPS location in meters. If negative, the latitude and longitude are not valid.
speed — The instantaneous speed of the GPS device in meters per second. Divide the results by 0.447 to get MPH (miles per hour).
direction — The direction the device is traveling in degrees clockwise from true north. If negative, the direction is invalid.
time — Returns the UTC timestamp of the GPS location event. This is a Unix-style timestamp, expressed in seconds since Jan. 1, 1970.
errorCode — A platform-specific integer for an error condition that is not language dependent. See Error Handling below for details.
errorMessage — A string that describes an error in acquiring a GPS location from the device. See Error Handling below for details. The string may be localized according to the user’s language.

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:

Current location has not been received yet.
Current location tracking is not available on the device.
The application does not have permission.

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()

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