Xamarin.Essentials: Geolocalización: Geolocation

La clase Geolocation proporciona las API para recuperar las coordenadas de geolocalización actuales del dispositivo.The Geolocation class provides APIs to retrieve the device's current geolocation coordinates.

Primeros pasosGet started

Para empezar a usar esta API, lea la guía de introducción para Xamarin.Essentials con el fin de asegurarse de que la biblioteca está correctamente instalada y configurada en los proyectos.To start using this API, read the getting started guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects.

Para acceder a la funcionalidad de Geolocation, se requiere la siguiente configuración específica para la plataforma:To access the Geolocation functionality, the following platform-specific setup is required:

Los permisos Coarse y Fine Location son requeridos y se deben configurar en el proyecto de Android.Coarse and Fine Location permissions are required and must be configured in the Android project. Además, si la aplicación tiene como destino Android 5.0 (nivel de API 21) o versiones posteriores, debe declarar que la aplicación usa las características de hardware en el archivo de manifiesto.Additionally, if your app targets Android 5.0 (API level 21) or higher, you must declare that your app uses the hardware features in the manifest file. Se puede agregar de las siguientes maneras:This can be added in the following ways:

Abra el archivo AssemblyInfo.cs de la carpeta Propiedades y agregue lo siguiente:Open the AssemblyInfo.cs file under the Properties folder and add:

[assembly: UsesPermission(Android.Manifest.Permission.AccessCoarseLocation)]
[assembly: UsesPermission(Android.Manifest.Permission.AccessFineLocation)]
[assembly: UsesFeature("android.hardware.location", Required = false)]
[assembly: UsesFeature("android.hardware.location.gps", Required = false)]
[assembly: UsesFeature("android.hardware.location.network", Required = false)]

O bien, actualice el manifiesto de Android:Or update the Android manifest:

Abra el archivo AndroidManifest.xml de la carpeta Propiedades y agregue lo siguiente dentro del nodo manifest:Open the AndroidManifest.xml file under the Properties folder and add the following inside of the manifest node:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-feature android:name="android.hardware.location" android:required="false" />
<uses-feature android:name="android.hardware.location.gps" android:required="false" />
<uses-feature android:name="android.hardware.location.network" android:required="false" />

O bien, haga clic con el botón derecho en el proyecto de Android y abra las propiedades del proyecto.Or right-click on the Android project and open the project's properties. En Manifiesto de Android, busque el área Permisos requeridos: y active los permisos ACCESS_COARSE_LOCATION y ACCESS_FINE_LOCATION.Under Android Manifest find the Required permissions: area and check the ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions. Esto actualizará automáticamente el archivo AndroidManifest.xml.This will automatically update the AndroidManifest.xml file.

Esta API usa permisos en tiempo de ejecución en Android.This API uses runtime permissions on Android. Asegúrese de que Xamarin.Essentials se haya inicializado por completo y de que el control de permisos esté configurado en la aplicación.Please ensure that Xamarin.Essentials is fully initialized and permission handling is setup in your app.

En MainLauncher del proyecto Android o en cualquier Activity que se inicia, Xamarin.Essentials se debe inicializar en el método OnCreate:In the Android project's MainLauncher or any Activity that is launched Xamarin.Essentials must be initialized in the OnCreate method:

protected override void OnCreate(Bundle savedInstanceState) 
{
    //...
    base.OnCreate(savedInstanceState);
    Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code, it may also be called: bundle
    //...
}    

Para controlar los permisos en tiempo de ejecución de Android, Xamarin.Essentials debe recibir cualquier OnRequestPermissionsResult.To handle runtime permissions on Android, Xamarin.Essentials must receive any OnRequestPermissionsResult. Agregue el código siguiente a todas las clases Activity:Add the following code to all Activity classes:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Android.Content.PM.Permission[] grantResults)
{
    Xamarin.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);

    base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
}

Uso de GeolocationUsing Geolocation

Agregue una referencia a Xamarin.Essentials en la clase:Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

La API Geolocation también le pedirá permisos al usuario cuando sea necesario.The Geolocation API will also prompt the user for permissions when necessary.

Puede obtener la última ubicación conocida del dispositivo mediante una llamada al método GetLastKnownLocationAsync.You can get the last known location of the device by calling the GetLastKnownLocationAsync method. A menudo, esto es más rápido que hacer una consulta completa, pero puede ser menos preciso y probablemente devuelva null si no existe ninguna ubicación en caché.This is often faster then doing a full query, but can be less accurate and may return null if no cached location exists.

