Platform Compatibility

Installation

Configuration

• Permissions.LOCATION permission must be granted. On iOS it must be granted with Always option — see Permissions.LOCATION for more details.
• "location" background mode must be specified in Info.plist file. See background tasks configuration guide. (iOS only)
• Background location task must be defined in the top-level scope, using TaskManager.defineTask.

• Permissions.LOCATION permission must be granted. On iOS it must be granted with Always option — see Permissions.LOCATION for more details.
• Geofencing task must be defined in the top-level scope, using TaskManager.defineTask.
• On iOS, there is a limit of 20 regions that can be simultaneously monitored.

Usage

API

import * as Location from 'expo-location';

Methods

Location.hasServicesEnabledAsync()

Returns

Location.requestPermissionsAsync()

Returns

Location.getPermissionsAsync()

Returns

Location.getLastKnownPositionAsync()

Returns

Location.getCurrentPositionAsync(options)

Note: calling it on iOS causes the location manager to obtain a location fix which may take several seconds. Consider using Location.getLastKnownPositionAsync if you expect to get a quick response and high accuracy is not required.

Arguments

• 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

Location.watchPositionAsync(options, callback)

Arguments

• 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

• remove (function) -- Call this function with no arguments to remove this subscription. The callback will no longer be called for location updates.

Location.getProviderStatusAsync()

Returns

• 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.

Location.enableNetworkProviderAsync()

Returns

Location.getHeadingAsync()

Returns

• 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

Location.watchHeadingAsync(callback)

Arguments

• 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

• remove (function) — Call this function with no arguments to remove this subscription. The callback will no longer be called for location updates.

Location.geocodeAsync(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.

Arguments

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

Returns

• 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.

Location.reverseGeocodeAsync(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.

Arguments

• 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

• 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".

Location.setApiKey(apiKey)

Arguments

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

Location.installWebGeolocationPolyfill()

Background Location Methods

Location.startLocationUpdatesAsync(taskName, options)

Arguments

• 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.

Returns

Task parameters

• 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);
});

Location.stopLocationUpdatesAsync(taskName)

Arguments

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

Returns

Location.hasStartedLocationUpdatesAsync(taskName)

Arguments

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

Returns

Geofencing Methods

Location.startGeofencingAsync(taskName, regions)

Arguments

• 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.

Returns

Task parameters

• eventType : Location.GeofencingEventType -- Indicates the reason for calling the task, which can be triggered by entering or exiting the region. See Location.GeofencingEventType.
• region : Region -- Object containing details about updated region. See Region for more details.

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);
  }
});

Location.stopGeofencingAsync(taskName)

Arguments

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

Returns

Location.hasStartedGeofencingAsync(taskName)

Arguments

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

Returns

Types

Location

• 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.

Region

• 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.

PermissionDetailsLocationIOS

• scope (string) - The scope of granted permission, which indicates when it's possible to use location. Possible values: whenInUse, always.

PermissionDetailsLocationAndroid

• scope (string) - The scope of granted permission, which indicates the type of location provider. Possible values: fine, coarse, none.

Enums

Location.Accuracy

Location.ActivityType

Location.GeofencingEventType

Location.GeofencingRegionState

Enabling Emulator Location

iOS Simulator

Android Emulator