Expo

Documentation

Location

This module allows reading geolocation information from the device. Your app can poll for the current location or subscribe to location update events.

For managed apps, you'll need to run expo install expo-location. To use it in a bare React Native app, follow its installation instructions.

If you're using the iOS or Android Emulators, ensure that Location is enabled.
You must request permission to access the user's location before attempting to get it. To do this, you will want to use the Permissions API. You can see this in practice in the following example.

import * as Location from 'expo-location';

Checks whether location services are enabled by the user.

Returns a promise resolving to true if location services are enabled on the device, or false if not.

Requests the user for location permissions, similarly to Permissions.askAsync(Permissions.LOCATION).

Returns a promise that resolves when the permissions are granted and rejects when denied.

Get the current position of the device.

  • options (object) -- A map of options:
    • accuracy : Location.Accuracy -- Location manager accuracy. Pass one of Location.Accuracy enum values. For low-accuracy the implementation can avoid geolocation providers that consume a significant amount of power (such as GPS).
    • maximumAge (number) -- (Android only). If specified, allow returning a previously cached position that is at most this old in milliseconds. If not specified, always gets a new location. On iOS this option is ignored and a new location is always returned.

Returns a promise resolving to an object representing Location type.

Subscribe to location updates from the device. Please note that updates will only occur while the application is in the foreground. To get location updates while in background you'll need to use Location.startLocationUpdatesAsync.

  • options (object) -- A map of options:
    • accuracy : Location.Accuracy -- Location manager accuracy. Pass one of Location.Accuracy enum values. For low accuracy the implementation can avoid geolocation providers that consume a significant amount of power (such as GPS).
    • timeInterval (number) -- Minimum time to wait between each update in milliseconds.
    • distanceInterval (number) -- Receive updates only when the location has changed by at least this distance in meters.
    • mayShowUserSettingsDialog (boolean) -- Specifies whether to ask the user to turn on improved accuracy location mode which uses Wi-Fi, cell networks and GPS sensor. The dialog can be shown only when the location mode is set to Device only. Defaults to true. (Android only)
  • callback (function) --
    This function is called on each location update. It is passed exactly one parameter: an object representing Location type.

Returns a promise resolving to a subscription object, which has one field:
  • remove (function) -- Call this function with no arguments to remove this subscription. The callback will no longer be called for location updates.

Check status of location providers.

Returns a promise resolving to an object with the following fields:
  • locationServicesEnabled (boolean) -- Whether location services are enabled. See Location.hasServicesEnabledAsync for a more convenient solution to get this value.
  • gpsAvailable (boolean) (android only) -- If the GPS provider is available, if yes, location data will be from GPS.
  • networkAvailable (boolean) (android only) -- If the network provider is available, if yes, location data will be from cellular network.
  • passiveAvailable (boolean) (android only) -- If the passive provider is available, if yes, location data will be determined passively.

Asks the user to turn on high accuracy location mode which enables network provider that uses Google Play services to improve location accuracy and location-based services.

A promise resolving as soon as the user accepts the dialog. Rejects if denied.

Gets the current heading information from the device

Object with:
  • magHeading (number) — measure of magnetic north in degrees
  • trueHeading (number) — measure of true north in degrees (needs location permissions, will return -1 if not given)
  • accuracy (number) — level of callibration of compass.
    • 3: high accuracy, 2: medium accuracy, 1: low accuracy, 0: none
    • Reference for iOS: 3: < 20 degrees uncertainty, 2: < 35 degrees, 1: < 50 degrees, 0: > 50 degrees

Subscribe to compass updates from the device.

  • callback (function) --
    This function is called on each compass update. It is passed exactly one parameter: an object with the following fields:
    • magHeading (number) — measure of magnetic north in degrees
    • trueHeading (number) — measure of true north in degrees (needs location permissions, will return -1 if not given)
    • accuracy (number) — level of callibration of compass.
      • 3: high accuracy, 2: medium accuracy, 1: low accuracy, 0: none
      • Reference for iOS: 3: < 20 degrees uncertainty, 2: < 35 degrees, 1: < 50 degrees, 0: > 50 degrees

Returns a promise resolving to a subscription object, which has one field:
  • remove (function) — Call this function with no arguments to remove this subscription. The callback will no longer be called for location updates.

Geocode an address string to latitiude-longitude location.
Note: Geocoding is resource consuming and has to be used reasonably. Creating too many requests at a time can result in an error so they have to be managed properly.
On Android, you must request a location permission (Permissions.LOCATION) from the user before geocoding can be used.

  • address (string) -- A string representing address, eg. "Baker Street London"

