Overview
This feature will allow forms filled out on CommCare for Android to automatically capture a GPS location with no intervention from the mobile user.
This feature includes the following functionality:
Automatically capturing GPS from a form. This will include the location data as part of the form’s metadata
If unsuccessful at getting a GPS location accurate with in 10 meters after 2 minutes, GPS location capture stops (to manage battery life). Below version 2.29 the cutoffs are 5 meters and 5 minutes, which caused issues with battery life.
Configuration of automatic GPS capture on a per-app level (turn it on and off per application)
Configuration of automatic GPS on a per-form level (if not set at the app level, can individually configure it per form)
Ability to access the automatic GPS captured data in a form export
Starting to capture GPS as soon as a form is opened that has a GPS question
When a form is set up to automatically capture a GPS location, it will do the following:
Upon opening the form, the phone will attempt to get a GPS location. Users will be able to fill out data in the form while this is occurring
Once the phone has captured a location of an acceptable accuracy (10m), the location will be recorded as part of the form’s metadata
If a GPS location is not captured to the acceptable level of accuracy within 2 minutes (the time threshold), the current location will be recorded as part of the form’s metadata. This behaviour is to save battery life on the device.
- If the form is completed prior to the time or accuracy threshold being met, the current GPS location is recorded as part of the form’s metadata. If there is no location information, a blank will be recorded.
Setting up Automatic GPS Capture
- Make sure that your application is running the appropriate versions of CommCare. Both the client and the application content must be updated:
- The CommCare client version from the Play Store must be 2.14 or greater. See Upgrading CommCare Mobile Software.
- Your application version on the settings page for your application must also be set to 2.14. More information found at How to Update CommCare Application Content
- Turn on Auto GPS Capture on CommCareHQ
- For all forms (when GPS capture will be active in all forms in an application)
- Navigate to the application settings page
- Under Android settings check the box for "Auto Capture Location (all forms)" and save
- For one form (when GPS capture will be active in only some forms in an application)
- Navigate to the specific form that you wish to auto capture GPS location
- Click the check box "Auto Capture Location (all forms)" and save
- For all forms (when GPS capture will be active in all forms in an application)
- Make a new version of your application and deploy it to your phone. Your phone will now attempt to automatically capture GPS locations for the forms you have selected.
| Configuration at the app level | Configuration at form specific level |
|---|---|
|
|
Saving GPS data to the case
To save GPS data to a case, just add a hidden value question and set the calculate expression to /data/meta/location. Then save this hidden value to the case like any other property. You can then take advantage of features like case list maps and distance sorting (a preview feature).
Exporting Automatically Captured GPS Data
One can use the standard Export Forms routine to export GPS data. To do so, select Show Advanced Settings in the Export Settings page and then include the Location field. To further break down the location and include latitude, longitude, altitude and accuracy in separate columns of the export, enable Expand Checkbox Questions.
Considerations/Notes
- For information on how to use GPS data please see Using GPS Data.
- For troubleshooting, see GPS Limitations.
- The phone's GPS must be on for this feature to work. If it is switched off, CommCare will prompt the user if they want to turn on GPS. This message will pop up each time they enter a form for which auto capture is on.
FAQs
- Q: Generally, what is "accurate" in GPS captures?
A: There are two accuracy thresholds. 1600m is "acceptable" and 10m is "good."
- Q: How does GPS capture differ between using the GPS question in a form and the autocapture form/app setting (aside from how it shows up in form exports)?
A: Aside from the fact that for the question, the user has to trigger the attempt at GPS capture, whereas for autocapture that happens automatically, there is no difference, notably in things like the accuracy of the capture or how long CommCare tries for the capture (2 minutes in both cases). For GPS questions, once the device gets a location that's "acceptable" it gets displayed to the user, but the GPS will keep querying until it reaches a "good" value (as it gets more accurate values, it'll keep updating the screen that says "Your location is ABC, do you want to save?"). For auto GPS capture, "acceptable" doesn't matter, the GPS just keeps querying until it hits a "good" value (or 2 minutes pass). So even if it never hits a "good" or even "acceptable" value, after 2 minutes, it saves whatever best value it has, regardless of how rough it is, notably because the accuracy is also stored with the location.
- Q: Does the CommCare version matter? I.e., is GPS capture via the question worse in v2.10.0 than in v2.26.0? Is that different for GPS via autocapture?
A: Accuracy shouldn't depend on CommCare. It will depend on location, hardware, and proximity to wifi networks. - Q: What happens if you move around after submitting the form? Say, drive in a car for the remaining 1.5 minutes after submitting a 30 second form? Does it try to find the location you submitted the form at (doubt this is possible?)?
A: It uses the last location acquired during form entry. I.e., it doesn't update once you hit submit on the form.
- Q: Generally, what is "accurate" in GPS captures?