Location

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

import React, { useState, useEffect } from 'react';
import { Platform, Text, View, StyleSheet } from 'react-native';
%%placeholder-start%%%%placeholder-end%%import Constants from 'expo-constants';
import * as Location from 'expo-location';

export default function App() {
  const [location, setLocation] = useState(null);
  const [errorMsg, setErrorMsg] = useState(null);

  useEffect(() => {
    (async () => {
      %%placeholder-start%%%%placeholder-end%%if (Platform.OS === 'android' && !Constants.isDevice) {
        setErrorMsg(
          'Oops, this will not work on Snack in an Android emulator. Try it on your device!'
        );
        return;
      }
      let { status } = await Location.requestPermissionsAsync();
      if (status !== 'granted') {
        setErrorMsg('Permission to access location was denied');
        return;
      }

      let location = await Location.getCurrentPositionAsync({});
      setLocation(location);
    })();
  }, []);

  let text = 'Waiting..';
  if (errorMsg) {
    text = errorMsg;
  } else if (location) {
    text = JSON.stringify(location);
  }

  return (
    <View style={styles.container}>
      <Text style={styles.paragraph}>{text}</Text>
    </View>
  );
}

%%placeholder-start%%const styles = StyleSheet.create({ ... }); %%placeholder-end%%const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 20,
  },
  paragraph: {
    fontSize: 18,
    textAlign: 'center',
  },
});

API

import * as Location from 'expo-location';

Methods

Location.hasServicesEnabledAsync()

Returns

Location.requestPermissionsAsync()

Returns

Location.getPermissionsAsync()

Returns

Location.getLastKnownPositionAsync(options)

Arguments

• options (object) — A map of options:
  • maxAge (number) — A number of miliseconds after which the last known location starts to be invalid and thus null is returned.
  • requiredAccuracy (number) — The maximum radius of uncertainty for the location, measured in meters. If the last known location's accuracy radius is bigger (less accurate) then null is returned.

Returns

Location.getCurrentPositionAsync(options)

Note: Calling it 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 : LocationAccuracy — Location manager accuracy. Pass one of LocationAccuracy enum values. For low-accuracy the implementation can avoid geolocation providers that consume a significant amount of power (such as GPS).

Returns

Location.watchPositionAsync(options, callback)

Arguments

• options (object) — A map of options:
  • accuracy : LocationAccuracy — Location manager accuracy. Pass one of LocationAccuracy 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) — (Android only) 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.
• callback (function) -- This function is called on each location update. It receives an object of type LocationObject as the first argument.

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

Location.enableNetworkProviderAsync()

Returns

Location.getHeadingAsync()

Returns

Location.watchHeadingAsync(callback)

Arguments

• callback (function) -- This function is called on each compass update. It receives an object of type LocationHeadingObject as the first argument.

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. It's also discouraged to use geocoding while the app is in the background and its results won't be shown to the user immediately.

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"
• options (object) — A map of options:
  • useGoogleMaps (boolean) — Whether to force using Google Maps API instead of the native implementation. Used by default only on Web platform. Requires providing an API key by setGoogleApiKey.

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. It's also discouraged to use geocoding while the app is in the background and its results won't be shown to the user immediately.

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.
• options (object) — A map of options:
  • useGoogleMaps (boolean) — Whether to force using Google Maps API instead of the native implementation. Used by default only on Web platform. Requires providing an API key by setGoogleApiKey.

Returns

• city (string | null) — City name of the address.
• district (string | null) — Additional city-level information like district name.
• street (string | null) — Street name of the address.
• region (string | null) — The state or province associated with the address.
• subregion (string | null) — Additional information about administrative area.
• postalCode (string | null) — Postal code of the address.
• country (string | null) — Localized country name of the address.
• name (string | null) — The name of the placemark, for example, "Tower Bridge".
• isoCountryCode (string | null) — Localized (iso) country code of the address, if available.
• timezone (string | null) — The timezone identifier associated with the address. (iOS only)

Location.setGoogleApiKey(apiKey)

Arguments

• apiKey (string) — Google API key obtained from Google API Console. This API key must have Geocoding API enabled, otherwise your geocoding requests will be denied.

Location.installWebGeolocationPolyfill()

Background Location Methods

Note: on Android, you have to submit your app for review and request access to use the background location permission.

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 : LocationAccuracy -- Location manager accuracy. Pass one of LocationAccuracy 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 : LocationActivityType -- The type of user activity associated with the location updates. See Apple docs for more details. Defaults to LocationActivityType.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 : LocationObject[] - 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

Note: on Android, you have to submit your app for review and request access to use the background location permission.

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 : LocationGeofencingEventType -- Indicates the reason for calling the task, which can be triggered by entering or exiting the region. See LocationGeofencingEventType.
• region : LocationRegion -- Object containing details about updated region. See LocationRegion for more details.

import { LocationGeofencingEventType } 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 === LocationGeofencingEventType.Enter) {
    console.log("You've entered region:", region);
  } else if (eventType === LocationGeofencingEventType.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

LocationPermissionResponse

• ios (object)
  • scope (string) — The scope of granted permission. Indicates when it's possible to use location, possible values are: whenInUse, always or none.
• android (object)
  • scope (string) — On Android it indicates the type of location provider with possible values: fine, coarse, none.

LocationObject

• 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 | null) — The altitude in meters above the WGS 84 reference ellipsoid. Can be null on Web if it's not available.
  • accuracy (number | null) — The radius of uncertainty for the location, measured in meters. Can be null on Web if it's not available.
  • altitudeAccuracy (number | null) — The accuracy of the altitude value, in meters. Can be null on Web if it's not available.
  • heading (number | null) — 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. Can be null on Web if it's not available.
  • speed (number | null) — The instantaneous speed of the device in meters per second. Can be null on Web if it's not available.
• timestamp (number) — The time at which this position information was obtained, in milliseconds since epoch.

LocationProviderStatus

• locationServicesEnabled (boolean) -- Whether location services are enabled. See Location.hasServicesEnabledAsync for a more convenient solution to get this value.
• gpsAvailable (boolean) -- (Android only) Whether the GPS provider is available. If true the location data will come from GPS, especially for requests with high accuracy.
• networkAvailable (boolean) -- (Android only) Whether the network provider is available. If true the location data will come from cellular network, especially for requests with low accuracy.
• passiveAvailable (boolean) -- (Android only) Whether the passive provider is available. If true the location data will be determined passively.

LocationRegion

• 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 : LocationGeofencingRegionState -- One of LocationGeofencingRegionState region state. Determines whether the device is inside or outside a region.

LocationHeadingObject

• 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

Enums

LocationAccuracy

LocationActivityType

LocationGeofencingEventType

LocationGeofencingRegionState

Enabling Emulator Location

iOS Simulator

Android Emulator