Returns a promise resolving to an array (in most cases its size is 1) of geocoded location objects with the following fields:
  • latitude (number) -- The latitude in degrees.
  • longitude (number) -- The longitude in degrees.
  • altitude (number) -- The altitude in meters above the WGS 84 reference ellipsoid.
  • accuracy (number) -- The radius of uncertainty for the location, measured in meters.

Reverse geocode a location to postal address.
Note: Geocoding is resource consuming and has to be used reasonably. Creating too many requests at a time can result in an error so they have to be managed properly.
On Android, you must request a location permission (Permissions.LOCATION) from the user before geocoding can be used.

  • location (object) -- An object representing a location:
    • latitude (number) -- The latitude of location to reverse geocode, in degrees.
    • longitude (number) -- The longitude of location to reverse geocode, in degrees.

Returns a promise resolving to an array (in most cases its size is 1) of address objects with following fields:
  • city (string) -- City name of the address.
  • street (string) -- Street name of the address.
  • region (string) -- Region/area name of the address.
  • postalCode (string) -- Postal code of the address.
  • country (string) -- Localized country name of the address.
  • name (string) -- Place name of the address, for example, "Tower Bridge".

Sets a Google API Key for using Geocoding API. This method can be useful for Android devices that do not have Google Play Services, hence no Geocoder Service. After setting the key using Google's API will be possible.

  • apiKey (string) -- API key collected from Google Developer site.

Polyfills navigator.geolocation for interop with the core React Native and Web API approach to geolocation.

Background Location API can notify your app about new locations, also while it's in background. There are some requirements in order to use Background Location API:

Registers for receiving location updates that can also come when the app is in the background.

  • taskName (string) -- Name of the task receiving location updates.
  • options (object) -- An object of options passed to the location manager.
    • accuracy : Location.Accuracy -- Location manager accuracy. Pass one of Location.Accuracy enum values. For low-accuracy the implementation can avoid geolocation providers that consume a significant amount of power (such as GPS).
    • timeInterval (number) -- Minimum time to wait between each update in milliseconds. Default value depends on accuracy option. (Android only)
    • distanceInterval (number) -- Receive updates only when the location has changed by at least this distance in meters. Default value may depend on accuracy option.
    • deferredUpdatesInterval (number) -- Minimum time interval in miliseconds that must pass since last reported location before all later locations are reported in a batched update. Defaults to 0.
    • deferredUpdatesDistance (number) -- The distance in meters that must occur between last reported location and the current location before deferred locations are reported. Defaults to 0.
    • showsBackgroundLocationIndicator (boolean) -- A boolean indicating whether the status bar changes its appearance when location services are used in the background. Defaults to false. (Takes effect only on iOS 11.0 and later)
    • foregroundService (object) -- Use this option to put the location service into a foreground state, which will make location updates in the background as frequent as in the foreground state. As a downside, it requires a sticky notification, so the user will be aware that your app is running and consumes more resources even if backgrounded. (Available since Android 8.0)
      • notificationTitle (string) -- Title of the foreground service notification. required
      • notificationBody (string) -- Subtitle of the foreground service notification. required
      • notificationColor (string) -- Color of the foreground service notification. Accepts #RRGGBB and #AARRGGBB hex formats. optional
    • pausesUpdatesAutomatically (boolean) -- A boolean value indicating whether the location manager can pause location updates to improve battery life without sacrificing location data. When this option is set to true, the location manager pauses updates (and powers down the appropriate hardware) at times when the location data is unlikely to change. You can help the determination of when to pause location updates by assigning a value to the activityType property. Defaults to false. (iOS only)
    • activityType : Location.ActivityType -- The type of user activity associated with the location updates. See Apple docs for more details. Defaults to Location.ActivityType.Other. (iOS only)
Deferred updates provide a way to report locations in a batch when the app is in the background state. Location updates aren't being deferred in the foreground.

A promise resolving once the task with location updates is registered.

Background location task will be receiving following data:
  • locations : Location[] - An array of the new locations.
import * as TaskManager from 'expo-task-manager';

TaskManager.defineTask(YOUR_TASK_NAME, ({ data: { locations }, error }) => {
  if (error) {
    // check `error.message` for more details.
    return;
  }
  console.log('Received new locations', locations);
});

Stops location updates for given task.

  • taskName (string) -- Name of the background location task to stop.

A promise resolving as soon as the task is unregistered.

  • taskName (string) -- Name of the location task to check.

A promise resolving to boolean value indicating whether the location task is started or not.

Geofencing API notifies your app when the device enters or leaves geographical regions you set up. To make it work in the background, it uses TaskManager Native API under the hood. There are some requirements in order to use Geofencing API:

