Geolocator Class

Definition

public ref class Geolocator sealed

/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class Geolocator final

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class Geolocator final

[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class Geolocator

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class Geolocator

function Geolocator()

Public NotInheritable Class Geolocator

Inheritance

Object Platform::Object IInspectable Geolocator

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows requirements

Examples

Basic location access with permission handling

This example shows how to request location access and get the current position with proper error handling.

using Windows.Devices.Geolocation;

private async Task GetCurrentLocationAsync()
{
    // Always request access first
    var accessStatus = await Geolocator.RequestAccessAsync();

    switch (accessStatus)
    {
        case GeolocationAccessStatus.Allowed:
            var geolocator = new Geolocator
            {
                DesiredAccuracy = PositionAccuracy.Default
            };

            try
            {
                var position = await geolocator.GetGeopositionAsync();
                var coordinate = position.Coordinate;

                // Use location data for app functionality
                Console.WriteLine($"Location: {coordinate.Latitude:F6}, {coordinate.Longitude:F6}");
                Console.WriteLine($"Accuracy: {coordinate.Accuracy:F0} meters");
                Console.WriteLine($"Source: {coordinate.PositionSource}");

                // App-specific: update map, search nearby places, etc.
            }
            catch (UnauthorizedAccessException)
            {
                // Location access was revoked during the operation
                Console.WriteLine("Location access was denied or revoked");
            }
            catch (Exception ex) when (ex.Message.Contains("timeout") || ex.Message.Contains("unavailable"))
            {
                // Location service timed out or unavailable
                Console.WriteLine("Location service is currently unavailable");
            }
            catch (Exception)
            {
                // Other location service errors
                Console.WriteLine("Unable to retrieve location at this time");
            }
            break;

        case GeolocationAccessStatus.Denied:
            // App-specific: show explanation and guide user to settings
            Console.WriteLine("Location access denied. Enable location in Settings > Privacy & Security > Location.");
            break;

        case GeolocationAccessStatus.Unspecified:
            Console.WriteLine("Location access error occurred");
            break;
    }
}

Continuous location tracking with status monitoring

This C++/WinRT example demonstrates continuous location tracking with proper event handling and resource management.

#include <winrt/Windows.Devices.Geolocation.h>
#include <winrt/Windows.Foundation.h>

using namespace winrt;
using namespace Windows::Devices::Geolocation;
using namespace Windows::Foundation;

class LocationTracker
{
private:
    Geolocator m_geolocator{ nullptr };
    event_token m_positionChangedToken;
    event_token m_statusChangedToken;

public:
    IAsyncAction StartTrackingAsync()
    {
        auto accessStatus = co_await Geolocator::RequestAccessAsync();

        if (accessStatus == GeolocationAccessStatus::Allowed)
        {
            m_geolocator = Geolocator();
            m_geolocator.DesiredAccuracyInMeters(50); // 50-meter accuracy
            m_geolocator.MovementThreshold(10);       // Update every 10 meters

            // Set up event handlers
            m_positionChangedToken = m_geolocator.PositionChanged(
                { this, &LocationTracker::OnPositionChanged });
            m_statusChangedToken = m_geolocator.StatusChanged(
                { this, &LocationTracker::OnStatusChanged });
        }
        co_return;
    }

    void StopTracking()
    {
        if (m_geolocator)
        {
            // Unsubscribe using remove_* pattern per C++/WinRT conventions
            m_geolocator.remove_PositionChanged(m_positionChangedToken);
            m_geolocator.remove_StatusChanged(m_statusChangedToken);
            m_geolocator = nullptr;
        }
    }

private:
    void OnPositionChanged(Geolocator const&, PositionChangedEventArgs const& args)
    {
        auto coordinate = args.Position().Coordinate();

        // App-specific: update tracking display, log position, etc.
        // Note: This runs on a background thread
    }

    void OnStatusChanged(Geolocator const&, StatusChangedEventArgs const& args)
    {
        switch (args.Status())
        {
            case PositionStatus::Ready:
                // Location service is available
                break;
            case PositionStatus::NoData:
                // Location service temporarily unavailable
                break;
            case PositionStatus::Disabled:
                // Location service disabled by user or policy
                break;
        }
    }
};

Remarks

The Geolocator class is the primary entry point for accessing location data in Windows applications. It provides both one-time location requests and continuous location tracking through events.

Key properties and methods

• RequestAccessAsync: Request permission to access location data. Always call this before attempting to get location.
• GetGeopositionAsync: Get the current location as a one-time request.
• PositionChanged: Event that fires when the device location changes during continuous tracking.
• StatusChanged: Event that fires when location permissions or service availability changes.
• DesiredAccuracy and DesiredAccuracyInMeters: Control the accuracy and power consumption tradeoff.

Permission and privacy considerations

Location access can be denied by the user or disabled by system policy. Handle GeolocationAccessStatus.Denied appropriately in your app logic.

Accuracy and power management

The location service balances accuracy with battery consumption. Use DesiredAccuracy.Default for most scenarios, or specify DesiredAccuracyInMeters when you need specific precision requirements.

Key considerations:

• Single-shot requests (GetGeopositionAsync) have lower battery impact per request.
• Continuous tracking (PositionChanged events) significantly drains battery and should be used sparingly.
• Lower ReportInterval values (< 30 seconds) increase power consumption exponentially.
• Higher MovementThreshold values (> 50 meters) reduce GNSS activation frequency.

Threading behavior

Version history

See also

• Geocoordinate
• GeolocationAccessStatus
• Geoposition
• PositionAccuracy
• PositionStatus
• Geolocation sample
• Get current location