Summary

The address question type was born out of the need to quickly and accurately input address data into CommCare. It is a question type that provides an address lookup, which lets users select a complete address. Other questions may be configured to "subscribe" to the address question. When an address is selected, the question will "broadcast" the address's  individual fields to subscribing questions, which will then be automatically filled out. In this way, one can build a form where a user selects an address and then the address's city, postal code, etc. are automatically populated into other questions.

The address question is available in Web Apps and App Preview, but not on CommCare Mobile.

Demonstration

Image Added

How to Enable the Address Question Type in a Form

1. The following feature flag is needed

   1. CASE_CLAIM_AUTOLAUNCH (USH Specific toggle to support several different case search/claim workflows in web apps)

2. Add an address lookup question to the form as a text question type, and also add any questions that will receive and populate with subparts of the address.
   Image Added

3. Open the Advanced section of the address question.
   Image Added

4. Under Appearance Attribute, enter "address broadcast-<topic>" where "<topic>" can be any name to identify the address (e.g. "home", "work", etc).
   Image Added

Go to the address-subpart-receiving questions and under Advanced / Appearance Attribute for each of those, enter "receive-<topic>-<field>", where "<topic>" matches the address question topic name from the previous step, and "<field>" is the subpart of the address to be received by each question (e.g. "city", "zipcode", etc).  The full list of available fields appears below.

Image Added

1. Test the new address lookup question in the app preview window to see that a selected address populates as expected and submit to save the form selections successfully.
   Image Added

Address Question Type Components

The address question is not a formal question type, but an appearance on a text question. When the appearance is set to 'address' on a text (by entering 'address' into the Appearance Attribute under the Advanced question fields as demonstrated above), the question appears as an address search bar.

Broadcasts

Broadcasts will have an appearance tag of 'broadcast-<topic>' where 'topic' is a reference name that ties broadcasts to receivers (e.g. 'broadcast-hello' is tied to 'receive-hello-street'). Please note that an appearance can have multiple appearance types, so to have an address question broadcast its address components to receivers, the appearance becomes 'address broadcast-<topic>.'

Receivers

Receivers will have an appearance type in the format 'receive-<topic>-<field>' where <topic> corresponds to the same topic of the broadcast. 

Fields

Fields will map to the mapbox geocoder API in one of the following ways:

• full: the whole address 

• zipcode: maps to 'postcode'  e.g. ‘02139’ (zipcode is specific to the US)

• postcode: also maps to 'postcode' (for use outside of the US where zipcode is not used) 

• city: maps to 'place' and can be cities, towns and villages e.g. ‘Cambridge’

• county: maps to 'district' (county is specific to the US)

• district: also maps to 'district' (for use outside of the US where county is not used)

• street: is the concatenation of 'address' and 'text' to include the address number and street name 

• country: maps to the 'country' e.g. ‘United States of America’

• country_short: maps to the shortcode of the 'country' e.g. ‘US’

• region: maps to region, which includes states, provinces, and prefectures e.g. ‘Massachusetts’ 

• us_state: maps to the region only if it is in the US.

• us_state_short: maps to the region shortcode only if it’s in the US

• geopoint: latitude and longitude, formatted as "lat long", e.g., "37.34367 -121.893684"

Usage Details

Receiver Question Types

Text

The text question type is preferred for most of the components that have wide range of options such as 'street', 'zipcode', 'city'. If you have a defined set of options like 'states', consider the Multiple Choice and Multiple Choice Combobox. 

Numeric

Numeric question types are supported as receivers, but they are less ideal than text questions. Although they seem reasonable for zipcode, they will strip out the leading '0' (e.g. '02139' becomes '2139'). A text question with validation is better.

Multiple Choice and Multiple Choice Combobox

These questions are ideal when you want to limit the set of options, e.g. 'states'. When a broadcast is sent to a receiver, an option in the multiple choice is selected only if it matches the field it subscribes to. If there is no match, it registers a NO ANSWER as an answer. This means that if there is a previously selected answer but it receives a field that does not match its options, it will clear out the previous answer.

Special Combobox Feature: Tiered Fallbacks

It is possible to receive multiple fields and select the first match in the multiple choice combobox options. For example, if you wanted to only match on states 'CA', 'NY' and 'MA', but if none of those states match the address being received you want to fallback to match on countries 'United States of America', 'Puerto Rico', you would use 'receive-<topic>-<field1>||<field2>||<fieldn>'. An option will be selected when the first match is encountered going down the list of fields. 

Repeat Groups

If an address group is used inside of a repeat group, the selected address's fields will only broadcast within that same group.

Image Added

Settings

In "Project Settings", on the "Basic" page, is an option to set the project's default location:

Image Added

This default location is used to set the proximity parameter, which influences search results when there are many, or ambiguous, results. For best results, select a location somewhere in your project's deployment area.