Xamarin.Essentials: GéolocalisationXamarin.Essentials: Geolocation

La classe Geolocation fournit des API permettant de récupérer les coordonnées de géolocalisation de l’appareil.The Geolocation class provides APIs to retrieve the device's current geolocation coordinates.

Prise en mainGet started

Pour commencer à utiliser cette API, lisez le Guide de prise en main de Xamarin.Essentials pour vérifier que la bibliothèque est correctement installée et configurée dans vos projets.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.

Pour accéder à la fonctionnalité de géolocalisation, la configuration suivante spécifique à la plateforme est obligatoire :To access the Geolocation functionality, the following platform-specific setup is required:

Les autorisations de localisation approximative et de localisation précise sont obligatoires, et doivent être configurées dans le projet Android.Coarse and Fine Location permissions are required and must be configured in the Android project. De plus, si votre application cible Android 5.0 (niveau d’API 21) ou une version ultérieure, vous devez déclarer que votre application utilise les fonctionnalités matérielles dans le fichier manifeste.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. Vous pouvez le faire de plusieurs façons, comme indiqué ci-dessous :This can be added in the following ways:

Ouvrez le fichier AssemblyInfo.cs sous le dossier Propriétés, puis ajoutez :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)]

Ou mettez à jour le manifeste Android :Or update the Android manifest:

Ouvrez le fichier AndroidManifest.xml sous le dossier Propriétés, puis ajoutez ce qui suit dans le nœud manifeste :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" />

Vous pouvez également cliquer avec le bouton droit sur le projet Android, et ouvrir les propriétés du projet.Or right-click on the Android project and open the project's properties. Sous Manifeste Android, recherchez la zone Autorisations nécessaires, puis cochez les autorisations ACCESS_COARSE_LOCATION et ACCESS_FINE_LOCATION.Under Android Manifest find the Required permissions: area and check the ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions. Cela entraîne la mise à jour automatique du fichier AndroidManifest.xml.This will automatically update the AndroidManifest.xml file.

Utilisation de la géolocalisationUsing Geolocation

Ajoutez une référence à Xamarin.Essentials dans votre classe :Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

Si nécessaire, l’API de géolocalisation demande également des autorisations à l’utilisateur.The Geolocation API will also prompt the user for permissions when necessary.

Vous pouvez obtenir la dernière localisation connue de l’appareil en appelant la méthode GetLastKnownLocationAsync.You can get the last known location of the device by calling the GetLastKnownLocationAsync method. Bien que cela soit souvent plus rapide que d’effectuer une requête complète, cela peut aussi être moins précis et retourner null si aucun emplacement mis en cache n’existe.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
}

L’altitude n’est pas toujours disponible.The altitude isn't always available. Dans ce cas, la propriété Altitude peut avoir une valeur null ou égale à zéro.If it is not available, the Altitude property might be null or the value might be zero. Si l’altitude est disponible, la valeur est exprimée en mètres au-dessus du niveau de la mer.If the altitude is available, the value is in meters above sea level.

Pour interroger les coordonnées relatives à la localisation de l’appareil actuel, vous pouvez utiliser GetLocationAsync.To query the current device's location coordinates, the GetLocationAsync can be used. Il est préférable de passer un GeolocationRequest et un CancellationToken complets, car il peut s’écouler un certain temps avant d’obtenir la localisation de l’appareil.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
}

Précision de la géolocalisationGeolocation Accuracy

Le tableau suivant indique la précision en fonction de la plateforme :The following table outlines accuracy per platform:

MinimaleLowest

PlateformePlatform Distance (en mètres)Distance (in meters)
AndroidAndroid 500500
iOSiOS 3 0003000
UWPUWP 1 000 - 5 0001000 - 5000

FaibleLow

PlateformePlatform Distance (en mètres)Distance (in meters)
AndroidAndroid 500500
iOSiOS 10001000
UWPUWP 300 - 3 000300 - 3000

Moyenne (par défaut)Medium (Default)

PlateformePlatform Distance (en mètres)Distance (in meters)
AndroidAndroid 100 - 500100 - 500
iOSiOS 100100
UWPUWP 30 - 50030-500

HauteHigh

PlateformePlatform Distance (en mètres)Distance (in meters)
AndroidAndroid 0 - 1000 - 100
iOSiOS 1010
UWPUWP <= 10<= 10

La meilleureBest

PlateformePlatform Distance (en mètres)Distance (in meters)
AndroidAndroid 0 - 1000 - 100
iOSiOS ~0~0
UWPUWP <= 10<= 10

Détection des emplacements fictifsDetecting Mock Locations

Certains appareils peuvent retourner un emplacement fictif du fournisseur ou par une application qui fournit des emplacements fictifs.Some devices may return a mock location from the provider or by an application that provides mock locations. Vous pouvez le détecter à l’aide de IsFromMockProvider sur tout 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
    }
}

Distance entre deux emplacementsDistance between Two Locations

Les classes Location et LocationExtensions définissent les méthodes CalculateDistance qui vous permettent de calculer la distance entre deux emplacements géographiques.The Location and LocationExtensions classes define CalculateDistance methods that allow you to calculate the distance between two geographic locations. Cette distance calculée ne prend pas en compte les routes et autres chemins. Elle constitue simplement la distance la plus courte entre deux points à la surface de la Terre, également appelée distance orthodromique ou, familièrement, distance « à vol d’oiseau ».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."

Voici un exemple :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);

Le constructeur Location a des arguments de latitude et de longitude dans cet ordre.The Location constructor has latitude and longitude arguments in that order. Les valeurs de latitude positives sont au nord de l’équateur, et les valeurs de longitude positives sont à l’est du premier méridien.Positive latitude values are north of the equator, and positive longitude values are east of the Prime Meridian. Utilisez le dernier argument pour CalculateDistance afin de spécifier des miles ou des kilomètres.Use the final argument to CalculateDistance to specify miles or kilometers. La classe UnitConverters définit également les méthodes KilometersToMiles et MilesToKilometers pour effectuer la conversion entre les deux unités.The UnitConverters class also defines KilometersToMiles and MilesToKilometers methods for converting between the two units.

APIAPI