try
{
    var location = await Geolocation.GetLastKnownLocationAsync();

    if (location != null)
    {
        Console.WriteLine($"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
}

La altitud no siempre está disponible.The altitude isn't always available. Si no lo está, es posible que la propiedad Altitude sea null o que el valor sea cero.If it is not available, the Altitude property might be null or the value might be zero. Si lo está, el valor se expresa en metros sobre el nivel del mar.If the altitude is available, the value is in meters above sea level.

Para consultar las coordenadas de ubicación del dispositivo actual, se puede usar GetLocationAsync.To query the current device's location coordinates, the GetLocationAsync can be used. Es mejor pasar un valor GeolocationRequest completo y CancellationToken, ya que se puede tardar algún tiempo en obtener la ubicación del dispositivo.It is best to pass in a full GeolocationRequest and CancellationToken since it may take some time to get the device's location.

try
{
    var request = new GeolocationRequest(GeolocationAccuracy.Medium);
    var location = await Geolocation.GetLocationAsync(request);

    if (location != null)
    {
        Console.WriteLine($"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
}

Precisión de la ubicación geográficaGeolocation Accuracy

En la tabla siguiente se describe la precisión por plataforma:The following table outlines accuracy per platform:

MínimaLowest

PlataformaPlatform Distancia (en metros)Distance (in meters)
AndroidAndroid 500500
iOSiOS 30003000
UWPUWP 1000 - 50001000 - 5000

BajoLow

PlataformaPlatform Distancia (en metros)Distance (in meters)
AndroidAndroid 500500
iOSiOS 10001000
UWPUWP 300 - 3000300 - 3000

Media (valor predeterminado)Medium (Default)

PlataformaPlatform Distancia (en metros)Distance (in meters)
AndroidAndroid 100 - 500100 - 500
iOSiOS 100100
UWPUWP 30-50030-500

AltoHigh

PlataformaPlatform Distancia (en metros)Distance (in meters)
AndroidAndroid 0 - 1000 - 100
iOSiOS 1010
UWPUWP <= 10<= 10

ÓptimaBest

PlataformaPlatform Distancia (en metros)Distance (in meters)
AndroidAndroid 0 - 1000 - 100
iOSiOS ~0~0
UWPUWP <= 10<= 10

Detección de ubicaciones ficticiasDetecting Mock Locations

Algunos dispositivos pueden devolver una ubicación ficticia desde el proveedor o desde una aplicación que proporciona ubicaciones ficticias.Some devices may return a mock location from the provider or by an application that provides mock locations. Puede detectarlo usando IsFromMockProvider en cualquier Location.You can detect this by using the IsFromMockProvider on any Location.

var request = new GeolocationRequest(GeolocationAccuracy.Medium);
var location = await Geolocation.GetLocationAsync(request);

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

Distancia entre dos ubicacionesDistance between Two Locations

Las clases Location y LocationExtensions definen métodos CalculateDistance que permiten calcular la distancia entre dos ubicaciones geográficas.The Location and LocationExtensions classes define CalculateDistance methods that allow you to calculate the distance between two geographic locations. Esta distancia calculada no tiene en cuenta las carreteras ni otros caminos, y simplemente es la distancia más corta entre los dos puntos a lo largo de la superficie de la Tierra, lo que también se conoce como distancia ortodrómica o coloquialmente, "distancia a vuelo de pájaro".This calculated distance does not take roads or other pathways into account, and is merely the shortest distance between the two points along the surface of the Earth, also known as the great-circle distance or colloquially, the distance "as the crow flies."

Por ejemplo:Here's an example:

Location boston = new Location(42.358056, -71.063611);
Location sanFrancisco = new Location(37.783333, -122.416667);
double miles = Location.CalculateDistance(boston, sanFrancisco, DistanceUnits.Miles);

El constructor Location tiene argumentos de latitud y longitud en ese orden.The Location constructor has latitude and longitude arguments in that order. Los valores de latitud positivos están al norte del Ecuador, y los valores de longitud positivos están al este del meridiano de Greenwich.Positive latitude values are north of the equator, and positive longitude values are east of the Prime Meridian. Use el argumento final CalculateDistance para especificar millas o kilómetros.Use the final argument to CalculateDistance to specify miles or kilometers. La clase UnitConverters también define los métodos KilometersToMiles y MilesToKilometers para la conversión entre las dos unidades.The UnitConverters class also defines KilometersToMiles and MilesToKilometers methods for converting between the two units.

Diferencias entre plataformasPlatform Differences

La altitud se calcula de forma diferente en cada plataforma.Altitude is calculated differently on each platform.

En Android, la altitud, si está disponible, se devuelve en metros por encima del elipsoide de referencia WGS 84.On Android, altitude, if available, is returned in meters above the WGS 84 reference ellipsoid. Si esta ubicación no tiene ninguna altitud, se devuelve 0.If this location does not have an altitude then 0.0 is returned.

APIAPI

Encuentre más vídeos de Xamarin en Channel 9 y YouTube.Find more Xamarin videos on Channel 9 and YouTube.