{"id":13635227,"url":"https://github.com/michalchudziak/react-native-geolocation","last_synced_at":"2025-05-14T03:11:48.929Z","repository":{"id":38960739,"uuid":"178442448","full_name":"michalchudziak/react-native-geolocation","owner":"michalchudziak","description":"Geolocation APIs for React Native","archived":false,"fork":false,"pushed_at":"2024-09-01T08:47:12.000Z","size":2113,"stargazers_count":1378,"open_issues_count":162,"forks_count":239,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-23T22:37:03.593Z","etag":null,"topics":["geolocation","library","location","react","react-native"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/michalchudziak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-29T16:41:44.000Z","updated_at":"2025-04-23T13:43:26.000Z","dependencies_parsed_at":"2024-03-28T20:39:13.537Z","dependency_job_id":"e08030e0-09de-4746-b070-e1d0c13234f8","html_url":"https://github.com/michalchudziak/react-native-geolocation","commit_stats":{"total_commits":233,"total_committers":99,"mean_commits":"2.3535353535353534","dds":0.8369098712446352,"last_synced_commit":"aa51e7e529a16843366002f52d1b5cd4a788df15"},"previous_names":["react-native-community/react-native-geolocation","react-native-geolocation/react-native-geolocation"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalchudziak%2Freact-native-geolocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalchudziak%2Freact-native-geolocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalchudziak%2Freact-native-geolocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michalchudziak%2Freact-native-geolocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michalchudziak","download_url":"https://codeload.github.com/michalchudziak/react-native-geolocation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059520,"owners_count":22007771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geolocation","library","location","react","react-native"],"created_at":"2024-08-02T00:00:42.719Z","updated_at":"2025-05-14T03:11:43.920Z","avatar_url":"https://github.com/michalchudziak.png","language":"Java","funding_links":[],"categories":["Maps","Java","React Native"],"sub_categories":["Geolocation","Maps"],"readme":"# `@react-native-community/geolocation`\n\n[![npm](https://img.shields.io/npm/v/@react-native-community/geolocation)](https://www.npmjs.com/package/@react-native-community/geolocation) ![Supports Android, iOS and web](https://img.shields.io/badge/platforms-android%20%7C%20ios%20%7C%20web-lightgrey.svg) ![MIT License](https://img.shields.io/npm/l/@react-native-community/geolocation.svg)\n\nThe Geolocation API 📍 module for React Native that extends the [Geolocation web spec](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation). \n\nSupports TurboModules ⚡️ and legacy React Native architecture.\n\nFully compatible with TypeScript.\n\nSupports modern [Play Services Location API](https://developers.google.com/android/reference/com/google/android/gms/location/FusedLocationProviderClient.html).\n\n\n## Supported platforms\n\n| Platform  |  Support |\n|---|---|\n| iOS  |  ✅ |\n| Android  |  ✅ |\n| Web  |  ✅ |\n| Windows  |  ❌ |\n| macOS  |  ❌ |\n\n## Compatibility\n| React Native  |  RNC Geoloaction |\n|---|---|\n| \u003e= 0.73.0  | \u003e= 3.2.0 |\n| \u003e= 0.70.0  | \u003e= 3.0.0 \u003c 3.2.0 |\n| \u003e= 0.64.0  | 2.x.x |\n| \u003c= 0.63.0  | 1.x.x |\n\n\n## Getting started\n\n`yarn add @react-native-community/geolocation`\n\nor\n\n`npm install @react-native-community/geolocation --save`\n\n## Configuration and Permissions\n\n\u003cdiv class=\"banner-crna-ejected\"\u003e\n  \u003ch3\u003eProjects with Native Code Only\u003c/h3\u003e\n  \u003cp\u003e\n    This section only applies to projects made with \u003ccode\u003ereact-native init\u003c/code\u003e\n    or to those made with \u003ccode\u003eexpo init\u003c/code\u003e or Create React Native App which have since ejected. For\n    more information about ejecting, please see\n    the \u003ca href=\"https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md\" target=\"_blank\"\u003eguide\u003c/a\u003e on\n    the Create React Native App repository.\n  \u003c/p\u003e\n\u003c/div\u003e\n\n### iOS\n\nYou need to include `NSLocationWhenInUseUsageDescription` and `NSLocationAlwaysAndWhenInUseUsageDescription` in `Info.plist` to enable geolocation when using the app. If your app supports iOS 10 and earlier, the `NSLocationAlwaysUsageDescription` key is also required. If these keys are not present in the `Info.plist`, authorization requests fail immediately and silently. Geolocation is enabled by default when you create a project with `react-native init`.\n\nIn order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.\n\nIOS \u003e= 15 Positions will also contain a `mocked` boolean to indicate if position was created from a mock provider / software.\n\n\n### Android\n\nTo request access to location, you need to add the following line to your app's `AndroidManifest.xml`:\n\n`\u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e`\n\nor \n\n`\u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" /\u003e`\n\nAndroid API \u003e= 18 Positions will also contain a `mocked` boolean to indicate if position was created from a mock provider.\n\n\u003cp\u003e\n  Android API \u003e= 23 Requires an additional step to check for, and request\n  the ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permissions using\n  the \u003ca href=\"https://reactnative.dev/docs/permissionsandroid.html\" target=\"_blank\"\u003ePermissionsAndroid API\u003c/a\u003e.\n  Failure to do so may result in a hard crash.\n\u003c/p\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eFor React Native \u003c 0.65 on Android we need to link manually\u003c/b\u003e\u003c/summary\u003e\n\n\n- android/settings.gradle\n```\ninclude ':react-native-community-geolocation'\nproject(':react-native-community-geolocation').projectDir = new File(rootProject.projectDir, '../node_modules/@react-native-community/geolocation/android')\n```\n- android/app/build.gradle\n```\ndependencies {\n   ...\n   implementation project(':react-native-community-geolocation')\n}\n```\n- android/app/src/main/.../MainApplication.java\n  On imports section:\n```java\nimport com.reactnativecommunity.geolocation.GeolocationPackage;\n```\n  In the class at `getPackages` method: \n```java\n@Override\nprotected List\u003cReactPackage\u003e getPackages() {\n      @SuppressWarnings(\"UnnecessaryLocalVariable\")\n      List\u003cReactPackage\u003e packages = new PackageList(this).getPackages();\n      // Packages that cannot be autolinked yet can be added manually here, for example:\n      packages.add(new GeolocationPackage()); // \u003c== add this line\n      return packages;\n}\n```\n\u003c/details\u003e\n\n## Migrating from the core `react-native` module\nThis module was created when the Geolocation was split out from the core of React Native. As a browser polyfill, this API was available through the `navigator.geolocation` global - you didn't need to import it. To migrate to this module you need to follow the installation instructions above and change following code:\n\n```javascript\nnavigator.geolocation.setRNConfiguration(config);\n```\n\nto:\n\n```javascript\nimport Geolocation from '@react-native-community/geolocation';\n\nGeolocation.setRNConfiguration(config);\n```\n\nIf you need to have geolocation API aligned with the browser (cross-platform apps), or want to support backward compatibility, please consider adding following lines at the root level, for example at the top of your App.js file (only for [react native](https://reactnative.dev/docs/platform-specific-code.html#native-specific-extensions-ie-sharing-code-with-nodejs-and-web)):\n\n```javascript\nnavigator.geolocation = require('@react-native-community/geolocation');\n```\n\n## Usage\n\n### Example\n\n```javascript\nimport Geolocation from '@react-native-community/geolocation';\n\nGeolocation.getCurrentPosition(info =\u003e console.log(info));\n```\n\nCheck out the [example project](example) for more examples.\n\n## Methods\n\n### Summary\n\n* [`setRNConfiguration`](#setrnconfiguration)\n* [`requestAuthorization`](#requestauthorization)\n* [`getCurrentPosition`](#getcurrentposition)\n* [`watchPosition`](#watchposition)\n* [`clearWatch`](#clearwatch)\n* [`stopObserving`](#stopobserving)\n\n---\n\n### Details\n\n#### `setRNConfiguration()`\n\nSets configuration options that will be used in all location requests.\n\n\n```ts\nGeolocation.setRNConfiguration(\n  config: {\n    skipPermissionRequests: boolean;\n    authorizationLevel?: 'always' | 'whenInUse' | 'auto';\n    enableBackgroundLocationUpdates?: boolean;\n    locationProvider?: 'playServices' | 'android' | 'auto';\n  }\n) =\u003e void\n```\n\nSupported options:\n\n* `skipPermissionRequests` (boolean) - Defaults to `false`. If `true`, you must request permissions before using Geolocation APIs.\n* `authorizationLevel` (string, iOS-only) - Either `\"whenInUse\"`, `\"always\"`, or `\"auto\"`. Changes whether the user will be asked to give \"always\" or \"when in use\" location services permission. Any other value or `auto` will use the default behaviour, where the permission level is based on the contents of your `Info.plist`.\n* `enableBackgroundLocationUpdates` (boolean, iOS-only) - When using `skipPermissionRequests`, toggle wether to automatically enableBackgroundLocationUpdates. Defaults to true.\n* `locationProvider` (string, Android-only) - Either `\"playServices\"`, `\"android\"`, or `\"auto\"`.  Determines wether to use `Google’s Location Services API` or `Android’s Location API`. The `\"auto\"` mode defaults to `android`, and falls back to Android's Location API if play services aren't available.\n\n---\n\n#### `requestAuthorization()`\n\nRequest suitable Location permission. \n\n```ts\n  Geolocation.requestAuthorization(\n    success?: () =\u003e void,\n    error?: (\n      error: {\n        code: number;\n        message: string;\n        PERMISSION_DENIED: number;\n        POSITION_UNAVAILABLE: number;\n        TIMEOUT: number;\n      }\n    ) =\u003e void\n  )\n```\n\nOn iOS if NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.\n\n---\n\n#### `getCurrentPosition()`\n\nInvokes the success callback once with the latest location info.\n\n```ts\n  Geolocation.getCurrentPosition(\n    success: (\n      position: {\n        coords: {\n          latitude: number;\n          longitude: number;\n          altitude: number | null;\n          accuracy: number;\n          altitudeAccuracy: number | null;\n          heading: number | null;\n          speed: number | null;\n        };\n        timestamp: number;\n      }\n    ) =\u003e void,\n    error?: (\n      error: {\n        code: number;\n        message: string;\n        PERMISSION_DENIED: number;\n        POSITION_UNAVAILABLE: number;\n        TIMEOUT: number;\n      }\n    ) =\u003e void,\n    options?: {\n        timeout?: number;\n        maximumAge?: number;\n        enableHighAccuracy?: boolean;\n    }\n  )\n```\n\n\nSupported options:\n\n* `timeout` (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to 10 minutes.\n* `maximumAge` (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.\n* `enableHighAccuracy` (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.\n\n---\n\n#### `watchPosition()`\n\nInvokes the success callback whenever the location changes. Returns a `watchId` (number).\n\n```ts\n  Geolocation.watchPosition(\n    success: (\n      position: {\n        coords: {\n          latitude: number;\n          longitude: number;\n          altitude: number | null;\n          accuracy: number;\n          altitudeAccuracy: number | null;\n          heading: number | null;\n          speed: number | null;\n        };\n        timestamp: number;\n      }\n    ) =\u003e void,\n    error?: (\n      error: {\n        code: number;\n        message: string;\n        PERMISSION_DENIED: number;\n        POSITION_UNAVAILABLE: number;\n        TIMEOUT: number;\n      }\n    ) =\u003e void,\n    options?: {\n      interval?: number;\n      fastestInterval?: number;\n      timeout?: number;\n      maximumAge?: number;\n      enableHighAccuracy?: boolean;\n      distanceFilter?: number;\n      useSignificantChanges?: boolean;\n    }\n  ) =\u003e number\n```\n\nSupported options:\n\n* `interval` (ms) -- (Android only) The rate in milliseconds at which your app prefers to receive location updates. Note that the location updates may be somewhat faster or slower than this rate to optimize for battery usage, or there may be no updates at all (if the device has no connectivity, for example).\n* `fastestInterval` (ms) -- (Android only) The fastest rate in milliseconds at which your app can handle location updates. Unless your app benefits from receiving updates more quickly than the rate specified in `interval`, you don't need to set it.\n* `timeout` (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to 10 minutes.\n* `maximumAge` (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.\n* `enableHighAccuracy` (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.\n* `distanceFilter` (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.\n* `useSignificantChanges` (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.\n\n---\n\n#### `clearWatch()`\n\nClears watch observer by id returned by `watchPosition()`\n\n```ts\nGeolocation.clearWatch(watchID: number);\n```\n\n## Maintainers\n\nThis module is developed and maintained by [michalchudziak](https://github.com/michalchudziak).\n\nI owe a lot to the fantastic React \u0026 React Native community, and I contribute back with my free time 👨🏼‍💼💻 so if you like the project, please star it ⭐️!\n\nIf you need any help with this module, or anything else, feel free to reach out to me! I provide boutique consultancy services for React \u0026 React Native. Just visit my [website](https://michalchudziak.dev), or send me an email at [hello@michalchudziak.dev](mailto:hello@michalchudziak.dev) 🙏🏻\n\n### Co-maintainers needed\n\nDue to personal commitments, recently I am unable to dedicate the necessary time to maintain this library as it deserves. I’m looking for passionate contributors to help keep the project alive and thriving. If you're interested in contributing or taking on a maintainer role, please reach out [hello@michalchudziak.dev](mailto:hello@michalchudziak.dev) — your support would mean a lot!\n\n## Contributors\n\nThis module was extracted from `react-native` core. Please refer to https://github.com/react-native-community/react-native-geolocation/graphs/contributors for the complete list of contributors.\n\n## License\nThe library is released under the MIT licence. For more information see `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichalchudziak%2Freact-native-geolocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichalchudziak%2Freact-native-geolocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichalchudziak%2Freact-native-geolocation/lists"}