メインコンテンツまでスキップ
バージョン: v9

@capacitor/geolocation

Geolocation APIは、GPSを使用してデバイスの現在位置を取得および追跡するためのシンプルなメソッドを提供します。利用可能な場合は、高度、方位、速度の情報も含まれます。

Install​

npm install @capacitor/geolocation
npx cap sync

iOS​

Appleは、位置情報のためにInfo.plistにプライバシー説明を指定することを要求しています：

  • NSLocationAlwaysAndWhenInUseUsageDescription（Privacy - Location Always and When In Use Usage Description）
  • NSLocationWhenInUseUsageDescription（Privacy - Location When In Use Usage Description）
バックグラウンド位置情報の使用目的文字列

このCapacitorプラグインはバックグラウンドジオロケーションを直接サポートしていません。ただし、 ion-ios-geolocationに依存しており、 バックグラウンドで位置を報告できます。そのため、AppleはInfo.plistに NSLocationAlwaysAndWhenInUseUsageDescriptionエントリを含めることを要求しています。この権限 プロンプトはユーザーには表示されないため、NSLocationWhenInUseUsageDescriptionと同じ 説明文字列を安全に使用できます。

XcodeでのiOSパーミッションの設定については、iOSガイドのInfo.plistの設定を参照してください。

Android​

このプラグインは、以下のパーミッションをAndroidManifest.xmlに追加する必要があります：

<!-- Geolocation Plugin -->
<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.gps" />

最初の2つのパーミッションは、大まかな位置と詳細な位置の両方の位置データを要求します。最後の行はオプションですが、アプリがGPSを必要とする場合は必要です。省略しても構いませんが、GPSハードウェアのないデバイスにアプリがインストールされる可能性があることに注意してください。

注記

概算位置（精度は変動しますが、通常は約2キロメートル）だけが必要な場合は、ACCESS_COARSE_LOCATION と <uses-feature> のみを宣言し、位置情報を要求するときに enableHighAccuracy=false を使用できます。

Androidパーミッションの設定の詳細については、Androidガイドのパーミッションの設定を参照してください。

API​

For list of error codes, see Errors

getCurrentPosition(...)​

getCurrentPosition(options?: PositionOptions | undefined) => Promise<Position>

Get the current GPS location of the device

ParamType
options
PositionOptions

Returns: 

Promise<Position>

Since: 1.0.0

watchPosition(...)​

watchPosition(options: PositionOptions, callback: WatchPositionCallback) => Promise<CallbackID>

Set up a watch for location changes. Note that watching for location changes can consume a large amount of energy. Be smart about listening only when you need to.

ParamType
options
PositionOptions
callback
WatchPositionCallback

Returns: Promise<string>

Since: 1.0.0

clearWatch(...)​

clearWatch(options: ClearWatchOptions) => Promise<void>

Clear a given watch

ParamType
options
ClearWatchOptions

Since: 1.0.0

checkPermissions()​

checkPermissions() => Promise<PermissionStatus>

Check location permissions. Will throw if system location services are disabled.

Returns: 

Promise<PermissionStatus>

Since: 1.0.0

requestPermissions(...)​

requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>

Request location permissions. Will throw if system location services are disabled.

Not available on web.

ParamType
permissions
GeolocationPluginPermissions

Returns: 

Promise<PermissionStatus>

Since: 1.0.0

Interfaces​

Position​

PropTypeDescriptionSince
timestampnumberCreation timestamp for coords1.0.0
coords{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number | null; altitude: number | null; speed: number | null; heading: number | null; magneticHeading: number | null; trueHeading: number | null; headingAccuracy: number | null; course: number | null; }The GPS coordinates along with the accuracy of the data1.0.0

PositionOptions​

