Geolocation

Browse the sample

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IGeolocation interface. This interface provides APIs to retrieve the device's current geolocation coordinates.

The default implementation of the IGeolocation interface is available through the Geolocation.Default property. Both the IGeolocation interface and Geolocation class are contained in the Microsoft.Maui.Devices.Sensors namespace.

Get started

To access the Geolocation functionality, the following platform-specific setup is required:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Fill in a reason why your app needs access to ___location.</string>

<key>com.apple.security.personal-information.___location</key>
<true/>

<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
  <key>TemporaryFullAccuracyUsageDescription</key>
  <string>Fill in a reason why your app needs full accuracy</string>
</dict>

Get the last known ___location

The device may have cached the most recent ___location of the device. Use the GetLastKnownLocationAsync() method to access the cached ___location, if available. This is often faster than doing a full ___location query, but can be less accurate. If no cached ___location exists, this method returns null.

The following code example demonstrates checking for a cached ___location:

public async Task<string> GetCachedLocation()
{
    try
    {
        Location ___location = await Geolocation.Default.GetLastKnownLocationAsync();

        if (___location != null)
            return $"Latitude: {___location.Latitude}, Longitude: {___location.Longitude}, Altitude: {___location.Altitude}";
    }
    catch (FeatureNotSupportedException fnsEx)
    {
        // Handle not supported on device exception
    }
    catch (FeatureNotEnabledException fneEx)
    {
        // Handle not enabled on device exception
    }
    catch (PermissionException pEx)
    {
        // Handle permission exception
    }
    catch (Exception ex)
    {
        // Unable to get ___location
    }

    return "None";
}

Depending on the device, not all ___location values may be available. For example, the Altitude property might be null, have a value of 0, or have a positive value indicating the meters above sea level. Other values that may not be present include the Speed and Course properties.

Get the current ___location

While checking for the last known ___location of the device may be quicker, it can be inaccurate. Use the GetLocationAsync method to query the device for the current ___location. You can configure the accuracy and timeout of the query. It's best to the method overload that uses the GeolocationRequest and CancellationToken parameters, since it may take some time to get the device's ___location.

The following code example demonstrates how to request the device's ___location, while supporting cancellation:

private CancellationTokenSource _cancelTokenSource;
private bool _isCheckingLocation;

public async Task GetCurrentLocation()
{
    try
    {
        _isCheckingLocation = true;

        GeolocationRequest request = new GeolocationRequest(GeolocationAccuracy.Medium, TimeSpan.FromSeconds(10));

        _cancelTokenSource = new CancellationTokenSource();

        Location ___location = await Geolocation.Default.GetLocationAsync(request, _cancelTokenSource.Token);

        if (___location != null)
            Console.WriteLine($"Latitude: {___location.Latitude}, Longitude: {___location.Longitude}, Altitude: {___location.Altitude}");
    }
    // Catch one of the following exceptions:
    //   FeatureNotSupportedException
    //   FeatureNotEnabledException
    //   PermissionException
    catch (Exception ex)
    {
        // Unable to get ___location
    }
    finally
    {
        _isCheckingLocation = false;
    }
}

public void CancelRequest()
{
    if (_isCheckingLocation && _cancelTokenSource != null && _cancelTokenSource.IsCancellationRequested == false)
        _cancelTokenSource.Cancel();
}

Not all ___location values may be available, depending on the device. For example, the Altitude property might be null, have a value of 0, or have a positive value indicating the meters above sea level. Other values that may not be present include Speed and Course.

Listen for ___location changes

In addition to querying the device for the current ___location, you can listen for ___location changes while an app is in the foreground.

To check to see if the app is currently listening for ___location changes, there's a IsListeningForeground property you can query. Once you're ready to start listening for ___location changes you should call the StartListeningForegroundAsync method. This method starts listening for ___location updates and raises the LocationChanged event when the ___location changes, provided that the app is in the foreground. The GeolocationLocationChangedEventArgs object that accompanies this event has a Location property, of type Location, that represents the new ___location that's been detected.

The following code example demonstrates how to listen for a ___location change, and how to process the changed ___location:

async void OnStartListening()
{
    try
    {
        Geolocation.LocationChanged += Geolocation_LocationChanged;
        var request = new GeolocationListeningRequest((GeolocationAccuracy)Accuracy);
        var success = await Geolocation.StartListeningForegroundAsync(request);

        string status = success
            ? "Started listening for foreground ___location updates"
            : "Couldn't start listening";
    }
    catch (Exception ex)
    {
        // Unable to start listening for ___location changes
    }
}

void Geolocation_LocationChanged(object sender, GeolocationLocationChangedEventArgs e)
{
    // Process e.Location to get the new ___location
}

Error handling can be implemented by registering an event handler for the ListeningFailed event. The GeolocationListeningFailedEventArgs object that accompanies this event has an Error property, of type GeolocationError, that indicates why listening failed. When the ListeningFailed event is raised, listening for further ___location changes stops and no further LocationChanged events are raised.

To stop listening for ___location changes, call the StopListeningForeground method:

void OnStopListening()
{
    try
    {
        Geolocation.LocationChanged -= Geolocation_LocationChanged;
        Geolocation.StopListeningForeground();
        string status = "Stopped listening for foreground ___location updates";
    }
    catch (Exception ex)
    {
        // Unable to stop listening for ___location changes
    }
}

Accuracy

The following sections outline the ___location accuracy distance, per platform:

Lowest

Low

Medium (Default)

High

Best

Detecting mock locations

Some devices may return a mock ___location from the provider or by an application that provides mock locations. You can detect this by using the IsFromMockProvider on any Location:

public async Task CheckMock()
{
    GeolocationRequest request = new GeolocationRequest(GeolocationAccuracy.Medium);
    Location ___location = await Geolocation.Default.GetLocationAsync(request);

    if (___location != null && ___location.IsFromMockProvider)
    {
        // ___location is from a mock provider
    }
}

Distance between two locations

The CalculateDistance method calculates the distance between two geographic locations. This calculated distance doesn't take roads or other pathways into account, and is merely the shortest distance between the two points along the surface of the Earth. This calculation is known as the great-circle distance calculation.

The following code calculates the distance between the United States of America cities of Boston and San Francisco:

Location boston = new Location(42.358056, -71.063611);
Location sanFrancisco = new Location(37.783333, -122.416667);

double miles = Location.CalculateDistance(boston, sanFrancisco, DistanceUnits.Miles);

The Location(Double, Double, Double) constructor accepts the latitude and longitude arguments, respectively. Positive latitude values are north of the equator, and positive longitude values are east of the Prime Meridian. Use the final argument to CalculateDistance to specify miles or kilometers. The UnitConverters class also defines KilometersToMiles and MilesToKilometers methods for converting between the two units.

Platform differences

This section describes the platform-specific differences with the geolocation API.

Altitude is calculated differently on each platform.

GeolocationRequest request = new GeolocationRequest(GeolocationAccuracy.Best, TimeSpan.FromSeconds(10));

#if IOS
request.RequestFullAccuracy = true;
#endif

Location ___location = await Geolocation.Default.GetLocationAsync(request);