Village Geographic Survey

Collection Screen


The Village Geographic Survey module is used to gather census data about each household. It records basic information: a house number, a head-of-household name, and the GPS coordinates of that household. The house number field is automatically increased with each saved record.

Recorded households are listed in the bottom portion of the screen. This list includes the name and house number, an Edit button that allows you to update the record, and an icon indicating whether the record is Valid or not. The validity of a record is determined by the accuracy of its GPS coordinates. The thresholds are set in the Configuration module.

The quality of the GPS signal is depicted by the color of the spinner and the specific rating listed.

Collection Screen with Poor GPS signal Collection Screen with Invalid Record

The above screen on the left depicts a GPS signal that is not accurate enough, and is displayed in yellow. The screen on the right shows that the icon next to Beth is an I for Invalid, rather than the V for Valid next to Alex.

A running total of records is indicated in between the collection portion of the screen and the record list. It is separated into the Valid, Invalid, and Excluded categories. The difference between Invalid and Excluded is that an Excluded record is manually excluded via the Exclude checkbox.

In Invalid, a record can only be made valid by recapturing the GPS coordinates when the accuracy is sufficient. The image below shows the record editing screen.

Collection Update Screen

To replace the GPS, the Replace GPS check-mark should be checked, and the Update button should be pressed.

After all of the household data has been recorded, the user should synchronize their results to the server (Syncing instructions).


The basic structure of the user interface is defined in assets/eps_collect.html, including all the input fields and the container for the list. Dynamic adjustments to this user interface, as well as calls to the database and device hardware, are made in assets/js/eps_collect.js. This file makes heavy use of the third-party Backbone JavaScript library. Also notice that the third-party library Underscore is included, along with template HTML, for dynamically adding list items.

The file eps_collect.js handles:

  1. Keeping track of the GPS coordinates and accuracy in real time. It also updates the user interface as necessary when these change. The thresholds for GPS accuracy are read from the settings with the epsConfigLib.js file.

  2. Reading, Creating, and Updating records in the Census table. This data is also validated before being recorded. The records are read through a number of calls to odkData.query(...) and odkData.ArbitraryQuery(...). They are recorded with calls to odkData.addRow(...) and they are updated with calls to odkData.updateRow(...).

  3. Dynamically creating the visualization of the list of records from the Census and updating it as that list changes. This list is also paginated. The running totals of Valid, Invalid, and Excluded records are populated with odkData.arbitraryQuery calls.

The file assets/js/util.js is included to generate UUIDs (unique ids and primary keys in the database) for each new record as it is created.


  • assets/eps_collect.html

  • assets/js/eps_collect.js

  • assets/js/util.js



Database Tables

  • Config

  • Census