PropTypeDescriptionDefaultSince
enableHighAccuracybooleanHigh accuracy mode (such as GPS, if available) On Android 12+ devices it will be ignored if users didn't grant ACCESS_FINE_LOCATION permissions (can be checked with location alias).false1.0.0
timeoutnumberThe maximum wait time in milliseconds for location updates.100001.0.0
maximumAgenumberThe maximum age in milliseconds of a possible cached position that is acceptable to return01.0.0
minimumUpdateIntervalnumberThe minimum update interval for watchPosition. Not to be confused with interval. If location updates are available faster than this interval then an update will only occur if the minimum update interval has expired since the last location update. This parameter is only available for Android. It has no effect on iOS or Web platforms.50006.1.0
intervalnumberDesired interval in milliseconds to receive location updates in watchPosition. For very low values of interval (a couple seconds or less), the platform may not guarantee timely location updates - they may take longer than specified. The platform may also be able to provide location updates faster than interval. You may use minimumUpdateInterval to control that behavior. For backwards compatibility with version 7.1.x, if no value is passed, the default value of this parameter is that of timeout. This parameter is only available for Android. It has no effect on iOS or Web platforms.
timeout
8.0.0
enableLocationFallbackbooleanWhether to fall back to the Android framework's LocationManager in case Google Play Service's location settings checks fail. This can happen for multiple reasons - e.g. device has no Play Services or device has no network connection (Airplane Mode) If set to false, failures are propagated to the caller. Note that LocationManager may not be as effective as Google Play Services implementation. If the device's in airplane mode, only the GPS provider is used, which may take longer to return a location, depending on GPS signal. This means that to receive location in such circumstances, you may need to provide a higher timeout. This parameter is only available for Android. It has no effect on iOS or Web platforms.true8.0.0

ClearWatchOptions​

PropType
id
CallbackID

PermissionStatus​

PropTypeDescriptionSince
location
PermissionState
Permission state for location alias. On Android it requests/checks both ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions. On iOS and web it requests/checks location permission.1.0.0
coarseLocation
PermissionState
Permission state for coarseLocation alias. On Android it requests/checks ACCESS_COARSE_LOCATION. On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) or Precise location (ACCESS_FINE_LOCATION), so this alias can be used if the app doesn't need high accuracy. On iOS and web it will have the same value as location alias.1.2.0

GeolocationPluginPermissions​

PropType
permissionsGeolocationPermissionType[]

Type Aliases​

WatchPositionCallback​

(position: Position | null, err?: any): void

CallbackID​

string

PermissionState​

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

GeolocationPermissionType​

'location' | 'coarseLocation'

Errors​

The plugin returns specific errors with specific codes on native Android and iOS. Web does not follow this standard for errors.

The following table list all the plugin errors:

Error codePlatform(s)Message
OS-PLUG-GLOC-0002Android, iOSThere was en error trying to obtain the location.
OS-PLUG-GLOC-0003Android, iOSLocation permission request was denied.
OS-PLUG-GLOC-0004iOSThe 'getCurrentPosition' input parameters aren't valid.
OS-PLUG-GLOC-0005iOSThe 'watchPosition' input parameters aren't valid.
OS-PLUG-GLOC-0006iOSThe 'clearWatch' input parameters aren't valid.
OS-PLUG-GLOC-0007Android, iOSLocation services are not enabled.
OS-PLUG-GLOC-0008iOSApplication's use of location services was restricted.
OS-PLUG-GLOC-0009AndroidRequest to enable location was denied.
OS-PLUG-GLOC-0010Android, iOSCould not obtain location in time. Try with a higher timeout.
OS-PLUG-GLOC-0011AndroidTimeout needs to be a positive value.
OS-PLUG-GLOC-0012AndroidWatchId not found.
OS-PLUG-GLOC-0013AndroidWatchId needs to be provided.
OS-PLUG-GLOC-0014AndroidGoogle Play Services error user resolvable.
OS-PLUG-GLOC-0015AndroidGoogle Play Services error.
OS-PLUG-GLOC-0016AndroidLocation settings error.
OS-PLUG-GLOC-0017AndroidUnable to retrieve location because device has both Network and Location turned off.
OS-PLUG-GLOC-0018AndroidLocation permissions are not declared in manifest. Make sure at least ACCESS_COARSE_LOCATION is declared in AndroidManifest.xml, and optionally ACCESS_FINE_LOCATION if you require precise location access.

Contents

このページを編集