Starts geofencing for given regions. When the new event comes, the task with specified name will be called with the region that the device enter to or exit from. If you want to add or remove regions from already running geofencing task, you can just call startGeofencingAsync again with the new array of regions.

  • taskName (string) -- Name of the task that will be called when the device enters or exits from specified regions.
  • regions (array) -- Array of region objects to be geofenced.
    • identifier (string) -- The identifier of the region object. Defaults to auto-generated UUID hash.
    • latitude (number) -- The latitude in degrees of region's center point. required
    • longitude (number) -- The longitude in degrees of region's center point. required
    • radius (number) -- The radius measured in meters that defines the region's outer boundary. required
    • notifyOnEnter (boolean) -- Boolean value whether to call the task if the device enters the region. Defaults to true.
    • notifyOnExit (boolean) -- Boolean value whether to call the task if the device exits the region. Defaults to true.

A promise resolving as soon as the task is registered.

Geofencing task will be receiving following data:
import * as Location from 'expo-location';
import * as TaskManager from 'expo-task-manager';

TaskManager.defineTask(YOUR_TASK_NAME, ({ data: { eventType, region }, error }) => {
  if (error) {
    // check `error.message` for more details.
    return;
  }
  if (eventType === Location.GeofencingEventType.Enter) {
    console.log("You've entered region:", region);
  } else if (eventType === Location.GeofencingEventType.Exit) {
    console.log("You've left region:", region);
  }
});

Stops geofencing for specified task. It unregisters the background task so the app will not be receiving any updates, especially in the background.

  • taskName (string) -- Name of the task to unregister.

A promise resolving as soon as the task is unregistered.

  • taskName (string) -- Name of the geofencing task to check.

A promise resolving to boolean value indicating whether the geofencing task is started or not.

Object of type Location contains following keys:
  • coords (object) -- The coordinates of the position, with the following fields:
    • latitude (number) -- The latitude in degrees.
    • longitude (number) -- The longitude in degrees.
    • altitude (number) -- The altitude in meters above the WGS 84 reference ellipsoid.
    • accuracy (number) -- The radius of uncertainty for the location, measured in meters.
    • altitudeAccuracy (number) -- The accuracy of the altitude value, in meters (iOS only).
    • heading (number) -- Horizontal direction of travel of this device, measured in degrees starting at due north and continuing clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on.
    • speed (number) -- The instantaneous speed of the device in meters per second.
  • timestamp (number) -- The time at which this position information was obtained, in milliseconds since epoch.

Object of type Region includes following fields:
  • identifier (string) -- The identifier of the region object passed to startGeofencingAsync or auto-generated.
  • latitude (number) -- The latitude in degress of region's center point.
  • longitude (number) -- The longitude in degress of region's center point.
  • radius (number) -- The radius measured in meters that defines the region's outer boundary.
  • state : Location.GeofencingRegionState -- One of Location.GeofencingRegionState region state. Determines whether the device is inside or outside a region.

AccuracyValueDescription
Accuracy.Lowest1Accurate to the nearest three kilometers.
Accuracy.Low2Accurate to the nearest kilometer.
Accuracy.Balanced3Accurate to within one hundred meters.
Accuracy.High4Accurate to within ten meters of the desired target.
Accuracy.Highest5The best level of accuracy available.
Accuracy.BestForNavigation6The highest possible accuracy that uses additional sensor data to facilitate navigation apps.

ActivityTypeValueDescription
ActivityType.Other1Default activity type. Use it if there is no other type that matches the activity you track.
ActivityType.AutomotiveNavigation2Location updates are being used specifically during vehicular navigation to track location changes to the automobile.
ActivityType.Fitness3Use this activity type if you track fitness activities such as walking, running, cycling, and so on.
ActivityType.OtherNavigation4Activity type for movements for other types of vehicular navigation that are not automobile related.
ActivityType.Airborne5Intended for airborne activities. Available since iOS 12.0, fall backs to ActivityType.Other otherwise.

Event typeValueDescription
GeofencingEventType.Enter1Emitted when the device entered observed region.
GeofencingEventType.Exit2Occurs as soon as the device left observed region.

Region stateValueDescription
GeofencingRegionState.Inside1Indicates that the device is inside the region.
GeofencingRegionState.Outside2Inverse of inside state.

With Simulator open, go to Debug > Location and choose any option besides "None" (obviously).
iOS Simulator location

Open Android Studio, and launch your AVD in the emulator. Then, on the options bar for your device, click the icon for "More" and navigate to the "Location" tab.
Android Simulator location