To collect GPS data automatically with a form submission, see Automatic GPS Capture. For troubleshooting, see GPS Limitations.

Deciphering the Data

GPS data in CommCare is captured in decimal degrees. It has 4 components, separated by a space character:

  1. Latitude: in decimal degrees
  2. Longitude: in decimal degrees
  3. Elevation: in metres, and
  4. Precision / Accuracy: in metres

For example, a data point collected in CommCare and viewed through form data may look something like 25.615311244889146 85.08323017699811 28.44 20.0, where:

  1. 25.615311244889146 specifies the latitude in decimal degrees
  2. 85.08323017699811 specifies the longitude in decimal degrees
  3. 28.44 specifies the elevation in metres, and
  4. 20.0 specifies the precision in metres.

 

Mapping the Data

GPS data in CommCare is captured in decimal degrees. It is easy to make a map using Google Earth.

Google Earth requires a kml file. You can generate a kml file using an Excel file and a free converter like this one.

  1. Export data from CommCareHQ into Excel
  2. If all of the coordinates are in one cell, select the GPS coordinates field and use the Excel "text to columns" feature to separate the GPS field into its 4 component fields (latitude, longitude, elevation, precision). You can delete the elevation and precision columns for a basic map.

Use the following formulas to extract latitude and longitude (in this example, H2 is the cell that contains the full GPS coordinates. Replace H2 with whatever cell contains your GPS coordinates):

Latitude:=LEFT(H2,SEARCH(" ",H2,1))

Longitude: =MID(H2,SEARCH(" ",H2,1)+1,SEARCH(" ",H2,SEARCH(" ",H2,1)+1)-SEARCH(" ",H2,1))

  1. Copy the latitude and longitude fields into a clean Excel file. The first number is latitude. Label the two columns in the top rows at latitude and longitude respectively.
  2. Create additional columns with other information you want in the map (i.e. name, ID, etc.)
  3. Save the Excel file as a xls (Excel 97-2003 Workbook) NOT xlsx
  4. Upload the file into the converter
  5. Open the resulting kml file in Google Earth

Extracting GPS Components

The location returned by a GPS question is a string composed of the latitude, longitude, altitude and accuracy, each separated by a space. In your export configuration, if you choose "Expand Checkbox Questions" then the GPS data will automatically be split into four columns.

If all of the coordinates are in one cell, the following expression will extract the latitude from the location: if(/data/location = '', '', selected-at(/data/location, 0))

Similarly, for longitude: if(/data/location = '', '', selected-at(/data/location, 1))

When using the Auto-Location capture feature, that GPS location is available through /data/meta/location and can be accessed by enabling "Show Advanced Questions" in a form export.

Calculating Distances Between GPS Coordinates

CommCare now supports distance calculation via the distance XPath function on both J2ME and Android phones. For example, the following expression returns the distance between two locations in meters:

distance(/data/location1, /data/location2)

Since the distance function returns -1 if either argument is an empty string, a more robust way to display the distance is shown below:

if(/data/location1 = '', '', if(/data/location2 = '', '', distance(/data/location1, /data/location2)))